I recently bought a pair of Token2 FIDO2 hardware security keys. Those are USB/NFC devices to store cryptographic keys on and use them for authentication purposes on various services.

Beside the main purpose of serving as my Passkey supply I’ve set them up to be used for SSH authentication as well.

This is straightforward meanwhile if you meet the prerequisites of using a recent version of SSH (OpenSSH >= 8.3)

Technicalities

SSH authentication by means of cryptographic keys usually works with an asymmetric pair of keys as you might know from tools like PGP. You put your public key part on the server you want to log in to. When opening an SSH session to the server, you provide your private key to sign the authentication challenge given by the server. The server verifies it’s really you by checking the signature of the challenge with your public that you placed on the server earlier.

For the FIDO2 keys, this is slightly different. The private key on your machine is not actually stored on the FIDO2 key. Instead when you create an SSH key to be used with the FIDO2 key you create a reference (key handle) to the FIDO2 hardware key that acts as your private key part.

Generating the SSH Keypair

To make use of your FIDO2 key for SSH you have to generate a new SSH key pair which is associated to your FIDO2 hardware key.

ssh-keygen -t ed25519-sk -O resident -O verify-required -C “Comment”

the option -t ed25519-sk will tell SSH to generate a key using the Elliptic Curve cryptography algorithm. More specifically the ED25519 curve. The suffix “-sk” indicates that this will be a key handle associated with the FIDO authenticator.

the option -O resident tells SSH to store the key handle on the FIDO key itself, the option -O verify-required will require you to press the FIDO key when requested to confirm your physical presence. And finally -C "Comment" should be obviously the comment of the keypair.

putting your new SSH public key on the destination server

As with normal SSH key pairs you just add the contents of your public key to the ~/.ssh/authorized_keys file on the destination server. You can you the ssh-copy-id command for this:

➜  ~ ssh-copy-id -i .ssh/id_ed25519_sk fzurell@ubuntu-server.local
/usr/bin/ssh-copy-id: INFO: Source of key(s) to be installed: ".ssh/id_ed25519_sk.pub"
/usr/bin/ssh-copy-id: INFO: attempting to log in with the new key(s), to filter out any that are already installed
/usr/bin/ssh-copy-id: INFO: 1 key(s) remain to be installed -- if you are prompted now it is to install the new keys
fzurell@ubuntu-server.local's password:

Number of key(s) added:        1

Now try logging into the machine, with:   "ssh 'fzurell@ubuntu-server.local'"
and check to make sure that only the key(s) you wanted were added.

Now you should be able to

login to the remote machine using your passkey

Plug in your FIDO key token and start the ssh connection. You’ll be asked for the PIN of the hardware token to unlock the keystone before the key can be used. If your PIN is correct the token will start blinking and request you to touch it to prove your physical presence.

➜  ~ ssh fzurell@ubuntu-server.local
Confirm user presence for key ED25519-SK SHA256:kPV/1RoegAqy2PwNwYJwoPa5VQ3gDARcAbLIKVAAsGY
Enter PIN for ED25519-SK key /Users/zurell/.ssh/id_ed25519_sk:
Confirm user presence for key ED25519-SK SHA256:kPV/1RoegAqy2PwNwYJwoPa5VQ3gDARcAbLIKVAAsGY
User presence confirmed
Welcome to Ubuntu 24.04.1 LTS (GNU/Linux 6.8.0-48-generic x86_64)

 * Documentation:  https://help.ubuntu.com
 * Management:     https://landscape.canonical.com
 * Support:        https://ubuntu.com/pro

This system has been minimized by removing packages and content that are
not required on a system that users do not log into.

To restore this content, you can run the 'unminimize' command.
Last login: Wed Nov 13 13:52:23 2024 from 192.168.75.114
fzurell@ubuntu-server:~$

Using your key on a new machine

Now they you have set up your machine to make use of the FIDO2 key, you might want to use your key on another computer. Since it’s stored on your hardware token, you can use it from any machine without copying your private key onto multiple machines.

All you need to do is to create the respective key handle file and import the public key for your private key on the hardware token. This can be achieved with the ssh-keygen -K command.

➜ ~ ssh-keygen -K
Enter PIN for authenticator:
You may need to touch your authenticator to authorize key download.
Enter passphrase for "id_ed25519_sk_rk" (empty for no passphrase):
Enter same passphrase again:
Saved ED25519-SK key to id_ed25519_sk_rk

This will put two files in the local directory. The file id_ed25519_sk_rk is the password protected key handle file referencing your private key on the FIDO hardware token. The file id_ed25519_sk_rk.pub is the respective SSH PublicKey which you can share with your remote machines.

Your private key is still safely located on the hardware token. The mere key handle file alone can’t be used to establish an SSH connection to remove machines. It requires the hardware token as well.

Manage your Token2 PIN

To manage the PIN of your Token2 keys you can either use a Chrome-based browser or use the fido2-manage tool provided by Token2.

Update 20.03.2025 – Apple SSH is broken

I’ve just set up a new Mac with macOS Sonoma. Turns out the Apple provided ssh is broken. They’ve disabled the security key support.

Homebrew to the rescue. First install SSH from home-brew and then ssh-keygen -K will work.

With the Apple provided ssh I got the error message “Cannot download keys without provider”

Solution found here