OpenPGP smartcards and Gentoo - part 2: card and gnupg setup

This is part 2 of a tutorial on OpenPGP smartcard use with Gentoo. Part 1 can be found in an earlier blog post. This time, we assume that you already have a smart card and a functioning reader, and continue setting up the card. Then we'll make everything ready for use with GnuPG by setting up a key pair. As already stated, I am picking a compromise between ultra-security and convenience. Please do not complain if you find guides on the web on how to do things "better". All information here is provided as a best effort, however I urge you to read up on your own. Even if you follow this guide to the last letter- if things break, it is your own responsibility.

Setting the AdminPIN and the PIN

OK, let's start. We insert a blank card into the card reader. The card should come with some paper documentation, stating the initial values of the PIN and the AdminPIN- these we will need in a moment. Now, we want to edit the card properties. We can do this with the command "gpg --card-edit".

jones@pinacolada ~ $ gpg --card-edit 

Application ID ...: D276000124010200000500000AFA0000
Version ..........: 2.0
Manufacturer .....: ZeitControl
Serial number ....: 00000AFA
Name of cardholder: [not set]
Language prefs ...: de
Sex ..............: unspecified
URL of public key : [not set]
Login data .......: [not set]
Signature PIN ....: forced
Key attributes ...: 2048R 2048R 2048R
Max. PIN lengths .: 32 32 32
PIN retry counter : 3 0 3
Signature counter : 0
Signature key ....: [none]
Encryption key....: [none]
Authentication key: [none]
General key info..: [none]

gpg/card> help
quit       quit this menu
admin      show admin commands
help       show this help
list       list all available data
fetch      fetch the key specified in the card URL
passwd     menu to change or unblock the PIN
verify     verify the PIN and list all data
unblock    unblock the PIN using a Reset Code

This menu is not really that helpful yet. However, a lot more commands are hidden below the "admin" keyword:

gpg/card> admin
Admin commands are allowed

gpg/card> help
quit       quit this menu
admin      show admin commands
help       show this help
list       list all available data
name       change card holder's name
url        change URL to retrieve key
fetch      fetch the key specified in the card URL
login      change the login name
lang       change the language preferences
sex        change card holder's sex
cafpr      change a CA fingerprint
forcesig   toggle the signature force PIN flag
generate   generate new keys
passwd     menu to change or unblock the PIN
verify     verify the PIN and list all data
unblock    unblock the PIN using a Reset Code

First of all we change the AdminPIN and the PIN from the manufacturer defaults to some nice random-looking values that only we know.

gpg/card> passwd
gpg: OpenPGP card no. D276000124010200000500000AFA0000 detected

1 - change PIN
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit

Your selection? 3

At this point a window from gpg-agent pops up (same as when asking for a passphrase), requests the old AdminPIN and twice the new AdminPIN. Make sure you remember the new AdminPIN or write it down somewhere safe. The AdminPIN allows to change the card parameters (from name of cardholder to stored keys and PIN) and can be used to reset the PIN if you have forgotten it or mistyped it three times. However, if you mistype the AdminPIN three times, your card locks up completely and is basically trash. Note that changing the PINs cannot be done via a reader keypad yet.

PIN changed.

1 - change PIN
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit

Your selection? 1
PIN changed.

1 - change PIN
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit

Your selection? q

gpg/card>

Setting the cardholder data

Now, let's enter the cardholder data. With the first change you will be prompted for the AdminPIN.

gpg/card> nameCardholder's surname: Jones
Cardholder's given name: Henry W.

gpg/card> lang
Language preferences: en

gpg/card> sex
Sex ((M)ale, (F)emale or space): M

gpg/card> quit
jones@pinacolada ~ $

What are the remaining commands good for? Well...

• "url" sets an URL where to retrieve the public keys. We will use that later on. 
• "login" sets a log-in data field. Here you could store your username for e.g. network authentication. 
• "forcesig" toggles a flag inside the card that has been introduced because of German legislative requirements for some smartcard applications. Normally, once you have inserted the card into the reader, you enter the PIN once for unlocking e.g. the encryption or the signature key, and then the key remains open for the moment. If the signature PIN is "forced", you will have to reenter the PIN again each time you want to make a signature.
• "generate" generates a RSA key pair directly on the card. This is the "high security option"; the generated private key will and can never leave the card, which enhances its security but also makes backups of the key impossible.

