1. Home
  2. PGP
  3. SSH authentication
  4. Windows

    SSH Authentication to GitHub Using a YubiKey on Windows

    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.

    Install an SSH Client

    You can choose to install either PuTTY, the native windows client or both.

    Install PuTTY

    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.

    Install OpenSSH Client feature

    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")

    Setting up Access to the YubiKey’s OpenPGP Application

    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.

    Warning
    		 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. 

    Accessing via GPG4Win

    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:

    gpg-connect-agent /bye

    Step 3 Enable SSH support by editing the gpg-agent.conf file located in the gnupg directory %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.

    Accessing via Smartcard Authentication (closed source alternative to GPG4Win)

    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.

    Configuring Git

    Step 1 To use Git with SSH on Windows, download and install the Git client on your machine. 

    Step 2 Check the general-key-id and authentication-key-id of the PGP keys at the YubiKey by running the command:

    gpg --card-status

    Example response where the authentication-key-id in this example is 4043 4AB6 BFE1 4040 EA6E 18BD 3C47 7268 8968 2A45. The general-key-id in this example is 51BCF7B00445B676.

    gpg-card-status-response.png

    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:0x89682A45
    gpg-export-ssh-key-cmd.png

    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-----
    gpg-pub-key-cmd.png

    Step 5 Log in to your GitHub account, select Settings and the option SSH and GPG keys.

    github-login-gpg-ssh-keys.png

    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.

    github-gpg-keys-add-new.png

    Step 7 Upload the SSH/GPG key to GitHub as described in GitHub’s instructions, Adding a New SSH Key to Your GitHub Account.

    github-ssh-keys-add-new.png

    A successful configuration of GPG and SSH at GitHub should look like this:

    github-gpg-ssh-keys-added.png

    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 git@github.com:<GitHub repository>
    git-clone-cmd.png

    To get additional features for the Git GUI using the command line tools, you can also download and install Tortoise Plink.

    Using Cygwin with GPG4Win

    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 GPG4Win. 


    • 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")

    Troubleshooting

    Solving the "Permission denied (publickey)" Error

    Problem:

    When running a Git command such as git clone, you encounter the following error:

    git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

    Common Cause:

    This error usually occurs when Git cannot authenticate your SSH key with the remote repository, often due to configuration issues with SSH keys or conflicting OpenSSH executables on your system.

    Steps to Troubleshoot:

    1. Check SSH Key Setup:

      • Ensure your SSH key is correctly set up and added to your SSH agent. You can verify this by running: 

        ssh -vT git@github.com

      • This command will provide detailed debugging output. If the key isn’t being recognized, follow GitHub’s SSH key setup guide.

    2. Verify Git Configuration:

      • If you are on Windows, the issue could be due to Git using a different version of OpenSSH than the one your SSH agent is using. By default, Windows may use its built-in OpenSSH, while Git for Windows may use its own.

      • Fix this by configuring Git to use the correct OpenSSH executable: 

        git config --global core.sshCommand "C:\\Windows\\System32\\OpenSSH\\ssh.exe"

    3. Modify Your Git Configuration File (~/.gitconfig):

      • Alternatively, you can add the following to your .gitconfig file: 

        [core]
    sshCommand = 'C:\\Windows\\System32\\OpenSSH\\ssh.exe'

    4. Restart SSH Agent:

      • If using an SSH agent, ensure it is running and your key is added: 

        ssh-add -l

      • If no keys are listed, add your key: 

        ssh-add ~/.ssh/id_rsa

    5. Check Repository Access:

      • Ensure you have the necessary permissions for the repository you’re trying to access. Check if you can view the repository in your GitHub account.

    6. Re-add SSH Key to GitHub:

      • If you’ve rotated your SSH keys or updated them recently, you may need to re-add the new public key to your GitHub account.