@ -2,12 +2,8 @@ This is a guide to using [YubiKey](https://www.yubico.com/products/) as a [smart
Keys stored on YubiKey are [non-exportable](https://web.archive.org/web/20201125172759/https://support.yubico.com/hc/en-us/articles/360016614880-Can-I-Duplicate-or-Back-Up-a-YubiKey-), unlike filesystem-based credentials, while remaining convenient for daily use. YubiKey can be configured to require a physical touch for cryptographic operations, reducing the risk of credential compromise.
Keys stored on YubiKey are [non-exportable](https://web.archive.org/web/20201125172759/https://support.yubico.com/hc/en-us/articles/360016614880-Can-I-Duplicate-or-Back-Up-a-YubiKey-), unlike filesystem-based credentials, while remaining convenient for daily use. YubiKey can be configured to require a physical touch for cryptographic operations, reducing the risk of credential compromise.
**Important** If you followed this guide before Jan 2021, *PIN* and *Admin PIN* may be set to default values of `123456` and `12345678`. See [Change PIN](#change-pin) to change PINs.
To suggest an improvement, send a pull request or open an [issue](https://github.com/drduh/YubiKey-Guide/issues).
To suggest an improvement, send a pull request or open an [issue](https://github.com/drduh/YubiKey-Guide/issues).
**Tip** [drduh/Purse](https://github.com/drduh/Purse) is a password manager based on GnuPG and YubiKey to securely store and use credentials.
- [Purchase YubiKey](#purchase-yubikey)
- [Purchase YubiKey](#purchase-yubikey)
- [Prepare environment](#prepare-environment)
- [Prepare environment](#prepare-environment)
* [Improving entropy](#improving-entropy)
* [Improving entropy](#improving-entropy)
@ -63,15 +59,9 @@ To suggest an improvement, send a pull request or open an [issue](https://github
# Purchase YubiKey
# Purchase YubiKey
All YubiKeys except the blue "security key" model and the "Bio Series - FIDO Edition" are compatible with this guide. NEO models are limited to 2048-bit RSA keys.
[Current YubiKeys](https://www.yubico.com/store/compare/) except the FIDO-only Security Key Series and Bio Series YubiKeys are compatible with this guide.
A list of the YubiKeys compatible with OpenPGP is available [here](https://support.yubico.com/hc/en-us/articles/360013790259-Using-Your-YubiKey-with-OpenPGP).
In May 2021, Yubico also released a press release and blog post about supporting resident SSH keys on YubiKey, including blue "security key 5 NFC" with OpenSSH 8.2 or later, see [here](https://www.yubico.com/blog/github-now-supports-ssh-security-keys/) for more information.
[Verify YubiKey](https://support.yubico.com/hc/en-us/articles/360013723419-How-to-Confirm-Your-Yubico-Device-is-Genuine) by visiting [yubico.com/genuine](https://www.yubico.com/genuine/). Select *Verify Device* to begin the process. Touch the YubiKey when prompted and allow the site to see the make and model of the device when prompted. This device attestation may help mitigate [supply chain attacks](https://media.defcon.org/DEF%20CON%2025/DEF%20CON%2025%20presentations/DEF%20CON%2025%20-%20r00killah-and-securelyfitz-Secure-Tokin-and-Doobiekeys.pdf).
To [verify a YubiKey](https://support.yubico.com/hc/en-us/articles/360013723419-How-to-Confirm-Your-Yubico-Device-is-Genuine), visit [yubico.com/genuine](https://www.yubico.com/genuine/). Insert a Yubico device, and select *Verify Device* to begin the process. Touch the YubiKey when prompted, and if asked, allow the site to see the make and model of the device. This device attestation may help mitigate [supply chain attacks](https://media.defcon.org/DEF%20CON%2025/DEF%20CON%2025%20presentations/DEF%20CON%2025%20-%20r00killah-and-securelyfitz-Secure-Tokin-and-Doobiekeys.pdf).
Several portable storage devices (such as microSD cards) for storing encrypted backups are also recommended.
Several portable storage devices (such as microSD cards) for storing encrypted backups are also recommended.
@ -425,9 +415,9 @@ EXPIRATION=2026-05-01
Generate a passphrase, which will be used to issue the Certify key and Subkeys.
Generate a passphrase, which will be used to issue the Certify key and Subkeys.
The passphrase is recommended to consist of only upper case letters and numbers for improved readability. A strong diceware passphrase can also provide equivalent protection.
The passphrase is recommended to consist of only upper case letters and numbers for improved readability. [Diceware](https://secure.research.vt.edu/diceware) is another method for creating strong and memorable passphrases.
The following command will generate a strong 30-character passphrase while avoiding ambiguous characters:
The following command will generate a strong passphrase while avoiding ambiguous characters:
Edit YubiKey with `gpg --edit-card` and the Admin PIN:
```console
gpg/card> admin
gpg/card> url
URL to retrieve public key: hkps://keyserver.ubuntu.com:443/pks/lookup?op=get&search=0xFF00000000000000
gpg/card> quit
```
# Configure YubiKey
# Configure YubiKey
Insert YubiKey and use GnuPG to configure it:
If the card is locked, [Reset](#reset) it.
```console
gpg --card-edit
```
Enter administrative mode:
```console
gpg/card> admin
Admin commands are allowed
```
If the card is locked, use [Reset](#reset).
**Windows** Use the [YubiKey Manager](https://developers.yubico.com/yubikey-manager) application (note, this is not the similarly named older YubiKey NEO Manager) to enable CCID functionality.
**Windows** Use the [YubiKey Manager](https://developers.yubico.com/yubikey-manager) application (note, this is not the similarly named older YubiKey NEO Manager) to enable CCID functionality.
@ -859,34 +801,30 @@ This step must be completed before changing PINs or moving keys or an error will
## Change PIN
## Change PIN
The [PGP interface](https://developers.yubico.com/PGP/) is separate from other modules on YubiKey, such as the [PIV interface](https://developers.yubico.com/PIV/Introduction/YubiKey_and_PIV.html) - the PGP interface has its own *PIN*, *Admin PIN*, and *Reset Code* which must be changed from default values.
YubiKey's PGP interface has its own PINs separate from other modules such as [PIV](https://developers.yubico.com/PIV/Introduction/YubiKey_and_PIV.html):
Entering the *PIN* incorrectly three times will cause the PIN to become blocked. It can be unblocked with either the *Admin PIN* or *Reset Code*.
Name | Default value | Capability
Entering the *Admin PIN* or *Reset Code* incorrectly three times destroys all GnuPG data on the card.
*PIN* values must be at least 6 characters. *Admin PIN* values must be at least 8 characters.
Entering the *PIN* incorrectly 3 times will cause the PIN to become blocked. It can be unblocked with either the *Admin PIN* or *Reset Code*.
**Warning** Entering the *Admin PIN* or *Reset Code* incorrectly 3 times will destroy data on YubiKey.
A maximum of 127 ASCII characters are allowed. See the GnuPG documentation on [Managing PINs](https://www.gnupg.org/howtos/card-howto/en/ch03s02.html) for more information.
Determine the desired PIN values. They can be shorter than the GnuPG identity passphrase due to limited brute-forcing opportunities. The User PIN should be convenient enough to remember for every-day use.
Determine the desired PIN values and set them manually, or generate them randomly:
*PIN* values must be at least 6 characters. *Admin PIN* values must be at least 8 characters. A maximum of 127 ASCII characters are allowed. See the GnuPG documentation on [Managing PINs](https://www.gnupg.org/howtos/card-howto/en/ch03s02.html) for more information.
Set PINs manually or generate them, for example a 6 digit User PIN and 8 digit Admin PIN:
**Note** The number of retry attempts can be changed later with the following command, documented [here](https://docs.yubico.com/software/yubikey/tools/ykman/OpenPGP_Commands.html#ykman-openpgp-access-set-retries-options-pin-retries-reset-code-retries-admin-pin-retries):
Remote and re-insert YubiKey.
**Optional** The number of [retry attempts](https://docs.yubico.com/software/yubikey/tools/ykman/OpenPGP_Commands.html#ykman-openpgp-access-set-retries-options-pin-retries-reset-code-retries-admin-pin-retries) can be changed to 5 with:
```console
```console
ykman openpgp access set-retries 5 5 5 -f -a $ADMIN_PIN
ykman openpgp access set-retries 5 5 5 -f -a $ADMIN_PIN
Set the [smart card attributes](https://gnupg.org/howtos/card-howto/en/smartcard-howto-single.html):
Set the [smart card attributes](https://gnupg.org/howtos/card-howto/en/smartcard-howto-single.html) with `gpg --edit-card` and `admin` mode - use `help` to see available options.
By default, YubiKey will perform cryptographic operations without requiring any action from the user after the key is unlocked once with the PIN.
By default, YubiKey will perform cryptographic operations without requiring any action from the user after the key is unlocked once with the PIN.
To require a touch for each key operation, install [YubiKey Manager](https://developers.yubico.com/yubikey-manager/) and use the Admin PIN to set policy:
To require a touch for each key operation, use [YubiKey Manager](https://developers.yubico.com/yubikey-manager/) and the Admin PIN to set policy:
Encryption:
Encryption:
@ -1241,6 +1187,8 @@ Encryption:
ykman openpgp keys set-touch dec on
ykman openpgp keys set-touch dec on
```
```
**Note** Versions of YubiKey Manager before 5.1.0 use `enc` instead of `dec` for encryption. Older versions of YubiKey Manager use `touch` instead of `set-touch`
Signature:
Signature:
```console
```console
@ -1253,8 +1201,6 @@ Authentication:
ykman openpgp keys set-touch aut on
ykman openpgp keys set-touch aut on
```
```
**Note** Versions of YubiKey Manager before 5.1.0 use `enc` instead of `dec` for encryption. Older versions of YubiKey Manager use `touch` instead of `set-touch`
To view and adjust policy options:
To view and adjust policy options:
```
```
@ -1677,7 +1623,7 @@ Then update the repository URL to `git@github.com:USERNAME/repository`
## GnuPG agent forwarding
## GnuPG agent forwarding
YubiKey can be used sign git commits and decrypt files on remote hosts with GPG Agent Forwarding. To ssh through another network, especially to push to/pull from GitHub using ssh, see [Remote Machines (SSH Agent forwarding)](#remote-machines-ssh-agent-forwarding).
YubiKey can be used sign git commits and decrypt files on remote hosts with GnuPG Agent Forwarding. To ssh through another network, especially to push to/pull from GitHub using ssh, see [Remote Machines (SSH Agent forwarding)](#ssh-agent-forwarding).
`gpg-agent.conf` is not needed on the remote host; after forwarding, remote GnuPG directly communicates with `S.gpg-agent` without starting `gpg-agent` on the remote host.
`gpg-agent.conf` is not needed on the remote host; after forwarding, remote GnuPG directly communicates with `S.gpg-agent` without starting `gpg-agent` on the remote host.
@ -1834,6 +1780,41 @@ Edit the file to enable options `pgp_default_key`, `pgp_sign_as` and `pgp_autosi
**Important** `pinentry-tty` set as the pinentry program in `gpg-agent.conf` is reported to cause problems with Mutt TUI, because it uses curses. It is recommended to use `pinentry-curses` or other graphic pinentry program instead.
**Important** `pinentry-tty` set as the pinentry program in `gpg-agent.conf` is reported to cause problems with Mutt TUI, because it uses curses. It is recommended to use `pinentry-curses` or other graphic pinentry program instead.
## Keyserver
Public keys can be uploaded to a public server for discoverability:
Edit YubiKey with `gpg --edit-card` and the Admin PIN:
```console
gpg/card> admin
gpg/card> url
URL to retrieve public key: hkps://keyserver.ubuntu.com:443/pks/lookup?op=get&search=0xFF00000000000000
gpg/card> quit
```
# Updating keys
# Updating keys
PGP does not provide [forward secrecy](https://en.wikipedia.org/wiki/Forward_secrecy), meaning a compromised key may be used to decrypt all past messages. Although keys stored on YubiKey are more difficult to exploit, it is not impossible: the key and PIN could be physically compromised, or a vulnerability may be discovered in firmware or in the random number generator used to create keys, for example. Therefore, it is recommended practice to rotate Subkeys periodically.
PGP does not provide [forward secrecy](https://en.wikipedia.org/wiki/Forward_secrecy), meaning a compromised key may be used to decrypt all past messages. Although keys stored on YubiKey are more difficult to exploit, it is not impossible: the key and PIN could be physically compromised, or a vulnerability may be discovered in firmware or in the random number generator used to create keys, for example. Therefore, it is recommended practice to rotate Subkeys periodically.