This guide explains how to set up accessing GitHub over SSH on Windows with the YubiKey’s OpenPGP application.
The YubiKey 5, YubiKey 4, and YubiKey NEO all support the OpenPGP interface for smart cards. This can be used with GPG4Win for encryption and signing, as well as for SSH authentication. These in turn can be used by several other useful tools, like Git and Cygwin, etc. This document guides you through setting up the required software for getting SSH to work on Windows with the YubiKey OpenPGP application.
You can choose to install either PuTTY, the native windows client or both.
Putty is an open source SSH client for connecting via SSH from a Windows system. PuTTY includes support for the Pageant protocol, which is used by other applications in this solution. Download PuTTY and install it.
The recent builds of Windows 10 and Windows 11 contain a native build of the OpenSSH binaries.
The client can be installed using the
Optional Features ( Windows Settings > Apps > Optional features, then search for "SSH")
Pageant.exe, the key-agent from the PuTTY-package, does not support smart cards, which is why further software is required. GPG4Win can act as a drop-in replacement for Pageant. GPG4Win is an OpenPGP client for Windows that enables Windows to access the OpenPGP application on the YubiKey. The Pageant executable in the Smartcard Authentication open source project is an alternative to GPG4Win that also enables Windows to access the OpenPGP application on the YubiKey.
To access the YubiKey’s OpenPGP application from Windows, first decide whether to use GPG4Win or Smartcard Authentication, then choose the corresponding installation instructions, Accessing via GPG4Win or Accessing via Smartcard Authentication in the current document.
|Do not install GPG4Win if Smartcard Authentication is used, and vice versa. GPG4Win and Smartcard Authentication both open the OpenPGP smart card in exclusive mode, each thereby blocking the other’s access.|
GPG4Win has built-in support for SSH authentication.
Step 1 Download and install GPG4Win.
Step 2 Start the
gpg-connect-agent.exe by running the following command in a PowerShell terminal or Command Prompt:
Step 3 Enable SSH support by editing the
gpg-agent.conf file located in the
%APPDATA%\.gnupg\ on Windows, where the typical path is
C:\Users\<username>\AppData\Roaming\. Add the following lines to it:
enable-ssh-support To Enable support for PuTTY enable-putty-support To Enable support for the native Microsoft OpenSSH binaries (requires gpg 2.4.0 / Gpg4win 4.1.0 or higher) enable-win32-openssh-support use-standard-socket default-cache-ttl 600 max-cache-ttl 7200
Step 4 To apply this change, restart the
gpg-agent by running the following command in a PowerShell terminal or Command Prompt:
gpg-connect-agent killagent /bye gpg-connect-agent /bye
Step 5 The SSH public key must be imported to the authorized key file on the server; instructions for doing this configuration for GitHub are provided in Configuring Git below.
If you need to generate or import a GPG key to the YubiKey, you can now use GPG4Win by following the steps in the Using Your YubiKey with OpenPGP guide.
Once SSH support is enabled, any application that supports SSH authentication using Pageant should work out-of-the-box. More information on how to connect to a server with PuTTY is available in the SSH documentation.
As an alternative to using GPG4Win, the Pageant executable in the Smartcard Authentication can be downloaded and used at your own risk.
Instructions on configuring Smartcard Authentication with PuTTY are available in this issue in the GitHub repository for developers.yubico.com.
Step 1 To use Git with SSH on Windows, download and install the Git client on your machine.
Step 2 Check the
authentication-key-id of the PGP keys at the YubiKey by running the command:
Example response where the authentication-key-id in this example is
B28F B5D2 9E6C 37FD 7E84 3CA4 6849 79BD 3F2F 3A7A. The general-key-id in this example is
Step 3 Export the GPG/SSH public key to a file by running the command
gpg --export-ssh-key <authentication-key-id> > ssh_auth_key.pub
Example command where the
ssh_auth_key.pub in this example is:
ssh-rsa AAAAB3NzaC1yc2E... openpgp:0x3F2F3A7A
Step 4 If the GPG public key is not yet configured in GitHub, export the GPG key from the YubiKey by running the command
gpg -o <GPG-public-key-file> --armor --export <general-key-id>
Example command where the
gpg-key.pub in this example is:
-----BEGIN PGP PUBLIC KEY BLOCK----- mQENBGDkNIEBCACqX3aZxtO4lQ6U... -----END PGP PUBLIC KEY BLOCK-----
Step 5 Log in to your GitHub account, select Settings and the option SSH and GPG keys.
Step 6 If the GPG key has not been added to your GitHub account, use GitHub’s instructions, Adding a New GPG Key to Your GitHub Account, to upload it.
Step 7 Upload the SSH/GPG key to GitHub as described in GitHub’s instructions, Adding a New SSH Key to Your GitHub Account.
A successful configuration of GPG and SSH at GitHub should look like this:
Step 8 Access GitHub by using the Git client over SSH with the YubiKey. All commands supported by the Git client can be used for managing your GitHub account. For example, you can use the
git clone command to clone a repository:
git clone <URL to GitHub repository>
To get additional features for the Git GUI using the command line tools, you can also download and install Tortoise Plink.
Cygwin provides a Unix-like terminal with several useful tools, such as SSH. During installation, you will be asked which packages to install.
Do not install
gpg, as you will use the already installed
Make sure to install
ssh-pageant to enable the SSH client that is included to use the YubiKey for authentication.
After installation, open a Cygwin shell and edit the
~/.bashrc file by adding the following at the bottom:
# ssh-pageant # eval $(/usr/bin/ssh-pageant -r -a "/tmp/.ssh-pageant-$USERNAME")