document Yubikey form factors (team#41194)

howto/yubikey.md

@@ -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