I’ve been using USB security keys for SSH keys since 2015. I have switched from a generic brand to Yubikey about two years ago, mostly as part of gaining additional flexibility - both with types of keys (first USB keys only supported 1024, later 2048 byte sized RSA keys, I wanted 4096 and eventually decided I really like ed25519 ones) and available technologies.
I have recently upgraded my Yubikey 5 Nano key to a newer version. Actually, the key model (device itself) is exactly the same, but firmware version is newer and now supports ed25519 keys.
How I use Yubikeys for SSH
Here are a few important bits, they’re not necessarily representing best practices so please DO YOUR OWN RESEARCH if you’re not sure you want to configure keys the same way I do.
Keys in GnuPG assume expiration dates and even revocation - this means if you lost a key (or just lost access to the key), there’s a way to revoke it from use - meaning it’s not going to be trusted anymore.
Because I’m using Yubikey just for SSH access AND because I’m managing authorized_keys via Ansible for all my infrastructure, I tend not to use any certificates or revocation functionality. Instead, I simply revoke access myself - by making sure I remove old keys from authorized_keys on all my servers.
Always Buy From Yubikey Website
IMPORTANT: be sure to order Yubikey 5 Nano from Yubikey’s official webstore, otherwise you might end up buying a device with older firmware that you can’t upgrade yourself - meaning it will support RSA keys, but not ECC (ed25519) ones.
The firmware you need is 5.2.3 or later - my key has 5.2.7:
YubiKey 5 Nano - You Need Firmware 5.2.3+ to support ed25519
Install relevant tools in macOS
Let’s install GnuPG with SmartCard support for interfacing with the Yubikey:
Setting card defaults
We should be able to set card defaults now:
Let’s enter the admin mode:
and now reset the key to factory defaults, just in case:
Changing Default PINs in Yubikey
Before we forget: let’s change the default PIN numbers for the Yubikey.
Factory ones are: 123456 is the user PIN, and 12345678 is the admin PIN.
First it’s option 3 (change admin PIN), then option 1 (change user PIN):
Generating ed25519 Keys
While still in the admin mode, we must use the key-attr command to make sure we’ll generate ed25519 keys instead of the default RSA ones.
IMPORTANT: although it seems like the command is repeating itself, you’re actually configuring same settings for 3 different keys (notice how it says first ed25519, then cv25519, then ed25519 again in the output below). So please answer the same things (select ECC, then Curve 25519) three times in a row to get the same result I did.
Excellent! So we’re ready to actually generate the keys.
We’re done with key creation - type q to complete the session:
Using GPG agent with new Yubikey ed25519
Let’s start gnupg agent:
NOTE: I’m using ZSH and seems this command line isn’t 100% working, so if I don’t see SSH_AUTH_SOCK variable set - I just copy output from the above and paste it in my shell to set it:
we should be able to see our keys now (I’ve redacted the output a bit):
IMPORTANT: if you don’t see ED25519 at the end of this line, and instead see RSA - this means you didn’t complete the key-attr settings and need to redo the steps (all of them, starting with the factory-reset)
That’s it for now!
Please let me know if you follow this project and highlight any issues with it - I used the brand new Yubikey device, but kept previous macOS desktop which means some tools were already installed.