Log in with a hardware security key (FIDO2)

Sternway can log in with SSH keys kept on a FIDO2 security key (a YubiKey, SoloKey, Nitrokey, Google Titan and the like): the key types OpenSSH 8.2 and later call ed25519-sk and ecdsa-sk. The private half never leaves the security key. Every login needs the key to sign, with a touch and, if you ask for it, its PIN.

Not yet tried with a real security key

Everything on this page has been tested against a software FIDO2 authenticator that speaks the same protocol, and against real OpenSSH servers, but no physical security key has been used with Sternway yet. If a step does not do what this page says, the error text Sternway shows is the most useful thing to report.

What works where

	Linux desktop	Windows desktop	Android
Reaching the key	USB	USB, NFC and Bluetooth, through Windows’ WebAuthn (Windows 10 1903 or later)	USB-C and NFC
Make ecdsa-sk and ed25519-sk keys	yes	yes	yes
Log in with them	yes; Sternway asks for the touch and PIN	yes; Windows shows its own PIN and touch dialog	yes; the app asks you to hold the key to the phone, then for the touch and PIN
Store the key on the security key	yes	yes	yes
Load stored keys from the security key	yes	only when Sternway runs as administrator	yes
Import an id_ecdsa_sk / id_ed25519_sk file	yes	yes	yes

ecdsa-sk works with every FIDO2 key. ed25519-sk needs a key that supports EdDSA (YubiKey firmware 5.2.3 and later, recent SoloKeys and Nitrokeys); an older key says “This security key cannot make this type of key”.

Before you start

• Set a PIN on the security key with its maker’s app (for a YubiKey: Yubico Authenticator, or ykman fido access change-pin).
• Linux: your user needs read and write access to the key’s device. Desktops with systemd 244 or later give it for any FIDO key; on others, install the libfido2 udev rules. Without them Sternway says “This computer does not let Sternway open the security key”.
• Have exactly one security key plugged in while you make or load keys. Logging in finds the right one by itself.

Make a key on the security key

1. Plug the key in. Open Keychain › Keys › Generate.
2. Choose the Type ECDSA security key (FIDO2) (or Ed25519 security key), a Label, and the key’s Security key PIN.
3. Optional:
   • Require the security key’s PIN or biometric: every login also needs the PIN, not just a touch.
   • Store the key on the security key, with a User name on the security key: lets you load it on another device later.
   • Require a touch for every login is on; turning it off also needs the server to allow it (no-touch-required in authorized_keys).
4. Choose Generate and touch the key when it blinks. On a phone over NFC, hold the key flat against the back of the phone until the dialog closes.

The key appears with a Security key badge.

Put it on a server and log in

1. On the key’s page, choose Install on host… and pick a server (Use SSH keys).
2. Connect to that server with the key. Sternway shows “Touch your security key”; touch it. With PIN required, you type the Security key PIN first.

On Windows, Windows’ own dialog asks for the touch and the PIN instead. Because of that dialog, a key made with “Require a touch” off still asks for a touch on Windows.

Load the key on another device

For a key stored on the security key: Keychain › Keys › Import from security key, with the PIN. The key comes back as “name@ssh:”. ssh-keygen -K finds the same key.

On Windows, listing the keys stored on a security key needs administrator rights: start Sternway once with Run as administrator to load them, or run ssh-keygen -K in an administrator terminal and import the files it writes.

When something fails

Message starts with	Means
No security key found	Nothing was plugged in, or held to the phone, in time.
This computer does not let Sternway open the security key / Android did not allow …	Linux udev rules missing; on Windows, raw access without administrator rights; on Android, the USB permission was refused.
More than one security key is plugged in	Making and loading keys need exactly one key.
Wrong PIN / … locked … / Too many wrong PINs in a row	The PIN was wrong. A locked PIN can only be reset, which erases the keys stored on it. Three wrong in a row need the key unplugged and plugged in again.
This security key has no PIN	Set one with the maker’s app first.
The security key was not touched in time	Touch it while it blinks (about 30 seconds).
This security key cannot make this type of key	Use ECDSA.
This security key does not hold this key	The key file was made on another security key.
… cannot list the keys stored on it	A key older than FIDO 2.1: import the key files instead.

There is no macOS or iOS build of Sternway yet, so neither is covered here.