Securing SSH and Git Commit Signing with FIDO2 on WSL2

You need 8.9 or newer. Most Windows 11 machines already have it.

If yours is older, reinstall the built-in client from an elevated PowerShell prompt. This pulls the current version from Windows Update and keeps it in C:\Windows\System32\OpenSSH, where Windows Update maintains it from then on:

Restart Windows, open a new terminal, then check ssh -V again.

If it is still older than 8.9, install the newest build from the Win32-OpenSSH releases page, following the install wiki. Despite the name, those are the Win64 and ARM64 builds, and every release there is tagged Beta, including the ones that ship in Windows. Install the newest. Windows Update does not maintain this install, so you own updating it from then on. It also installs to C:\Program Files\OpenSSH, so use that path wherever this guide shows a System32\OpenSSH example.

The helper ssh-sk-helper.exe is the Windows component that raises the PIN and touch prompts. Part 3 points WSL2 at it. To find it:

Expect a path such as C:\Windows\System32\OpenSSH\ssh-sk-helper.exe. Note it, Part 3 needs it.

This resolves through PATH, the same lookup that decides which ssh.exe answers when you type ssh. In the usual case each install’s directory holds both binaries, so the helper you get comes from the same install as that ssh.exe. That pairing matters: ssh.exe and its helper must come from the same install.

If the command returns nothing, OpenSSH is not on PATH. Install it per Step 1.

Both checks pass: continue to Part 2.

From PowerShell:

Your distribution must show VERSION 2. If it shows 1, convert it:

Inside WSL2:

Both checks pass: continue to Part 3.

Use the helper path you noted in Part 1, Step 2:

If Part 1, Step 2 reported the Program Files install instead, use /mnt/c/Program Files/OpenSSH/ssh-sk-helper.exe.

This export applies only to the distribution you ran it in. If you use Git from more than one WSL2 distribution, add it to each one. The command above assumes bash and ~/.bashrc. If your shell is zsh or fish, add the equivalent export to that shell’s own profile.

Open a new WSL2 shell so that the variable takes effect. Then run:

Expect the path you set, followed by helper found. If the second command prints nothing, the path is wrong or WSL2 cannot reach it. Check the value against Part 1, Step 2. Catching a typo here saves you debugging a silent failure in Part 4.

Check your firmware version first. In PowerShell:

Then pick:

The -O resident flag stores the credential on the YubiKey itself as a discoverable credential (ssh-keygen calls it a resident key). That is what makes the Part 8 recovery possible.

Insert the YubiKey, then run this in WSL2:

The three -O options decide what gets written to the YubiKey, and each has a benefit and a cost. Two of them have a real alternative worth knowing about. The remaining flags are host-side: -f names the handle file (Step 4 and "How credentials are named" cover it), -N '' sets its empty passphrase (explained after the sequence below), and -C is a comment.

Expect the following, in order:

Your PIN goes into the Windows dialog, never into the terminal. The Windows helper delegates user verification to the Windows WebAuthn API, which collects the PIN itself. Treat the PIN with care: eight incorrect entries in a row block the FIDO2 application, and unblocking it requires a reset that destroys every credential on the key. To see how many attempts remain, run ykman fido info from an elevated PowerShell prompt.

There is no passphrase prompt, because -N '' sets an empty passphrase on the handle file. The private key is on the YubiKey, not in the file, so there is nothing that needs encryption, and with -O resident the file is regenerable anyway.

The command prints this immediately, before any PIN or touch, even on a brand-new YubiKey with nothing stored on it:

Answer y.

The prompt is wrong twice over, and both errors matter.

First, it fires when nothing exists. This is a known bug in Win32-OpenSSH, issue #2394, confirmed to still occur on OpenSSH_for_Windows_9.5p2. The check appears even on an authenticator holding no credentials at all, with an application string that has never been used, so there is nothing to overwrite.

Second, answering y does not overwrite anything. It adds a credential. If a credential with that application string already exists, the new one joins it, and both stay live on the key.

That second point matters when you regenerate a key rather than create your first one. If you are rotating a credential you believe is compromised, the old one remains on the hardware and remains usable. Answering y does not retire it. Delete it explicitly, as Part 8, Step 3 describes.

