SSH Resident Key Guide

guide.md

General Note

Make sure to check out NitroKeys, OnlyKeys or SoloKeys. They are based on open-source hardware and firmware while YubiKey's are closed source. ssh-keygen is able to generate FIDO authenticator-backed keys which can be either an ecdsa-sk or an ed25519-sk key-pair. The sk extension stands for security key. Note that an ed25519-sk key-pair is only supported by new YubiKeys with firmware 5.2.3 or higher which supports FIDO2. This means YubiKeys with firmware below 5.2.3 are only compatible with ecdsa-sk key-pairs. If possible, generate an ed25519-sk SSH key-pair for this reason.

We can check the firmware version of a YubiKey with the following command.

$ lsusb -v 2>/dev/null | grep -A2 Yubico | grep "bcdDevice" | awk '{print $2}'

4.37

Initial checks

Set up FIDO PIN, this is the PIN entered via keyboard and used for FIDO2 register/login.

~$ onlykey-cli set-pin
~$ ykman fido access change-pin --new-pin

Start by checking that there aren't any previous ssh keys inside the FIDO2 authenticator of your OnlyKey or YubiKey. You can check if they exist by running the command below:

~$ onlykey-cli credential ls
~$ ykman fido credentials list

If the command above outputs a string mentioning "ssh" or "openssh", then you have already got a key generated and store on your OnlyKey or YubiKey.

Evaluating additional authentication factors

Before generating a new ssh key to store on your OnlyKey or YubiKey you must consider which additional required authentication factors you want to use. Below you can see a table with the available factors and their corresponding command:

Factors	Description	Command
No PIN or touch are required	You will not be required to enter your FIDO2 PIN or touch your *Key each time to authenticate	ssh-keygen -t ed25519-sk -O resident -O no-touch-required
PIN but no touch required	Entering the PIN will be required but touching the physical key will not	ssh-keygen -t ed25519-sk -O resident -O verify-required -O no-touch-required
No PIN but touch is required	You will only need to touch the *Key to authenticate	ssh-keygen -t ed25519-sk -O resident
A PIN and a touch are required (most secure)	This is the most secure option, it requires both the PIN and touching to be used	ssh-keygen -t ed25519-sk -O resident -O verify-required

Generating the key

Once you've decided which option fits best for your threat model you will need to run one of the commands above. Note that if using a PIN you don't need to add an additional ssh passphrase as it's redundant due to the FIDO2 PIN being used instead. I personally went with the last and most secure option so the command I used to generate the key was:

ssh-keygen -t ed25519-sk -O resident -O verify-required

Adding the new keys

Now that you have generated a key which you can use, you will need to add it to your current ssh-agent session. You can do that by first starting the agent like so:

eval "$(ssh-agent -s)"

Then add the key on the FIDO U2F security key with the command below:

ssh-add -K

You can verify that the key was added by listing all the keys available in the current ssh-agent session:

ssh-add -l

We just added our brand new ssh key temporarily to our current session. If you would like to have it permanently available on the system you can run the command:

ssh-keygen -K

This retrieves our ssh key from our FIDO U2F security key and puts the private (still protected by FIDO authenticator) and public key in the current working directory. You must now rename them accordingly to id_ed25519_sk and id_ed25519_sk.pub and place them in your ~/.ssh directory so ssh can detect them.

Authenticating with GitHub

In order to authenticate with GitHub you will have to add your new public key to your GitHub profile over at -> github.com/settings/keys. You can retrieve the keypair by running

ssh-keygen -K

and copy the public key directly from the newly added files to the current folder, for example, id_ed25519_sk_rk.pub.

Testing authentication

Now that we've added our ssh key to GitHub we can test that the setup works correctly by running:

ssh -T git@github.com

If this worked correctly you should be greeted by a "welcoming message".

NOTE: In order to make sure that you are using the new SSH key consider moving out existing keys from the ~/.ssh directory just for this test.