Today, GitHub has announced support for using U2F and FIDO2 security keys for SSH, and we’re honored to have been an early collaborator in working with GitHub on developing this feature. This makes it easier than ever to use YubiKeys to secure all your GitHub access, making your SSH keys much more secure while maintaining a great user experience.

While it has long been possible to use the YubiKey for SSH via the OpenPGP or PIV features, the direct support in SSH is easier to set up, more portable, and works with any U2F or FIDO2 security key – even older ones like the FIDO U2F Security Key by Yubico. Let’s dive in!

Getting started

To get started you’ll need OpenSSH version 8.2 or later, and you’ll also need libfido2 installed. Windows users may need to use Cygwin for this.

First you’ll need to generate a key pair. Plug in your security key and run the command:

$ ssh-keygen -t ecdsa-sk

The option -t ecdsa-sk instructs OpenSSH to create an ECDSA key on a FIDO security key instead of a traditional private key file. You can also use -t ed25519-sk to create an EdDSA key instead, but this is not supported by all security keys.

This will create two files in your SSH directory. The first is id_ecdsa_sk.pub, which is a normal OpenSSH public key file whose contents you’ll need to paste into the new SSH key form on GitHub. The second is id_ecdsa_sk which would usually contain the corresponding private key, but in this case it instead contains a “key handle” that references the security key. You’ll need to copy the id_ecdsa_sk file to each computer where you want to use this SSH key. Or, if your security key supports it, you can use a FIDO2 resident key.

Using resident keys

If your security key supports FIDO2 resident keys*, like the YubiKey 5 Series, YubiKey 5 FIPS Series, or the Security Key NFC by Yubico, you can enable this when creating your SSH key:

$ ssh-keygen -t ecdsa-sk -O resident

This works the same as before, except a resident key is easier to import to a new computer because it can be loaded directly from the security key. To use the SSH key on a new computer, make sure you have ssh-agent running and simply run:

$ ssh-add -K

This will load a “key handle” into the SSH agent and make the key available for use on the new computer. This works great for short visits, but it won’t last forever – you’ll need to run ssh-add again if you reboot the computer, for example. To import the key permanently, instead run:

$ ssh-keygen -K

This will write two files into the current directory: id_ecdsa_sk_rk and id_ecdsa_sk_rk.pub. Now you just need to rename the private key file to id_ecdsa_sk and move it into your SSH directory:

$ mv id_ecdsa_sk_rk ~/.ssh/id_ecdsa_sk

Finally, there’s one more feature to be excited about…

Passwordless MFA

Passwordless multi-factor authentication is one of the greatest benefits of FIDO security keys, and it is now available for SSH too! If your security key supports FIDO2 user verification, like the YubiKey 5 Series, YubiKey 5 FIPS Series, or the Security Key NFC by Yubico, you can enable it when creating your SSH key:

$ ssh-keygen -t ecdsa-sk -O verify-required

This will configure the security key to require a PIN or other user authentication whenever you use this SSH key. Your SSH access is now protected with passwordless multi-factor authentication!

Yubico’s mission is to make the internet safer for everyone, and we are thrilled to have both GitHub and the OpenSSH project showing that you don’t have to choose between great security and ease of use. The technologies are still young, but we hope to see more SSH services offer these capabilities in the future.

For additional details, please read today’s blog from GitHub on this new functionality! 

* “Resident keys” have been renamed to “discoverable credentials” in the WebAuthn and CTAP standards, but OpenSSH still uses the “resident key” terminology.