[[!tag yubikey gpg]]

Introduction
Terminology
Outline
Configure GnuPG
Create new keys
Export secret keys to files, make a backup
Install subkeys on a Yubikey
Use subkey on Yubikey as your SSH key
See also

Introduction

I've written before about using a U2F key with PAM. This post continues the theme and explains how to use a smartcard with GnuPG for storing OpenPGP private keys. Specifically, a Yubikey 4 card, because that's what I have, but any good GnuPG compatible card should work. The Yubikey is both a GnuPG compatible smart card, and a U2F card. The Yubikey 4 can handle keys up to 4096 bits. Older Yubikeys can only handle keys up to 2095 bits.

The reason to do this is to make it harder for an attacker to steal your encryption keys.

I will assume you don't already have an OpenPGP key, or are willing to generate a new one. I will also assume you run Debian stretch; some of the desktop environment setup details may differ between Debian versions or between Linux distributions. You will need:

A Yubikey 4 (or other GnuPG compatible smartcard).
Two USB memory sticks to store master copies of the key you create.
Either a lot of patience, or a ChaosKey or something else to generate a lot of entropy for the kernel. Entropy is used by GnuPG to create encryption keys.

Terminology

Some terminology:

OpenPGP is a standard of encryption keys.
GnuPG (also known as GPG or gpg) is an encryption program that supports OpenPGP.
Encryption key or key pair is a secret and a public key for encryption. Key and key pair are often used as synonyms.
The secret keys is yours, and only you will have it or be able to you use. The public key is public, anyone can have a copy. The two are linked and you can't create a secret key linked to a public key. (If you can, you will become a famous cryptographer. Like Isaac Newton famous among apple growers.)
Master key is the important thing to keep track of. In the encryption world, the master key is what identifies you.
A subkey is a secondary key or key pair for encryption, derived from the master key. Subkeys can be created and revoked almost at will, and there can be any number of them. Subkeys are always associated with a single master key.
Subkeys can be dedicated for encryption, signing, and authentication. You can have one of each.
Encryption is the process of taking a file and making it illegible to everyone except the owner of a secret key. When the public key is used to encrypt, only the secret key can decrypt.
Signing is using a secret key to make a separate file that others can verify using the corresponding public key. This means the signer can "prove" they have the file. For example, you might sign emails to prove they came from you.
Authentication is the process of proving you're you. Typically, for example, a server will know your public key, and will give a large random number encrypted with your public key. Only you have the corresponding secret key, so only you can send the random number back to the server, and thereby the server knows you're you.

Outline

The process outline is:

Create a new, signing-only master key with GnuPG.
Create three "subkeys", one each for encryption, signing, and authentication. These subkeys are what everyone else uses.
Export copies of the master key pair and the subkey pairs and put them in a safe place.
Put the subkeys on the Yubikey.
GnuPG will automatically use the keys from the card. You have to have the card plugged into a USB port for things to work. If someone steals your laptop, they won't get the private subkeys. Even if they steal your Yubikey, they won't get them (the smartcard is physically designed to prevent that), and can't even use them (because there's PIN codes or passphrases and getting them wrong several times locks up the smartcard).
Use gpg-agent as your SSH agent, and the authentication-only subkey on the Yubikey is used as your ssh key.

Configure GnuPG

The process in more detail:

Configure GnuPG with regards to checksum and encryption algorithms. You can use the defaults, but depending on the version of GnuPG you have, they may be weaker than is recommended. These values are from Riseup.net OpenPGP guide, see link at the end.

Add the following lines to ~/.gnupg/gpg.conf:
```
  personal-digest-preferences SHA512
  cert-digest-algo SHA512
  default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
  personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES
  keyserver pool.sks-keyservers.net
```

Create new keys

Create new sign-only master key.

$ gpg --full-generate-key gpg (GnuPG) 2.1.18; Copyright (C) 2017 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? 4 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 = key expires in n days w = key expires in n weeks m = key expires in n months y = key expires in n years Key is valid for? (0) 1y Key expires at Tue 29 May 2018 06:43:54 PM EEST Is this correct? (y/N) y GnuPG needs to construct a user ID to identify your key. Real name: Lars Wirzenius Email address: liw@liw.fi Comment: test key You selected this USER-ID: "Lars Wirzenius (test key) <liw@liw.fi>>" Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o 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: key 25FB738D6EE435F7 marked as ultimately trusted gpg: directory '/home/liw/.gnupg/openpgp-revocs.d' created gpg: revocation certificate stored as '/home/liw/.gnupg/openpgp-revocs.d/A734C10BF2DF39D19DC0F6C025FB738D6EE435F7.rev' public and secret key created and signed. Note that this key cannot be used for encryption. You may want to use the command "--edit-key" to generate a subkey for this purpose. pub rsa4096 2017-05-29 [SC] [expires: 2018-05-29] A734C10BF2DF39D19DC0F6C025FB738D6EE435F7 A734C10BF2DF39D19DC0F6C025FB738D6EE435F7 uid Lars Wirzenius (test key) <liw@liw.fi>

