FIDO2 Hardware Keys

FIDO2 security keys such as YubiKey can authenticate SSH sessions through the sk- key types OpenSSH introduced in 8.2. With these keys the private key material lives on the token, and every signature requires a physical touch. ZestSSH supports them on desktop by connecting to your operating system’s ssh-agent — the agent (and the hardware behind it) handles the FIDO2 ceremony, and ZestSSH proxies the signing request.

Availability

Hardware-key support is delivered through the OS ssh-agent, so it is a desktop feature.

Platform	Transport	Status
Windows	Named pipe (\\.\pipe\openssh-ssh-agent)	Full support
macOS	Unix socket ($SSH_AUTH_SOCK)	Full support
Linux	Unix socket ($SSH_AUTH_SOCK)	Full support
Android	—	Not available (no system ssh-agent)
iOS	—	Not available (no system ssh-agent)

How It Works

ZestSSH does not talk to the USB/NFC token directly. Instead it speaks the SSH agent protocol to the agent your OS already runs, and the agent — backed by the FIDO2 authenticator — does the low-level work:

1. Discover the agent. On Linux/macOS ZestSSH connects to the Unix domain socket in $SSH_AUTH_SOCK; on Windows it opens the OpenSSH named pipe \\.\pipe\openssh-ssh-agent. On Unix the socket’s permissions are checked first — a world- or group-writable socket is refused, because a hostile local process on that socket could man-in-the-middle every signing request.
2. Enumerate keys. ZestSSH asks the agent for its loaded identities and lists them, including any sk- (FIDO2) keys.
3. Attach as an identity. You pick a key from the agent and save it as a ZestSSH identity. Only the public key blob and label are stored — no private material ever reaches the app.
4. Sign on demand. When you connect, the SSH signing request is forwarded to the agent. The agent triggers the authenticator, you touch the token (and enter its PIN if configured), and the hardware returns the signature — complete with the user-presence/user-verified flags byte and the monotonic counter that the sk- signature format carries. ZestSSH relays the signature to the server.

Because the key never leaves the token, possession of the physical device is required for every authentication.

Supported Key Types

OpenSSH 8.2+ defines two FIDO2 SSH key types, and ZestSSH presents both when the agent holds them:

Key type	Notes
[email protected]	Supported by essentially all FIDO2 authenticators.
[email protected]	Requires a token with Ed25519 support (for example YubiKey 5 with firmware 5.2.3+).

These differ from software keys by embedding an application string (usually ssh:) and by requiring the token to produce the signature together with the flags byte and counter. All of that is handled by the agent and the hardware — ZestSSH just forwards the request and the response.

The matching certificate types, [email protected] and [email protected], are also understood — see OpenSSH Certificates.

Configuring in ZestSSH

1. Create the hardware key (one time)

If you have not already, create a security-key credential with OpenSSH on your desktop:

# Ed25519 variant (needs a capable token); use ecdsa-sk for universal support
ssh-keygen -t ed25519-sk -O resident -O verify-required

Add the resulting public key to the server’s ~/.ssh/authorized_keys as usual.

2. Load it into your ssh-agent

ssh-add        # loads keys, including sk- keys, into the running agent
ssh-add -L     # confirms the sk- key is present

On Windows, make sure the OpenSSH Authentication Agent service is running.

3. Attach the agent key in ZestSSH

1. Open the Keys view.
2. Under Hardware Tokens, choose Connect via ssh-agent….
3. ZestSSH probes the agent. If it is not installed or stopped, the dialog offers to guide you through installing/starting it; if it is running, it lists the loaded keys.
4. Select the sk- key (or any agent-held key) and add it as an identity.

4. Connect

Assign the identity to a connection and connect. When the server asks for a signature, touch your token. That is it.

Common Mistakes

• Agent not running or empty. ZestSSH can only see keys the agent holds. If the list is empty, run ssh-add (and on Windows confirm the OpenSSH Authentication Agent service is started).
• $SSH_AUTH_SOCK not set. On Linux/macOS, launch ZestSSH from an environment where the variable is set, or point the identity at the socket path explicitly.
• Insecure socket permissions. ZestSSH refuses a world-/group-writable agent socket. Fix the permissions rather than trying to bypass the check — a writable socket is a real hijacking risk.
• Expecting mobile support. There is no system ssh-agent on Android or iOS, so hardware-key auth via the agent is desktop-only.
• Confusing this with agent forwarding. Attaching an agent key (this page) is different from forwarding your agent to a remote host. See SSH Agent Forwarding.

Free Tier vs Pro

Hardware-key authentication is not tier-gated — it works on Free, Squeezed, and Juiced. The only Free-tier limit affecting SSH is the concurrent-session cap (up to 4 on desktop, 2 on mobile).

FAQ

Q: Can I use my YubiKey with ZestSSH? A: Yes, on desktop. Load its sk- key into your OS ssh-agent, then attach it in the Keys view. Signing prompts you to touch the token.

Q: Does ZestSSH talk to the security key directly over USB/NFC? A: No. It goes through the operating system’s ssh-agent, which owns the token interaction. This keeps the private key on the hardware and off your disk and out of the app.

Q: Why can’t I do this on my phone? A: Android and iOS have no system ssh-agent for ZestSSH to connect to. Hardware-key auth is available on Windows, macOS, and Linux.

Q: Do resident (discoverable) and non-resident keys both work? A: Both work as long as the key is loaded in the agent. Resident keys can be re-loaded onto a fresh machine with ssh-add -K.

Q: Can a FIDO2 certificate be used? A: The sk-*[email protected] certificate formats are supported. See OpenSSH Certificates.

Next Steps

• SSH Agent Forwarding — forward an agent to onward hosts (a different feature).
• OpenSSH Certificates — certificate-based login, including sk- certificate types.
• Public Key Authentication — software key generation and import.
• SSH Connections — the connection protocol and authentication methods.