Securing SSH with FIDO2

Staring with 8.2p1, OpenSSH has added support for registering and authenticating with FIDO2 Credentials. With support for both Discoverable and Non-Discoverable Credentials, OpenSSH allows for the uses of both Security Keys and YubiKeys.

Configuring OpenSSH to support FIDO2 credentials requires configuration on both the client and server. Further, slightly different settings are required depending if a Discoverable or Non-Discoverable credential is being used.

OpenSSH with support for FIDO2 credentials is avalible on Linux and MacOS, but not yet on Windows.

Discoverable vs Non-Discoverable Credentials

Before configurating an OpenSSH server or Client for FIDO2 credentials, the decision must be reached as whether to use Discoverable or Non-Discoverable credentials. Either option has different strengths, and the best option depends on the environment SSH is being used in.

Depending on the version of OpenSSH in use, the choice between Discoverable and non-Discoverable keys may not exist. Discoverable credentials require OpenSSH 8.3, while non-discoverable credentials only require OpenSSH 8.2p1. 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. If using a publicly accesable endpoint, it is not recommened to use non-Discoverable credentials for this reason.

Benefits of Non-discoverable keys:
  • Cannot be used by another person if the YubiKey is found

  • Ideal for higher security systems

Benefits of Discoverable keys:
  • Can be taken to any compatible workstation and used to authenticate by touch and FIDO2 PIN

  • Ideal for ease of access where the PIN is known

Setting up OpenSSH for FIDO2 Authentication

Regardless of which credential options is selected, there are some prerequisites:

  • Local and Remote systems must be running OpenSSH 8.2p1 or higher for non-resident keys

  • Local and Remote systems must be running OpenSSH 8.3 or higher for resident keys

  • FIDO2 PIN must be set on the YubiKey. This can be accomplished using YubiKey Manager or local tools

  • The words anything, homedirectory or username below are for example purposes only

Discoverable Key Instructions

Local system configuration

  1. Insert YubiKey into the system

  2. Open a Terminal window and type the following command to generate a key using the ecdsa curve:

    ssh-keygen -t ecdsa-sk -O resident -O application=ssh:YourTextHere

    To use the ed25519 curve, use the following command instead:

    ssh-keygen -t ed25519-sk -O resident -O application=ssh:YourTextHere

    For both commands, YourTextHere can be replaced by anything which helps you identify where this key is being used, for example a server name. This is not a mandatory option.

  3. SSH will request the user to enter their PIN and touch the device. When this request occurs, the YubiKey will flash.

    1. Note that not all systems may ask for the user to touch their YubiKey, but only require the PIN

  4. SSH will save two files. A user can check their console and to display the actual filenames. By default, these filenames will be id_ecdsa_sk & id_ecdsa_sk.pub, but may be different dependent on whether or not it was changed to something else when prompted for a save location. In the example below, the default names are used.

    The first file, id_ecdsa_sk, contains the private key credential stored on the YubiKey. The second file ,id_ecdsa_sk.pub, contains the public key which is required to complete authentication with a remote system.

  5. The public key can be added to a remote server with the following command:

    ssh-copy-id -i ~/.ssh/id_ecdsa_sk user@host

Using a discoverable credential on a new local system

  1. Follow the previous instructions and insert the configured YubiKey into the new system

  2. Open a Terminal window and type the following commands:

    cd ~/.ssh

    ssh-keygen -K

  3. SSH will ask the user to enter your PIN and touch the device. Some systems may not ask for a touch. When this request occurs, the YubiKey will flash.

  4. If this is the only credential on the system, you can rename the exported credentials as id_ecdsa_sk and id_ecdsa_sk.pub to allow seamless authentication.

    If there is a need to keep multiple credentials in an .ssh folder, the command to authenticate to a remote system is: ssh -i ~/.ssh/id_ecdsa_sk user@host (Where you have checked and confirmed id_ecdsa_sk is the actual filename written by ssh-keygen)

    It is also possible to configure ssh to always use a specific credential by creating a config file. To do this set the IdentityFile in the user SSH config (This file may need to be created).

    For example, in ~/.ssh/config adding the following two lines will direct ssh to always use id_ecdsa_sk_rk_credential_example_com as the identity file when accessing example.demo.com

    Host example.demo.com
    IdentityFile ~/.ssh/id_ecdsa_sk_rk_credential_example_com
  5. SSH to the remote system and touch the key when prompted. When this request occurs, the YubiKey will flash.

Non Discoverable Key Instructions

Local system configuration

  1. Insert YubiKey into the system

  2. Open a Terminal window and type the following command to generate a key using the ecdsa curve:

    ssh-keygen -t ecdsa-sk

    To use the ed25519 curve, use the following command instead: ssh-keygen -t ed25519-sk

  3. SSH will request the user to enter their PIN and touch the device. When this request occurs, the YubiKey will flash.

    1. Note that not all systems may ask for the user to touch their YubiKey, but only require the PIN

  4. SSH will save two files. A user can check their console and to display the actual filenames. By default, these filenames will be id_ecdsa_sk & id_ecdsa_sk.pub, but may be different dependent on whether or not it was changed to something else when prompted for a save location. In the example below, the default names are used.

    The first file, id_ecdsa_sk, contains the private key credential stored on the YubiKey. The second file ,id_ecdsa_sk.pub, contains the public key which is required to complete authentication with a remote system.

  5. The public key can be added to a remote server with the following command:

    ssh-copy-id -i ~/.ssh/id_ecdsa_sk user@host

Using non-discoverable keys on another local system configuration

  1. Follow the previous instructions and insert the configured YubiKey into system.

  2. Copy the id_ecdsa_sk file and id_ecdsa_sk.pub from step 4 in the previous instructions to the` ~/.ssh` folder on the new local system.

  3. SSH to the remote system and touch the key when prompted.

Troubleshooting

In the event you are prompted for a password instead of the YubiKey, further configuration of the remote system may be required. Some areas to consider investigating are:
  • Restart/log out and back in again

  • Check the version of ssh is 8.2p1 minimum with ssh -V (for non-discoverable keys)

  • Check the version of ssh is 8.3 minimum with ssh -V where discoverable keys are used

  • If the remote system is Linux based check the logs:

    Ubuntu/Debian: tail /var/log/syslog | grep sshd Fedora: journalctl -r /usr/sbin/sshd

  • Run debug mode from the local system ssh -vvvv username@host.com and review the debug output for any errors

  • Sometimes when logging on to the remote system an error saying /home/username/.ssh/id_ecdsa_sk cannot be read will be displayed. This may be because it can’t see the YubiKey properly, remove and re-insert

  • SSH Public Keys will be rejected if the permissions on the id_ecdsa_sk file are incorrect. This can be corrected with chmod 600 id_ecdsa_sk

  • Due to inconsistencies between Operating Systems, the key may not flash or prompt for touch