Which leaves the "reset code" to be explained. Imagine you are issued a card by e.g. your employer. The card will be preset with your name, login, and keys, and you should not be able to change that. So, you will not know the AdminPIN. If you enter your user PIN wrong three times in a row, it is invalidated. Now the reset code instead of the AdminPIN can also be used to reset the PIN. Basically this is the same functionality as the PUK for mobile phone SIM cards. The definitive source on all this functionality is the OpenPGP Card 2.0 specification.

Generating GnuPG keypairs

As mentioned in the beginning, there are many different ways to proceed. A keypair can be generated on the card or in the computer. Different types of keys or parts of keys can be uploaded to the card. I'm now presenting the following use case:

• We generate the GnuPG keys not on the card but on the trusted computer, and then copy them to the card. This makes backups of the keys possible, and you can also upload them later to a second card should the first one accidentally drop into the document shredder.
• We upload the whole key, not just subkeys as described in some howtos. This makes it possible to access the entire GnuPG functionality from the card- decrypting, signing, and also especially certifying (i.e. signing keys). Of course this means that your primary key is on the card, too.

In general, before you generate a GnuPG keyset you may want to read up on GnuPG best practices; see e.g. this mailing list post of our Gentoo Infra team lead robbat2 for information and further pointers.
Enough talk. We use GPG to generate a 4096bit RSA primary key for signing and certifying with an 4096bit RSA encryption subkey. Note that for all the following steps you need in Gentoo at least app-crypt/gnupg-2.0.19-r2; I strongly recommend app-crypt/gnupg-2.0.20 since there smartcard handling has improved a lot.

jones@pinacolada ~ $ gpg --gen-key
gpg (GnuPG) 2.0.19; Copyright (C) 2012 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Please select what kind of key you want:
   (1) RSA and RSA (default)
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
Your selection? 1
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048) 4096
Requested keysize is 4096 bits
Please specify how long the key should be valid.
         0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0) 3y
Key expires at Tue May 24 23:26:58 2016 CEST
Is this correct? (y/N) y

GnuPG needs to construct a user ID to identify your key.

Real name: Henry W. Jones Jr.
Email address: henry.w.jones@uchicago.edu
Comment:
You selected this USER-ID:
    "Henry W. Jones Jr. <henry.w.jones@uchicago.edu>"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
You need a Passphrase to protect your secret key.

We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: /home/jones/.gnupg/trustdb.gpg: trustdb created
gpg: key 14ED37BC marked as ultimately trusted
public and secret key created and signed.

gpg: checking the trustdb
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
gpg: next trustdb check due at 2016-05-24
pub   4096R/14ED37BC 2013-05-25 [expires: 2016-05-24]
      Key fingerprint = 3C94 3AC9 713D E3E3 B3C6  BF73 3898 61DB 14ED 37BC
uid                  Henry W. Jones Jr. <henry.w.jones@uchicago.edu>
sub   4096R/345D5ECB 2013-05-25 [expires: 2016-05-24]

jones@pinacolada ~ $

Got it. Now we do something unusual- in addition to the sign/certify (SC) main key and the encryption (E) subkey, we add a second subkey, an authentication (A) key (for later on). We edit the just generated key with the --expert option:

jones@pinacolada ~ $ gpg --expert --edit 14ED37BC
gpg (GnuPG) 2.0.19; Copyright (C) 2012 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Secret key is available.

pub  4096R/14ED37BC  created: 2013-05-25  expires: 2016-05-24  usage: SC  
                     trust: ultimate      validity: ultimate
sub  4096R/345D5ECB  created: 2013-05-25  expires: 2016-05-24  usage: E   
[ultimate] (1). Henry W. Jones Jr. <henry.w.jones@uchicago.edu>

gpg> addkey
Please select what kind of key you want:
   (3) DSA (sign only)
   (4) RSA (sign only)
   (5) Elgamal (encrypt only)
   (6) RSA (encrypt only)
   (7) DSA (set your own capabilities)
   (8) RSA (set your own capabilities)
Your selection? 8

We select to add an RSA key where we set the capabilities ourselves. Now we disable Sign and Encrypt, and enable Authenticate instead.

