2022-12-21
OpenSSH 8.2 added support for registering and authenticating with FIDO2 Credentials, which is possible on YubiKey series 5 devices. When used for SSH operations, the sensitive part of your SSH key is moved from your computer to an external security key. To get started you’ll need OpenSSH version 8.2 or later, as well as libfido2.
Discoverable vs Non-Discoverable Credentials
Before generating a keypair, you should decide between discoverable (aka resident) or non-discoverable keys. Discoverable credentials means that the private key and associated metadata is stored in persistent memory on the device. For maximum security, choose non-discoverable as the credentials cannot be used if someone else were to steal the physical YubiKey. Non-Discoverable credentials will also require the private key to be stored within the ~/.ssh folder of the logged in user as well as the YubiKey.
Yubico has a great developer guide on this topic.
Configure YubiKey
Before creating new keys, optionally reset the FIDO application on the YubiKey. You can do this using the ykman command:
NOTE: THE FOLLOWING COMMAND IS DESTRUCTIVE - USE WITH CAUTION!
$ ykman fido reset
WARNING! This will delete all FIDO credentials, including FIDO U2F credentials, and restore factory settings. Proceed? [y/N]:
...Optionally set the PIN for FIDO (required if you want to force verification or manage credentials):
$ ykman fido access change-pin
Enter your new PIN:
...Configure Git
It can be trivial to save your private key on a physical machine, but this isn't secure. Generating keys, for a common use case as Git, is almost identical to the standard ssh-keygen workflow. However, there are a few additional things to note:
- The "sk" suffix (short for "security key") is appended to the type (
-t) value. E.g.ed25519-skorecdsa-sk. - There is a new option to create a discoverable (resident) key:
-O resident. - There is a new option to require the security key PIN in order to use the credentials:
-O verify-required. - Giving the key a name makes it more distinguishable when listing them from the YubiKey. E.g.
-O application=ssh:github.
To create a non-discoverable key without requiring verification, use the following command:
$ ssh-keygen -t ed25519-sk -C [email] -O application=ssh:github
Generating public/private ed25519-sk key pair.
You may need to touch your authenticator to authorize key generation.
$ ykman fido credentials list
Enter your PIN:
ssh:github 0000000000000000000000000000000000000000000000000000000000000000 openssh
$ ls ~/.ssh
...
id_ed25519_sk
id_ed25519_sk.pubYou should then be able to add the public key to GitHub and authenticate as usual, entering your PIN and/or touching the YubiKey when prompted:
$ ssh -T git@github.com
Confirm user presence for key ED25519-SK [key]
User presence confirmed
Hi [username]! You've successfully authenticated, but GitHub does not provide shell access.It's worth noting that some operations might require you to touch the YubiKey without bing prompted. When running commands such as git clone, the device light will blink if physical input is required.