... | ... | @@ -15,8 +15,53 @@ USB form factor. |
|
|
|
|
|
# How to
|
|
|
|
|
|
* TODO: talk about form factors
|
|
|
* TODO: consider nylon vs steel for nano key rings
|
|
|
## Getting a security key
|
|
|
|
|
|
There is a wild variety of security keys out there. This guide focuses
|
|
|
on the YubiKey, but there are [alternatives](#other-alternatives) as well.
|
|
|
|
|
|
You may order a YubiKey directly from [their store](https://www.yubico.com/store/). You can also
|
|
|
ask TPA if they have any remaining keys although at the time of
|
|
|
writing, the whole stock was depleted at the 2023 Costa Rica meeting.
|
|
|
|
|
|
## Form factors
|
|
|
|
|
|
YubiKeys come mainly in two form factor axis:
|
|
|
|
|
|
1. USB-C or USB-A
|
|
|
2. "normal" or "nano"
|
|
|
|
|
|
The decision on USB-C vs USB-A should be relatively simple:
|
|
|
|
|
|
1. if you have older computers that do not have USB-C, or are worried
|
|
|
about backwards-compatibility, use USB-A.
|
|
|
|
|
|
2. if you want to go USB-C only, use USB-C, but be aware there's been
|
|
|
anecdotal reports of the USB-C form factor being more fragile than
|
|
|
the USB-A form (the connector can apparently get dented, although
|
|
|
other reports claim this has been fixed)
|
|
|
|
|
|
The decision between "normal" and "nano" depends mostly on how big you
|
|
|
like the key, but also how sturdy you expect it to be.
|
|
|
|
|
|
The author of this guide (@anarcat), has been wearing a YubiKey NEO
|
|
|
for over 8 years on his keyring. It has been dropped in water, slush,
|
|
|
sand, probably been in a laundry at least once, and has been worn out
|
|
|
quite significantly, up to the point that the connector is round
|
|
|
instead of square. It still works relatively reliably.
|
|
|
|
|
|
Another example is a YubiKey 5 "nano" that has had a part of it's
|
|
|
plastic case uncapped after only a few months of active use.
|
|
|
|
|
|
So it seems the sturdy one is the "normal" form factor, and that the
|
|
|
"nano" is designed to be stuck in a USB port and stay there.
|
|
|
|
|
|
Finally, also note that the USB-C "nano" form factor doesn't have a
|
|
|
hole to hook on a wire or keyring. The USB-A "nano" form factor *does*
|
|
|
have such a ring and Yubico [sells a lanyard](https://www.yubico.com/ca/product/yubico-keyport-parapull-lanyard/) to hook it up to your
|
|
|
keyring. The lanyard is 0.18" thick, so presumably any wire of that
|
|
|
gauge (AWG ~5 or SWG 6-7) would fit as well. Note that a metal wire
|
|
|
might wear out faster, consider a [fishing line](https://en.wikipedia.org/wiki/Fishing_line) (e.g. Nylon).
|
|
|
|
|
|
## YubiKey training
|
|
|
|
... | ... | @@ -669,6 +714,12 @@ operation (sign, authenticate, decrypt) will hang without warning |
|
|
until the button is touched. The only indication is the blinking LED,
|
|
|
there's no other warning from the user interface.
|
|
|
|
|
|
Also note that the PIN itself is cached by the YubiKey, *not* the
|
|
|
agent. There is a [wishlist item](https://dev.gnupg.org/T3362) on GnuPG to expire the password
|
|
|
after a delay, respecting the `default-cache-ttl` and `max-cache-ttl`
|
|
|
settings from `gpg-agent.conf`, but alas this do not currently take
|
|
|
effect.
|
|
|
|
|
|
### Making a second YubiKey copy
|
|
|
|
|
|
At this point, we have a backup of the keyring that is encrypted with
|
... | ... | @@ -772,56 +823,72 @@ This procedure should be enough to get you started on a new machine. |
|
|
gpg --clearsign < /dev/null
|
|
|
gpg --encrypt -r $FINGERPRINT < /dev/null | gpg --decrypt
|
|
|
|
|
|
### git
|
|
|
|
|
|
git config --global user.signingkey $FINGERPRINT
|
|
|
git config --global commit.gpgsign true
|
|
|
|
|
|
### agent setup
|
|
|
### Agent setup
|
|
|
|
|
|
TODO: agent setup, varies wildly
|
|
|
At this point, GnuPG is likely working well enough for OpenPGP
|
|
|
operations. If you want to use it for OpenSSH as well, however, you'll
|
|
|
need to replace the built-in SSH agent with `gpg-agent`.
|
|
|
|
|
|
TODO: talk about gnome keyring agent, see [this guide for how to turn
|
|
|
it off](https://gist.github.com/artizirk/d09ce3570021b0f65469cb450bee5e29#permanent)
|
|
|
The right configuration for this is tricky, and may vary wildly
|
|
|
depending on your operating system, graphical and desktop
|
|
|
environment.
|
|
|
|
|
|
The [Ultimate Yubikey Setup Guide with ed25519!][] suggests:
|
|
|
The [Ultimate Yubikey Setup Guide with ed25519!][] suggests adding
|
|
|
this to your environment:
|
|
|
|
|
|
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))
|
|
|
If you are running a version before GnuPG 2.1 (and you really
|
|
|
shouldn't), you will also need:
|
|
|
|
|
|
use-standard-socket
|
|
|
|
|
|
default-cache-ttl 60
|
|
|
max-cache-ttl 120
|
|
|
Then you can restart `gpg-agent` with:
|
|
|
|
|
|
gpgconf --kill gpg-agent
|
|
|
gpgconf --launch gpg-agent
|
|
|
|
|
|
If you're on a Mac, you'll also need:
|
|
|
|
|
|
pinentry-program /usr/local/bin/pinentry-mac
|
|
|
|
|
|
In GNOME, there's a [keyring agent](https://wiki.gnome.org/Projects/GnomeKeyring) which also [includes an SSH
|
|
|
agent](https://wiki.gnome.org/Projects/GnomeKeyring/Ssh), see [this guide for how to turn it off](https://gist.github.com/artizirk/d09ce3570021b0f65469cb450bee5e29#permanent).
|
|
|
|
|
|
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.
|
|
|
|
|
|
### exporting SSH public key from GnuPG
|
|
|
### Exporting SSH public keys from GnuPG
|
|
|
|
|
|
Newer GnuPG has this:
|
|
|
|
|
|
gpg --export-ssh-key $FINGERPRINT
|
|
|
|
|
|
In older, you can also use:
|
|
|
You can also use the more idiomatic:
|
|
|
|
|
|
ssh-add -L
|
|
|
|
|
|
### preliminary performance evaluation
|
|
|
... assuming the key has been used at least once.
|
|
|
|
|
|
### Signed Git commit messages
|
|
|
|
|
|
To sign Git commits with OpenPGP, you can use the following configuration:
|
|
|
|
|
|
git config --global user.signingkey $FINGERPRINT
|
|
|
git config --global commit.gpgsign true
|
|
|
|
|
|
Git should be able to find GnuPG and will transparently use the
|
|
|
YubiKey to sign commits
|
|
|
|
|
|
### Preliminary performance evaluation
|
|
|
|
|
|
Preparation:
|
|
|
|
... | ... | @@ -855,7 +922,7 @@ configuration. An acceptable compromise, perhaps. |
|
|
|
|
|
### Troubleshooting
|
|
|
|
|
|
If an opreation fails, check if GnuPG can see the card with:
|
|
|
If an operation fails, check if GnuPG can see the card with:
|
|
|
|
|
|
gpg --card-status
|
|
|
|
... | ... | @@ -893,6 +960,11 @@ can completely wipe the OpenPGP applet with: |
|
|
WARNING: that will WIPE all the keys on the device, make sure you have
|
|
|
a backup or that the keys are revoked!
|
|
|
|
|
|
If GnuPG doesn't pop up a dialog prompting you for a password, you
|
|
|
might have an incorrect `TTY` variable. Try to kick `gpg-agent` with:
|
|
|
|
|
|
gpg-connect-agent updatestartuptty /bye
|
|
|
|
|
|
See also [drduh's troubleshooting guide](https://github.com/drduh/YubiKey-Guide#troubleshooting).
|
|
|
|
|
|
## FAQ
|
... | ... | |