Answering n produces Key enrollment failed: bad permissions. That message does not mean a permissions problem. It means only that you declined.

To see what the key actually holds before or after you answer, open an elevated PowerShell prompt and run:

Expect a fingerprint line ending in (ED25519-SK), or (ECDSA-SK) if you used that type instead.

The file name you chose is not one ssh tries by default, so declare it:

"How credentials are named" below explains why this step exists, and when to replace Host * with per-host blocks.

The application string (-O application) lives on the YubiKey and names the service. It must begin with ssh:, and it appears in the file names ssh-keygen -K writes during recovery, so use a distinct string per service. It does not enforce uniqueness: several credentials can share one string, as Step 2 describes.

The file name (-f) is local to this machine and names the physical key, which pays off when you add a backup YubiKey and hold two handle files. The tradeoff: ssh only tries a fixed list of default names (id_ed25519_sk, id_ecdsa_sk, id_rsa, and a few others), so any other name must be declared in ~/.ssh/config, which Step 4 does. Without the declaration, ssh never offers the key.

The Host * block in Step 4 is fine for one key, since servers only trigger the PIN and touch after accepting a public key. When you add a credential for a second service, replace the wildcard with per-host blocks and add IdentitiesOnly yes to them, so ssh offers only the right identity to each host.

A credential cannot be copied between YubiKeys, so a backup key holds its own credential and its own handle file. Enroll one by repeating Step 1 with -f "$HOME/.ssh/id_yubikey_backup", then add it below the primary. Identities are tried in order, so the backup is only used when the primary is absent:

Register the backup’s .pub with GitHub in both lists, as in Part 5. For rotating and revoking keys, see Key Management Lifecycle.

On first connection, ssh shows GitHub’s host key fingerprint and asks you to confirm it. Compare it against GitHub’s published SSH key fingerprints before you accept. This is the one moment when host authenticity is in your hands.

Then expect the Windows dialog to ask for your FIDO2 PIN, followed by a touch. As in Part 4, the PIN goes into the dialog and not into the terminal. The result:

That message is a success. GitHub authenticated you, and it is saying that it speaks only Git, not shell. Part 7 verifies signing end to end, after Part 6 configures it.

If git config user.email prints nothing, set your identity. The verification in Part 7 matches on this email:

If you already sign commits with GPG, check your current setup before you continue. Run this from inside a repository you work in, so that any repository-level setting is included:

No output means nothing is configured and you can continue. If gpg.format prints openpgp, or user.signingkey prints a hex key ID, you are signing with GPG today and Step 2 will replace that globally. To keep GPG as your default and use SSH signing only in specific repositories, run Step 2’s commands with --local from inside those repositories.

WSL2 needs no gpg.ssh.program. Its own ssh-keygen reaches the YubiKey through the bridge from Part 3. That setting matters only when Git runs from a Windows shell instead of a WSL shell, which Part 9 covers.

With commit.gpgsign true and a verify-required credential, every commit from now on takes a PIN and a touch. That happens per commit, permanently. Using ssh-agent does not change it, because verify-required means user verification on every operation, not once per session. To opt in per commit instead, skip the commit.gpgsign and tag.gpgsign lines, then pass -S when you want a signature. The rest of this guide assumes sign-by-default.

Without this step, your own signatures show as unverifiable in your own log. GitHub keeps its own trust list, as Part 5 covers. Local git log needs one too, called allowed_signers:

Each line in allowed_signers holds the identity (an email address), then any options, then the key format, then the public key, separated by spaces. The namespaces="git" option restricts the key to Git signatures, so a signature made for Git cannot be presented as valid for another purpose that also checks this file.

Signing is entirely local: no connection to GitHub is needed. It also prompts differently from the authentication in Part 5. The terminal asks first:

Press Enter. That prompt accepts any value, including an empty one, and does not check anything. The Windows dialog opens next and collects the real PIN, followed by a touch. Expect the log to show Good "git" signature.

In GitHub, create a new empty repository. Private is fine. Do not add a README, because that creates a commit you did not sign.

Then, from /tmp/sign-test:

Expect another PIN and touch. Open the repository on github.com and select the commit. It carries a green Verified badge.

