arno/YubiKey-Guide
1
0
Fork 0
mirror of https://github.com/drduh/YubiKey-Guide.git synced 2024-11-22 15:28:06 +00:00
Code Issues Releases Wiki Activity

Merge pull request #419 from drduh/wip-12feb24

Browse Source 
12feb24
This commit is contained in:
drduh 2024-02-12 19:35:14 +00:00 committed by GitHub
commit 17ca4d058a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 89 additions and 129 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

218
README.md
View File

@ -1,4 +1,4 @@
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. 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) * [Temporary working directory](#temporary-working-directory)
* [Hardened configuration](#hardened-configuration) * [Hardened configuration](#hardened-configuration)
- [Certify key](#certify-key) - [Certify key](#certify-key)
- [Sign with existing key](#sign-with-existing-key)
- [Subkeys](#subkeys) - [Subkeys](#subkeys)
* [Signing](#signing) * [Signature key](#signature-key)
* [Encryption](#encryption) * [Encryption key](#encryption-key)
* [Authentication](#authentication) * [Authentication key](#authentication-key)
* [Extra Identities](#extra-identities)
- [Verify](#verify) - [Verify](#verify)
- [Export secret keys](#export-secret-keys) - [Export secret keys](#export-secret-keys)
- [Revocation certificate](#revocation-certificate) - [Revocation certificate](#revocation-certificate)
- [Backup](#backup) - [Backup](#backup)
- [Export public keys](#export-public-keys) - [Export public key](#export-public-key)
- [Configure YubiKey](#configure-yubikey) - [Configure YubiKey](#configure-yubikey)
* [Enable KDF](#enable-kdf) * [Enable KDF](#enable-kdf)
* [Change PIN](#change-pin) * [Change PIN](#change-pin)
* [Set information](#set-information) * [Set information](#set-information)
- [Transfer keys](#transfer-keys) - [Transfer keys](#transfer-keys)
* [Signing](#signing-1) * [Signature key](#signature-key-1)
* [Encryption](#encryption-1) * [Encryption key](#encryption-key-1)
* [Authentication](#authentication-1) * [Authentication key](#authentication-key-1)
- [Verify card](#verify-card) - [Verify transfer](#verify-transfer)
- [Multiple YubiKeys](#multiple-yubikeys) - [Multiple YubiKeys](#multiple-yubikeys)
* [Switching between YubiKeys](#switching-between-yubikeys) * [Switching between YubiKeys](#switching-between-yubikeys)
- [Finish](#finish) - [Finish](#finish)
@ -420,11 +418,11 @@ throw-keyids
# Certify key # 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. 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. 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 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 ```console
Please select what kind of key you want: Please select what kind of key you want:
@ -505,15 +503,18 @@ Current allowed actions: Certify
(Q) Finished (Q) Finished
``` ```
Type `Q` then `4096` as the requested keysize. Type `Q` then `4096` as the requested keysize:
Do **not** set the Certify key to expire (see [Note #3](#notes)).
```console ```console
Your selection? Q Your selection? Q
RSA keys may be between 1024 and 4096 bits long. RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048) 4096 What keysize do you want? (2048) 4096
Requested keysize is 4096 bits 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. Please specify how long the key should be valid.
0 = key does not expire 0 = key does not expire
<n> = key expires in n days <n> = key expires in n days
@ -525,7 +526,7 @@ Key does not expire at all
Is this correct? (y/N) y 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 ```console
GnuPG needs to construct a user ID to identify your key. GnuPG needs to construct a user ID to identify your key.
@ -551,25 +552,19 @@ pub rsa4096/0xF0F2CFEB04341FB5 2024-01-01 [C]
uid YubiKey User <yubikey@example> uid YubiKey User <yubikey@example>
``` ```
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 ```console
export KEYID=0xF0F2CFEB04341FB5 export KEYID=0xF0F2CFEB04341FB5
``` ```
# Sign with existing key **Optional** Existing keys may be used to sign new ones to prove ownership.
**Optional** Existing PGP keys may be used to sign new ones to prove ownership. Export the existing key to the working keyring and sign the new key:
Export the existing key to move it to the working keyring:
```console ```console
gpg --export-secret-keys --armor --output /tmp/new.sec gpg --export-secret-keys --armor --output /tmp/new.sec
```
Sign the new key:
```console
gpg --default-key $OLDKEY --sign-key $KEYID gpg --default-key $OLDKEY --sign-key $KEYID
``` ```
@ -583,11 +578,11 @@ gpg --expert --edit-key $KEYID
RSA with 4096-bit key length is recommended. RSA with 4096-bit key length is recommended.
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 ```console
gpg> addkey gpg> addkey
@ -629,9 +624,9 @@ ssb rsa4096/0xB3CD10E502E19637
[ultimate] (1). YubiKey User <yubikey@example> [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:
```console ```console
gpg> addkey gpg> addkey
@ -675,11 +670,11 @@ ssb rsa4096/0x30CBE8C4B085B9F7
[ultimate] (1). YubiKey User <yubikey@example> [ultimate] (1). YubiKey User <yubikey@example>
``` ```
## Authentication ## Authentication key
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:
```console ```console
gpg> addkey gpg> addkey
@ -765,13 +760,13 @@ ssb rsa4096/0xAD9E24E1B8CB9600
[ultimate] (1). YubiKey User <yubikey@example> [ultimate] (1). YubiKey User <yubikey@example>
``` ```
Finish by saving the keys: Finish by saving Subkeys:
```console ```console
gpg> save gpg> save
```
## Extra Identities gpg> quit
```
**Optional** To add additional email addresses or identities, use `adduid` **Optional** To add additional email addresses or identities, use `adduid`
@ -806,7 +801,7 @@ ssb rsa4096/0xAD9E24E1B8CB9600
[ unknown] (2). YubiKey User <yubikey@somewhere> [ unknown] (2). YubiKey User <yubikey@somewhere>
``` ```
Configure trust: Then configure ultimate trust for the new identity:
```console ```console
gpg> trust gpg> trust
@ -827,10 +822,9 @@ List available secret keys:
gpg -K gpg -K
``` ```
Verify output: The output will display Certify, Signature, Encryption and Authentication keys, for example:
```console ```console
---------------------------------------
sec rsa4096/0xF0F2CFEB04341FB5 2024-01-01 [C] sec rsa4096/0xF0F2CFEB04341FB5 2024-01-01 [C]
Key fingerprint = 4E2C 1FA3 372C BA96 A06A C34A F0F2 CFEB 0434 1FB5 Key fingerprint = 4E2C 1FA3 372C BA96 A06A C34A F0F2 CFEB 0434 1FB5
uid [ultimate] YubiKey User <yubikey@example> uid [ultimate] YubiKey User <yubikey@example>
@ -845,7 +839,7 @@ ssb rsa4096/0xAD9E24E1B8CB9600 2024-01-01 [A] [expires: 2026-01-01]
gpg --export $KEYID | hokey lint gpg --export $KEYID | hokey lint
``` ```
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). 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. 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. 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: Insert YubiKey and use GnuPG to configure it:
```console ```console
$ gpg --card-edit 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]
``` ```
Enter administrative mode: 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. **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 ```console
gpg --edit-key $KEYID 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 ```console
gpg> key 1 gpg> key 1
@ -1352,9 +1326,9 @@ Please select where to store the key:
Your selection? 1 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 ```console
gpg> key 1 gpg> key 1
@ -1378,9 +1352,9 @@ Please select where to store the key:
Your selection? 2 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 ```console
gpg> key 2 gpg> key 2
@ -1410,9 +1384,9 @@ Save and quit:
gpg> save 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:
```console ```console
sec rsa4096/0xF0F2CFEB04341FB5 2024-01-01 [C] sec rsa4096/0xF0F2CFEB04341FB5 2024-01-01 [C]
@ -1423,6 +1397,8 @@ ssb> rsa4096/0x30CBE8C4B085B9F7 2024-01-01 [E] [expires: 2026-01-01]
ssb> rsa4096/0xAD9E24E1B8CB9600 2024-01-01 [A] [expires: 2026-01-01] ssb> rsa4096/0xAD9E24E1B8CB9600 2024-01-01 [A] [expires: 2026-01-01]
``` ```
A `>` after a tag indicates the key is stored on a smart card.
# Multiple YubiKeys # Multiple YubiKeys
To provision additional YubiKeys, restore the Certify key backup and repeat [Configure YubiKey](#configure-yubikey). To provision additional YubiKeys, restore the Certify key backup and repeat [Configure YubiKey](#configure-yubikey).
@ -1437,9 +1413,9 @@ cd $GNUPGHOME
## Switching between YubiKeys ## 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. 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: 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 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 passphrase to a secure and durable location
- [ ] Saved Certify key, Subkeys and revocation certificate on encrypted portable storage, to be kept offline - [ ] 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. 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`
```console ```console
gpg --delete-secret-key $KEYID gpg --delete-secret-key $KEYID
@ -1557,7 +1533,7 @@ export KEYID=0xF0F2CFEB04341FB5
gpg --edit-key $KEYID gpg --edit-key $KEYID
``` ```
Assign ultimate trust by tying `trust` and selecting option `5`: Assign ultimate trust by typing `trust` and selecting option `5`:
```console ```console
gpg> trust gpg> trust
@ -1606,7 +1582,7 @@ ssb> rsa4096/0xAD9E24E1B8CB9600 created: 2024-01-01 expires: 2026-01-01
card-no: 0006 05553211 card-no: 0006 05553211
``` ```
`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. **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. - 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 ## 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. Import the Certify key and configuration to a temporary working directory.
Note that Windows users should import certify.gpg:
```console ```console
export GNUPGHOME=$(mktemp -d -t gnupg_$(date +%Y%m%d%H%M)_XXX) export GNUPGHOME=$(mktemp -d -t gnupg_$(date +%Y%m%d%H%M)_XXX)
@ -1780,13 +1754,13 @@ Set the expiration date, then `save`
Next, [Export public keys](#export-public-keys): Next, [Export public keys](#export-public-keys):
```console ```console
gpg --armor --export $KEYID > gpg-$KEYID-$(date +%F).asc gpg --armor --export $KEYID > $KEYID-$(date +%F).asc
``` ```
Transfer the public key to the destination host, and then import it: Transfer the public key to the destination host, and then import it:
```console ```console
gpg --import gpg-0x*.asc gpg --import 0x*.asc
``` ```
Alternatively, publish to a public key server to update the expiration: 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 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 ## 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. Previous Subkeys may be kept or deleted from the identity.
@ -1875,7 +1849,7 @@ Use `showpref` to verify notions were correctly added.
# SSH # 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. [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 ### 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 ### Use S.gpg-agent.ssh
@ -2197,13 +2171,9 @@ The goal is to configure SSH client inside WSL work together with the Windows ag
![WSL agent architecture](media/schema_gpg.png) ![WSL agent architecture](media/schema_gpg.png)
**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. **Note** 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: 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.
* Ubuntu 16.04 or newer for WSL
* Kleopatra
* [Windows configuration](#windows)
Download [vuori/weasel-pageant](https://github.com/vuori/weasel-pageant). Download [vuori/weasel-pageant](https://github.com/vuori/weasel-pageant).
@ -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. **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 ```console
scp ~/.gnupg/pubring.kbx remote:~/.gnupg/ scp ~/.gnupg/pubring.kbx remote:~/.gnupg/
@ -2510,28 +2480,28 @@ Use `gpg -K` to verify the identity is listed.
**Note** This is not possible on YubiKey NEO. **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: To require a touch for each key operation, install [YubiKey Manager](https://developers.yubico.com/yubikey-manager/) and recall the Admin PIN:
Authentication:
```console
ykman openpgp keys set-touch aut on
```
Signing:
```console
ykman openpgp keys set-touch sig on
```
Encryption: Encryption:
```console ```console
ykman openpgp keys set-touch dec on ykman openpgp keys set-touch dec on
``` ```
Signature:
```console
ykman openpgp keys set-touch sig on
```
Authentication:
```console
ykman openpgp keys set-touch aut on
```
**Note** Versions of YubiKey Manager before 5.1.0 use `enc` instead of `dec` for encryption. **Note** Versions of YubiKey Manager before 5.1.0 use `enc` instead of `dec` for encryption.
**Note** Older versions of YubiKey Manager use `touch` instead of `set-touch` **Note** Older versions of YubiKey Manager use `touch` instead of `set-touch`
@ -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 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 # Troubleshooting
@ -2736,32 +2706,22 @@ Generate the Certify key:
gpg --batch --generate-key gen-params-rsa4096 gpg --batch --generate-key gen-params-rsa4096
``` ```
Verify results: Verify the Certify key:
```console ```console
gpg --list-key gpg --list-key
``` ```
The fingerprint is used to create the three Subkeys for encryption, signing and authentication operations. Export the Certify key ID and create the Subkeys:
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):
```console ```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 2y
gpg --quick-add-key "$KEYID" rsa4096 encrypt 1y
```
Finally, create an [authentication subkey](https://superuser.com/questions/390265/what-is-a-gpg-with-authenticate-capability-used-for): gpg --quick-add-key "$KEYID" rsa4096 auth 2y
```console
gpg --quick-add-key "$KEYID" rsa4096 auth 1y
``` ```
# Additional resources # Additional resources