Possible actions for a RSA key: Sign Encrypt Authenticate
Current allowed actions: Sign Encrypt

   (S) Toggle the sign capability
   (E) Toggle the encrypt capability
   (A) Toggle the authenticate capability
   (Q) Finished

Your selection? s

Possible actions for a RSA key: Sign Encrypt Authenticate
Current allowed actions: Encrypt

   (S) Toggle the sign capability
   (E) Toggle the encrypt capability
   (A) Toggle the authenticate capability
   (Q) Finished

Your selection? e

Possible actions for a RSA key: Sign Encrypt Authenticate
Current allowed actions:

   (S) Toggle the sign capability
   (E) Toggle the encrypt capability
   (A) Toggle the authenticate capability
   (Q) Finished

Your selection? a

Possible actions for a RSA key: Sign Encrypt Authenticate
Current allowed actions: Authenticate

   (S) Toggle the sign capability
   (E) Toggle the encrypt capability
   (A) Toggle the authenticate capability
   (Q) Finished

Your selection? q
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048) 4096
Requested keysize is 4096 bits
Please specify how long the key should be valid.
         0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0) 3y
Key expires at Tue May 24 23:39:55 2016 CEST
Is this correct? (y/N) y
Really create? (y/N) y
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.

pub  4096R/14ED37BC  created: 2013-05-25  expires: 2016-05-24  usage: SC  
                     trust: ultimate      validity: ultimate
sub  4096R/345D5ECB  created: 2013-05-25  expires: 2016-05-24  usage: E   
sub  4096R/808D3DB3  created: 2013-05-25  expires: 2016-05-24  usage: A   
[ultimate] (1). Henry W. Jones Jr. <henry.w.jones@uchicago.edu>

gpg> save
jones@pinacolada ~ $

This additional key cannot be used directly by GnuPG, but it is stored in the keyring and will come in handy later on.

Copying the keys to the smartcard

Now we copy the secret keys to the smartcard.

jones@pinacolada ~ $ gpg --edit 14ED37BC
gpg (GnuPG) 2.0.19; Copyright (C) 2012 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Secret key is available.

pub  4096R/14ED37BC  created: 2013-05-25  expires: 2016-05-24  usage: SC  
                     trust: ultimate      validity: ultimate
sub  4096R/345D5ECB  created: 2013-05-25  expires: 2016-05-24  usage: E   
sub  4096R/808D3DB3  created: 2013-05-25  expires: 2016-05-24  usage: A   
[ultimate] (1). Henry W. Jones Jr. <henry.w.jones@uchicago.edu>

With "toggle" we switch from public key to secret key view.

gpg> toggle

sec  4096R/14ED37BC  created: 2013-05-25  expires: 2016-05-24
ssb  4096R/345D5ECB  created: 2013-05-25  expires: never     
ssb  4096R/808D3DB3  created: 2013-05-25  expires: never     
(1)  Henry W. Jones Jr. <henry.w.jones@uchicago.edu>

We select the authentication key and move it to the card (we need the AdminPIN for that):

gpg> key 2

sec  4096R/14ED37BC  created: 2013-05-25  expires: 2016-05-24
ssb  4096R/345D5ECB  created: 2013-05-25  expires: never     
ssb* 4096R/808D3DB3  created: 2013-05-25  expires: never     
(1)  Henry W. Jones Jr. <henry.w.jones@uchicago.edu>

gpg> keytocard
Signature key ....: [none]
Encryption key....: [none]
Authentication key: [none]

Please select where to store the key:
   (3) Authentication key
Your selection? 3

sec  4096R/14ED37BC  created: 2013-05-25  expires: 2016-05-24
ssb  4096R/345D5ECB  created: 2013-05-25  expires: never     
ssb* 4096R/808D3DB3  created: 2013-05-25  expires: never     
                     card-no: 0005 00000AFA
(1)  Henry W. Jones Jr. <henry.w.jones@uchicago.edu>

Then, we select the encryption key and deselect the authentication key; same procedure follows.

gpg> key 1

sec  4096R/14ED37BC  created: 2013-05-25  expires: 2016-05-24
ssb* 4096R/345D5ECB  created: 2013-05-25  expires: never     
ssb* 4096R/808D3DB3  created: 2013-05-25  expires: never     
                     card-no: 0005 00000AFA
(1)  Henry W. Jones Jr. <henry.w.jones@uchicago.edu>

gpg> key 2

