@ -4,7 +4,7 @@ An authentication key can also be created for SSH and used with [gpg-agent](http
Keys stored on a smartcard like YubiKey seem more difficult to steal than ones stored on disk, and are convenient for everyday use.
Instructions written for Debian GNU/Linux 8 (jessie) using YubiKey 4 in OTP+CCID mode. Note, older YubiKeys are limited to 2048 bit RSA keys.
Instructions written for Debian GNU/Linux 8 (jessie) using YubiKey 4 in OTP+CCID mode, updated to GPG version 2.2.1. Some notes are included for macOS as well. Note, older YubiKeys are limited 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.
@ -14,19 +14,19 @@ If you have a comment or suggestion, please open an [issue](https://github.com/d
@ -139,6 +143,15 @@ If on [Tails](https://tails.boum.org/), you also need to install libykpers-1-1 f
$ sudo apt-get install -t testing libykpers-1-1
## Install - macOS
You will need to install the following software:
1. [Homebrew](https://brew.sh/) package manager
2. The following brew packages:
$ brew install gnupg yubikey-personalization
# Creating keys
## Create temporary working directory for GPG
@ -172,9 +185,14 @@ Paste the following [text](https://stackoverflow.com/questions/2500436/how-does-
## Create master key
Generate a new key with GPG, selecting RSA (sign only) and the appropriate keysize, optionally specifying an expiry:
> 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.
$ gpg --gen-key
Generate a new key with GPG, selecting RSA (sign only) and the appropriate keysize:
% 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.
There is NO WARRANTY, to the extent permitted by law.
Please select what kind of key you want:
(1) RSA and RSA (default)
@ -194,10 +212,8 @@ Generate a new key with GPG, selecting RSA (sign only) and the appropriate keysi
Key is valid for? (0) 0
Key does not expire at all
Is this correct? (y/N) y
You need a user ID to identify your key; the software constructs the user ID
from the Real Name, Comment and Email Address in this form:
pub 4096R/0xFF3E7D88647EBCDB created: 2016-05-24 expires: never usage: SC
trust: ultimate validity: ultimate
sec rsa4096/0xEA5DE91459B80592
created: 2017-10-09 expires: never usage: SC
trust: ultimate validity: ultimate
[ultimate] (1). Dr Duh <doc@duh.to>
### Signing key
@ -320,12 +300,11 @@ First, create a [signing key](https://stackoverflow.com/questions/5421107/can-rs
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
...................+++++
..+++++
pub 4096R/0xFF3E7D88647EBCDB created: 2016-05-24 expires: never usage: SC
trust: ultimate validity: ultimate
sub 4096R/0xBECFA3C1AE191D15 created: 2016-05-24 expires: never usage: S
sec rsa4096/0xFF3E7D88647EBCDB
created: 2017-10-09 expires: never usage: SC
trust: ultimate validity: ultimate
ssb rsa4096/0xBECFA3C1AE191D15
created: 2017-10-09 expires: never usage: S
[ultimate] (1). Dr Duh <doc@duh.to>
### Encryption key
@ -333,12 +312,6 @@ First, create a [signing key](https://stackoverflow.com/questions/5421107/can-rs
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
Key is protected.
You need a passphrase to unlock the secret key for
user: "Dr Duh <doc@duh.to>"
4096-bit RSA key, ID 0xFF3E7D88647EBCDB, created 2016-05-24
Please select what kind of key you want:
(3) DSA (sign only)
(4) RSA (sign only)
@ -346,6 +319,10 @@ Next, create an [encryption key](https://www.cs.cornell.edu/courses/cs5430/2015s
(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
@ -365,26 +342,22 @@ Next, create an [encryption key](https://www.cs.cornell.edu/courses/cs5430/2015s
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
.+++++
...........+++++
pub 4096R/0xFF3E7D88647EBCDB created: 2016-05-24 expires: never usage: SC
trust: ultimate validity: ultimate
sub 4096R/0xBECFA3C1AE191D15 created: 2016-05-24 expires: never usage: S
sub 4096R/0x5912A795E90DD2CF created: 2016-05-24 expires: never usage: E
sec rsa4096/0xFF3E7D88647EBCDB
created: 2017-10-09 expires: never usage: SC
trust: ultimate validity: ultimate
ssb rsa4096/0xBECFA3C1AE191D15
created: 2017-10-09 expires: never usage: S
ssb rsa4096/0x5912A795E90DD2CF
created: 2017-10-09 expires: never usage: E
[ultimate] (1). Dr Duh <doc@duh.to>
### Authentication key
Finally, create an [authentication key](https://superuser.com/questions/390265/what-is-a-gpg-with-authenticate-capability-used-for), selecting RSA (set your own capabilities):
Finally, create an [authentication key](https://superuser.com/questions/390265/what-is-a-gpg-with-authenticate-capability-used-for).
gpg> addkey
Key is protected.
You need a passphrase to unlock the secret key for
user: "Dr Duh <doc@duh.to>"
4096-bit RSA key, ID 0xFF3E7D88647EBCDB, created 2016-05-24
GPG doesn't provide a 'RSA (authenticate only)' key type out of the box, so select 'RSA (set your own capabilities)' and toggle the required capabilities to end up with an Authenticate-only key:
gpg> addkey
Please select what kind of key you want:
(3) DSA (sign only)
(4) RSA (sign only)
@ -392,46 +365,50 @@ Finally, create an [authentication key](https://superuser.com/questions/390265/w
(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
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
Your selection? S
Possible actions for a RSA key: Sign Encrypt Authenticate
Current allowed actions: Encrypt
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
Your selection? E
Possible actions for a RSA key: Sign Encrypt Authenticate
Current allowed actions:
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
Your selection? A
Possible actions for a RSA key: Sign Encrypt Authenticate
Current allowed actions: Authenticate
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
@ -451,14 +428,16 @@ Finally, create an [authentication key](https://superuser.com/questions/390265/w
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
+++++
.....+++++
pub 4096R/0xFF3E7D88647EBCDB created: 2016-05-24 expires: never usage: SC
trust: ultimate validity: ultimate
sub 4096R/0xBECFA3C1AE191D15 created: 2016-05-24 expires: never usage: S
sub 4096R/0x5912A795E90DD2CF created: 2016-05-24 expires: never usage: E
sub 4096R/0x3F29127E79649A3D created: 2016-05-24 expires: never usage: A
sec rsa4096/0xFF3E7D88647EBCDB
created: 2017-10-09 expires: never usage: SC
trust: ultimate validity: ultimate
ssb rsa4096/0xBECFA3C1AE191D15
created: 2017-10-09 expires: never usage: S
ssb rsa4096/0x5912A795E90DD2CF
created: 2017-10-09 expires: never usage: E
ssb rsa4096/0x3F29127E79649A3D
created: 2017-10-09 expires: never usage: A
[ultimate] (1). Dr Duh <doc@duh.to>
gpg> save
@ -468,14 +447,14 @@ Finally, create an [authentication key](https://superuser.com/questions/390265/w
The output will display any problems with your key in red text. If everything is green, your key passes each of the tests below. If it is red, your key has failed one of the tests.
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.
>hokey may warn (orange text) about cross certification for the authentication key. GPG's [Signing Subkey Cross-Certification](https://gnupg.org/faq/subkey-cross-certify.html) documentation has more detail on cross certification, and gpg v2.2.1 notes "subkey <keyid> does not sign and so does not need to be cross-certified".
Once keys are moved to hardware, they cannot be extracted again (otherwise, what would be the point?), so make sure you have made an *encrypted* backup before proceeding.
@ -616,6 +603,10 @@ Make sure the correct files were copied, then unmount and disconnected the encry
## Configure YubiKey
YubiKey NEOs shipped after November 2015 have [all modes enabled](https://www.yubico.com/support/knowledge-base/categories/articles/yubikey-neo-manager/), skip to the next step.
Older versions of the YubiKey NEO may need to be reconfigured as a composite USB device (HID + CCID) which allows OTPs to be emitted while in use as a smart card.
Plug in your YubiKey and configure it:
$ ykpersonalize -m82
@ -625,7 +616,7 @@ Plug in your YubiKey and configure it:
Commit? (y/n) [n]: y
> The -m option is the mode command. To see the different modes, enter ykpersonalize –help. Mode 82 (in hex) enables the YubiKey NEO as a composite USB device (HID + CCID) and allows OTPs to be emitted while in use as a smart card. Once you have changed the mode, you need to re-boot the YubiKey – so remove and re-insert it.
> The -m option is the mode command. To see the different modes, enter `ykpersonalize –help`. Mode 82 (in hex) enables the YubiKey NEO as a composite USB device (HID + CCID). Once you have changed the mode, you need to re-boot the YubiKey – so remove and re-insert it.
> On YubiKey NEO with firmware version 3.3 or higher you can enable composite USB device with -m86 instead of -m82.
@ -638,19 +629,18 @@ Use GPG to configure YubiKey as a smartcard:
$ gpg --card-edit
Reader ...........: Yubico Yubikey 4 OTP U2F CCID
Application ID ...: D2760001240102010006055532110000
Version ..........: 2.1
Manufacturer .....: unknown
Manufacturer .....: Yubico
Serial number ....: 05553211
Name of cardholder: [not set]
Language prefs ...: [not set]
Sex ..............: unspecified
URL of public key : [not set]
Login data .......: [not set]
Private DO 1 .....: [not set]
Private DO 2 .....: [not set]
Signature PIN ....: not forced
Key attributes ...: 2048R 2048R 2048R
Key attributes ...: rsa4096 rsa4096 rsa4096
Max. PIN lengths .: 127 127 127
PIN retry counter : 3 3 3
Signature counter : 0
@ -661,7 +651,9 @@ Use GPG to configure YubiKey as a smartcard:
### Change PINs
The default PIN codes are `12345678` and `123456`.
The default PIN codes are `12345678` for the Admin PIN (aka PUK) and `123456` for the PIN. The CCID-mode PINs can be up to 127 ASCII characters long.
The Admin PIN is required for some card operations, and to unblock a PIN that has been entered incorrectly more than three times. See the GnuPG documentation on [Managing PINs](https://www.gnupg.org/howtos/card-howto/en/ch03s02.html) for details.
gpg/card> admin
Admin commands are allowed
@ -684,12 +676,6 @@ The default PIN codes are `12345678` and `123456`.
4 - set the Reset Code
Q - quit
1 - change PIN
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit
Your selection? 1
PIN changed.
@ -741,44 +727,41 @@ Some fields are optional:
## Transfer keys
Transfering keys to YubiKey hardware is a one-way operation only, so make sure you've made a backup before proceeding:
Transferring keys to YubiKey hardware is a one-way operation only, so make sure you've made a backup before proceeding. Previous gpg versions required the 'toggle' command before selecting keys. The currently selected key(s) are indicated with an `*`. When moving keys only one key should be selected at a time.
$ gpg --edit-key $KEYID
% gpg --edit-key $KEYID
Secret key is available.
pub 4096R/0xFF3E7D88647EBCDB created: 2016-05-24 expires: never usage: SC
trust: ultimate validity: ultimate
sub 4096R/0xBECFA3C1AE191D15 created: 2016-05-24 expires: never usage: S
sub 4096R/0x5912A795E90DD2CF created: 2016-05-24 expires: never usage: E
sub 4096R/0x3F29127E79649A3D created: 2016-05-24 expires: never usage: A
sec rsa4096/0xFF3E7D88647EBCDB
created: 2017-10-09 expires: never usage: SC
trust: ultimate validity: ultimate
ssb rsa4096/0xBECFA3C1AE191D15
created: 2017-10-09 expires: never usage: S
ssb rsa4096/0x5912A795E90DD2CF
created: 2017-10-09 expires: never usage: E
ssb rsa4096/0x3F29127E79649A3D
created: 2017-10-09 expires: never usage: A
[ultimate] (1). Dr Duh <doc@duh.to>
gpg> toggle
### Signature key
sec 4096R/0xFF3E7D88647EBCDB created: 2016-05-24 expires: never
ssb 4096R/0xBECFA3C1AE191D15 created: 2016-05-24 expires: never
ssb 4096R/0x5912A795E90DD2CF created: 2016-05-24 expires: never
ssb 4096R/0x3F29127E79649A3D created: 2016-05-24 expires: never
(1) Dr Duh <doc@duh.to>
Select and move the signature key (you will be prompted for the key passphrase and admin PIN):
gpg> key 1
sec 4096R/0xFF3E7D88647EBCDB created: 2016-05-24 expires: never
ssb* 4096R/0xBECFA3C1AE191D15 created: 2016-05-24 expires: never
ssb 4096R/0x5912A795E90DD2CF created: 2016-05-24 expires: never
ssb 4096R/0x3F29127E79649A3D created: 2016-05-24 expires: never
(1) Dr Duh <doc@duh.to>
### Signature key
Move the signature key (you will be prompted for the key passphrase and admin PIN):
sec rsa4096/0xFF3E7D88647EBCDB
created: 2017-10-09 expires: never usage: SC
trust: ultimate validity: ultimate
ssb* rsa4096/0xBECFA3C1AE191D15
created: 2017-10-09 expires: never usage: S
ssb rsa4096/0x5912A795E90DD2CF
created: 2017-10-09 expires: never usage: E
ssb rsa4096/0x3F29127E79649A3D
created: 2017-10-09 expires: never usage: A
[ultimate] (1). Dr Duh <doc@duh.to>
gpg> keytocard
Signature key ....: [none]
Encryption key....: [none]
Authentication key: [none]
Please select where to store the key:
(1) Signature key
(3) Authentication key
@ -788,107 +771,59 @@ Move the signature key (you will be prompted for the key passphrase and admin PI
user: "Dr Duh <doc@duh.to>"
4096-bit RSA key, ID 0xBECFA3C1AE191D15, created 2016-05-24
sec 4096R/0xFF3E7D88647EBCDB created: 2016-05-24 expires: never
ssb* 4096R/0xBECFA3C1AE191D15 created: 2016-05-24 expires: never
card-no: 0006 05553211
ssb 4096R/0x5912A795E90DD2CF created: 2016-05-24 expires: never
ssb 4096R/0x3F29127E79649A3D created: 2016-05-24 expires: never
(1) Dr Duh <doc@duh.to>
### Encryption key
Type `key 1` again to deselect and `key 2` to select the next key:
gpg> key 1
sec 4096R/0xFF3E7D88647EBCDB created: 2016-05-24 expires: never
ssb 4096R/0xBECFA3C1AE191D15 created: 2016-05-24 expires: never
card-no: 0006 05553211
ssb 4096R/0x5912A795E90DD2CF created: 2016-05-24 expires: never
ssb 4096R/0x3F29127E79649A3D created: 2016-05-24 expires: never
(1) Dr Duh <doc@duh.to>
...
gpg> key 2
sec 4096R/0xFF3E7D88647EBCDB created: 2016-05-24 expires: never
ssb 4096R/0xBECFA3C1AE191D15 created: 2016-05-24 expires: never
card-no: 0006 05553211
ssb* 4096R/0x5912A795E90DD2CF created: 2016-05-24 expires: never
ssb 4096R/0x3F29127E79649A3D created: 2016-05-24 expires: never
Unplug and replug the Yubikey. Check the card's status:
$ gpg --card-status
Application ID ...: D2760001240102010006055532110000
@ -1212,13 +1147,18 @@ Paste the following text into a terminal window to create a [recommended](https:
use-standard-socket
EOF
If you are using Linux on the desktop, you may want to use `/usr/bin/pinentry-gnome3` to use a GUI manager.
If you are using Linux on the desktop, you may want to use `/usr/bin/pinentry-gnome3` to use a GUI manager. For macOS, try `brew install pinentry-mac`, and adjust the `pinentry-program` setting to suit.
[gpg-agent](https://wiki.archlinux.org/index.php/GnuPG#SSH_agent) provides OpenSSH agent emulation. To launch the agent for use by ssh use the `gpg-connect-agent /bye` or `gpgconf --launch gpg-agent` commands.
Depending on how your environment is set up, you might need to add these to your shell `rc` file:
@ -1248,6 +1188,19 @@ There is a `-L` option of `ssh-add` that lists public key parameters of all iden
debug1: Authentication succeeded (publickey).
[...]
## Requiring touch to authenticate
By default the Yubikey will perform key operations without requiring a touch from the user. To require a touch for every SSH connection, use the [Yubikey Manager](https://developers.yubico.com/yubikey-manager/) (you'll need the Admin PIN):
ykman openpgp touch aut on
To require a touch for the signing and encrypting keys as well:
ykman openpgp touch sig on
ykman openpgp touch enc on
The Yubikey will blink when it's waiting for the touch.
# Troubleshooting
- If you don't understand some option, read `man gpg`.
@ -1268,6 +1221,10 @@ There is a `-L` option of `ssh-add` that lists public key parameters of all iden
- If you totally screw up, you can [reset the card](https://developers.yubico.com/ykneo-openpgp/ResetApplet.html).
## Yubikey OTP Mode and cccccccc....
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).