I've had an OpenPGP smartcard for quite some time now. I recently acquired a
Crypto Stick as well thanks to rcvalle. Using these things with GnuPG isn't very clear and took a lot of work to figure out. Rather than let others struggle through all this, I'll document the procedure here.
The basic idea behind using a smartcard to hold your GPG keys is that an attacker can't steal the key. The worst they could do is to sign or decrypt something while you have the card inserted.
Please take the time to understand what's going on here. I have lots of examples to make this all work, but be sure you understand what's happening. Public key cryptography is hard, you should at least have a basic grasp of what's happening here. This howto should be treated as an example, not a cookie cutter recipe to follow.
This is a rather long post, more after the fold.
Get your card working
My focus here is going to be Fedora. I suspect instructions for other variants of Linux won't be all that different. The cryptostick is supported by pcsc. This means that you don't have to worry about any silly permissions issues (which used to be an issue with some cardreaders). To install pcsc you'll want to install the pcsc-lite, pcsc-lite-ccid, and pcsc-tools packages.
Once those are all installed, make sure you enable the pcscd daemon to start on boot. If you're using systemd, pcscd also comes with a magic sock to autostart pcscd on demand. To enable it use:
bress@computer ~ % systemctl start pcscd.socket
bress@computer ~ % systemctl start pcscd.service
bress@computer ~ % systemctl enable pcscd.socket
bress@computer ~ % systemctl enable pcscd.service
|
If you now plugin your cryptostick and run pcsc_scan, you should get some output like this:
bress@computer ~ % pcsc_scan
PC/SC device scanner
V 1.4.17 (c) 2001-2009, Ludovic Rousseau <ludovic.rousseau@free.fr>
Compiled with PC/SC lite version: 1.6.6
Scanning present readers...
0: German Privacy Foundation Crypto Stick v1.2 00 00
... lots more text
|
You can double check the card by trying the command 'gpg --card-status'. It will give an output that we don't need to worry about just yet.
Generate a primary key
We're going to generate our keys on a computer, then import them into the card. It's possible to generate the keys directly on card but then if you ever lose the card, or it breaks, you have no way to access your keys. It's of course up to you how to do this. We're going to generate a primary key which will never touch a networked computer, then a signing subkey, an encryption subkey, and an authentication subkey. There are lots of documents out there that describe using this approach and why it's useful. Rather than try to rehash them here, I'll leave it up to the reader to understand this method. In short, you want to do this.
First we need a computer that's a fresh install and has never seen the internet. We're going to shred the disk once we're done so don't bother tweaking it to death. I'd suggest against trying to use a liveimage here. Anything that could get written to the drive could possible be read off later due to the way flash drives work (you can't reliably wipe them).
Once you have a clean install, we want to create a directory for gpg to work out of.
bress@computer ~ % mkdir /tmp/gnupg
bress@computer ~ % chmod 700 /tmp/gnupg
bress@computer ~ % export GNUPGHOME=/tmp/gnupg
|
Then we should generate the keys. Initially we're going to end up with a primary key and an encryption subkey. This is what we want. To generate the key:
bress@computer ~ % gpg --gen-key
|
Choose the option "(1) RSA and RSA (default)". The cryptostick can do a keysize of 3072, obviously use whatever you want, I'd suggest nothing less than 2048.
Once that's done, we can see our key:
bress@computer ~ % gpg --list-keys
/tmp/gnupg/pubring.gpg
----------------------
pub 3072R/B186836A 2012-02-25
uid Test Key <test@example.com>
sub 3072R/AFA38F8E 2012-02-25
|
Generate subkeys
Now we want to generate our signing subkey. As you can see above, my primary key id is B186836A. So we need to issue the command:
bress@computer ~ % gpg --edit-key B186836A
|
At the gpg> prompt, issue the command 'addkey'. We want an 'RSA (sign only)' key. Once you get the gpg> prompt back, type 'save'. Now we can see our new key:
bress@computer ~ % gpg --list-keys
/tmp/gnupg/pubring.gpg
----------------------
pub 3072R/B186836A 2012-02-25
uid Test Key <test@example.com>
sub 3072R/AFA38F8E 2012-02-25
sub 3072R/D8072AAF 2012-02-25
|
At this point you want to backup your /tmp/gnupg directory. Keep this copy safe. It should never ever be used on a network connected computer. Ideally you want to lock it away somewhere nobody can get it. If this directory ever falls into the wrong hands, it's game over for your keys.
Import the keys
Now that the /tmp/gnupg directory is backed up (right), we can put our keys in the card. We're also going to generate the authentication key (we didn't forget about it). Issue the edit-key command again. This time at the gpg> prompt, issue the command 'toggle' to operate on the private keys. Next you want to issue the command 'key 2' probably to select the signing subkey. Your screen should end up looking like this (pay attention to the asterisk)
bress@computer ~ % gpg --edit-key B186836A
gpg (GnuPG) 1.4.11; Copyright (C) 2010 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 3072R/B186836A created: 2012-02-25 expires: never usage: SC
trust: ultimate validity: ultimate
sub 3072R/AFA38F8E created: 2012-02-25 expires: never usage: E
sub 3072R/D8072AAF created: 2012-02-25 expires: never usage: S
[ultimate] (1). Test Key <test@example.com>
gpg> toggle
sec 3072R/B186836A created: 2012-02-25 expires: never
ssb 3072R/AFA38F8E created: 2012-02-25 expires: never
ssb 3072R/D8072AAF created: 2012-02-25 expires: never
(1) Test Key <test@example.com>
gpg> key 2
sec 3072R/B186836A created: 2012-02-25 expires: never
ssb 3072R/AFA38F8E created: 2012-02-25 expires: never
ssb* 3072R/D8072AAF created: 2012-02-25 expires: never
(1) Test Key <test@example.com>
|
Now that the signing subkey is selected, we want to issue the 'keytocard' command. We pick the '(1) Signature key' option. Enter the various passwords and PINs it will prompt you for. Once the operation is done, you should see this:
gpg> keytocard
gpg: detected reader `German Privacy Foundation Crypto Stick v1.2 00 00'
Signature key ....: 0A51 251C 30F0 686D B979 09CF C8D2 DDBB 2464 A219
Encryption key....: E432 D249 0A87 1E14 CA3C A9E7 F04B BB6B 6D5D 0AC8
Authentication key: 11C1 A41C 9891 D703 6F26 F296 DC30 1231 FB1A 5E41
Please select where to store the key:
(1) Signature key
(3) Authentication key
Your selection? 1
gpg: WARNING: such a key has already been stored on the card!
Replace existing key? (y/N) y
You need a passphrase to unlock the secret key for
user: "Test Key <test@example.com>"
3072-bit RSA key, ID D8072AAF, created 2012-02-25
gpg: existing key will be replaced
gpg: 3 Admin PIN attempts remaining before card is permanently locked
Please enter the Admin PIN
sec 3072R/B186836A created: 2012-02-25 expires: never
ssb 3072R/AFA38F8E created: 2012-02-25 expires: never
ssb* 3072R/D8072AAF created: 2012-02-25 expires: never
card-no: 0005 000011BB
(1) Test Key <test@example.com>
gpg>
|
Notice the bit about 'card-no:'. That means the key is now stored on the card. Do the same for the encryption key now (You'll need to use the command 'key 2' to deselect the signing key, then 'key 1' to select the encryption key). Now we should see this:
gpg> keytocard
Signature key ....: 0A51 251C 30F0 686D B979 09CF C8D2 DDBB 2464 A219
Encryption key....: E432 D249 0A87 1E14 CA3C A9E7 F04B BB6B 6D5D 0AC8
Authentication key: 11C1 A41C 9891 D703 6F26 F296 DC30 1231 FB1A 5E41
Please select where to store the key:
(2) Encryption key
Your selection? 2
gpg: WARNING: such a key has already been stored on the card!
Replace existing key? (y/N) y
You need a passphrase to unlock the secret key for
user: "Test Key <test@example.com>"
3072-bit RSA key, ID AFA38F8E, created 2012-02-25
gpg: existing key will be replaced
sec 3072R/B186836A created: 2012-02-25 expires: never
ssb* 3072R/AFA38F8E created: 2012-02-25 expires: never
card-no: 0005 000011BB
ssb 3072R/D8072AAF created: 2012-02-25 expires: never
card-no: 0005 000011BB
(1) Test Key <test@example.com>
gpg>
|
Note the encryption key now has the 'card-no:' tag.
Generate the authentication key
Now it's time to generate an authentication key. We'll do this one in card since we don't really want a backup. I've never been able to generate this key offcard, so it may not even be possible (I've also not tried very hard). Presuming you left off from the previous step and are still at a gpg> prompt, you likely need to issue the 'toggle' command again. Now issue the command 'addcardkey' and select '(3) Authentication key'. The rest of the steps should make sense at this point. Generating a large key will take the cryptostick a long time, be patient. Once it's done running this is what you should see:
gpg> addcardkey
Signature key ....: 0A51 251C 30F0 686D B979 09CF C8D2 DDBB 2464 A219
Encryption key....: E432 D249 0A87 1E14 CA3C A9E7 F04B BB6B 6D5D 0AC8
Authentication key: 11C1 A41C 9891 D703 6F26 F296 DC30 1231 FB1A 5E41
Please select the type of key to generate:
(1) Signature key
(2) Encryption key
(3) Authentication key
Your selection? 3
gpg: WARNING: such a key has already been stored on the card!
Replace existing key? (y/N) y
Please enter the PIN
What keysize do you want for the Authentication key? (3072)
Key is protected.
You need a passphrase to unlock the secret key for
user: "Test Key <test@example.com>"
3072-bit RSA key, ID B186836A, created 2012-02-25
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)
Key does not expire at all
Is this correct? (y/N) y
Really create? (y/N) y
gpg: existing key will be replaced
gpg: please wait while key is being generated ...
gpg: key generation completed (44 seconds)
pub 3072R/B186836A created: 2012-02-25 expires: never usage: SC
trust: ultimate validity: ultimate
sub 3072R/AFA38F8E created: 2012-02-25 expires: never usage: E
sub 3072R/D8072AAF created: 2012-02-25 expires: never usage: S
sub 3072R/E50B666F created: 2012-02-25 expires: never usage: A
[ultimate] (1). Test Key <test@example.com>
|
Just type 'save' at the gpg> prompt, and we're almost done!
Remove the primary key
So at this point, we have a keyring that has the primary private key on disk, and three subkeys in the card. We need to extract the three subkeys, but not the primary key. Obviously we didn't put the primary key on the card, and we have a safe backup (RIGHT!).
First we need to save a copy of the public keys (it will make sense later).
bress@computer ~ % gpg --export -a 'B186836A' > /tmp/public-keys
|
gpg has an option called '--export-secret-subkeys'. We just have to run
bress@computer ~ % gpg --export-secret-subkeys > /tmp/secret-subkeys
|
At this point, you can transfer the public and subkeys to a computer where you plan to do your real gpg work. You could import it into an existing keyring, or start a new one.
bress@computer ~ % gpg --import /tmp/public-keys
gpg: keyring `/tmp/new-gpg/secring.gpg' created
gpg: keyring `/tmp/new-gpg/pubring.gpg' created
gpg: /tmp/new-gpg/trustdb.gpg: trustdb created
gpg: key B186836A: public key "Test Key <test@example.com>" imported
gpg: Total number processed: 1
gpg: imported: 1 (RSA: 1)
bress@computer ~ % gpg --import /tmp/secret-subkeys
gpg: key B186836A: secret key imported
gpg: key B186836A: "Test Key <test@example.com>" not changed
gpg: Total number processed: 1
gpg: unchanged: 1
gpg: secret keys read: 1
gpg: secret keys imported: 1
|
Change your card PIN
If you've not already done so, you need to change your card PINs. There is an admin PIN, and and the key PIN. Issue this command
bress@computer ~ % gpg --card-edit
|
You'll then need to issue 'admin', then 'passwd'. The prompts are pretty clear.
gpg/card> admin
Admin commands are allowed
gpg/card> passwd
gpg: OpenPGP card no. D2760001240102000005000011BB0000 detected
1 - change PIN
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit
Your selection? 1
Please enter the PIN
New PIN
New PIN
PIN changed.
1 - change PIN
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit
Your selection? 3
gpg: 3 Admin PIN attempts remaining before card is permanently locked
Please enter the Admin PIN
New Admin PIN
New Admin PIN
PIN changed.
1 - change PIN
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit
Your selection? q
gpg/card> quit
|
Now you're pretty much set as far as protected keys go. Be sure to keep that backup safe. I'll leave the topic of revocation certificates up to you. There's plenty of information out there and I'd rather you understand how it works than follow a tutorial (it's pretty important stuff).
Don't forget to shred the disk on the computer you did all this work. The last thing you want is your key staying on the disk for a long period of time.
Setup the GnuPG agent
If we use the GnuPG agent, we cal use our authentication key for SSH authentication. This is quite handy as it makes it quite hard for someone to steal your SSH key.
First, run the gpg-agent as such
bress@computer ~ % gpg-agent --enable-ssh-support --daemon
|
The --enable-ssh-support option is key. It's possible your desktop environment tried running a gpg-agent and ssh-agent for you. You may need to unset the GPG_AGENT_INFO, SSH_AUTH_SOCK, and SSH_AGENT_PID environment variables before trying to run gpg-agent yourself.
Now we can extract a SSH public key
bress@computer ~ % gpgkey2ssh E50B666F
ssh-rsa <Lots of key data> COMMENT
|
Add that to your ~/.ssh/authorized_keys file and you're all set (probably change the COMMENT bit to something like 'GPG_TOKEN_KEY').
That's it!
Obviously there's a lot of reasons for the various steps we take to properly handle GPG keys. Most of that information is outside the scope of this tutorial. I encourage you to read up on it and understand how to best handle things like subkeys and smart cards. This is really just meant as an exercise to get things moving along quickly. Try this out a few times before you generate your real keys. Get a feel for what's going on and if you don't understand a step, spend some time reading the documentation. Unfortunately public key cryptography is difficult.
