# YubiKey & FIDO2 SSH Authentication

Tempest has **built-in FIDO2 support** for SSH — plug in a YubiKey, SoloKey, or any U2F/FIDO2 security key, generate an OpenSSH `ed25519-sk` or `ecdsa-sk` key, and Tempest handles the touch / PIN flow natively. No `ssh-agent`, no `pam_u2f`, no third-party tooling — just hardware-backed SSH on macOS, Windows, and Linux.

## Why hardware keys?

* The private key never leaves the security key — even if your laptop is fully compromised, the key can't be exfiltrated.
* A physical touch is required for every signature, so phishing and malware can't authenticate without you.
* GitHub, GitLab, Gitea, and most OpenSSH 8.2+ servers accept `ed25519-sk` / `ecdsa-sk` natively.

## Generate an sk key

You can generate the key with `ssh-keygen` outside of Tempest:

```bash
# Touch your key when prompted
ssh-keygen -t ed25519-sk -O resident -f ~/.ssh/id_ed25519_sk
```

Or use Tempest's built-in key generation if available in your platform build (Settings → SSH Keys).

The generated `~/.ssh/id_ed25519_sk` is *not* a private key in the traditional sense — it's a credential handle that tells the security key "use the resident credential for this site." The actual key material lives on the YubiKey.

## Use the sk key in Tempest

1. Edit your SSH connection.
2. Auth Method → **Private Key**
3. Key source → **Path**
4. Private key path → `~/.ssh/id_ed25519_sk`
5. Save and connect.

When Tempest needs to authenticate, it triggers the FIDO2 challenge — the YubiKey starts blinking, you tap it, and the SSH session continues. If the key is PIN-protected, Tempest prompts for the PIN.

## Touch and PIN behavior

* **Touch-only keys**: Tempest waits for a touch (the YubiKey LED flashes). Tap within \~30 seconds.
* **PIN + touch keys**: Tempest prompts for the PIN, then asks for touch.
* **Resident credentials**: enumerable via `ssh-add -K`, useful for moving between machines without copying any handle file.

## Multiple security keys

Tempest enumerates connected FIDO2 devices automatically. If multiple keys are plugged in, it'll use the one that holds the matching credential. You can also list devices from your shell with `fido2-token -L`.

## Compatibility

| Platform                  | Status                                                                                                 |
| ------------------------- | ------------------------------------------------------------------------------------------------------ |
| **macOS** (Apple Silicon) | ✅ Works out of the box                                                                                 |
| **Windows**               | ✅ Native FIDO2 + Windows Hello fallback — **may require running Tempest as administrator** (see below) |
| **Linux**                 | ✅ Native FIDO2 (requires udev rule for non-root use)                                                   |
| **iOS / Android**         | ✅ NFC mode — tap an NFC-capable security key against your phone to authenticate                        |

## Windows: run as administrator

On Windows, raw HID access to FIDO2 devices is restricted by the OS — non-elevated processes can't talk to the security key directly. If Tempest can't see your YubiKey, **right-click the Tempest shortcut → Run as administrator**.

Alternatively, use the **WebHello** fallback (Windows Hello acting as a FIDO2 authenticator) which works without elevation if your machine has a TPM and Windows Hello set up.

## Linux udev permissions

If your security key isn't detected on Linux, install the YubiKey udev rules:

```bash
sudo cp ~/.ssh/70-u2f.rules /etc/udev/rules.d/
sudo udevadm control --reload
```

Most distributions provide a `libu2f-udev` or equivalent package that does this for you.

## See also

* [Post-Quantum SSH Algorithms](/authentication/post-quantum-ssh-algorithms.md) — pair hardware keys with PQ-safe key exchange
* [SSH Client for Teleport, Cloudflare Access, AWS SSM, GCP IAP & Tailscale](/connect-to-servers/ssh-client-for-teleport-cloudflare-access-aws-ssm-gcp-iap-and-tailscale.md) — many zero-trust platforms can issue FIDO2-backed SSH certs


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gotempest.app/authentication/yubikey-fido2-ssh-authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.