DEV Community

uyriq
uyriq

Posted on • Edited on

A step-by-step guide to setting up SSH authentication with YubiKey 5.7 or later version and ED25519-SK keys on Windows 11.

#yubikey #ssh #security #github

Here is the corrected version of your post with grammar, spelling, and clarity improvements:

Setting Up YubiKey for SSH on Windows 11

Prerequisites

  • A YubiKey 5.7 (or later) security key with a user PIN activated for FIDO2 functionality
  • Git installed and a GitHub repository
  • GitHub CLI tool (gh)
  • Administrator rights for ykman operations

Step 1: Install YubiKey CLI and GUI Tools, Set PIN for FIDO

YubiKey offers two management tools:

winget install Yubico.YubiKeyManagerCLI # Deprecated Windows app winget install Yubico.YubikeyManager # Modern CLI tool: ykman
Enter fullscreen mode Exit fullscreen mode

Run the following command in an administrative terminal to set or change your PIN:

ykman fido access change-pin
Enter fullscreen mode Exit fullscreen mode

Alternatively, you can set the PIN using the YubiKey Manager GUI.

Step 2: Configure GPG Agent for SSH Support

Locate and edit (or create if missing) the following configuration file:

$env:AppData\Roaming\gnupg\gpg-agent.conf
Enter fullscreen mode Exit fullscreen mode

Alternatively, it may be under the .gnupg directory. Add or update the file with:

# Enable SSH support through GPG agent enable-ssh-support enable-win32-openssh-support enable-putty-support # Cache settings default-cache-ttl 600 max-cache-ttl 7200 default-cache-ttl-ssh 1800 max-cache-ttl-ssh 7200 # Use a standard socket for SSH control use-standard-socket
Enter fullscreen mode Exit fullscreen mode

Step 3: Generate an ED25519-SK SSH Key

Run the following command to generate an SSH key using the YubiKey:

ssh-keygen -t ed25519-sk -O resident -O verify-required -C "Your Comment"
Enter fullscreen mode Exit fullscreen mode

To generate multiple credentials on the same security key:

ssh-keygen -t ed25519-sk -O resident -O application=ssh:Description -C "Your Comment"
Enter fullscreen mode Exit fullscreen mode

Replace Description with a unique identifier, such as your email.

Step 4: Verify Credentials

Run the following command in an elevated terminal to check stored credentials:

ykman fido credentials list
Enter fullscreen mode Exit fullscreen mode

Example output:

Enter your PIN: Credential ID RP ID Username Display name 50f... ssh: openssh openssh
Enter fullscreen mode Exit fullscreen mode

Ensure that your SSH public key is added to your GitHub account for code signing and, optionally, for authentication.

GitHub documentation

gh ssh-key add ~/.ssh/ed25519-sk.pub --title "Key linked to YubiKey" --type signing gh ssh-key add ~/.ssh/ed25519-sk.pub --title "Key linked to YubiKey" --type authentication
Enter fullscreen mode Exit fullscreen mode

Step 5: Test SSH Authentication

Test your SSH connection to GitHub if the key has the authentication option:

ssh -i "C:\Users\User\.ssh\id_ed25519_sk" -T git@github.com
Enter fullscreen mode Exit fullscreen mode

Expected output:

Confirm user presence for key ED25519-SK SHA256:J... User presence confirmed Hi username! You've successfully authenticated, but GitHub does not provide shell access.
Enter fullscreen mode Exit fullscreen mode

Step 6: Configure Git for Signed Commits

Set up your repository for commit signing:

git config --local user.name "your_username" git config --local user.email "your_username@users.noreply.github.com" git config --local commit.gpgsign true git config --local gpg.format ssh git config --local user.signingkey "C:/Users/Username/.ssh/id_ed25519_sk"
Enter fullscreen mode Exit fullscreen mode

Step 7: Update SSH Config File

Edit ~/.ssh/config to streamline authentication. I recommend adding your key after your primary key to avoid frequent authorization prompts during git fetch:

Host github.com User git Port 22 IdentitiesOnly yes PreferredAuthentications publickey PasswordAuthentication no IdentityFile ~/.ssh/id_ed25519.home # Primary key for Git operations  IdentityFile ~/.ssh/id_ed25519_sk # Additional key if added to GitHub as an authentication key
Enter fullscreen mode Exit fullscreen mode

Step 8: Verify Git Authentication

Try pulling from your repository:

git pull
Enter fullscreen mode Exit fullscreen mode

Expected output:

Confirm user presence for key ED25519-SK SHA256:... User presence confirmed Already up to date.
Enter fullscreen mode Exit fullscreen mode

You will receive the same notification when committing changes.

References

This guide ensures secure SSH authentication using YubiKey on Windows 🚀

Top comments (0)