knowledge/YubiKey-Guide
1
0
Fork 0
mirror of https://github.com/drduh/YubiKey-Guide.git synced 2024-11-10 23:00:56 +00:00
Code Issues Releases Activity

Compare commits

base: knowledge:ac8ff82085170a165dba8edf89ea011d171377b6
Branches Tags
knowledge:master
..
compare: knowledge:a1081d20acd6d122303debf0df67ca60dba21a7f
Branches Tags
knowledge:master

No commits in common. "ac8ff82085170a165dba8edf89ea011d171377b6" and "a1081d20acd6d122303debf0df67ca60dba21a7f" have entirely different histories.
ac8ff82085 ... a1081d20ac

2 changed files with 111 additions and 104 deletions
Show Stats Expand all files Collapse all files

201
README.md
View File

@ -2,8 +2,12 @@ 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.
**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).
**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)
- [Prepare environment](#prepare-environment)
* [Improving entropy](#improving-entropy)
@ -59,9 +63,15 @@ To suggest an improvement, send a pull request or open an [issue](https://github
# Purchase YubiKey
[Current YubiKeys](https://www.yubico.com/store/compare/) except the FIDO-only Security Key Series and Bio Series YubiKeys are compatible with this guide.
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.
[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).
Compare YubiKeys [here](https://www.yubico.com/products/yubikey-hardware/compare-products-series/).
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.
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.
@ -415,9 +425,9 @@ EXPIRATION=2026-05-01
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. [Diceware](https://secure.research.vt.edu/diceware) is another method for creating strong and memorable passphrases.
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 following command will generate a strong passphrase while avoiding ambiguous characters:
The following command will generate a strong 30-character passphrase while avoiding ambiguous characters:
```console
PASS=$(LC_ALL=C tr -dc 'A-Z1-9' < /dev/urandom | \
@ -775,9 +785,57 @@ gpg --armor --export $KEYID | doas tee /mnt/public/$KEYID-$(date +%F).asc
gpg -o \path\to\dir\pubkey.gpg --armor --export $KEYID
```
**Keyserver**
**Optional** Upload the public key to a keyserver:
```console
gpg --send-key $KEYID
gpg --keyserver keys.gnupg.net --send-key $KEYID
gpg --keyserver hkps://keyserver.ubuntu.com:443 --send-key $KEYID
```
Or if [uploading to keys.openpgp.org](https://keys.openpgp.org/about/usage):
```console
gpg --send-key $KEYID | curl -T - https://keys.openpgp.org
```
The public key URL can also be added to YubiKey (based on [Shaw 2003](https://datatracker.ietf.org/doc/html/draft-shaw-openpgp-hkp-00)):
```console
URL="hkps://keyserver.ubuntu.com:443/pks/lookup?op=get&search=${KEYID}"
```
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
If the card is locked, [Reset](#reset) it.
Insert YubiKey and use GnuPG to configure 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.
@ -801,30 +859,34 @@ This step must be completed before changing PINs or moving keys or an error will
## Change PIN
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):
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.
Name | Default value | Capability
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*.
Entering the *Admin PIN* or *Reset Code* incorrectly three times destroys all GnuPG data on the card.
Name | Default Value | Capability
-----------|---------------|-------------------------------------------------------------
User PIN | `123456` | cryptographic operations (decrypt, sign, authenticate)
PIN | `123456` | cryptographic operations (decrypt, sign, authenticate)
Admin PIN | `12345678` | reset PIN, change Reset Code, add keys and owner information
Reset Code | None | reset PIN ([more information](https://forum.yubico.com/viewtopicd01c.html?p=9055#p9055))
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*.
*PIN* values must be at least 6 characters. *Admin PIN* values must be at least 8 characters.
**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.
*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:
Determine the desired PIN values and set them manually, or generate them randomly:
```console
ADMIN_PIN=$(LC_ALL=C tr -dc '0-9' < /dev/urandom | fold -w8 | head -1)
ADMIN_PIN=$(LC_ALL=C tr -dc '0-9' < /dev/urandom | \
fold -w 30 | sed "-es/./ /"{1..26..5} | \
cut -c2- | tr " " "-" | head -1)
USER_PIN=$(LC_ALL=C tr -dc '0-9' < /dev/urandom | fold -w6 | head -1)
USER_PIN=$(LC_ALL=C tr -dc '0-9' < /dev/urandom | \
fold -w 15 | sed "-es/./ /"{1..26..5} | \
cut -c2- | tr " " "-" | head -1)
echo "\nAdmin PIN: $ADMIN_PIN\nUser PIN: $USER_PIN"
echo "Admin PIN: $ADMIN_PIN\nUser PIN: $USER_PIN"
```
Update the admin PIN:
@ -851,9 +913,7 @@ q
EOF
```
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:
**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):
```console
ykman openpgp access set-retries 5 5 5 -f -a $ADMIN_PIN
@ -861,9 +921,7 @@ ykman openpgp access set-retries 5 5 5 -f -a $ADMIN_PIN
## Set attributes
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.
Or use predetermined values:
Set the [smart card attributes](https://gnupg.org/howtos/card-howto/en/smartcard-howto-single.html):
```console
gpg --command-fd=0 --pinentry-mode=loopback --edit-card <<EOF
@ -933,7 +991,7 @@ EOF
# Verify transfer
Verify Subkeys have been moved to YubiKey with `gpg -K` and look for `ssb>`, for example:
To Verify Subkeys have been moved to YubiKey, look for `ssb>` with `gpg -K`, for example:
```console
sec rsa4096/0xF0F2CFEB04341FB5 2024-01-01 [C]
@ -1035,21 +1093,23 @@ gpg/card> fetch
gpg/card> quit
```
Determine the key ID:
Edit the Certify key:
```console
KEYID=0xF0F2CFEB04341FB5
gpg --edit-key $KEYID
```
Assign ultimate trust by typing `trust` and selecting option `5` then `quit`:
```console
gpg --command-fd=0 --pinentry-mode=loopback --edit-key $KEYID <<EOF
trust
5
y
save
EOF
gpg> trust
Your decision? 5
Do you really want to set this key to ultimate trust? (y/N) y
gpg> quit
```
Remove and re-insert YubiKey.
@ -1099,8 +1159,7 @@ ssb> rsa4096/0xAD9E24E1B8CB9600 created: 2024-01-01 expires: 2026-01-01
Encrypt a message to yourself (useful for storing credentials or protecting backups):
```console
echo "\ntest message string" | \
gpg --encrypt --armor --recipient $KEYID -o encrypted.txt
echo "test message string" | gpg --encrypt --armor --recipient $KEYID -o encrypted.txt
```
To encrypt to multiple recipients or keys (the preferred key ID goes last):
@ -1112,25 +1171,27 @@ echo "test message string" | \
-o encrypted.txt
```
Decrypt the message - a User PIN prompt will appear:
Decrypt the message:
```console
gpg --decrypt --armor encrypted.txt
$ gpg --decrypt --armor encrypted.txt
gpg: anonymous recipient; trying secret key 0x0000000000000000 ...
gpg: okay, we are the anonymous recipient.
gpg: encrypted with RSA key, ID 0x0000000000000000
test message string
```
Use a [shell function](https://github.com/drduh/config/blob/master/zshrc) to make encrypting files easier:
```console
secret () {
output=~/"${1}".$(date +%s).enc
gpg --encrypt --armor --output ${output} \
-r $KEYID "${1}" && echo "${1} -> ${output}"
output=~/"${1}".$(date +%s).enc
gpg --encrypt --armor --output ${output} -r 0x0000 -r 0x0001 -r 0x0002 "${1}" && echo "${1} -> ${output}"
}
reveal () {
output=$(echo "${1}" | rev | cut -c16- | rev)
gpg --decrypt --output ${output} "${1}" && \
echo "${1} -> ${output}"
output=$(echo "${1}" | rev | cut -c16- | rev)
gpg --decrypt --output ${output} "${1}" && echo "${1} -> ${output}"
}
```
@ -1147,8 +1208,6 @@ gpg: encrypted with RSA key, ID 0x0000000000000000
document.pdf.1580000000.enc -> document.pdf
```
[drduh/Purse](https://github.com/drduh/Purse) is a password manager based on GnuPG and YubiKey to securely store and use credentials.
## Signature
Sign a message:
@ -1160,12 +1219,7 @@ echo "test message string" | gpg --armor --clearsign > signed.txt
Verify the signature:
```console
gpg --verify signed.txt
```
The output will be similar to:
```console
$ gpg --verify signed.txt
gpg: Signature made Mon 01 Jan 2024 12:00:00 PM UTC
gpg: using RSA key CF5A305B808B7A0F230DA064B3CD10E502E19637
gpg: Good signature from "YubiKey User <yubikey@example>" [ultimate]
@ -1179,7 +1233,7 @@ Primary key fingerprint: 4E2C 1FA3 372C BA96 A06A C34A F0F2 CFEB 0434 1FB5
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, use [YubiKey Manager](https://developers.yubico.com/yubikey-manager/) and the Admin PIN to set policy:
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:
Encryption:
@ -1187,8 +1241,6 @@ Encryption:
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:
```console
@ -1201,6 +1253,8 @@ Authentication:
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:
```
@ -1623,7 +1677,7 @@ Then update the repository URL to `git@github.com:USERNAME/repository`
## GnuPG 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).
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).
`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.
@ -1780,41 +1834,6 @@ 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.
## Keyserver
Public keys can be uploaded to a public server for discoverability:
```console
gpg --send-key $KEYID
gpg --keyserver keys.gnupg.net --send-key $KEYID
gpg --keyserver hkps://keyserver.ubuntu.com:443 --send-key $KEYID
```
Or if [uploading to keys.openpgp.org](https://keys.openpgp.org/about/usage):
```console
gpg --send-key $KEYID | curl -T - https://keys.openpgp.org
```
The public key URL can also be added to YubiKey (based on [Shaw 2003](https://datatracker.ietf.org/doc/html/draft-shaw-openpgp-hkp-00)):
```console
URL="hkps://keyserver.ubuntu.com:443/pks/lookup?op=get&search=${KEYID}"
```
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
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.
@ -1977,7 +1996,6 @@ scd apdu 00 20 00 83 08 40 40 40 40 40 40 40 40
scd apdu 00 e6 00 00
scd apdu 00 44 00 00
/echo Card has been successfully reset.
/bye
```
Or use `ykman` (sometimes in `~/.local/bin/`):
@ -2089,6 +2107,7 @@ EOF
# Additional resources
* [Yubico - PGP](https://developers.yubico.com/PGP/)
* [Yubico - PGP Card edit](https://developers.yubico.com/PGP/Card_edit.html)
* [Yubico - Yubikey Personalization](https://developers.yubico.com/yubikey-personalization/)
* [A Visual Explanation of GPG Subkeys (2022)](https://rgoulter.com/blog/posts/programming/2022-06-10-a-visual-explanation-of-gpg-subkeys.html)
* [dhess/nixos-yubikey](https://github.com/dhess/nixos-yubikey)
@ -2100,3 +2119,5 @@ EOF
* [PGP and SSH keys on a Yubikey NEO (2015)](https://www.esev.com/blog/post/2015-01-pgp-ssh-key-on-yubikey-neo/)
* [Offline GnuPG Master Key and Subkeys on YubiKey NEO Smartcard (2014)](https://blog.josefsson.org/2014/06/23/offline-gnupg-master-key-and-subkeys-on-yubikey-neo-smartcard/)
* [Creating the perfect GPG keypair (2013)](https://alexcabal.com/creating-the-perfect-gpg-keypair/)
* [GPG and SSH with Yubikey NEO (2013)](https://blog.habets.se/2013/02/GPG-and-SSH-with-Yubikey-NEO)
* [Riseup - OpenPGP Best Practices](https://help.riseup.net/en/security/message-security/openpgp/best-practices)

14
reset-yubikey
View File

@ -1,14 +0,0 @@
/hex
scd serialno
scd apdu 00 20 00 81 08 40 40 40 40 40 40 40 40
scd apdu 00 20 00 81 08 40 40 40 40 40 40 40 40
scd apdu 00 20 00 81 08 40 40 40 40 40 40 40 40
scd apdu 00 20 00 81 08 40 40 40 40 40 40 40 40
scd apdu 00 20 00 83 08 40 40 40 40 40 40 40 40
scd apdu 00 20 00 83 08 40 40 40 40 40 40 40 40
scd apdu 00 20 00 83 08 40 40 40 40 40 40 40 40
scd apdu 00 20 00 83 08 40 40 40 40 40 40 40 40
scd apdu 00 e6 00 00
scd apdu 00 44 00 00
/echo Card has been successfully reset.
/bye