sec  4096R/14ED37BC  created: 2013-05-25  expires: 2016-05-24
ssb* 4096R/345D5ECB  created: 2013-05-25  expires: never     
ssb  4096R/808D3DB3  created: 2013-05-25  expires: never     
                     card-no: 0005 00000AFA
(1)  Henry W. Jones Jr. <henry.w.jones@uchicago.edu>

gpg> keytocard
Signature key ....: [none]
Encryption key....: [none]
Authentication key: 8474 2310 057F 1D64 056F  5903 F15B 3DEE 808D 3DB3

Please select where to store the key:
   (2) Encryption key
Your selection? 2

sec  4096R/14ED37BC  created: 2013-05-25  expires: 2016-05-24
ssb* 4096R/345D5ECB  created: 2013-05-25  expires: never     
                     card-no: 0005 00000AFA
ssb  4096R/808D3DB3  created: 2013-05-25  expires: never     
                     card-no: 0005 00000AFA
(1)  Henry W. Jones Jr. <henry.w.jones@uchicago.edu>

Finally we deselect the encryption key, so no subkey is selected anymore, and move the primary (signature/certification) key.

gpg> key 1

sec  4096R/14ED37BC  created: 2013-05-25  expires: 2016-05-24
ssb  4096R/345D5ECB  created: 2013-05-25  expires: never     
                     card-no: 0005 00000AFA
ssb  4096R/808D3DB3  created: 2013-05-25  expires: never     
                     card-no: 0005 00000AFA
(1)  Henry W. Jones Jr. <henry.w.jones@uchicago.edu>

gpg> keytocard
Really move the primary key? (y/N) y
Signature key ....: [none]
Encryption key....: 2050 EC35 2F6C 3EB0 223C  C551 279A 16D7 345D 5ECB
Authentication key: 8474 2310 057F 1D64 056F  5903 F15B 3DEE 808D 3DB3

Please select where to store the key:
   (1) Signature key
   (3) Authentication key
Your selection? 1

sec  4096R/14ED37BC  created: 2013-05-25  expires: 2016-05-24
                     card-no: 0005 00000AFA
ssb  4096R/345D5ECB  created: 2013-05-25  expires: never     
                     card-no: 0005 00000AFA
ssb  4096R/808D3DB3  created: 2013-05-25  expires: never     
                     card-no: 0005 00000AFA
(1)  Henry W. Jones Jr. <henry.w.jones@uchicago.edu>

Now we leave GnuPG, and it's important that we leave without saving. Otherwise, the secret key would be deleted on-disk and only remain on the card. (Of course, this may also be desired.)

gpg> quit
Save changes? (y/N) n
Quit without saving? (y/N) y
jones@pinacolada ~ $

Now, the card is basically ready for use. Let's have a look at its contents once more:

jones@pinacolada ~ $ gpg --card-status
Application ID ...: D276000124010200000500000AFA0000
Version ..........: 2.0
Manufacturer .....: ZeitControl
Serial number ....: 00000AFA
Name of cardholder: Henry W. Jones
Language prefs ...: en
Sex ..............: male
URL of public key : [not set]
Login data .......: [not set]
Signature PIN ....: forced
Key attributes ...: 4096R 4096R 4096R
Max. PIN lengths .: 32 32 32
PIN retry counter : 3 0 3
Signature counter : 0
Signature key ....: 3C94 3AC9 713D E3E3 B3C6  BF73 3898 61DB 14ED 37BC
      created ....: 2013-05-25 21:30:56
Encryption key....: 2050 EC35 2F6C 3EB0 223C  C551 279A 16D7 345D 5ECB
      created ....: 2013-05-25 21:30:56
Authentication key: 8474 2310 057F 1D64 056F  5903 F15B 3DEE 808D 3DB3
      created ....: 2013-05-25 21:39:35
General key info..: pub  4096R/14ED37BC 2013-05-25 Henry W. Jones Jr. <henry.w.jones@uchicago.edu>
sec   4096R/14ED37BC  created: 2013-05-25  expires: 2016-05-24
ssb   4096R/345D5ECB  created: 2013-05-25  expires: 2016-05-24
ssb   4096R/808D3DB3  created: 2013-05-25  expires: 2016-05-24
jones@pinacolada ~ $

We'll discuss how to exactly use the card next time (but that's not really hard to figure out either :). Cheers!