From ca052604c3012a23788931edd3b3b690ad483848 Mon Sep 17 00:00:00 2001 From: drduh Date: Mon, 12 Feb 2024 10:45:38 -0800 Subject: [PATCH 1/6] standard names for subkeys --- README.md | 121 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 63 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index 57a0912..603de10 100644 --- a/README.md +++ b/README.md @@ -25,12 +25,10 @@ To suggest an improvement, please send a pull request or open an [issue](https:/ * [Temporary working directory](#temporary-working-directory) * [Hardened configuration](#hardened-configuration) - [Certify key](#certify-key) -- [Sign with existing key](#sign-with-existing-key) - [Subkeys](#subkeys) - * [Signing](#signing) - * [Encryption](#encryption) - * [Authentication](#authentication) - * [Extra Identities](#extra-identities) + * [Signature key](#signature-key) + * [Encryption key](#encryption-key) + * [Authentication key](#authentication-key) - [Verify](#verify) - [Export secret keys](#export-secret-keys) - [Revocation certificate](#revocation-certificate) @@ -41,10 +39,10 @@ To suggest an improvement, please send a pull request or open an [issue](https:/ * [Change PIN](#change-pin) * [Set information](#set-information) - [Transfer keys](#transfer-keys) - * [Signing](#signing-1) - * [Encryption](#encryption-1) - * [Authentication](#authentication-1) -- [Verify card](#verify-card) + * [Signature key](#signature-key-1) + * [Encryption key](#encryption-key-1) + * [Authentication key](#authentication-key-1) +- [Verify transfer](#verify-transfer) - [Multiple YubiKeys](#multiple-yubikeys) * [Switching between YubiKeys](#switching-between-yubikeys) - [Finish](#finish) @@ -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 = 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. @@ -557,11 +558,9 @@ Copy the Certify key identifier beginning with `0x` and export it as a [variable 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 move it to the working keyring: +Export the existing key to the working keyring: ```console gpg --export-secret-keys --armor --output /tmp/new.sec @@ -585,9 +584,9 @@ 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). -## 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: +Create Signature key by typing `addkey` then type `4` to select the `(4) RSA (sign only)` option: ```console gpg> addkey @@ -629,9 +628,9 @@ ssb rsa4096/0xB3CD10E502E19637 [ultimate] (1). YubiKey User ``` -## 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: +Next, create an Encryption key by typing `addkey` then type `6` to select the `(6) RSA (encrypt only)` option: ```console gpg> addkey @@ -675,11 +674,11 @@ ssb rsa4096/0x30CBE8C4B085B9F7 [ultimate] (1). YubiKey User ``` -## 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. +Finally, create an Authentication key by typing `addkey` then type `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 gpg> addkey @@ -765,13 +764,13 @@ ssb rsa4096/0xAD9E24E1B8CB9600 [ultimate] (1). YubiKey User ``` -Finish by saving the keys: +Finish by saving Subkeys: ```console gpg> save -``` -## Extra Identities +gpg> quit +``` **Optional** To add additional email addresses or identities, use `adduid` @@ -806,7 +805,7 @@ ssb rsa4096/0xAD9E24E1B8CB9600 [ unknown] (2). YubiKey User ``` -Configure trust: +Then configure ultimate trust for the new identity: ```console gpg> trust @@ -827,7 +826,7 @@ List available secret keys: gpg -K ``` -Verify output: +The output should display Certify, Signature, Encryption and Authentication keys, for example: ```console --------------------------------------- @@ -845,7 +844,7 @@ ssb rsa4096/0xAD9E24E1B8CB9600 2024-01-01 [A] [expires: 2026-01-01] 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 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 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). @@ -1325,11 +1324,11 @@ The currently selected key(s) are indicated with an `*`. When transferring keys, gpg --edit-key $KEYID ``` -## Signing +The Certify key passphrase and Admin PIN will be prompted. -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*`): +Select and transfer the Signature key - `*` will appear next to the selected subkey (`ssb*`): ```console gpg> key 1 @@ -1352,7 +1351,7 @@ 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: @@ -1378,9 +1377,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: ```console gpg> key 2 @@ -1410,9 +1409,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: ```console sec rsa4096/0xF0F2CFEB04341FB5 2024-01-01 [C] @@ -1423,6 +1422,8 @@ ssb> rsa4096/0x30CBE8C4B085B9F7 2024-01-01 [E] [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 To provision additional YubiKeys, restore the Certify key backup and repeat [Configure YubiKey](#configure-yubikey). @@ -1458,7 +1459,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 @@ -1606,7 +1607,7 @@ ssb> rsa4096/0xAD9E24E1B8CB9600 created: 2024-01-01 expires: 2026-01-01 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. @@ -1687,7 +1688,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 @@ -1801,7 +1802,7 @@ 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 @@ -2510,28 +2511,28 @@ 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: - -```console -ykman openpgp keys set-touch aut on -``` - -Signing: - -```console -ykman openpgp keys set-touch sig on -``` - Encryption: ```console 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** Older versions of YubiKey Manager use `touch` instead of `set-touch` @@ -2742,9 +2743,13 @@ Verify results: gpg --list-key ``` -The fingerprint is used to create the three Subkeys for encryption, signing and authentication operations. +The fingerprint is used to create the three Subkeys: -Use a one or several year expiration for Subkeys - they can be renewed using the Certify key, see [rotating keys](#rotating-keys). +```console +export KEYID=0xF0F2CFEB04341FB5 +``` + +Use a one or several year expiration for Subkeys - they must 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): From 0b24d77c1825f66c2c0c1a3b23a93498d621a8a9 Mon Sep 17 00:00:00 2001 From: drduh Date: Mon, 12 Feb 2024 10:51:55 -0800 Subject: [PATCH 2/6] simplify batch instructions --- README.md | 42 ++++++++++++------------------------------ 1 file changed, 12 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 603de10..bbb473a 100644 --- a/README.md +++ b/README.md @@ -422,7 +422,7 @@ The primary key to generate is the Certify key, which will be used to issue Subk 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. @@ -552,7 +552,7 @@ pub rsa4096/0xF0F2CFEB04341FB5 2024-01-01 [C] uid YubiKey User ``` -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 @@ -560,15 +560,11 @@ export KEYID=0xF0F2CFEB04341FB5 **Optional** Existing keys may be used to sign new ones to prove ownership. -Export the existing key to the working keyring: +Export the existing key to the working keyring and sign the new key: ```console gpg --export-secret-keys --armor --output /tmp/new.sec -``` -Sign the new key: - -```console gpg --default-key $OLDKEY --sign-key $KEYID ``` @@ -582,11 +578,11 @@ gpg --expert --edit-key $KEYID 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). ## Signature key -Create Signature key by typing `addkey` then type `4` to 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 @@ -630,7 +626,7 @@ ssb rsa4096/0xB3CD10E502E19637 ## Encryption key -Next, create an Encryption key by typing `addkey` then type `6` to 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 gpg> addkey @@ -676,7 +672,7 @@ ssb rsa4096/0x30CBE8C4B085B9F7 ## Authentication key -Finally, create an Authentication key by typing `addkey` then type `8` to 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 allowed action: @@ -2737,36 +2733,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: +Export the Certify key ID and create the Subkeys: ```console export KEYID=0xF0F2CFEB04341FB5 -``` -Use a one or several year expiration for Subkeys - they must be renewed using the Certify key, see [rotating keys](#rotating-keys). +gpg --quick-add-key "$KEYID" rsa4096 sign 2y -Create a [signing subkey](https://stackoverflow.com/questions/5421107/can-rsa-be-both-used-as-encryption-and-signature/5432623#5432623): +gpg --quick-add-key "$KEYID" rsa4096 encrypt 2y -```console -gpg --quick-add-key "$KEYID" rsa4096 sign 1y -``` - -Create an [encryption subkey](https://www.cs.cornell.edu/courses/cs5430/2015sp/notes/rsa_sign_vs_dec.php): - -```console -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): - -```console -gpg --quick-add-key "$KEYID" rsa4096 auth 1y +gpg --quick-add-key "$KEYID" rsa4096 auth 2y ``` # Additional resources From 29563423c1aef6f532508db05923b69005de1b64 Mon Sep 17 00:00:00 2001 From: drduh Date: Mon, 12 Feb 2024 11:03:26 -0800 Subject: [PATCH 3/6] explicit keytocard instructions --- README.md | 47 +++++++++++++---------------------------------- 1 file changed, 13 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index bbb473a..5a06055 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ To suggest an improvement, please send a pull request or open an [issue](https:/ - [Export secret keys](#export-secret-keys) - [Revocation certificate](#revocation-certificate) - [Backup](#backup) -- [Export public keys](#export-public-keys) +- [Export public key](#export-public-key) - [Configure YubiKey](#configure-yubikey) * [Enable KDF](#enable-kdf) * [Change PIN](#change-pin) @@ -822,10 +822,9 @@ List available secret keys: gpg -K ``` -The output should display Certify, Signature, Encryption and Authentication keys, for example: +The output will display Certify, Signature, Encryption and Authentication keys, for example: ```console ---------------------------------------- sec rsa4096/0xF0F2CFEB04341FB5 2024-01-01 [C] Key fingerprint = 4E2C 1FA3 372C BA96 A06A C34A F0F2 CFEB 0434 1FB5 uid [ultimate] YubiKey User @@ -1071,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. @@ -1183,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: @@ -1314,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 ``` -The Certify key passphrase and Admin PIN will be prompted. +The Certify key passphrase and Admin PIN are required to transfer keys. ## 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 @@ -1349,7 +1328,7 @@ Your selection? 1 ## 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 @@ -1375,7 +1354,7 @@ Your selection? 2 ## Authentication key -Type `key 2` again to deselect the second key and `key 3` to select the third 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 @@ -2031,7 +2010,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 From 6e19ae4cc4fe94f5c26def4b0ce4eb27581c5f8b Mon Sep 17 00:00:00 2001 From: drduh Date: Mon, 12 Feb 2024 11:24:27 -0800 Subject: [PATCH 4/6] few more style nits --- README.md | 24 +++++++++--------------- 1 file changed, 9 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 5a06055..d8caee3 100644 --- a/README.md +++ b/README.md @@ -1413,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 `keytocard` and now will 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. @@ -1443,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` ```console gpg --delete-secret-key $KEYID @@ -1533,7 +1533,7 @@ export KEYID=0xF0F2CFEB04341FB5 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 gpg> trust @@ -1688,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: - ```console export GNUPGHOME=$(mktemp -d -t gnupg_$(date +%Y%m%d%H%M)_XXX) @@ -1756,13 +1754,13 @@ Set the expiration date, then `save` Next, [Export public keys](#export-public-keys): ```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: ```console -gpg --import gpg-0x*.asc +gpg --import 0x*.asc ``` Alternatively, publish to a public key server to update the expiration: @@ -1781,7 +1779,7 @@ The validity of the GnuPG identity will be extended, allowing it to be used agai ## 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. @@ -1851,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. @@ -2175,11 +2173,7 @@ 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: - -* 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. Download [vuori/weasel-pageant](https://github.com/vuori/weasel-pageant). From 678e779b1f74b06a507db269c805508338bfed77 Mon Sep 17 00:00:00 2001 From: drduh Date: Mon, 12 Feb 2024 11:28:49 -0800 Subject: [PATCH 5/6] typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d8caee3..724c89f 100644 --- a/README.md +++ b/README.md @@ -1415,7 +1415,7 @@ cd $GNUPGHOME 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. -When the operation is repeated for an additional YubiKey, the stub is overwritten `keytocard` 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. From 07e0fe71fd5cbc2ea35164527329cf23655e0132 Mon Sep 17 00:00:00 2001 From: drduh Date: Mon, 12 Feb 2024 11:32:26 -0800 Subject: [PATCH 6/6] few more standard terms --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 724c89f..1fc8001 100644 --- a/README.md +++ b/README.md @@ -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. @@ -418,7 +418,7 @@ 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. @@ -2171,7 +2171,7 @@ The goal is to configure SSH client inside WSL work together with the Windows ag ![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 Ubuntu 16.04 or newer for WSL and Kleopatra. @@ -2283,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/ @@ -2614,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