Unplug the YubiKey, then try creating another signed commit and rerun ssh -T git@github.com. Both must fail, because signing and authentication need the hardware. git log --show-signature -1 still succeeds, and should: verification uses only the public key, so anyone can check your signatures without your YubiKey.

The test repository and the commit you pushed are both disposable:

Delete the GitHub repository too, if you created it only for this test.

Open an elevated WSL2 session. Launch Windows Terminal as administrator, then open your distribution. Elevation applies to the Windows side, not to Linux. You are still a normal Linux user, but the interop process needs administrator rights to reach the device directly.

From ~/.ssh, run:

Every other command in this guide reaches the YubiKey through webauthn.dll, the Windows library that gives ordinary programs unprivileged access to security keys. Despite the name, it is not browser-only: it is the same machinery behind the PIN dialogs you have seen so far. But it only creates credentials and signs with them. It has no call for listing what a key holds. So ssh-keygen -K has to talk to the YubiKey directly, and direct FIDO device access on Windows requires administrator rights.

Going direct also means ssh collects the PIN itself, in the terminal, rather than through a Windows dialog.

Without elevation, the command fails with an error that names neither permissions nor elevation:

Seeing that means running ssh-keygen -K again from an elevated WSL2 session.

Enter the FIDO2 PIN and touch the key when prompted.

The command writes a fresh handle and public key file for each discoverable credential on the key. It names them id_ed25519_sk_rk_<application-suffix>_<user-id-hex>, plus the same name with .pub appended. For example: id_ed25519_sk_rk_github_f9681759ccf46f50a2b43d3beb7a8aa6cdf10519.... The final hexadecimal component is the generated FIDO user ID, not the credential key handle. The application string appears in the file name, so the recovered files identify themselves when the key holds several credentials.

Rename the files to the name your ssh config declares, id_yubikey_primary and id_yubikey_primary.pub in this guide, then repeat the Git configuration from Part 6. The keys registered with GitHub do not change, so no re-registration is needed.

The recovered handle has the same fingerprint as the original. A handle created with -O verify-required still demands the PIN after recovery, on OpenSSH 9.5p2 for Windows. The known exception is the YubiKey Bio Series, where verification is a fingerprint rather than a PIN: recovered keys have been reported to lose verify-required there, so test a recovered handle before trusting it. Back up the handle files as you would any other OpenSSH key regardless. Recovery through ssh-keygen -K is a fallback, not a substitute.

The credentials this guide creates live on the YubiKey itself, not in ~/.ssh. Deleting the local key handle files removes nothing from the key. Regenerating a credential removes nothing either, as Part 4, Step 2 explains. Retiring a credential means deleting it here.

From an elevated PowerShell prompt, list what the key holds:

Then delete anything you no longer need, by credential ID:

A truncated ID prefix from the list output is enough.

Discoverable credentials share a limited pool on the key: 25 slots on firmware earlier than 5.7.0, and 100 from firmware 5.7.0 onward. Credentials you replaced but never deleted still occupy slots.

From inside WSL2, replacing <windows-username> with your Windows user name:

The files are key handles, not private keys, so the copy exposes nothing the hardware does not protect. If the WSL2 files are gone, run the Part 8 recovery from an elevated PowerShell prompt instead.

In PowerShell:

Git for Windows bundles its own OpenSSH, whose FIDO2 behavior varies by build. Point Git at the Windows-native binaries explicitly. Find them first:

If either path is under \Git\, that is Git’s own bundled copy, which is the build this step exists to avoid. Git for Windows usually sits ahead of the Windows client on PATH, so this is the common result rather than the exception. Ignore it and use the Windows install instead, either C:\Windows\System32\OpenSSH or the C:\Program Files\OpenSSH install from Part 1.

Use those paths below, with forward slashes. If yours contain a space, as C:\Program Files\OpenSSH does, wrap the core.sshCommand value in single quotes inside the double quotes. Windows Git keeps its own configuration, so set your identity here even if you already set it in WSL2 in Part 6.

Expect the Windows dialog for PIN and touch, then GitHub’s greeting. That confirms the copied handle and the ssh config. The two Git settings verify themselves on first use: your next commit from a Windows shell takes a PIN and a touch, and git log --show-signature -1 shows Good "git" signature.