Using YubiKey resident keys for Git and SSH on macOS

Xavier — Wed, 19 Oct 2022 16:07:01 +0000

I wanted to improve the security of my SSH keys, which are currently only protected by a passphrase. Likewise, I also wanted to ease their migration when I configure a new machine. I used resident keys and a YubiKey to do both.

Resident keys or discoverable credentials mean that the private key is stored in persistent memory on a FIDO authenticator like a YubiKey. This has two advantages. First, if the authenticator is not connected to the computer, the key cannot be used. Second, if you carry your authenticator with you, you can import the key on any machine that has a compatible version of OpenSSH (8.2 or above).

Yet, setting this up is more complex than it should be, at least on macOS.

Generating a resident key pair

The OpenSSH bundled with macOS can not generate resident keys, despite being compatible with them. This is due to a compilation flag that disables this option (--disable-security-key). To work around this, we'll install the latest version of OpenSSH using homebrew:

brew install openssh

Generating a resident key pair is quite similar to how you're used to generate and use SSH keys. The main difference is that the keys will be stored on the YubiKey (resident). Note that a YubiKey 5 can store up to 25 resident keys.

To store a resident key, the Yubikey must have firmware 5.2.3 or above and a PIN configured.

In a terminal window, type the following command:

ssh-keygen -t ed25519-sk -O application=ssh:personal -O no-touch-required -O resident

Let's dive into the different parameters.

-t ed25519-sk is the key type, two options are possible ecdsa-sk and ed25519-sk (sk stands for security key). If you do not know which one to choose, stick with ed25519-sk
-O application=ssh:* names the key, so you can identify it more easily later, very handy if you generate a few
-O no-touch-required prevents you from having to touch the YubiKey every time you want to use the key
-O resident tells OpenSSH to store the key on the YubiKey

Just like you would expect, ssh-keygen created two files on your local machine:

id_ed25519_sk is the private key. But, it's a key handle that can only be used with the YubiKey, making it unusable without it. The "real" private key is stored on the YubiKey. Meaning that you'll need to have the YubiKey plugged into your computer to be able to use it. The YubiKey, in this case, acts as a second authentication factor.
id_ed25519_sk.pub is the public key

Adding your SSH key to the ssh-agent

Even though we've installed the latest version of OpenSSH, the default ssh-agent bundled with macOS is still running. This agent is not capable of loading resident keys. To tackle this issue, we'll install Funtoo Keychain to run and manage our own agent from the version of OpenSSH we just installed.

brew install keychain

You now need to eval Keychain before you can load a resident key.

# In bash
eval $(keychain --eval --noinherit -q)

# In fish
source (keychain --eval --noinherit -q | psub)

That's it!

Importing your SSH key on another machine

One of the biggest advantages of resident keys is that they can be imported from a YubiKey. This allows you to securely transfer them from one computer to another. To do this, we have two options:

Use ssh-add -K to load all resident keys from a YubiKey into your ssh-agent
Use ssh-keygen -K to download all resident keys from a YubiKey and write them to your current directory. In this scenario, ssh-agent will be able to load the keys from your disk which is more suitable for permanent use.

As you can see, the downloaded key has an _rk_personal suffix. The rk part is there to remind you that it's a resident key, and personal is its name.

By default, OpenSSH will look for these paths to automatically load private keys:

~/.ssh/id_dsa
~/.ssh/id_ecdsa
~/.ssh/id_ecdsa_sk
~/.ssh/id_ed25519
~/.ssh/id_ed25519_sk
~/.ssh/id_rsa

Hence, _rk_personal must be removed from the filename for the key to be automatically loaded. If you want to keep this suffix, specify its path in your ~/.ssh/config.

Due to the current implementation of resident keys in OpenSSH, the no-touch-required flag is not restored when importing keys from a YubiKey. This flag will only be available with the original private key handle.

Using it

Git

Like normal ssh keys, resident keys are usable for git operations. Add the public key to your profile of your favorite git service and you're good to go.

At the time of writing, Gitea, GitHub and GitLab do not support no-touch-required. You'll have to touch the YubiKey for each git operation.

SSH

Using a resident key for SSH is the same as using a regular key. Add the public key to your authorized_keys and you’re good to go. If the resident key was generated with no-touch-required, prepend this option to the public key.

~/.ssh/authorized_keys

# Without `no-touch-required` option
sk-ssh-ed25519@openssh.com ...

# With `no-touch-required` option
no-touch-required sk-ssh-ed25519@openssh.com ...

DEV Community: Xavier

Using YubiKey resident keys for Git and SSH on macOS

Generating a resident key pair

Adding your SSH key to the ssh-agent

Importing your SSH key on another machine

Using it

Git

SSH

References