DEV Community

Cover image for Using YubiKey resident keys for Git and SSH on macOS
Xavier Hurst
Xavier Hurst

Posted on • Updated on

Using YubiKey resident keys for Git and SSH on macOS

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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 Image description
  • -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:

Image description

  • 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.
  • 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
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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:

  1. Use ssh-add -K to load all resident keys from a YubiKey into your ssh-agent
  2. 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.

Image description

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


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.


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.


# Without `no-touch-required` option ...

# With `no-touch-required` option
no-touch-required ...
Enter fullscreen mode Exit fullscreen mode


Top comments (3)

juniel_katarn profile image
J • Edited

What exactly is psub?

Are you using a different shell than macOS's default (zsh)?

% psub
zsh: command not found: psub
Enter fullscreen mode Exit fullscreen mode

That command doesn't show up in homebrew search.

juniel_katarn profile image

Found my answer online.
psub is a fish shell command.

The following worked for me in Bash:

eval $(keychain --eval --noinherit -q)
Enter fullscreen mode Exit fullscreen mode
tw3n profile image
Xavier Hurst

Thank you for pointing this out. I've updated the post to address this question for future readers!