... | @@ -125,9 +125,11 @@ YubiKey and then use that key to authenticate to SSH servers. TPA may |
... | @@ -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
|
|
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).
|
|
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.
|
|
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
|
|
## SSH RSA authentication in PIV mode
|
|
|
|
|
|
This guide should be followed if you want to use SSH without depending
|
|
This guide should be followed if you want to use SSH without depending
|
... | @@ -214,6 +216,259 @@ regardless of purpose. For signatures, the operation is relatively |
... | @@ -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
|
|
similar to the [SSH guide above](#ssh-authentication-in-openpgp-mode), except there's no need to do any
|
|
SSH-specific configuration.
|
|
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
|
|
### Special considerations for storing encryption keys
|
|
|
|
|
|
For *encryption* keys, however, special care need to be taken as the
|
|
For *encryption* keys, however, special care need to be taken as the
|
... | @@ -471,13 +726,28 @@ the secret key material is available on the backup YubiKey. |
... | @@ -471,13 +726,28 @@ the secret key material is available on the backup YubiKey. |
|
|
|
|
|
## Other documentation
|
|
## 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/): U2F, keepass, LUKS, PIV and age support
|
|
* [A YubiKey cheatsheet](https://debugging.works/blog/yubikey-cheatsheet/)
|
|
* [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
|
|
* [TPA-RFC-53][] and [discussion ticket](https://gitlab.torproject.org/tpo/tpa/team/-/issues/41083)
|
|
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
|
|
* [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
|
|
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
|
|
[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
|
|
# Discussion
|
|
|
|
|
... | | ... | |