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-skis the key type, two options are possible
skstands for security key). If you do not know which one to choose, stick with
-O application=ssh:*names the key, so you can identify it more easily later, very handy if you generate a few
-O no-touch-requiredprevents you from having to touch the YubiKey every time you want to use the key
-O residenttells OpenSSH to store the key on the YubiKey
Just like you would expect,
ssh-keygen created two files on your local machine:
id_ed25519_skis 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.pubis 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)
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:
ssh-add -Kto load all resident keys from a YubiKey into your
ssh-keygen -Kto download all resident keys from a YubiKey and write them to your current directory. In this scenario,
ssh-agentwill 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:
_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
Due to the current implementation of resident keys in OpenSSH, the
no-touch-requiredflag is not restored when importing keys from a YubiKey. This flag will only be available with the original private key handle.
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.
~/.ssh/authorized_keys # Without `no-touch-required` option firstname.lastname@example.org ... # With `no-touch-required` option no-touch-required email@example.com ...
Oldest comments (3)
What exactly is
Are you using a different shell than macOS's default (zsh)?
That command doesn't show up in
Found my answer online.
psubis a fish shell command.
The following worked for me in Bash:
Thank you for pointing this out. I've updated the post to address this question for future readers!