--- date: 2018-09-04 tags: Security YubiKey PGP GPG description: > An introduction to decent security using the Yubikey as your physical security card. --- = Setting up PGP with a Yubikey :toc: preamble I've recently started a job where I am required to have above-average security practices in place on my machine. I already had some standard security in place, such as full disk encryption and PGP encrypted email, but I thought that this would be a good time to up my game. To accomplish this, I purchased a Yubikey to act as my physical security token. Additionally, I have a USB device which is also encrypted to hold backups of the keys. In this blogpost, I will detail how I set up my security policies in the hopes it will be able to help out other people looking to improve their security, and to get feedback to improve my set up as well. [NOTE] ==== I am using the Yubikey 4. If you're using another version, some steps may differ. ==== == Installing required software You'll need some software to set all of this up. Depending on your distribution, some of it might already be installed. Everything not installed yet should be installed with your distribution's package manager. For encrypting the disk and the USB key, you will need `cryptsetup`. To generate and use the PGP keys, you will need `gpg`, at least version 2.0.12. To interface with the Yubikey itself, you'll need `pcsc-lite`, and start the service as well. It may be necessary to restart the `gpg-agent` after installing `pcsc-lite`, which you can do by simply killing the existing `gpg-agent` process. It restarts itself when needed. To securely remove the temporary data we need, you should make sure you have `secure-delete` available on your system as well. == Personalizing the Yubikey The Yubikey can be personalized. Some of this personalization is completely optional, such as setting personal information. However, setting new PIN codes is strongly advised, as the default values are publicly known. === PIN codes The PIN codes are short combinations of numbers, letters and symbols to grant permission to write to or retrieve data from the Yubikey. The default value for the user PIN is `123456`. The admin PIN is `12345678` by default. These should be changed, as they're publicly known and allow the usage of your private keys. To change these, use the `gpg` program and enter admin mode: [source] ---- gpg --card-edit gpg/card> admin Admin commands are allowed ---- You'll notice it immediately says that admin commands are now allowed to be used. The admin PIN (`12345678`) will be asked whenever an admin command is executed. It will then be stored for this session, so you won't have to enter it right away. To update the PIN values, run the following commands: [source] ---- gpg/card> passwd gpg/card> 3 ---- This will change the admin PIN first. This PIN is required for managing the keys and user PIN on the Yubikey. To set the user PIN, pick `1` instead of `3`: [source] ---- gpg/card> 1 ---- Once this is done, you can quit the `passwd` submenu using `q`: [source] ---- gpg/card> q ---- You may have noticed we skipped the reset code. Resetting the device will wipe existing keys, so it's not a serious risk to keep this at the default. The private keys will be backed up to an encrypted USB drive, so we can always retrieve them and put them back on the Yubikey if ever needed. === Personal information The personal information is optional, but could be used by a friendly person to find out who a found Yubikey belongs to. They can contact the owner, and send the key back. You can set as many of the personally identifying fields as you want. If you're interested in setting this information, plug in your Yubikey and edit the card information with `gpg`: [source] ---- gpg --card-edit ---- Once you're back in the GPG shell, you can update your personal information. There are 5 attributes that you can set in this way: - `name`, which is your real name; - `lang`, which is your preferred contact language; - `sex`, which is your real sex; - `url`, which indicates a location to retrieve your public key from; - `login`, which indicates your email address. Each of these attributes can be updated by running the command in the GPG shell. For instance, to update your real name, run the following: [source] ---- gpg/card> name ---- You do not need to explicitly save once you're done. You can run `quit` to quit the GPG shell and return to your regular shell. == Creating PGP keys To create the PGP keys, we'll create a temporary directory which will function as our working directory to store the keys in. This way you can't accidentally break existing keys if you have them, and ensure that the private keys don't accidentally linger on in your filesystem. === Preparing a clean environment To create such a temporary directory, we'll use `mktemp`, and store the result in an environment variable so we can easily re-use it: [source,sh] ---- export GNUPGHOME="$(mktemp -d)" ---- Now you can switch to that directory using `cd "$GNUPGHOME"`. Additionally, `$GNUPGHOME` is also the directory `gpg` uses as its working directory, if it is set. This means you can use a temporary custom configuration for `gpg` as well, without it affecting your normal setup. The following configuration is recommended to set in `$GNUPGHOME/gpg.conf` before starting: [source,conf] ---- use-agent charset utf-8 no-comments keyid-format 0xlong list-options show-uid-validity verify-options show-uid-validity with-fingerprint ---- If you have a `gpg-agent` running, it is recommended to stop it before continuing with `killall gpg-agent`. === Creating the master key For our master key, we'll go for a 4096 bytes RSA key. 2048 would be plenty as well, if you want the generation to be a tad quicker. `gpg` will ask you a couple questions to establish your identity, which is required for a PGP key. You can add more identities later, in case you're using multiple email addresses, for instance. Start the key generation process with `gpg`: [source] ---- gpg --full-generate-key ---- When asked what kind of key you want, choose `4` (RSA (sign only)). Next is the key size, which should be `4096`. The key's expiration is optional, though highly recommended. It will be more effort to maintain the keys, as you'll occasionally need the private master keys to extend the validity, but you can also guarantee that your keys won't stay valid in case you ever lose them. If you don't want to bother with refreshing your keys from time to time, just press enter here to continue. When prompted on whether the data is correct, doublecheck whether the data is really correct, and then enter `y` and press enter to accept the current values. `gpg` will continue with your identity information, which you should fill out with your real information. The comment field can be left empty, this is an optional field to add a comment to your identity, such as "School", or "Work keys". `gpg` will ask your confirmation one final time. Enter an `o` (it's not case sensitive) and press enter again. The final step before it will generate a key is to enter a passphrase. This is technically optional, but highly recommended. If anyone ever gets their hands on your private master key, they will need the passphrase in order to use it. Adding one is yet another layer against malicious use of your key. Once you've chosen a passphrase, it will generate they key and output some information about the key. Verify whether this information is correct one more time, and if it is, you can continue to the next step. If it is not, redo the whole PGP section of this post. Take note of the line starting with `pub`. It shows that the key is an `rsa4096` key, followed by a `/`, and then the key ID. You'll need this key ID throughout the rest of this post. For convenience, you can store this ID in a variable, and just refer to the variable when you need it's value again: [source,sh] ---- export KEYID=0x27F53A16486878C7 ---- This post will use the `$KEYID` variable from now on, to make it easier to follow. === Creating a revocation certificate The revocation certificate can be used to invalidate your newly created key. You should store it seperately from the private master key, preferably printed on a sheet of paper. If you want to be able to easily read it back in, consider printing it as a QR code. To create the certificate, run the following: [source] ---- gpg --gen-revoke $KEYID > $GNUPGHOME/revoke.txt ---- This will prompt you to specify a reason, for which you'll want to use `1`. This way you can easily revoke the key's validity if you ever lose it. If you want to revoke your keys in the future for any other reason, you can always generate a new revocation certificate for that specific purpose. You don't have to supply an additional description, so just hit enter. A revocation certificate will be written to `$GNUPGHOME/revoke.txt`. === Creating the subkeys Now that you have your master key and the ability to revoke it in case anything goes wrong in the future, it's time to create a couple of subkeys which can be stored on the Yubikey, and used in your daily life. We'll create seperate keys for _encryption_, _signing_ and _authentication_, and store each of them in their own dedicated slot on the Yubikey. To add subkeys to your master key, enter a GPG shell to edit your existing key with `gpg --expert --edit-key $KEYID`. The `--expert` is required to show all the options we're going to need. Once the GPG shell has started, run `addkey` to add a new key. Just like with the master key, a number of questions will be asked. Expiration for subkeys is generally not advised, as the subkeys will be considered invalid whenever the master key has expired. The key sizes for the subkeys can be left at 2048 as well, which is also the maximum size for keys for the older Yubikey models. The key type is different for all 3 subkeys. You will want to select type `4` (RSA (sign only)) for your signing key, type `6` (RSA (encrypt only)) for the encryption key, and type `8` (RSA (set your own capabilities)) for the authentication key. With the final key, it will ask you what capabilities you want to enable. The only capability you want it to have is *Authentication*. Once you've created the subkeys, you can check `gpg --list-secret-keys` to look at your newly created keys. You should have 1 `sec` key, which is the master key, and 3 `ssb` keys, which are the subkeys. One line should end with `[S]`, one with `[E]` and one with `[A]`. These denote the capabilities of the subkeys, _Sign_, _Encrypt_ and _Authenticate_, respectively. === Export the keys Now that you have your keys generated, you should export them, allowing you to easily import them in another environment in case you ever need to generate more keys, invalidate some keys, or extend the validity of the keys in case you set an expiry date. This can be done with the following commands: [source,sh] ---- gpg --armor --export-secret-keys $KEYID > masterkey.asc gpg --armor --export-secret-subkeys $KEYID > subkeys.asc ---- == Creating a backup USB For the backup of the private keys, I'm using an encrypted USB device. You can also opt to print the keys to paper, and retype them if you ever need them. Or print a QR code that you can scan. But for convenience sake, I went with a USB device. I encrypted it, and stored it in a safe and sealed location, so it's easy to detect unwanted attempted access. === Encrypting the USB For the encryption, I went with full device encryption using LUKS. You will need the `cryptsetup` utility to apply the encryption, and to unlock the drive. You can find out the device name from `dmesg` or `lsblk`. Once you know it, encrypt the drive with the `luksFormat` subcommand. [WARNING] ==== Using the wrong name for the device can irrecoverably destroy data from another drive! ==== [source,sh] ---- cryptsetup luksFormat /dev/sdb ---- It will prompt you whether you want to continue, and ask twice for a passphrase to ensure it is correct. Make sure you don't forget the passphrase, or you'll lose access to your backup keys. Once it has been encrypted, unlock the device. [source,sh] ---- cryptsetup luksOpen /dev/sdb crypt ---- This will open the device as `/dev/mapper/crypt`. Format it with your favourite filesystem. I used `ext4`. [source,sh] ---- mkfs.ext4 /dev/mapper/crypt ---- Once it has been formatted, you can mount it as a regular device. [source,sh] ---- mount /dev/mapper/crypt /mnt/usb ---- === Copying the keys Copying the keys is as straightforward as copying other files. You can use `$GNUPGHOME` to target the source directory. [source,sh] ---- cp -arv "$GNUPGHOME"/* /mnt/usb/. ---- Once the files are copied, you can unmount the drive, lock it and unplug the USB. [source,sh] ---- sync umount /mnt/usb cryptsetup luksClose crypt ---- Store the USB in a safe location, because these private keys can give someone full control of your identity. == Storing the private keys on the Yubikey The Yubikey has key slots for encryption, signing and authentication. These need to be set individually, which can be done using `gpg`. First, you need to select a key using the `key` command, then store it on the card using `keytocard` and select a slot to store it in, then finally deselect the key by using the `key` command again. [source] ---- gpg --edit-key $KEYID gpg> key 1 gpg> keytocard Your selection? 1 gpg> key 1 gpg> key 2 gpg> keytocard Your selection? 2 gpg> key 2 gpg> key 3 gpg> keytocard Your selection? 3 gpg> save ---- You can verify whether the keys are available on the Yubikey now using `gpg --card-status`. It will show the key fingerprints for the `Signature key`, `Encryption key` and `Authentication key`. === Sharing your public key You can share your public keys in many ways. Mine is hosted link:/pubkey.txt[on my own site], for instance. There are also https://sks-keyservers.net/[public keyservers] on which you can upload your keys. `gpg` has the `--send-keys` and `--recv-keys` switches to interact with these public keyservers. For ease of use, I would recommend uploading them to a public keyserver, so that other people can easily import it. For instance, my key can be imported using `gpg`: [source] ---- gpg --recv-keys 0x7A6AC285E2D98827 ---- == Clean up The keys are on the Yubikey, and you probably do not want to leave traces on your local system of these new keys, so you should clean up the `$GNUPGHOME` directory. There's a utility for securely removing a directory with all its contents, called `secure-delete`, which provides the `srm` program. You can use it just like the regular `rm` on the temporary directory. [source,sh] ---- srm -r "$GNUPGHOME" ---- You can also `unset` the `$GNUPGHOME` variable at this point, so `gpg` will use it's default configuration again. [source,sh] ---- unset GNUPGHOME ---- == Configure GPG Finally, you have your keys on the Yubikey and the traces that might have been left on your device are wiped clean. Now you should configure `gpg` for regular use as well, however, this is completely optional. All this configuration does is ensure you have good defaults for the current day and age. [source] ---- auto-key-locate keyserver keyserver hkps://hkps.pool.sks-keyservers.net keyserver-options no-honor-keyserver-url personal-cipher-preferences AES256 AES192 AES CAST5 personal-digest-preferences SHA512 SHA384 SHA256 SHA224 default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed cert-digest-algo SHA512 s2k-cipher-algo AES256 s2k-digest-algo SHA512 charset utf-8 fixed-list-mode no-comments no-emit-version keyid-format 0xlong list-options show-uid-validity verify-options show-uid-validity with-fingerprint use-agent require-cross-certification ---- == Conclusion You now have PGP keys available on your Yubikey. These keys are only available to your system if the Yubikey is inserted, and the user PIN is given. You can use these keys for authentication, signing and encrypting/decrypting messages. In a future post, I'll detail how to set up a number of services to use these keys as well.