Note that I set a 1-year expiration for they key. The expiration can be extended at any time (if you have the master secret key), but unless you do, the key won't accidentally live longer than the chosen time.
Review the key:

$ gpg --list-secret-keys /home/liw/.gnupg/pubring.kbx ---------------------------- sec rsa4096 2017-05-29 [SC] [expires: 2018-05-29] A734C10BF2DF39D19DC0F6C025FB738D6EE435F7 uid [ultimate] Lars Wirzenius (test key) <liw@liw.fi>

You now have the signing-only master key. You should now create three subkeys (keyid is the key identifier shown in the key listing, A734C10BF2DF39D19DC0F6C025FB738D6EE435F7 above). Use the --expert option to be able to add an authentication-only subkey.

$ gpg --edit-key --expert A734C10BF2DF39D19DC0F6C025FB738D6EE435F7z gpg (GnuPG) 2.1.18; Copyright (C) 2017 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. sec rsa4096/25FB738D6EE435F7 created: 2017-05-29 expires: 2018-05-29 usage: SC trust: ultimate validity: ultimate [ultimate] (1). Lars Wirzenius (test key) <liw@liw.fi> 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) (10) ECC (sign only) (11) ECC (set your own capabilities) (12) ECC (encrypt only) (13) Existing key Your selection? 4 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 = key expires in n days w = key expires in n weeks m = key expires in n months y = key expires in n years Key is valid for? (0) 1y Key expires at Tue 29 May 2018 06:44:52 PM EEST 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. sec rsa4096/25FB738D6EE435F7 created: 2017-05-29 expires: 2018-05-29 usage: SC trust: ultimate validity: ultimate ssb rsa4096/05F88308DFB71774 created: 2017-05-29 expires: 2018-05-29 usage: S [ultimate] (1). Lars Wirzenius (test key) <liw@liw.fi> 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) (10) ECC (sign only) (11) ECC (set your own capabilities) (12) ECC (encrypt only) (13) Existing key Your selection? 6 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 = key expires in n days w = key expires in n weeks m = key expires in n months y = key expires in n years Key is valid for? (0) 1y Key expires at Tue 29 May 2018 06:45:22 PM EEST 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. sec rsa4096/25FB738D6EE435F7 created: 2017-05-29 expires: 2018-05-29 usage: SC trust: ultimate validity: ultimate ssb rsa4096/05F88308DFB71774 created: 2017-05-29 expires: 2018-05-29 usage: S ssb rsa4096/2929E8A96CBA57C7 created: 2017-05-29 expires: 2018-05-29 usage: E [ultimate] (1). Lars Wirzenius (test key) <liw@liw.fi> 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) (10) ECC (sign only) (11) ECC (set your own capabilities) (12) ECC (encrypt only) (13) Existing key Your selection? 8 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? a Possible actions for a RSA key: Sign Encrypt Authenticate Current allowed actions: Sign Encrypt Authenticate (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 Authenticate (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: 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 btween 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 = key expires in n days w = key expires in n weeks m = key expires in n months y = key expires in n years Key is valid for? (0) 1y Key expires at Tue 29 May 2018 06:45:56 PM EEST 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. sec rsa4096/25FB738D6EE435F7 created: 2017-05-29 expires: 2018-05-29 usage: SC trust: ultimate validity: ultimate ssb rsa4096/05F88308DFB71774 created: 2017-05-29 expires: 2018-05-29 usage: S ssb rsa4096/2929E8A96CBA57C7 created: 2017-05-29 expires: 2018-05-29 usage: E ssb rsa4096/4477EB0AEF1C440A created: 2017-05-29 expires: 2018-05-29 usage: A [ultimate] (1). Lars Wirzenius (test key) <liw@liw.fi> gpg> save

Export secret keys to files, make a backup

You now have a master key and three subkeys. They are hidden in the ~/.gnupg directory. It is time to "export" the secret keys out from there.

$ gpg --export-secret-key --armor keyid > master.key $ gpg --export-secret-subkeys --armor keyid > subkeys.key

You should keep these files safe. You don't want to lose them, and you don't want anyone else to get access to them. I recommend you format two USB memory sticks, format them using full-disk encryption, and copy the exported files to both of them. Then keep them somewhere safe.

There's ways of making this part more sophisticated, but that's for another time.
The next step involves some hoop-jumping. What we want is to have the master secret key NOT on you machine, so we tell GnuPG to remove it. We exported it above, so we won't lose it. However, deleting the master secret key also removes the secret subkeys. But we can import those without importing the master secret key.

$ gpg --delete-secret-key keyid $ gpg --import subkeys.key

Now verify that you have the secret subkeys, but not the master key. There should be one line starting with sec# (note the hash mark, which indicates the key isn't available), and three lines starting with ssb (no hash mark).

$ gpg -K /home/liw/.gnupg/pubring.kbx ---------------------------- sec# rsa4096 2017-05-29 [SC] [expires: 2018-05-29] A734C10BF2DF39D19DC0F6C025FB738D6EE435F7 uid [ultimate] Lars Wirzenius (test key) <liw@liw.fi> ssb rsa4096 2017-05-29 [S] [expires: 2018-05-29] ssb rsa4096 2017-05-29 [E] [expires: 2018-05-29] ssb rsa4096 2017-05-29 [A] [expires: 2018-05-29]

Install subkeys on a Yubikey

Now insert the Yubikey in a USB slot. We can start transferring the secret subkeys to the Yubikey. If you want, you can set your name and other information, and change PIN codes. There's several types of PIN codes: normal use, unblocking a locked card, and a third PIN code for admin operations. Changing the PIN codes is a good idea, otherwise everyone will just try the default of 123456 (admin 12345678). However, I'm skipping that in the interest of brevity.

$ gpg -card-edit ...

Actually move the subkeys to the card. Note that this does a move, not a copy, and the subkeys will be removed from your ~/.gnupg (check with gpg -K).

$ gpg --edit-key liw gpg (GnuPG) 2.1.18; Copyright (C) 2017 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 rsa4096/25FB738D6EE435F7 created: 2017-05-29 expires: 2018-05-29 usage: SC trust: ultimate validity: ultimate ssb rsa4096/05F88308DFB71774 created: 2017-05-29 expires: 2018-05-29 usage: S ssb rsa4096/2929E8A96CBA57C7 created: 2017-05-29 expires: 2018-05-29 usage: E ssb rsa4096/4477EB0AEF1C440A created: 2017-05-29 expires: 2018-05-29 usage: A [ultimate] (1). Lars Wirzenius (test key) <liw@liw.fi> gpg> key 1 pub rsa4096/25FB738D6EE435F7 created: 2017-05-29 expires: 2018-05-29 usage: SC trust: ultimate validity: ultimate ssb* rsa4096/05F88308DFB71774 created: 2017-05-29 expires: 2018-05-29 usage: S ssb rsa4096/2929E8A96CBA57C7 created: 2017-05-29 expires: 2018-05-29 usage: E ssb rsa4096/4477EB0AEF1C440A created: 2017-05-29 expires: 2018-05-29 usage: A [ultimate] (1). Lars Wirzenius (test key) <liw@liw.fi> gpg> keytocard Please select where to store the key: (1) Signature key (3) Authentication key Your selection? 1 pub rsa4096/25FB738D6EE435F7 created: 2017-05-29 expires: 2018-05-29 usage: SC trust: ultimate validity: ultimate ssb* rsa4096/05F88308DFB71774 created: 2017-05-29 expires: 2018-05-29 usage: S ssb rsa4096/2929E8A96CBA57C7 created: 2017-05-29 expires: 2018-05-29 usage: E ssb rsa4096/4477EB0AEF1C440A created: 2017-05-29 expires: 2018-05-29 usage: A [ultimate] (1). Lars Wirzenius (test key) <liw@liw.fi> gpg> key 1 pub rsa4096/25FB738D6EE435F7 created: 2017-05-29 expires: 2018-05-29 usage: SC trust: ultimate validity: ultimate ssb rsa4096/05F88308DFB71774 created: 2017-05-29 expires: 2018-05-29 usage: S ssb rsa4096/2929E8A96CBA57C7 created: 2017-05-29 expires: 2018-05-29 usage: E ssb rsa4096/4477EB0AEF1C440A created: 2017-05-29 expires: 2018-05-29 usage: A [ultimate] (1). Lars Wirzenius (test key) <liw@liw.fi> gpg> key 2 pub rsa4096/25FB738D6EE435F7 created: 2017-05-29 expires: 2018-05-29 usage: SC trust: ultimate validity: ultimate ssb rsa4096/05F88308DFB71774 created: 2017-05-29 expires: 2018-05-29 usage: S ssb* rsa4096/2929E8A96CBA57C7 created: 2017-05-29 expires: 2018-05-29 usage: E ssb rsa4096/4477EB0AEF1C440A created: 2017-05-29 expires: 2018-05-29 usage: A [ultimate] (1). Lars Wirzenius (test key) <liw@liw.fi> gpg> keytocard Please select where to store the key: (2) Encryption key Your selection? 2 pub rsa4096/25FB738D6EE435F7 created: 2017-05-29 expires: 2018-05-29 usage: SC trust: ultimate validity: ultimate ssb rsa4096/05F88308DFB71774 created: 2017-05-29 expires: 2018-05-29 usage: S ssb* rsa4096/2929E8A96CBA57C7 created: 2017-05-29 expires: 2018-05-29 usage: E ssb rsa4096/4477EB0AEF1C440A created: 2017-05-29 expires: 2018-05-29 usage: A [ultimate] (1). Lars Wirzenius (test key) <liw@liw.fi> gpg> key 2 pub rsa4096/25FB738D6EE435F7 created: 2017-05-29 expires: 2018-05-29 usage: SC trust: ultimate validity: ultimate ssb rsa4096/05F88308DFB71774 created: 2017-05-29 expires: 2018-05-29 usage: S ssb rsa4096/2929E8A96CBA57C7 created: 2017-05-29 expires: 2018-05-29 usage: E ssb rsa4096/4477EB0AEF1C440A created: 2017-05-29 expires: 2018-05-29 usage: A [ultimate] (1). Lars Wirzenius (test key) <liw@liw.fi> gpg> key 3 pub rsa4096/25FB738D6EE435F7 created: 2017-05-29 expires: 2018-05-29 usage: SC trust: ultimate validity: ultimate ssb rsa4096/05F88308DFB71774 created: 2017-05-29 expires: 2018-05-29 usage: S ssb rsa4096/2929E8A96CBA57C7 created: 2017-05-29 expires: 2018-05-29 usage: E ssb* rsa4096/4477EB0AEF1C440A created: 2017-05-29 expires: 2018-05-29 usage: A [ultimate] (1). Lars Wirzenius (test key) <liw@liw.fi> gpg> keytocard Please select where to store the key: (3) Authentication key Your selection? 3 pub rsa4096/25FB738D6EE435F7 created: 2017-05-29 expires: 2018-05-29 usage: SC trust: ultimate validity: ultimate ssb rsa4096/05F88308DFB71774 created: 2017-05-29 expires: 2018-05-29 usage: S ssb rsa4096/2929E8A96CBA57C7 created: 2017-05-29 expires: 2018-05-29 usage: E ssb* rsa4096/4477EB0AEF1C440A created: 2017-05-29 expires: 2018-05-29 usage: A [ultimate] (1). Lars Wirzenius (test key) <liw@liw.fi> gpg> save

If you want to use several Yubikeys, or have a spare one just in case, repeat the previous four steps (starting from importing subkeys back into ~/.gnupg).
You're now done, as far GnuPG use is concerned. Any time you need to sign, encrypt, or decrypt something, GnuPG will look for your subkeys on the Yubikey, and will tell you to insert it in a USB port if it can't find the key.

Use subkey on Yubikey as your SSH key

To actually use the authentication-only subkey on the Yubikey for ssh, you need to configure your system to use gpg-agent as the SSH agent. Add the following line to .gnupg/gpg-agent.conf:
```
 enable-ssh-support
```
On a Debian stretch system with GNOME, edit /etc/xdg/autostart/gnome-keyring-ssh.desktop to have the following line, to prevent the GNOME ssh agent from starting up:
```
 Hidden=true
```
Edit /etc/X11/Xsession.options and remove or comment out the line that says use-ssh-agent. This stops a system-started ssh-agent from being started when the desktop start.

Create the file ~/.config/autostart/gpg-agent.desktop with the following content:

 [Desktop Entry]
 Type=Application
 Name=gpg-agent
 Comment=gpg-agent
 Exec=/usr/bin/gpg-agent --daemon
 OnlyShowIn=GNOME;Unity;MATE;
 X-GNOME-Autostart-Phase=PreDisplayServer
 X-GNOME-AutoRestart=false
 X-GNOME-Autostart-Notify=true
 X-GNOME-Bugzilla-Bugzilla=GNOME
 X-GNOME-Bugzilla-Product=gnome-keyring
 X-GNOME-Bugzilla-Component=general
 X-GNOME-Bugzilla-Version=3.20.0

To test, log out, and back in again, run the following in a terminal:

$ ssh-add -l

The output should contain a line that looks like this:

    4096 SHA256:PDCzyQPpd9tiWsELM8LwaLBsMDMm42J8/eEfezNgnVc cardno:000604626953 (RSA)

You need to export the authentication-only subkey in the SSH key format. You need this for adding to .ssh/authorized_keys, if nothing else.

$ gpg --export-ssh-key keyid > ssh.pub

Happy hacking.