Loading howto/yubikey.md +274 −4 Original line number Diff line number Diff line Loading @@ -125,9 +125,11 @@ YubiKey and then use that key to authenticate to SSH servers. TPA may eventually sublime this rather long guide in a simpler version specifically tailored for you, possibly based on [anarcat's guide](https://anarc.at/blog/2015-12-14-yubikey-howto/#configuring-a-pin). Also review the [Ultimate Yubikey Setup Guide with ed25519!](https://zach.codes/ultimate-yubikey-setup-guide/) and Also review the [Ultimate Yubikey Setup Guide with ed25519!][] and the [other documentation](#other-documentation) section. [Ultimate Yubikey Setup Guide with ed25519!]: https://zach.codes/ultimate-yubikey-setup-guide/ ## SSH RSA authentication in PIV mode This guide should be followed if you want to use SSH without depending Loading Loading @@ -214,6 +216,259 @@ regardless of purpose. For signatures, the operation is relatively similar to the [SSH guide above](#ssh-authentication-in-openpgp-mode), except there's no need to do any SSH-specific configuration. WARNING: this is just a collection of notes, a draft that @anarcat is working on and which will hopefully evolve in a cohesive (and tested) guide. TODO: merge with the above SSH guide? TODO: give background, why, talk about the stack Stack, from hardware up to server 1. Yubikey 2. scdaemon 3. gpg-agent 4. gpg | ssh Assertions * entropy, failing that, this can feed entropy from the YK (from [drduh's guide](https://github.com/drduh/YubiKey-Guide#yubikey)): echo "SCD RANDOM 512" | gpg-connect-agent | sudo tee /dev/random | hexdump -C * trusted device ### Install software and preparation apt install gnupg scdaemon yubikey-manager If you're on a Mac, you'll also need to explicitly install `pinentry-mac`, see the [Ultimate Yubikey Setup Guide with ed25519!][] If you're on Windows, good luck, maybe [this section of drduh's guide](https://github.com/drduh/YubiKey-Guide#windows-1) can help you. Make sure the key is detected: ykman list This should show your key, for example this is with my old NEO: $ ykman list YubiKey NEO (3.4.3) [OTP+FIDO+CCID] $ Make sure the right things are enabled: $ ykman info Device type: YubiKey NEO Firmware version: 3.0.0 Form factor: Keychain (USB-A) Enabled USB interfaces: OTP, FIDO, CCID NFC transport is enabled. Applications USB NFC FIDO2 Not available Not available OTP Enabled Enabled FIDO U2F Enabled Enabled OATH Enabled Enabled YubiHSM Auth Not available Not available OpenPGP Enabled Enabled PIV Enabled Enabled TODO: check with an actual YK5. TODO: talk about applications, TL;DR: ykman config mode FIDO+CCID TODO: check what those do from [Ultimate Yubikey Setup Guide with ed25519!][] ykman openpgp set-touch aut cached ykman openpgp set-touch sig on ykman openpgp set-touch enc on TODO: pin change ykman TODO: wtf is a management key, see https://developers.yubico.com/yubikey-piv-manager/PIN_and_Management_Key.html and https://gist.github.com/xirkus/20552a9b026413cc84191131bbeeb48a#yubikeys-default-state-of-insecurity TODO: wtf all PINs, see [drduh's guide](https://github.com/drduh/YubiKey-Guide#change-pin) which talks about [the reset pin](https://forum.yubico.com/viewtopicd01c.html?p=9055#p9055) TODO: consider YK KDF, see [drduh's guide](https://github.com/drduh/YubiKey-Guide#enable-kdf): gpg --card-edit gpg/card> admin gpg/card> kdf-setup ### key generation Here we're generating a new OpenPGP key as we're transitioning from an old RSA4096 key. DO NOT follow those steps if you wish to keep your old key, of course. TODO: consider batch mode, see https://www.gnupg.org/documentation/manuals/gnupg/Unattended-GPG-key-generation.html and https://github.com/drduh/YubiKey-Guide/blob/master/contrib/gen-params-rsa4096 TODO: talk about airgapped systems and tmpfs TODO: talk about why not generating on the key GNUPGHOME=${XDG_RUNTIME_DIR:-/nonexistent} gpg --full-gen-key # TODO: --expert? FINGERPRINT=0000000000000000000000000000000000000000 TODO: talk about expiration date TODO: how to generate a SC, A E key and why (because 3 slots and screw S vs C) TODO: talk about ed25519, debunk EC concerns in [this gist](https://gist.github.com/xirkus/20552a9b026413cc84191131bbeeb48a) as we're not ecdsa, we're ed25519 TODO: lint key with `hokey lint`, from [drduh's guide](https://github.com/drduh/YubiKey-Guide#verify) Sign the new key with old key: gpg --default-key $OLDKEY --sign-key $FINGERPRINT Revoke the old key: gpg --generate-revocation $OLDKEY Do not publish the revocation certificate just yet, in case the procedure fails. TODO: Generate a revocation cert for the new key as well, talk about printing and OCR? TODO: move this entire section to howto/openpgp? ### export to backup gpg --export-secret-keys $FINGERPRINT > secret.key gpg --export-secret-subkeys $FINGERPRINT > secret-subkeys.key gpg --export $FINGERPRINT > public.key TODO: consider LUKS? or plain text? filesystem? exfat? SSSS? rejected [drduh's LUKS approach](https://github.com/drduh/YubiKey-Guide#backup) ### moving to key WARNING: this MOVES the key to the security card, make sure you have backups as explained above. gpg --edit-key $FINGERPRINT then, for N in 1,2,3: key $N keytocard Then keys should *not* be present in the keyring: gpg --list-secret-keys `sec>`, not `sec`. #### troubleshooting if this fails, check if GnuPG can see the card: gpg-connect-agent --hex "scd apdu 00 f1 00 00" /bye For example, this is the output when successfully connecting to an old Yubikey NEO running the 1.10 firmware: gpg-connect-agent --hex "scd apdu 00 f1 00 00" /bye D[0000] 05 01 00 90 00 ..... OK The `OK` means it can talk to the key correctly. Here's an example with a Yubikey 5 (TODO: confirm output): gpg-connect-agent --hex "scd apdu 00 f1 00 00" /bye D[0000] 05 01 00 90 00 ..... OK Possible error: ERR 100663404 Card error <SCD> TODO: need `scdaemon`? see my own howto TODO: maybe just do `gpg --card-status` instead? ### git git config --global user.signingkey $FINGERPRINT git config --global commit.gpgsign true ### agent setup TODO: agent setup varies wildly TODO: talk about gnome keyring agent, see [this guide for how to turn it off](https://gist.github.com/artizirk/d09ce3570021b0f65469cb450bee5e29#permanent) the [Ultimate Yubikey Setup Guide with ed25519!][] suggests: export "GPG_TTY=$(tty)" export "SSH_AUTH_SOCK=${HOME}/.gnupg/S.gpg-agent.ssh" gpgconf --launch gpg-agent and this in `~/.gnupg/gpg-agent.conf`: use-standard-socket enable-ssh-support TODO: talk about TTLs (apparently doesn't apply with yk with pins, according to [drduh](https://github.com/drduh/YubiKey-Guide#create-configuration)) default-cache-ttl 60 max-cache-ttl 120 If you're on a Mac, you'll also need: pinentry-program /usr/local/bin/pinentry-mac At this point, SSH should be able to see the key: ssh-add -L If not, make sure `SSH_AUTH_SOCK` is pointing at the GnuPG agent. TODO: recovery on new computer, basically import and trust, see [drduh's guide](https://github.com/drduh/YubiKey-Guide#using-keys) TODO: recovery from backups (--import secrets in tmp keyring, keytocard) see also [Recovering lost GPG public keys from your YubiKey – Nicholas Sherlock create](https://www.nicksherlock.com/2021/08/recovering-lost-gpg-public-keys-from-your-yubikey/) if even public key is missing. TODO: `ykman openpgp reset` TODO: https://github.com/drduh/YubiKey-Guide#troubleshooting ### exporting SSH public key from GnuPG Newer GnuPG has this: gpg --export-ssh-key $FINGERPRINT In older, you can also use: ssh-add -L ### Special considerations for storing encryption keys For *encryption* keys, however, special care need to be taken as the Loading Loading @@ -471,13 +726,28 @@ the secret key material is available on the backup YubiKey. ## Other documentation * [Anarcat's old (2015) YubiKey howto](https://anarc.at/blog/2015-12-14-yubikey-howto/) * [A YubiKey cheatsheet](https://debugging.works/blog/yubikey-cheatsheet/) * [TPA-RFC-53][] and [discussion ticket](https://gitlab.torproject.org/tpo/tpa/team/-/issues/41083) * [A YubiKey cheatsheet](https://debugging.works/blog/yubikey-cheatsheet/): U2F, keepass, LUKS, PIV and age support * [Yubikey + OpenPGP guide](https://support.yubico.com/hc/en-us/articles/360013790259-Using-Your-YubiKey-with-OpenPGP), [another](https://developers.yubico.com/PGP/Importing_keys.html): basic configuration from Yubico * [Ultimate Yubikey Setup Guide with ed25519!][]: simple and straightforward guide, Mac-oriented * [drduh's YubiKey Guide][]: excellent guide, very (too?) detailed, includes instructions on air-gapped systems, LUKS-encrypted backups * [Yubikey + GnuPG + SSH howto][]: good guide, but also confusingly drifts into PIV * [Artizik: OpenPGP SSH access with Yubikey and GnuPG](https://gist.github.com/artizirk/d09ce3570021b0f65469cb450bee5e29): recommends `pcscd` needlessly, drifts into other GnuPG configuration but used for ideas on how to turn off GNOME keyring, might be relevant for Estonians needing to have their key work in parallel with the national key ID * [Anarcat's old (2015) YubiKey howto](https://anarc.at/blog/2015-12-14-yubikey-howto/): GnuPG, SSH, OATH * [Recovering lost GPG public keys from your YubiKey – Nicholas Sherlock create](https://www.nicksherlock.com/2021/08/recovering-lost-gpg-public-keys-from-your-yubikey/) - untested * [TPA-RFC-53][] and [discussion ticket](https://gitlab.torproject.org/tpo/tpa/team/-/issues/41083) [TPA-RFC-53]: policy/tpa-rfc-53-security-keys [Yubikey + GnuPG + SSH howto]: https://gist.github.com/xirkus/20552a9b026413cc84191131bbeeb48a [drduh's YubiKey Guide]: https://github.com/drduh/YubiKey-Guide # Discussion Loading Loading
howto/yubikey.md +274 −4 Original line number Diff line number Diff line Loading @@ -125,9 +125,11 @@ YubiKey and then use that key to authenticate to SSH servers. TPA may eventually sublime this rather long guide in a simpler version specifically tailored for you, possibly based on [anarcat's guide](https://anarc.at/blog/2015-12-14-yubikey-howto/#configuring-a-pin). Also review the [Ultimate Yubikey Setup Guide with ed25519!](https://zach.codes/ultimate-yubikey-setup-guide/) and Also review the [Ultimate Yubikey Setup Guide with ed25519!][] and the [other documentation](#other-documentation) section. [Ultimate Yubikey Setup Guide with ed25519!]: https://zach.codes/ultimate-yubikey-setup-guide/ ## SSH RSA authentication in PIV mode This guide should be followed if you want to use SSH without depending Loading Loading @@ -214,6 +216,259 @@ regardless of purpose. For signatures, the operation is relatively similar to the [SSH guide above](#ssh-authentication-in-openpgp-mode), except there's no need to do any SSH-specific configuration. WARNING: this is just a collection of notes, a draft that @anarcat is working on and which will hopefully evolve in a cohesive (and tested) guide. TODO: merge with the above SSH guide? TODO: give background, why, talk about the stack Stack, from hardware up to server 1. Yubikey 2. scdaemon 3. gpg-agent 4. gpg | ssh Assertions * entropy, failing that, this can feed entropy from the YK (from [drduh's guide](https://github.com/drduh/YubiKey-Guide#yubikey)): echo "SCD RANDOM 512" | gpg-connect-agent | sudo tee /dev/random | hexdump -C * trusted device ### Install software and preparation apt install gnupg scdaemon yubikey-manager If you're on a Mac, you'll also need to explicitly install `pinentry-mac`, see the [Ultimate Yubikey Setup Guide with ed25519!][] If you're on Windows, good luck, maybe [this section of drduh's guide](https://github.com/drduh/YubiKey-Guide#windows-1) can help you. Make sure the key is detected: ykman list This should show your key, for example this is with my old NEO: $ ykman list YubiKey NEO (3.4.3) [OTP+FIDO+CCID] $ Make sure the right things are enabled: $ ykman info Device type: YubiKey NEO Firmware version: 3.0.0 Form factor: Keychain (USB-A) Enabled USB interfaces: OTP, FIDO, CCID NFC transport is enabled. Applications USB NFC FIDO2 Not available Not available OTP Enabled Enabled FIDO U2F Enabled Enabled OATH Enabled Enabled YubiHSM Auth Not available Not available OpenPGP Enabled Enabled PIV Enabled Enabled TODO: check with an actual YK5. TODO: talk about applications, TL;DR: ykman config mode FIDO+CCID TODO: check what those do from [Ultimate Yubikey Setup Guide with ed25519!][] ykman openpgp set-touch aut cached ykman openpgp set-touch sig on ykman openpgp set-touch enc on TODO: pin change ykman TODO: wtf is a management key, see https://developers.yubico.com/yubikey-piv-manager/PIN_and_Management_Key.html and https://gist.github.com/xirkus/20552a9b026413cc84191131bbeeb48a#yubikeys-default-state-of-insecurity TODO: wtf all PINs, see [drduh's guide](https://github.com/drduh/YubiKey-Guide#change-pin) which talks about [the reset pin](https://forum.yubico.com/viewtopicd01c.html?p=9055#p9055) TODO: consider YK KDF, see [drduh's guide](https://github.com/drduh/YubiKey-Guide#enable-kdf): gpg --card-edit gpg/card> admin gpg/card> kdf-setup ### key generation Here we're generating a new OpenPGP key as we're transitioning from an old RSA4096 key. DO NOT follow those steps if you wish to keep your old key, of course. TODO: consider batch mode, see https://www.gnupg.org/documentation/manuals/gnupg/Unattended-GPG-key-generation.html and https://github.com/drduh/YubiKey-Guide/blob/master/contrib/gen-params-rsa4096 TODO: talk about airgapped systems and tmpfs TODO: talk about why not generating on the key GNUPGHOME=${XDG_RUNTIME_DIR:-/nonexistent} gpg --full-gen-key # TODO: --expert? FINGERPRINT=0000000000000000000000000000000000000000 TODO: talk about expiration date TODO: how to generate a SC, A E key and why (because 3 slots and screw S vs C) TODO: talk about ed25519, debunk EC concerns in [this gist](https://gist.github.com/xirkus/20552a9b026413cc84191131bbeeb48a) as we're not ecdsa, we're ed25519 TODO: lint key with `hokey lint`, from [drduh's guide](https://github.com/drduh/YubiKey-Guide#verify) Sign the new key with old key: gpg --default-key $OLDKEY --sign-key $FINGERPRINT Revoke the old key: gpg --generate-revocation $OLDKEY Do not publish the revocation certificate just yet, in case the procedure fails. TODO: Generate a revocation cert for the new key as well, talk about printing and OCR? TODO: move this entire section to howto/openpgp? ### export to backup gpg --export-secret-keys $FINGERPRINT > secret.key gpg --export-secret-subkeys $FINGERPRINT > secret-subkeys.key gpg --export $FINGERPRINT > public.key TODO: consider LUKS? or plain text? filesystem? exfat? SSSS? rejected [drduh's LUKS approach](https://github.com/drduh/YubiKey-Guide#backup) ### moving to key WARNING: this MOVES the key to the security card, make sure you have backups as explained above. gpg --edit-key $FINGERPRINT then, for N in 1,2,3: key $N keytocard Then keys should *not* be present in the keyring: gpg --list-secret-keys `sec>`, not `sec`. #### troubleshooting if this fails, check if GnuPG can see the card: gpg-connect-agent --hex "scd apdu 00 f1 00 00" /bye For example, this is the output when successfully connecting to an old Yubikey NEO running the 1.10 firmware: gpg-connect-agent --hex "scd apdu 00 f1 00 00" /bye D[0000] 05 01 00 90 00 ..... OK The `OK` means it can talk to the key correctly. Here's an example with a Yubikey 5 (TODO: confirm output): gpg-connect-agent --hex "scd apdu 00 f1 00 00" /bye D[0000] 05 01 00 90 00 ..... OK Possible error: ERR 100663404 Card error <SCD> TODO: need `scdaemon`? see my own howto TODO: maybe just do `gpg --card-status` instead? ### git git config --global user.signingkey $FINGERPRINT git config --global commit.gpgsign true ### agent setup TODO: agent setup varies wildly TODO: talk about gnome keyring agent, see [this guide for how to turn it off](https://gist.github.com/artizirk/d09ce3570021b0f65469cb450bee5e29#permanent) the [Ultimate Yubikey Setup Guide with ed25519!][] suggests: export "GPG_TTY=$(tty)" export "SSH_AUTH_SOCK=${HOME}/.gnupg/S.gpg-agent.ssh" gpgconf --launch gpg-agent and this in `~/.gnupg/gpg-agent.conf`: use-standard-socket enable-ssh-support TODO: talk about TTLs (apparently doesn't apply with yk with pins, according to [drduh](https://github.com/drduh/YubiKey-Guide#create-configuration)) default-cache-ttl 60 max-cache-ttl 120 If you're on a Mac, you'll also need: pinentry-program /usr/local/bin/pinentry-mac At this point, SSH should be able to see the key: ssh-add -L If not, make sure `SSH_AUTH_SOCK` is pointing at the GnuPG agent. TODO: recovery on new computer, basically import and trust, see [drduh's guide](https://github.com/drduh/YubiKey-Guide#using-keys) TODO: recovery from backups (--import secrets in tmp keyring, keytocard) see also [Recovering lost GPG public keys from your YubiKey – Nicholas Sherlock create](https://www.nicksherlock.com/2021/08/recovering-lost-gpg-public-keys-from-your-yubikey/) if even public key is missing. TODO: `ykman openpgp reset` TODO: https://github.com/drduh/YubiKey-Guide#troubleshooting ### exporting SSH public key from GnuPG Newer GnuPG has this: gpg --export-ssh-key $FINGERPRINT In older, you can also use: ssh-add -L ### Special considerations for storing encryption keys For *encryption* keys, however, special care need to be taken as the Loading Loading @@ -471,13 +726,28 @@ the secret key material is available on the backup YubiKey. ## Other documentation * [Anarcat's old (2015) YubiKey howto](https://anarc.at/blog/2015-12-14-yubikey-howto/) * [A YubiKey cheatsheet](https://debugging.works/blog/yubikey-cheatsheet/) * [TPA-RFC-53][] and [discussion ticket](https://gitlab.torproject.org/tpo/tpa/team/-/issues/41083) * [A YubiKey cheatsheet](https://debugging.works/blog/yubikey-cheatsheet/): U2F, keepass, LUKS, PIV and age support * [Yubikey + OpenPGP guide](https://support.yubico.com/hc/en-us/articles/360013790259-Using-Your-YubiKey-with-OpenPGP), [another](https://developers.yubico.com/PGP/Importing_keys.html): basic configuration from Yubico * [Ultimate Yubikey Setup Guide with ed25519!][]: simple and straightforward guide, Mac-oriented * [drduh's YubiKey Guide][]: excellent guide, very (too?) detailed, includes instructions on air-gapped systems, LUKS-encrypted backups * [Yubikey + GnuPG + SSH howto][]: good guide, but also confusingly drifts into PIV * [Artizik: OpenPGP SSH access with Yubikey and GnuPG](https://gist.github.com/artizirk/d09ce3570021b0f65469cb450bee5e29): recommends `pcscd` needlessly, drifts into other GnuPG configuration but used for ideas on how to turn off GNOME keyring, might be relevant for Estonians needing to have their key work in parallel with the national key ID * [Anarcat's old (2015) YubiKey howto](https://anarc.at/blog/2015-12-14-yubikey-howto/): GnuPG, SSH, OATH * [Recovering lost GPG public keys from your YubiKey – Nicholas Sherlock create](https://www.nicksherlock.com/2021/08/recovering-lost-gpg-public-keys-from-your-yubikey/) - untested * [TPA-RFC-53][] and [discussion ticket](https://gitlab.torproject.org/tpo/tpa/team/-/issues/41083) [TPA-RFC-53]: policy/tpa-rfc-53-security-keys [Yubikey + GnuPG + SSH howto]: https://gist.github.com/xirkus/20552a9b026413cc84191131bbeeb48a [drduh's YubiKey Guide]: https://github.com/drduh/YubiKey-Guide # Discussion Loading
