SSH Resident Key Guide

Initial checks

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

nix shell nixpkgs#yubikey-manager -c 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 YubiKey.

Evaluating additional authentication factors

Before generating a new ssh key to store on your 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 YubiKey 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 YubiKey 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 YubiKey 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 YubiKey and puts the private (still protected by YubiKey) 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 [email protected]

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.