YubiKey SSH Authentication: Stop Trusting Key Files on Disk

OpenSSH can use FIDO security keys so private signing material remains hardware-bound. This reduces reliance on copyable private-key files, but it does not make a compromised workstation harmless: software controlling the local session can still request signatures while the key is available.

Compatibility requirements#

Yubico documents these minimum OpenSSH versions:

• OpenSSH 8.2 or newer for FIDO-backed -sk keys;
• OpenSSH 8.3 or newer to retrieve resident keys with ssh-keygen -K;
• OpenSSH 8.4 or newer for -O verify-required.

A recent version number is not sufficient if the build lacks FIDO support. Apple’s bundled macOS OpenSSH is not compiled with FIDO support, including on Ventura and later releases. Install a FIDO-enabled build such as Homebrew OpenSSH, put it ahead of the system binaries on PATH, and verify the selected executable:

brew install openssh
which ssh
which ssh-keygen
ssh -V

On Apple Silicon, Homebrew normally installs under /opt/homebrew/bin; Intel installations commonly use /usr/local/bin. Confirm the actual path instead of copying one path blindly.

Choose resident or non-resident credentials#

A resident credential can be discovered from the security key on another compatible machine. A non-resident credential still keeps private signing material on the authenticator, but requires its local key-handle file.

For a compatible YubiKey and OpenSSH build, a resident ED25519 security-key credential with user verification can be created with:

ssh-keygen -t ed25519-sk -O resident -O verify-required -C "security-key-primary"

Yubico notes that ed25519-sk resident credentials require compatible firmware. Use ecdsa-sk when the authenticator does not support the ED25519 security-key type. The generated private file is a handle, not the private key material itself, but it still deserves normal file permissions and a backup plan.

Enroll a recovery path before disabling passwords#

1. Enroll at least one separate recovery credential or retain a tested administrative recovery route.
2. Add the public key to the target account’s authorized_keys.
3. Open a second session and verify FIDO authentication.
4. Test recovery without the primary key.
5. Only then change server authentication policy.

ssh-copy-id -i ~/.ssh/id_ed25519_sk.pub user@server
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519_sk user@server

Do not close the existing administrative session while changing sshd_config. Validate the daemon configuration with the platform’s supported command before reloading it.

Use a resident key on another machine#

With OpenSSH 8.3 or newer and a FIDO-capable build, insert the key and retrieve resident credential handles:

ssh-keygen -K

This writes local handle and public-key files. Review the output location, permissions, and filename collisions before using it on a shared or temporary machine.

Agent forwarding works, but expands key usability#

FIDO-backed keys can be used through SSH agent forwarding. The OpenSSH ssh-agent manual explicitly describes forwarded agent connections and FIDO-specific restrictions. Private keys and passphrases do not travel to the remote host, but a remote process with access to the forwarded agent socket can ask the local agent to sign authentication challenges.

FIDO user-presence and user-verification requirements still apply, so a forwarded request normally requires a local touch and, when configured, a PIN or biometric verification. That reduces unattended abuse but does not make forwarding risk-free: a compromised remote host can present a misleading signing request while the forwarding session is open.

Yubico therefore recommends avoiding ssh -A unless it is necessary. Prefer ProxyJump when the goal is only to traverse a bastion without exposing an agent socket on that host. If forwarding is required, restrict it to specific hosts, keep sessions short, and confirm every unexpected touch prompt.

Hardware selection and recovery#

For SSH, confirm FIDO2 support, firmware requirements, connector type, NFC needs, and client compatibility. A USB-C YubiKey 5C NFC and a USB-A YubiKey 5 NFC are examples with different connector choices. Enrollment and recovery matter more than a generic model ranking. Register separate recovery credentials before relying on one physical device.

Frequently Asked Questions#

Primary references#

• Yubico: Securing SSH Authentication with FIDO2 Security Keys
• OpenSSH ssh-agent manual