GPG with yubikey

Posted on Thursday, 7 January, 2016

In last week's post on YubiKey, I explained how to use your YubiKey 4 to log in to various websites that support them.

In another post on secure library distribution, I discussed the problem of trust of third-party libraries and the need for signatures and signature verification. I also postulated an idea of using a service such as to publish the keys of trusted library authors.

In order for this scheme to work, we need it to be both trustworthy and popular. Usually, the more secure a system is, the less convenient it is. Longer passwords are harder to remember and take longer to type. However, one advantage with the Yubikey is that it offers great security along with greater convenience.

In this article I'm going to show how to set up your YubiKey to give both greater security and convenience when signing jars, tags and commits and doing other things where proving your identity is required.

YubiKey 4

The YubiKey 4 can store GPG keys up to 4096 bits, which is the key-size I use. Previous versions of the YubiKey, including the YubiKey NEO, only support keys up to 2048 bits.

YubiKey 4

The advantage of storing your GPG key on a YubiKey instead of a computer is that it's more secure, since it's harder to steal and harder for key-logging malware to get access to it.

Of course, it's possible for someone to steal your YubiKey, but for that reason we can protect it with a 6-digit PIN (where 3 failed PIN attempts locks the hardware, a defense against brute-force attacks).

If you're going to follow my guide, I assume you've already got the following:

  1. A YubiKey 4
  2. A GPG key

If you haven't set up your YubiKey 4 as a U2F device, see my previous post.

If you are a Clojure library author and the cost of a YubiKey is prohibitive for you, let me know your clojars username and your shipping address, via a GPG encrypted attachment to and let me know your public key by publishing it on I will then purchase a YubiKey on your behalf from my own funds.

There are plenty of good guides about how to create a GPG key, so I'm not going to try to repeat those. Here's a good one.

Use a proper passphrase when creating your key. Usually a very long passphrase is inconvenient to type every time your use your private key. But once your key is safely on the YubiKey you won't need to keep typing it, so there's no problem using a really long passphrase at this point, so long as you don't lose it.

Backing up your GPG key

Before we start it's important you realise we are going to move your GPG private key to the YubiKey, so do the following now:

  1. Plug in a USB stick into your computer and mount it
  2. Copy over your ~/.gnupg directory
  3. Unmount and remove the USB stick, and lock it away in a safe, lockable drawer or filing cabinet.

If you use your YubiKey, you can re-create it using this USB stick (as long as you also have the passphrase).

Enabling CCID your YubiKey

In order for your YubiKey to be a U2F device and behave as a GPG card, you need to put the card into a mode called 'super combo mode'.

Since this is not the mode the card ships in, we need to change it. The way to do this is via the YubiKey Personalization Tool, which is available for most platforms including OS X.

On Arch Linux, I installed yubikey-personalization and set the 'super combo mode' (86) like this:

\\\$ pacman -S yubikey-personalization
\\\$ ykpersonalize -m 86

Alternatively, Yubico recommends its YubiKey NEO Manager to configure this.

Setting your YubiKey PINs

There are 2 PINs.

The first is the 8-digit admin PIN, which is used for certain operations. It's important to change this because it is used to change the 6-digit user PIN, which is the one you use on a day-to-day basis to use your GPG key to sign or encrypt.

(There is a third PIN called the Reset PIN which can be used to reset your YubiKey to the original factory settings. This will also trash your GPG key. If your YubiKey got stolen, the thief wouldn't get access to your GPG key so it's not so critical to change this).

Create and write down a new 8-digit admin PIN and 6-digit user PIN on a post-it now and lock it away with the USB key you backed-up your GPG key on. Since your admin PIN can't unlock your original GPG key (because that's protected by a pass-phrase), it's OK to keep the together.

If you're doing this for lots of users (e.g. at your company), you may want to keep the admin PIN secret but provide individual users with their user PIN, allowing them to change it, while still retaining the ability to unblock their PIN should the need arise.

Let's change the admin PIN now.

\\\$ gpg --card-edit
gpg/card> admin
Admin commands are allowed
gpg/card> passwd

1 - change PIN
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit

Your selection? 3

You should then be confronted by a dialog asking for the YubiKey's existing admin PIN which is 12345678. Then you should get a dialog asking you for the new PIN. Enter your new PIN (twice to confirm).

Now change the user PIN.

1 - change PIN
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit

Your selection? 1

This time, you'll be asked for the existing user PIN which is 123456. Enter a new PIN, which must be 6 digits or more.

Now quit the passwd menu with Q:

PIN changed.

1 - change PIN
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit

Your selection? Q

Personalizing your YubiKey

Now we've set the admin key, let's do a few operations on the key to test it

At this stage you can set your name on your GPG key.

gpg/card> name
Cardholder's surname: Sparks
Cardholder's given name: Malcolm

You will now be prompted for your admin key. Enter the 8-digit admin key (the one you just changed to).

If you have a keybase account, set the URL of your public key. In my case this is:

gpg/card> url
URL to retrieve public key:

Test your changes with list

gpg/card> list

Reader ...........: 1050:0407:X:0
Application ID ...: D2760001240102010006041321720000
Version ..........: 2.1
Manufacturer .....: Yubico
Name of cardholder: Malcolm Sparks
Language prefs ...: en
Sex ..............: unspecified
URL of public key :

Now quit:

gpg/card> quit

Moving your GPG private key to the YubiKey

Now we're ready to move the GPG private key to the card. We do this with the --edit-key option to GPG, with your email address as the second argument.

\\\$ gpg --edit-key

The procedure is explained more fully here. You have to select each key in turn and enter keytocard for each one.

Enabling touch-only mode

It's possible that your YubiKey could be activated by malware on your machine, which you conceivably use a keylogger to capture your PIN and use that information to automatically sign and upload jars and tags when you're not aware.

Therefore, a final step is to activate a new feature for YubiKey 4 devices whereby you must touch the device in order for it to release the result of a cryptographic operation involving its GPG key.

Full details on how to do this are here.

Once you enable touch-only mode, bear in mind this also applies to your U2F logins.

Signing your git tags

Now we've completed all the steps, it's time to try it out.

Remove the YubiKey and re-insert it, just to ensure things work from a fresh injection.

Find a Git repository and type the following

\\\$ git tag -m "Test" -s test-01

This tells Git to create a signed tag called test-01 (with the message "Test")

A dialog will appear asking you to enter the user PIN. This only happens the first time when you plug-in your YubiKey, or after a period of inactivity.

You should now see your YubiKey start to flash slowly. This is an invitation for you to press your finger against the flashing LED. When you do so the YubiKey will release the result of the signing operation and the signed tag will be applied. You can also configure git to use your GPG to sign all your commits in the same way.

Deploying jars


When deploying a release that's not a snapshot, Leiningen will attempt to sign it using GPG to prove your authorship of the release.


That's it for now. The whole process is fairly straight-forward and shouldn't take more than an hour. Make 2016 the year you improve your operational security. What better way to start than to order your YubiKey 4 from Amazon or