This is a guide to using [YubiKey](https://www.yubico.com/products/) as a [smart card](https://security.stackexchange.com/questions/38924/how-does-storing-gpg-ssh-private-keys-on-smart-cards-compare-to-plain-usb-drives) for secure encryption, signing and authentication operations.
This is a guide to using [YubiKey](https://www.yubico.com/products/) as a [smart card](https://security.stackexchange.com/questions/38924/how-does-storing-gpg-ssh-private-keys-on-smart-cards-compare-to-plain-usb-drives) for secure encryption, signature and authentication operations.
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.
@ -25,26 +25,24 @@ To suggest an improvement, please send a pull request or open an [issue](https:/
* [Temporary working directory](#temporary-working-directory)
* [Switching between YubiKeys](#switching-between-yubikeys)
- [Finish](#finish)
@ -420,11 +418,11 @@ throw-keyids
# Certify key
The primary key to generate is the Certify key, which will be used to issue Subkeys for Encrypt, Sign and Authenticate operations.
The primary key to generate is the Certify key, which will be used to issue Subkeys for encryption, signature and authentication operations.
The Certify key should be kept offline at all times and only accessed from a secure environment to revoke or issue Subkeys. Keys can also be generated on the YubiKey itself to avoid duplication, however for usability and durability reasons this guide recommends against doing so.
Generate a passphrase which will be needed throughout the guide to create and export Subkeys. The passphrase should be memorized or written down in a secure location, ideally separate from the portable storage device used for key material.
Generate a passphrase which will be needed throughout the guide to create Subkeys. The passphrase should be memorized or written down in a secure location, ideally separate from the portable storage device used for key material.
The passphrase is recommended to consist of only upper case letters and numbers for improved readability.
@ -459,7 +457,7 @@ Generate the Certify key with GnuPG:
gpg --expert --full-generate-key
```
Select `(8) RSA (set your own capabilities)`, then type `E` and `S`deselect Encrypt and Sign actions and only the Certify capability remains:
Select `(8) RSA (set your own capabilities)`, then type `E` and `S`to deselect **Encrypt** and **Sign** actions, so the only **Current allowed actions** remaining is **Certify**:
```console
Please select what kind of key you want:
@ -505,15 +503,18 @@ Current allowed actions: Certify
(Q) Finished
```
Type `Q` then `4096` as the requested keysize.
Do **not** set the Certify key to expire (see [Note #3](#notes)).
Type `Q` then `4096` as the requested keysize:
```console
Your selection? Q
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048) 4096
Requested keysize is 4096 bits
```
Type `0` for key validity - there is no reason to expire the Certify key (see [Note #3](#notes)) - then type `y` to confirm.
```console
Please specify how long the key should be valid.
0 = key does not expire
<n> = key expires in n days
@ -525,7 +526,7 @@ Key does not expire at all
Is this correct? (y/N) y
```
Input any value for Real name and Email address; Comment is optional:
Input any value for **Real name** and **Email address**; **Comment** is optional, then type `O` to confirm:
```console
GnuPG needs to construct a user ID to identify your key.
Copy the Certify key identifier beginning with `0x` and export it as a [variable](https://stackoverflow.com/questions/1158091/defining-a-variable-with-or-without-export/1158231#1158231) (`KEYID`):
Copy the Certify key identifier beginning with `0x`from the output and export it as a [variable](https://stackoverflow.com/questions/1158091/defining-a-variable-with-or-without-export/1158231#1158231) (`KEYID`):
```console
export KEYID=0xF0F2CFEB04341FB5
```
# Sign with existing key
**Optional** Existing PGP keys may be used to sign new ones to prove ownership.
**Optional** Existing keys may be used to sign new ones to prove ownership.
Export the existing key to move it to the working keyring:
Export the existing key to the working keyring and sign the new key:
Subkeys are recommended to have one or several year expirations. They must be renewed using the Certify key - see [Rotating keys](#rotating-keys).
Subkeys are recommended to have one or several year expirations. They must be renewed or replaced using the Certify key - see [Rotating keys](#rotating-keys).
## Signing
## Signature key
Create a [signing key](https://stackoverflow.com/questions/5421107/can-rsa-be-both-used-as-encryption-and-signature/5432623#5432623) by typing `addkey` then select the `(4) RSA (sign only)` option:
Generate a Signature key by typing `addkey` then `4` to select the `(4) RSA (sign only)` option:
```console
gpg> addkey
@ -629,9 +624,9 @@ ssb rsa4096/0xB3CD10E502E19637
[ultimate] (1). YubiKey User <yubikey@example>
```
## Encryption
## Encryption key
Next, create an [encryption key](https://www.cs.cornell.edu/courses/cs5430/2015sp/notes/rsa_sign_vs_dec.php) by typing `addkey` then select the `(6) RSA (encrypt only)` option:
Generate an Encryption key by typing `addkey` then `6` to select the `(6) RSA (encrypt only)` option:
Finally, create an [authentication key](https://superuser.com/questions/390265/what-is-a-gpg-with-authenticate-capability-used-for) by typing `addkey` then select the `(8) RSA (set your own capabilities)` option.
Generate an Authentication key by typing `addkey` then `8` to select the `(8) RSA (set your own capabilities)` option.
Toggle the required capabilities with `S`, `E` and `A` until `Authenticate` is the only selected action:
Toggle the required capabilities with `S`, `E` and `A` until **Authenticate** is the only allowed action:
hokey may warn (orange text) about cross certification for the authentication key. GnuPG [Signing Subkey Cross-Certification](https://gnupg.org/faq/subkey-cross-certify.html) documentation has more detail on cross certification, and version 2.2.1 notes "subkey <keyid> does not sign and so does not need to be cross-certified".
hokey may warn (orange text) about cross certification for the Authentication key. GnuPG [Signing Subkey Cross-Certification](https://gnupg.org/faq/subkey-cross-certify.html) documentation has more detail on cross certification, and version 2.2.1 notes "subkey <keyid> does not sign and so does not need to be cross-certified".
hokey may also indicate a problem (red text) with `Key expiration times: []` on the primary key - see [Note #3](#notes).
@ -1076,9 +1070,9 @@ doas bioctl -d sd3
See [OpenBSD FAQ#14](https://www.openbsd.org/faq/faq14.html#softraidCrypto) for more information.
# Export public keys
# Export public key
**Important** Without the *public* key, it will **not** be possible to use GnuPG to encrypt, decrypt, nor sign messages. However, YubiKey may still be used for SSH authentication.
**Important** Without the public key, it will **not** be possible to use GnuPG to decrypt and sign messages. However, YubiKey can still be used for SSH authentication.
Create another partition on the portable storage device to store the public key, or reconnect networking and upload to a key server.
@ -1188,29 +1182,7 @@ gpg/card> quit
Insert YubiKey and use GnuPG to configure it:
```console
$ gpg --card-edit
Reader ...........: Yubico Yubikey 4 OTP U2F CCID
Application ID ...: D2760001240102010006055532110000
Application type .: OpenPGP
Version ..........: 3.4
Manufacturer .....: Yubico
Serial number ....: 05553211
Name of cardholder: [not set]
Language prefs ...: [not set]
Salutation .......:
URL of public key : [not set]
Login data .......: [not set]
Signature PIN ....: not forced
Key attributes ...: rsa2048 rsa2048 rsa2048
Max. PIN lengths .: 127 127 127
PIN retry counter : 3 0 3
Signature counter : 0
KDF setting ......: off
Signature key ....: [none]
Encryption key....: [none]
Authentication key: [none]
General key info..: [none]
gpg --card-edit
```
Enter administrative mode:
@ -1319,17 +1291,19 @@ gpg/card> quit
**Important** Transferring keys to YubiKey is a one-way operation. Verify backups were made before proceeding. `keytocard` converts the local, on-disk key into a stub, which means the on-disk copy is no longer usable to transfer to subsequent YubiKeys.
The currently selected key(s) are indicated with an `*`. When transferring keys, only one subkey should be selected at a time.
The currently selected key(s) are indicated with an `*`.
When transferring keys, only one subkey should be selected at a time.
```console
gpg --edit-key $KEYID
```
## Signing
The Certify key passphrase and Admin PIN are required to transfer keys.
The Certify key passphrase and Admin PIN are required for this step.
## Signature key
Select and transfer the signature key - `*` will appear next to the selected subkey (`ssb*`):
Type `key 1` to select the first key and `keytocard` to transfer it, then `1` as the destination:
```console
gpg> key 1
@ -1352,9 +1326,9 @@ Please select where to store the key:
Your selection? 1
```
## Encryption
## Encryption key
Type `key 1` again to deselect the first key and `key 2` to select the next key:
Type `key 1` again to deselect the first key and `key 2` to select the next key, then `keytocard` to transfer it, then `2` as the destination:
```console
gpg> key 1
@ -1378,9 +1352,9 @@ Please select where to store the key:
Your selection? 2
```
## Authentication
## Authentication key
Type `key 2` again to deselect the second key and `key 3` to select the last key:
Type `key 2` again to deselect the second key and `key 3` to select the third key, then `keytocard` to transfer it, then `3` as the destination:
```console
gpg> key 2
@ -1410,9 +1384,9 @@ Save and quit:
gpg> save
```
# Verify card
# Verify transfer
Verify Subkeys have been moved to YubiKey as indicated by`ssb>` with `gpg -K`, for example:
To Verify Subkeys have been moved to YubiKey, look for`ssb>` with `gpg -K`, for example:
A `>` after a tag indicates the key is stored on a smart card.
# Multiple YubiKeys
To provision additional YubiKeys, restore the Certify key backup and repeat [Configure YubiKey](#configure-yubikey).
@ -1437,9 +1413,9 @@ cd $GNUPGHOME
## Switching between YubiKeys
When GnuPG key is added to YubiKey using the *keytocard* command, the key is deleted from the keyring and a *stub* is added, pointing to the YubiKey. The stub identifies the GnuPG key ID and YubiKey serial number.
When a GnuPG key is added to YubiKey using `keytocard`, the key is deleted from the keyring and a **stub** is added, pointing to the YubiKey. The stub identifies the GnuPG key ID and YubiKey serial number.
However, when the operation is repeated for an additional YubiKey, the stub is overwritten by the *keytocard* operation and now will point to the latest YubiKey.
When the operation is repeated for an additional YubiKey, the stub is overwritten and will now point to the latest YubiKey.
GnuPG will request a specific YubiKey by serial number, as referenced by the stub, and will not recognize another YubiKey with a different serial number without manual intervention.
@ -1458,7 +1434,7 @@ To use the second YubiKey, repeat the command.
Before completing setup, verify the following:
- [ ] Saved encryption, signing and authentication Subkeys to YubiKey (`gpg -K` will show `ssb>` for Subkeys)
- [ ] Saved Encryption, Signature and Authentication Subkeys to YubiKey (`gpg -K` will show `ssb>` for 3 Subkeys)
- [ ] Saved YubiKey user and admin PINs, which are unique and were changed from default values
- [ ] Saved Certify key passphrase to a secure and durable location
- [ ] Saved Certify key, Subkeys and revocation certificate on encrypted portable storage, to be kept offline
@ -1467,7 +1443,7 @@ Before completing setup, verify the following:
Reboot to finish.
If an ephemeral environment was not used for setup, delete secret keys from the keyring and [securely delete](https://srm.sourceforge.net/) `$GNUPGHOME`.
If an ephemeral environment was not used for setup, delete secret keys from the keyring and [securely delete](https://srm.sourceforge.net/) `$GNUPGHOME`
`sec#` indicates the corresponding key is not available.
`sec#` indicates the corresponding key is not available (the Certify key is offline).
**Note** If `General key info..: [none]` appears in the output instead - go back and import the public key using the previous step.
@ -1687,7 +1663,7 @@ When a Subkey expires, it can either be renewed or replaced. Both actions requir
- Replacing Subkeys is less convenient but potentially more secure: the new Subkeys will **not** be able to decrypt previous messages, authenticate with SSH, etc. Contacts will need to receive the updated public key and any encrypted secrets need to be decrypted and re-encrypted to new Subkeys to be usable. This process is functionally equivalent to losing the YubiKey and provisioning a new one.
Neither rotation method is superior and it is up to personal philosophy on identity management and individual threat modeling to decide which one to use, or whether to expire Subkeys at all. Ideally, Subkeys would be ephemeral: used only once for each unique encryption, signing and authentication event, however in practice that is not really practical nor worthwhile with YubiKey. Advanced users may dedicate an air-gapped machine for frequent credential rotation.
Neither rotation method is superior and it is up to personal philosophy on identity management and individual threat modeling to decide which one to use, or whether to expire Subkeys at all. Ideally, Subkeys would be ephemeral: used only once for each unique encryption, signature and authentication event, however in practice that is not really practical nor worthwhile with YubiKey. Advanced users may dedicate an air-gapped machine for frequent credential rotation.
## Setup environment
@ -1712,8 +1688,6 @@ sudo mount /dev/mapper/secret /mnt/encrypted-storage
Import the Certify key and configuration to a temporary working directory.
Note that Windows users should import certify.gpg:
Transfer the public key to the destination host, and then import it:
```console
gpg --import gpg-0x*.asc
gpg --import 0x*.asc
```
Alternatively, publish to a public key server to update the expiration:
@ -1801,11 +1775,11 @@ Download the public key with updated expiration:
gpg --recv $KEYID
```
The validity of the GnuPG identity will be extended, allowing it to be used again for encryption, signing and authentication operations. The SSH public key does **not** need to be updated on remote hosts.
The validity of the GnuPG identity will be extended, allowing it to be used again for encryption, signature and authentication operations. The SSH public key does **not** need to be updated on remote hosts.
## Rotating keys
Follow the original steps to generate and add each Subkey.
Follow the original procedure to generate and add [Subkeys](#subkeys).
Previous Subkeys may be kept or deleted from the identity.
@ -1875,7 +1849,7 @@ Use `showpref` to verify notions were correctly added.
# SSH
**Tip** YubiKey can be used directly for SSH only, without GnuPG features, starting in [OpenSSH v8.2](https://www.openssh.com/txt/release-8.2). For more information, see [ed25519-sk.md](https://github.com/vorburger/vorburger.ch-Notes/blob/develop/security/ed25519-sk.md) and [Yubico - GitHub now supports SSH security keys](https://www.yubico.com/blog/github-now-supports-ssh-security-keys/).
**Tip** YubiKey can be used directly for SSH only, without GnuPG features, starting in [OpenSSH v8.2](https://www.openssh.com/txt/release-8.2). For more information, see [vorburger/ed25519-sk.md](https://github.com/vorburger/vorburger.ch-Notes/blob/develop/security/ed25519-sk.md) and [Yubico - GitHub now supports SSH security keys](https://www.yubico.com/blog/github-now-supports-ssh-security-keys/).
[gpg-agent](https://wiki.archlinux.org/title/GnuPG#SSH_agent) supports the OpenSSH ssh-agent protocol (`enable-ssh-support`) as well as PuTTy's Pageant on Windows (`enable-putty-support`). This means it can be used instead of the traditional ssh-agent / pageant. There are some differences from ssh-agent, notably that gpg-agent does not _cache_ keys rather it converts, encrypts and stores them persistently as keys, then makes them available to ssh clients. Any existing ssh private keys should be deleted after importing to GnuPG agent.
@ -2034,7 +2008,7 @@ For example, tmux does not have environment variables such as `$SSH_AUTH_SOCK` w
### Use ssh-agent
You should now be able to use `ssh -A remote` on the _local_ host to log into _remote_ host, and should then be able to use YubiKey as if it were connected to the remote host. For example, using e.g. `ssh-add -l` on that remote host should show the public key from the YubiKey (note `cardno:`). (If you don't want to have to remember to use `ssh -A`, you can use `ForwardAgent yes` in `~/.ssh/config`. As a security best practice, always use `ForwardAgent yes` only for a single `Hostname`, never for all servers.)
You should now be able to use `ssh -A remote` on the _local_ host to log into _remote_ host, and should then be able to use YubiKey as if it were connected to the remote host. For example, using e.g. `ssh-add -l` on that remote host will show the public key from the YubiKey (`cardno:`). Always use `ForwardAgent yes` only for a single host, never for all servers.
### Use S.gpg-agent.ssh
@ -2197,13 +2171,9 @@ The goal is to configure SSH client inside WSL work together with the Windows ag
**Note** this works only for SSH agent forwarding. GnuPG forwarding for cryptographic operations is not supported. See [vuori/weasel-pageant](https://github.com/vuori/weasel-pageant) for more information.
One way to forward is just `ssh -A` (still need to eval weasel to setup local ssh-agent), and only relies on OpenSSH. In this track, `ForwardAgent` and `AllowAgentForwarding` in ssh/sshd config may be involved. However, when using ssh socket forwarding, do not enable `ForwardAgent` in ssh config. See [SSH Agent Forwarding](#remote-machines-ssh-agent-forwarding) for more information. This requires:
**Note** GnuPG forwarding for cryptographic operations is not supported. See [vuori/weasel-pageant](https://github.com/vuori/weasel-pageant) for more information.
* Ubuntu 16.04 or newer for WSL
* Kleopatra
* [Windows configuration](#windows)
One way to forward is just `ssh -A` (still need to eval weasel to setup local ssh-agent), and only relies on OpenSSH. In this track, `ForwardAgent` and `AllowAgentForwarding` in ssh/sshd config may be involved. However, when using ssh socket forwarding, do not enable `ForwardAgent` in ssh config. See [SSH Agent Forwarding](#remote-machines-ssh-agent-forwarding) for more information. This requires Ubuntu 16.04 or newer for WSL and Kleopatra.
@ -2313,7 +2283,7 @@ On the remote host, edit `/etc/ssh/sshd_config` to set `StreamLocalBindUnlink ye
**Optional** Without root access on the remote host to edit `/etc/ssh/sshd_config`, socket located at `gpgconf --list-dir agent-socket` on the remote host will need to be removed before forwarding works. See [AgentForwarding GNUPG wiki page](https://wiki.gnupg.org/AgentForwarding) for more information.
Import public keys on the remote host. On the local host, copy the public keyring to the remote host:
Import the public key on the remote host. On the local host, copy the public keyring to the remote host:
```console
scp ~/.gnupg/pubring.kbx remote:~/.gnupg/
@ -2510,26 +2480,26 @@ Use `gpg -K` to verify the identity is listed.
**Note** This is not possible on YubiKey NEO.
By default, YubiKey will perform encryption, signing and authentication operations without requiring any action from the user after the key is plugged in and 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 recall the Admin PIN:
Authentication:
Encryption:
```console
ykman openpgp keys set-touch aut on
ykman openpgp keys set-touch dec on
```
Signing:
Signature:
```console
ykman openpgp keys set-touch sig on
```
Encryption:
Authentication:
```console
ykman openpgp keys set-touch dec on
ykman openpgp keys set-touch aut on
```
**Note** Versions of YubiKey Manager before 5.1.0 use `enc` instead of `dec` for encryption.
@ -2644,7 +2614,7 @@ To reset YubiKey from the Certify key backup (such as the one on encrypted porta
1. To switch between multiple identities on different YubiKeys, unplug the first YubiKey and restart gpg-agent, ssh-agent and pinentry with `pkill gpg-agent ; pkill ssh-agent ; pkill pinentry ; eval $(gpg-agent --daemon --enable-ssh-support)` then insert the other YubiKey and run `gpg-connect-agent updatestartuptty /bye`
1. To use YubiKey on multiple computers, import the corresponding public keys on them. Confirm see YubiKey is visible with `gpg --card-status`, then trust the imported public keys ultimately. `gpg --list-secret-keys` will show the correct and trusted key.
1. To use YubiKey on multiple computers, import the corresponding public keys. Confirm see YubiKey is visible with `gpg --card-status`, then trust the imported public keys ultimately. `gpg --list-secret-keys` will show the correct and trusted key.
# Troubleshooting
@ -2736,32 +2706,22 @@ Generate the Certify key:
gpg --batch --generate-key gen-params-rsa4096
```
Verify results:
Verify the Certify key:
```console
gpg --list-key
```
The fingerprint is used to create the three Subkeys for encryption, signing and authentication operations.
Use a one or several year expiration for Subkeys - they can be renewed using the Certify key, see [rotating keys](#rotating-keys).
Create a [signing subkey](https://stackoverflow.com/questions/5421107/can-rsa-be-both-used-as-encryption-and-signature/5432623#5432623):
Export the Certify key ID and create the Subkeys:
```console
gpg --quick-add-key "$KEYID" rsa4096 sign 1y
```
export KEYID=0xF0F2CFEB04341FB5
Create an [encryption subkey](https://www.cs.cornell.edu/courses/cs5430/2015sp/notes/rsa_sign_vs_dec.php):
gpg --quick-add-key "$KEYID" rsa4096 sign 2y
```console
gpg --quick-add-key "$KEYID" rsa4096 encrypt 1y
```
gpg --quick-add-key "$KEYID" rsa4096 encrypt 2y
Finally, create an [authentication subkey](https://superuser.com/questions/390265/what-is-a-gpg-with-authenticate-capability-used-for):
drduh
3 months ago
committed by