Skip to main content

Using YubiKeys In 2023

(updated )

I’ve been using a YubiKey 5C NFC for almost a year now and finally decided to get a second one to serve as a backup in case I lose my original key. Since I’ve just finished setting up my second YubiKey, I wanted to document my experiences in the hope that it would be useful for anyone thinking of using a YubiKey (or any FIDO2 compatible key).

Table of Contents

Setting The FIDO2 Pin

Before using the YubiKey for the use cases described below, you’ll have to set a FIDO2 pin for the YubiKey. This is a pin that you’ll be asked to enter before using an SSH key stored on the YubiKey or authenticating to a FIDO2 compatible website. Since physical possession of the YubiKey is required to use it, the pin doesn’t need to be as long as a traditional password.

Download the YubiKey manager to configure the FIDO2 pin as well as other settings for your YubiKey.

2FA Authentication

I hate the user experience of looking up a 6-digit code on my phone whenever I need to provide 2FA credentials, so this was one of the main reasons I wanted a YubiKey.

Enrolling the YubiKey as a 2FA method is straightforward for sites that support the use of FIDO2 authenticators: navigate to the website’s security settings page and look for security or hardware keys, touch the YubiKey when prompted and you’re set. I recommend enrolling two keys, a primary and a backup key in case you lose one of them.

Once enrolled, using the YubiKey for authentication is equally straightforward: touch the YubiKey when prompted and that’s it. I leave my YubiKey plugged in, so this is much nicer than looking up 2FA codes on my phone.

However, support for YubiKeys and other FIDO2 devices is still poor. Out of all my accounts, I was only able to use the YubiKey for Apple’s iCloud, Dropbox, Facebook, GitHub, Google, Microsoft, PayPal and Twitter.

The quality of FIDO2 support also varies. PayPal stands out for being the only service I’ve found that doesn’t allow the use of more than one key. Additionally, PayPal does not work with YubiKeys on iOS, forcing the use of authenticator apps as a fallback.

The YubiKey 5C NFC is compatible with iPhones via NFC. It took some trial and error to figure out how to get my phone to detect it. On my iPhone 14, I had to place it on the top centre edge of the phone screen for a few seconds. Apple Pay doesn’t require such close contact between the phone and payment terminal, so I expected that to be the case for the YubiKey.

SSH

OpenSSH 8.2 introduced support for FIDO2 devices. This means that you can generate SSH keypairs on devices like the YubiKey, with the private keys never leaving the device.

To generate a resident key backed by the YubiKey:

ssh-keygen -C 'YubiKey 5C NFC' -t ed25519-sk -O resident -f ~/.ssh/id_ed25519_sk

This generates the public key id_ed25519_sk.pub as usual. id_ed25519_sk is also generated but it does not contain the actual private key, but a pointer to the information stored on the YubiKey.

The -o resident argument generates a resident key, which makes it more convenient to transfer the keyfiles to another computer. To do so, use ssh-keygen -K with the YubiKey attached and the keyfiles should be generated on the new computer.

To log in via SSH with the YubiKey, touch the YubiKey when prompted and enter the Fido2 pin.

Forcing User Verification

OpenSSH 8.4 introduced the ability to require user verification to log into an SSH server via a security key. This means requiring the user to touch the key or enter a pin before logging in. Both the server and client must be running at least OpenSSH 8.4 for this to work.

To enable this, prefix the public key in ~/.ssh/authorized_keys with verify-required:

verify-required sk-ssh-ed25519@openssh.com AAAA...o= YubiKey 5C NFC

Windows

On Windows, SSH would not work with YubiKeys because the version of OpenSSH shipped with Windows is too old.

To fix this, install the latest release of Win32 OpenSSH.

WSL2

Using a YubiKey from WSL2 directly isn’t currently supported as the WSL2 kernel isn’t compiled with the required drivers.

It took me a long time to figure out how to work around this.

You can configure OpenSSH on WSL2 to use the host machine’s support for FIDO2. After installing the latest release of Win32 OpenSSH on the host machine, set the SSH_SK_HELPER variable in WSL2 to the path of the ssh-sk-helper.exe binary from Win32 OpenSSH on the windows host.

export SSH_SK_HELPER="/mnt/c/Program Files/OpenSSH/ssh-sk-helper.exe"

Git

Disable IDE Background Fetches

I used Vs Code and was having a strange problem: I would be prompted to touch my YubiKey every few minutes.

It turns out that VS Code and other IDEs automatically fetch the latest changes from the remote periodically. Since I was using an SSH key on the YubiKey to access the repository, I would need to manually allow each use of the SSH key.

In VS Code, change the git.autofetch setting to false to disable this behaviour.

Signing Git Commits

From Git 2.34.0, you can sign commits with SSH keys. This works with YubiKeys too.

To configure this:

# add the --global flag if needed
# switch to using ssh signatures
git config gpg.format ssh
# configure the key to use
git config user.signingKey '~/.ssh/id_ed25519_sk.pub'

# to force all future commits and tags to be signed
git config commit.gpgsign true
git config tag.gpgsign true

When showing commit signatures, Git will complain that the SSH signature could not be verified.

To fix this, create an allowed_signers file and add your public keys to it. The allowed_signers file should look like this:

<email> sk-ssh-ed25519@openssh.com AAA...o= YubiKey 5C NFC

Then configure Git to use this file with git config [--global] gpg.ssh.allowedSignersFile "/path/to/allowed_signers"

Once configured, you’ll be prompted to touch your YubiKey when signing a commit. This means that if you’re rebasing many commits, you will be asked to touch the YubiKey multiple times, once per commit.

Changing The SSH Binary In Git For Windows

The version of SSH in Git For Windows is too old and does not support FIDO2 keys.

Assuming that you’ve installed a recent release of Win32 OpenSSH in “C:/Program Files/OpenSSH”, configure Git to use the SSH binaries there instead of the built-in ones.

git config --global core.sshCommand "C:/Program Files/OpenSSH/ssh.exe"
git config --global gpg.ssh.program "C:/Program Files/OpenSSH/ssh-keygen.exe"

Conclusion

Overall, I’ve found the YubiKeys to be quite useful. Most of the difficulties I’ve had were caused by the lacking support for FIDO2 devices. This is something I hope will improve over time.

Additional Reading

For a much more detailed introduction on the YubiKey and its features, see “What the heck is a Yubikey and why did I buy one?”: A user guide