This is a practical guide to using [YubiKey](https://www.yubico.com/faq/yubikey/) as a [SmartCard](https://security.stackexchange.com/questions/38924/how-does-storing-gpg-ssh-private-keys-on-smart-cards-compare-to-plain-usb-drives) for storing GPG encryption and signing keys.
This is a guide to using [YubiKey](https://www.yubico.com/faq/yubikey/) as a [SmartCard](https://security.stackexchange.com/questions/38924/how-does-storing-gpg-ssh-private-keys-on-smart-cards-compare-to-plain-usb-drives) for storing GPG encryption and signing keys.
An authentication key can also be created for SSH and used with [gpg-agent](https://unix.stackexchange.com/questions/188668/how-does-gpg-agent-work/188813#188813).
Keys stored on a smartcard like YubiKey are more difficult to steal than ones stored on disk, and are convenient for everyday use.
Keys stored on a smartcard like YubiKey are non-exportable (as opposed to keys that are stored on disk) and are convenient for everyday use. Instead of having to remember and enter passphrases to unlock SSH/GPG keys, YubiKey needs only a physical touch after being unlocked with a PIN code - and all signing and encryption operations happen on the card, rather than in OS memory.
Instructions written for Debian GNU/Linux 8 (jessie) using YubiKey 4 - with support for **4096 bit** RSA keys - in OTP+CCID mode, updated to GPG version 2.2.1. Some notes are included for macOS as well. Note, older YubiKeys like the Neo are limited to **2048 bit** RSA keys. Please see a comparison of the different YubiKeys [here](https://www.yubico.com/products/yubikey-hardware/compare-yubikeys/).
Debian live install images are available from [here](https://www.debian.org/CD/live/) and are suitable for writing to USB drives.
These instructions are current to Debian 9 using YubiKey 4 - with support for **4096 bit** RSA keys - in OTP+CCID mode, using GPG version 2.2. Note, older YubiKeys like the Neo are [limited](https://www.yubico.com/products/yubikey-hardware/compare-yubikeys/) to **2048 bit** RSA keys. Debian live install images are available from [here](https://www.debian.org/CD/live/) and are suitable for writing to USB drives.
Programming YubiKey for GPG keys still lets you use its two slots - [OTP](https://www.yubico.com/faq/what-is-a-one-time-password-otp/) and [static password](https://www.yubico.com/products/services-software/personalization-tools/static-password/) modes, for example.
@ -75,7 +73,7 @@ If you have a comment or suggestion, please open an [issue](https://github.com/d
https://www.yubico.com/products/yubikey-hardware/
Consider purchasing a pair and programming both in case of loss or damage to one of them.
Consider purchasing a pair (or more) and programming both in case of loss or damage to one of them.
# 2. Install required software
@ -86,45 +84,43 @@ You will need to install the following software:
You may also need to download and install more recent versions of [yubikey-personalization](https://developers.yubico.com/yubikey-personalization/Releases/) and [yubico-c](https://developers.yubico.com/yubico-c/Releases/):
gpg: assuming signed data in `libyubikey-1.13.tar.gz'
gpg: Signature made Thu 05 Mar 2015 11:51:51 AM UTC
gpg: assuming signed data in 'libyubikey-1.13.tar.gz'
gpg: Signature made Thu Mar 5 03:51:51 2015 PST
gpg: using RSA key 0xBCA00FD4B2168C0A
gpg: Good signature from "Klas Lindfors <klas@yubico.com>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
@ -139,24 +135,27 @@ You may also need to download and install more recent versions of [yubikey-perso
$ cd ..
$ tar xf ykpers-1.17.3.tar.gz
$ tar xf ykpers-1.19.0.tar.gz
$ cd ykpers-1.17.3
$ cd ykpers-1.19.0
$ ./configure && make && sudo make install
$ sudo ldconfig
```
If on [Tails](https://tails.boum.org/), you also need to install libykpers-1-1 from the testing repository. This is a temporary fix suggested on a [securedrop issue](https://github.com/freedomofpress/securedrop/issues/1035):
If on [Tails](https://tails.boum.org/), you also need to install `libykpers-1-1` from the testing repository. This is a temporary fix suggested on a [securedrop issue](https://github.com/freedomofpress/securedrop/issues/1035):
```
$ sudo apt-get install -t testing libykpers-1-1
$ sudo apt-get install -t testing libykpers-1-1
```
## 2.2 Install - macOS
You will need to install [Homebrew](https://brew.sh/) and the following brew packages:
@ -171,32 +170,34 @@ Skip to [3.3](#3.3-create-master-key)
## 3.1 Create temporary working directory for GPG
Create a directory in `/tmp` which won't survive a [reboot](https://serverfault.com/questions/377348/when-does-tmp-get-cleared):
```
$ export GNUPGHOME=$(mktemp -d) ; echo $GNUPGHOME
/tmp/tmp.aaiTTovYgo
$ export GNUPGHOME=$(mktemp -d) ; echo $GNUPGHOME
/tmp/tmp.aaiTTovYgo
```
## 3.2 Create configuration
Paste the following [text](https://stackoverflow.com/questions/2500436/how-does-cat-eof-work-in-bash) into a terminal window to create a [recommended](https://github.com/drduh/config/blob/master/gpg.conf) GPG configuration:
@ -206,7 +207,7 @@ Paste the following [text](https://stackoverflow.com/questions/2500436/how-does-
> A note on key expiry: setting an expiry essentially forces you to manage your subkeys and announces to the rest of the world that you are doing so. Setting an expiry on a primary key is ineffective for protecting the key from loss - whoever has the primary key can simply extend its expiry period. Revocation certificates are [better suited](https://security.stackexchange.com/questions/14718/does-openpgp-key-expiration-add-to-security/79386#79386) for this purpose. It may be appropriate for your use case to set expiry dates on subkeys.
Generate a new key with GPG, selecting RSA (sign only) and the appropriate key-size:
```
% gpg --full-generate-key
gpg (GnuPG) 2.2.1; Copyright (C) 2017 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
@ -266,15 +267,17 @@ Note that as of [v2.1](https://www.gnupg.org/faq/whats-new-in-2.1.html#autorev),
### 3.4 Save Key ID
Export the key ID as a [variable](https://stackoverflow.com/questions/1158091/defining-a-variable-with-or-without-export/1158231#1158231) for use throughout:
```
$ export KEYID=0xFF3E7D88647EBCDB
$ export KEYID=0xFF3E7D88647EBCDB
```
### 3.5 Create subkeys
Note: If using a Yubikey 4, please use **4096 bit** as the size for the subkeys; if using a YubiKey Neo, please use **2048 bit** as the size for the subkeys.
Edit the key to add subkeys:
```
$ gpg --expert --edit-key $KEYID
Secret key is available.
@ -288,7 +291,7 @@ Edit the key to add subkeys:
### 3.5a Signing key
First, create a [signing key](https://stackoverflow.com/questions/5421107/can-rsa-be-both-used-as-encryption-and-signature/5432623#5432623), selecting RSA (sign only):
```
gpg> addkey
Key is protected.
@ -329,11 +332,10 @@ First, create a [signing key](https://stackoverflow.com/questions/5421107/can-rs
created: 2017-10-09 expires: never usage: S
[ultimate] (1). Dr Duh <doc@duh.to>
### 3.5b Encryption key
Next, create an [encryption key](https://www.cs.cornell.edu/courses/cs5430/2015sp/notes/rsa_sign_vs_dec.php), selecting RSA (encrypt only):
```
gpg> addkey
Please select what kind of key you want:
(3) DSA (sign only)
@ -480,13 +482,14 @@ List your new secret keys:
ssb rsa4096/0x5912A795E90DD2CF 2017-10-09 [E]
ssb rsa4096/0x3F29127E79649A3D 2017-10-09 [A]
Verify with OpenPGP key checks:
If you're on Linux or macOS, use the automated [key best practice checker](https://riseup.net/en/security/message-security/openpgp/best-practices#openpgp-key-checks):
$ sudo apt-get install hopenpgp-tools
$ gpg --export $KEYID | hokey lint
```
$ sudo apt-get install hopenpgp-tools
$ gpg --export $KEYID | hokey lint
```
The output will display any problems with your key in red text. If everything is green, your key passes each of the tests. If it is red, your key has failed one of the tests.
@ -498,8 +501,10 @@ The output will display any problems with your key in red text. If everything is
Please note that using any extension other than .gpg or attempting IO redirection to a file will garble your secret key, making it impossible to import it again at a later date.
@ -795,7 +802,6 @@ Previous gpg versions required the `toggle` command before selecting keys. The c
created: 2017-10-09 expires: never usage: A
[ultimate] (1). Dr Duh <doc@duh.to>
### 3.11a Signature key
Select and move the signature key (you will be prompted for the key passphrase and admin PIN):
@ -823,7 +829,6 @@ Select and move the signature key (you will be prompted for the key passphrase a
user: "Dr Duh <doc@duh.to>"
4096-bit RSA key, ID 0xBECFA3C1AE191D15, created 2016-05-24
### 3.11b Encryption key
Type `key 1` again to deselect and `key 2` to select the next key:
@ -849,7 +854,6 @@ Type `key 1` again to deselect and `key 2` to select the next key:
Your selection? 2
...
### 3.11c Authentication key
Type `key 2` again to deselect and `key 3` to select the next key:
@ -869,8 +873,6 @@ Type `key 2` again to deselect and `key 3` to select the next key:
created: 2017-10-09 expires: never usage: A
[ultimate] (1). Dr Duh <doc@duh.to>
gpg> keytocard
Please select where to store the key:
(3) Authentication key
@ -1188,19 +1190,6 @@ Verify the previous signature:
There is a `-L` option of `ssh-add` that lists public key parameters of all identities currently represented by the agent. Copy and paste the following output to the server authorized_keys file:
@ -1377,30 +1368,19 @@ On OpenBSD, you will need to install `pcsc-tools` and enable with `sudo rcctl en
The Yubikey has two configurations, one invoked with a short press, and the other with a long press. By default the short-press mode is configured for HID OTP - a brief touch will emit an OTP string starting with `cccccccc`. If you rarely use the OTP mode, you can swap it to the second configuration via the Yubikey Personalization tool. If you *never* use OTP, you can disable it entirely using the [Yubikey Manager](https://developers.yubico.com/yubikey-manager) application (note, this not the similarly named Yubikey NEO Manager).
drduh
6 years ago
committed by