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!