Skip to content

For a couple of years now I've been using a hardware token to store SSH private keys. The Yubikey NEO is a really convenient device with support for both U2F and OpenSSH secrets. On the hardware side of things the device is compact, lightweight and durable. Setting up the software side of things required far more trial and error than it should but once configured has remained reliable. This post isn't a step by step guide but instead is a place to record the trickier details of getting this set up.

Key generation

This part was largely directed by Simon Josefsson's post Offline GnuPG Master Key and Subkeys on YubiKey NEO Smartcard which is best followed directly rather than trying to reproduce it here. The basic steps are:

  1. Generate a master key
  2. Create subkeys for signing, encryption and authentication
  3. Move the three subkeys to the Yubikey

Handling multiple smartcards

Almost all of my machines have multiple smartcard readers or TPMs. GPG's scdaemon gets confused by these when they don't talk OpenSSH but doesn't make it entirely clear that's what's going on. To rememdy this, depending on platform, in %HOME%\AppData\Roaming\gnupg\scdaemon.conf or ~/.gnupg/scdaemon.conf, add the line:

reader-port "Yubico Yubikey NEO U2F+CCID 0"

SSH support (Linux, OS X)

On Linux and OSX this provides a drop-in replacement for a usual SSH agent. In ~./gnupg/gpg-agent.conf, add the following:

enable-ssh-support

SSH support (Windows)

In %HOME%\AppData\Roaming\gnupg\gpg-agent.conf, add the line:

enable-putty-support

This provides support for PuTTY where it replaces the role Pageant plays. More recently I prefer to use Mosh which has much better support for intermittent connectivity and higher latency connections. Mosh is easily used from inside a Cygwin environment but for various reasons there isn't a Cygwin-native gpg-agent. Instead, ssh-pageant can be installed from Cygwin's setup tool and will automatically connect to the Pageant emulation provided by gpg-agent.

In the Cygwin ~/.bash_profile add the following: 

ssh-pageant
eval $(/usr/bin/ssh-pageant -r -a "/tmp/.ssh-pageant-$USERNAME")

Bonus: Stub generation

Usually this happens automatically but in some cases a new machine may need to be prompted to generate stubs for the keys on the Yubikey. The are simply pointers to the secure keys that remain on the device. Reference

gpg-connect-agent learn /bye