Using YubiKey resident keys for Git and SSH on macOS
Tags: git, macos, security, tutorial
Published: 2022-10-19 16:07:01

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:

```sh
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:

```sh
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
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/y3qumra1wamrxh7c9a3g.png)
- `-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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/cluoqi8adsuxrmputkfr.png)

- `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](https://www.funtoo.org/Funtoo:Keychain) to run and manage our own agent from the version of OpenSSH we just installed.

```sh
brew install keychain
```

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

```sh
# 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:

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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/shh81bhl9s23izhf7vdz.png)

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 ...
```

## References
- [macOS: Enable security keys](https://github.com/apple-oss-distributions/OpenSSH/pull/1)
- [Gitea: Support for `no-touch-required`](https://github.com/go-gitea/gitea/issues/18416)
- [GitHub: Support for `no-touch-required`](https://github.com/community/community/discussions/10593)
- [GitLab: Support for FIDO2](https://gitlab.com/gitlab-org/gitlab/-/issues/213259)
- [no-touch-required flag not restored from hardware token](https://bugzilla.mindrot.org/show_bug.cgi?id=3355)
- [Securing SSH with FIDO2](https://developers.yubico.com/SSH/Securing_SSH_with_FIDO2.html)