Use FIDO keys with the SSH agent to replace passwords with physical hardware tokens, ensuring that authentication requires both your private key and possession of the device. This setup prevents remote credential theft because the private key never leaves the secure element inside the YubiKey or similar token.
Prerequisites and Hardware Setup
Before configuring software, you must ensure your operating system supports FIDO2/CTAP2 protocols. Most modern Linux distributions, macOS, and Windows 10/11 include the necessary libraries. You need a compatible hardware key, such as a YubiKey 5 series, which supports both U2F and FIDO2 standards. Connect the key to your machine via USB or NFC if supported. Verify that the
ssh-agent is running on your local machine, as it will manage the interaction between your SSH client and the FIDO key.
Generating the Key Pair
The core of this security enhancement lies in generating a specific type of SSH key that binds to the hardware token. Use the
ssh-keygen command with the
-t ecdsa-sk or
-t ed25519-sk flag. The
-sk suffix indicates a "smartcard" key, which instructs OpenSSH to use the FIDO interface. For example, run the following command in your terminal:
ssh-keygen -t ed25519-sk -f ~/.ssh/id_ed25519_fido
During generation, the tool will prompt you to touch the FIDO key. This action proves physical possession of the device. It may also ask for a PIN if one is set on the key. Once completed, two files are created: a public key file (ending in
.pub) and a private key file. Note that the private key file contains metadata about the smartcard but does not hold the actual cryptographic material; the material remains inside the hardware token.
Configuring the SSH Agent
To allow your SSH client to communicate with the FIDO key, you must add the generated key to the running
ssh-agent. Simply adding the key to your known hosts is insufficient because the agent needs to handle the interactive challenge-response protocol required by FIDO devices. Execute the following command to load the key into the agent:
ssh-add ~/.ssh/id_ed25519_fido
You will be prompted to touch the FIDO key again. If successful, the agent now holds the reference to the hardware token. When you initiate an SSH connection, the agent will automatically present this key during the authentication handshake. Ensure that your
~/.ssh/config file allows the use of smartcard keys by verifying that
IdentitiesOnly yes is set if you have multiple keys configured, preventing the client from trying all available keys and failing due to missing hardware.
Deploying the Public Key
Copy the public key from your local machine to the remote server. Use
ssh-copy-id or manually append the content of
id_ed25519_fido.pub to the
~/.ssh/authorized_keys file on the target host. The entry will look standard but represents a hardware-bound identity. On the server side, no special configuration is typically required beyond having
PubkeyAuthentication yes enabled in
/etc/ssh/sshd_config. However, for enhanced security, consider restricting access using
Match blocks in
sshd_config to enforce key-based login only for specific users.
Testing the Connection
Initiate an SSH session to the remote host. The client will attempt authentication using the key loaded in the agent. At some point, you must physically touch the FIDO key. If the key is not touched within a few seconds, the authentication will fail with a timeout error. This behavior confirms that the two-factor requirement is active. If you encounter issues, check the output of
ssh -v user@host to see if the client is correctly offering the
ecdsa-sha2-nistp256-sk or
ssh-ed25519-sk algorithm.
For more advanced networking scenarios involving multiple servers, you might want to explore how to securely tunnel connections through intermediate hosts. See our guide on
Multi-hop SSH Tunnel with Two VPS Servers: S1 to S2 Setup to extend these secure practices across complex infrastructures.
Troubleshooting Common Issues
If the agent fails to recognize the key, ensure that your OS version supports the specific FIDO profile used by your key. Older versions of OpenSSH may require updates to support Ed25519-SK keys. Additionally, verify that the
ssh-agent process has the correct permissions to access the USB device. On Linux, udev rules may need adjustment if the key is not detected as a smartcard.
Another common issue arises when switching between different FIDO keys. The
ssh-agent caches the first successful key association. To switch keys, you may need to remove the existing key from the agent using
ssh-add -d before adding the new one. Always test your configuration against a non-critical server first to avoid lockouts. Remember that losing access to your FIDO key can result in permanent loss of access if no backup methods are configured. For information on managing idle sessions to reduce exposure risks, refer to
How to Close SSH Connection after Idle Time with no Key Pressed.
Frequently Asked Questions
Can I use a FIDO key without an SSH agent?
No, standard OpenSSH clients require the
ssh-agent to mediate the communication with FIDO hardware. The agent handles the interactive challenges sent by the token, which cannot be processed directly by the CLI command line alone. Without the agent, the client cannot trigger the physical touch requirement securely.
What happens if my FIDO key battery dies?
Most FIDO keys do not have batteries; they are powered by the USB port or NFC field. However, if you are using a wireless model that relies on internal power, the key will cease to function once depleted. Always keep a spare key registered on your servers to prevent lockout situations.
Is it safe to store the private key file on disk?
Yes, the private key file generated for FIDO keys is essentially a wrapper containing metadata. It does not contain the actual secret cryptographic material, which resides exclusively inside the hardware token. Even if an attacker steals this file, they cannot use it without possessing the physical key.
How do I recover access if I lose my FIDO key?
Recovery depends on your server configuration. If you have other authentication methods like password login or additional keys enabled, you can log in normally. Otherwise, you will need console access to the server to remove the compromised key from
authorized_keys or disable public key authentication temporarily.
Does FIDO2 work with older SSH servers?
FIDO2 support requires OpenSSH version 8.2 or later on both the client and server sides. Older servers may not advertise the necessary algorithms in their
KexAlgorithms or
HostKeyAlgorithms lists. Check your server's
sshd_config to ensure compatibility, as outlined in discussions about
Understanding KEX Algorithms in sshd_config.