In this post I’m going to go over the steps to configure your YubiKey for SSH authentication using a GPG key stored on the YubiKey itself.

This guide goes through the steps for setting this up on a Mac running OS X. Although the concepts of doing this under Linux and Windows are the same, the exact steps will be different.

Ensure your YubiKey has CCID mode enabled

Per Yubico’s site, this is usually enabled by default:

“Note that all YubiKey NEOs shipped after November 2015 come preconfigured with all modes enabled.” — yubico.com

If you’re using an older YubiKey and need to enable it, you’ll want to download the YubiKey NEO Manager from Yubico’s website and run it to ensure that your YubiKey has CCID mode enabled. The link to this tool and instructions to run it are here.

Once you’re certain that CCID mode is enabled, you can move ahead with the next section.

Install GPG

The remainder of the steps in this guide use the command line interface for GPG tools. If you don’t have either GPG Tools or GnuPG installed, install one of them. If you already have one installed, you can skip on to the next section.

GPG Tools provides a nice set of GUI tools and is recommend for most users, but if you’re not afraid of the command line and have Homebrew installed on your Mac, you can install GnuPG2 using Homebrew with the following command:

brew install gnupg2

Decide if you want to require touch

YubiKey will prompt for your PIN during SSH authentication. Starting with YubiKey version 4, YubiKey can also require a touch on the sensor during authentication. Enabling this will require a touch confirmation on the touch sensor for each and every SSH connection.

If you want to enable this, it is highly recommend that you install and use the Yubikey Manager CLI using the instructions from this page. Once installed, you can enable touch using the following command:

ykman openpgp touch aut <'on'|'off'|'fixed'>

If you want more information on these specific policies, please see this page under the heading “Yubikey 4 touch”. IMPORTANT NOTE: A link to a bash script to enable touch is found on that page. Because the behavior of that script requires providing your admin key on the command line, it should be considered insecure. I highly recommend using the ykman tool instead whenever possible.

Unless you set ‘fixed’, (ON_FIXED), you can always come back and change this setting later. If you set fixed, you can’t change it until you put a new secret key onto the YubiKey.

Change the YubiKey PINs

Before continuing, it’s you should change the YubiKey PINs from their defaults if you have not already. The default PIN is 123456 and the default admin pin is 12345678.

To do this, start by running: gpg --card-edit

Once you have the card editor open, allow admin commands by running admin

Then, open the PIN change dialog with passwd

From here, set your PIN, Admin PIN, and reset code. Store these in a safe place.

Once you’ve set your PINs, you can further personalize the data on the card. Here’s the full list of commands available after running admin:

gpg/card> help
quit       quit this menu
admin      show admin commands
help       show this help
list       list all available data
name       change card holder's name
url        change URL to retrieve key
fetch      fetch the key specified in the card URL
login      change the login name
lang       change the language preferences
sex        change card holder's sex
cafpr      change a CA fingerprint
forcesig   toggle the signature force PIN flag
generate   generate new keys
passwd     menu to change or unblock the PIN
verify     verify the PIN and list all data
unblock    unblock the PIN using a Reset Code

Generate and move a GPG key to the YubiKey

If you already have a set of GPG tools installed and your own key generated and available within those tools, good on you! Run the following commands to be sure:

gpg --list-keys
gpg --list-secret-keys

If your public and secret keys do show up as expected, there’s no need to generate another key. You simply need to move your existing key to the YubiKey.

IMPORTANT NOTE: If you want to make use of the ability to revoke your key in the future, then you must generate the revocation certificate before moving the key to your YubiKey. Once you move a key to your YubiKey, it is not possible to generate a revocation certificate unless you have a full backup of the secret key somewhere and are able to re-import it to your GPG keyring.

To move your secret key from your GPG keyring to your YubiKey, go to this page and start where it says “To import the key on your YubiKey”

If you need to generate a GPG key for SSH authentication, take a look at this guide and follow one of the two methods provided.

Once your key is generated and moved to the card, you’re all set to move on to the next section.

Making it all work locally

This part requires editing just a few files to make gpg-agent work as expected.

Really important note: Starting with GnuPG 2.1, the –write-env-file is obsolete. See the GnuPG 2.1 FAQ for more information. The following instructions have been updated with configuration information for versions both below and above GnuPG 2.1. A reader, Nick, confirms these instructions work for versions starting at 2.1, and eliminate the error message that appears regarding write-env-file being obsolete.

If any of the below configuration instructions do not work for you, I recommend that you reach out to the GnuPG mailing list for more help.

You can check your GPG version with:

gpg-agent --version

A precautionary note:

For GPG versions before 2.1, add the following to ~/.bash_profile:

[ -f ~/.gpg-agent-info ] && source ~/.gpg-agent-info
if [ -S "${GPG_AGENT_INFO%%:*}" ]; then
    export GPG_AGENT_INFO
    export SSH_AUTH_SOCK
    export SSH_AGENT_PID
else
    eval $( gpg-agent --daemon --write-env-file ~/.gpg-agent-info )
fi

For GPG versions at or above 2.1, add the following to ~/.bash_profile:

GPG_TTY=$(/usr/bin/tty)
SSH_AUTH_SOCK="$HOME/.gnupg/S.gpg-agent.ssh"
export GPG_TTY SSH_AUTH_SOCK
gpgconf --launch gpg-agent

For GPG versions before 2.1, add the following to ~/.gnupg/gpg-agent.conf:

enable-ssh-support
write-env-file ~/.gpg-agent-info
pinentry-program /usr/local/MacGPG2/libexec/pinentry-mac.app/Contents/MacOS/pinentry-mac

For GPG versions at or above 2.1, add the following to ~/.gnupg/gpg-agent.conf:

enable-ssh-support
~/.gpg-agent-info pinentry-program /usr/local/MacGPG2/libexec/pinentry-mac.app/Contents/MacOS/pinentry-mac

Restart gpg-agent:

sudo killall gpg-agent
source ~/.bash_profile
source ~/.gpg-agent-info

Get your SSH public key

Use the following command to get the SSH public key that corresponds to the key installed on your YubiKey:

ssh-add -L | grep cardno

This can be installed on any server that you want to use your YubiKey-stored key to access.