Developers Guide to GPG and YubiKey

A YubiKey is a hardware-based authentication device that can securely store secret keys. Once a private key is written to your YubiKey, it cannot be recovered. Keeping secrets off your computer is more secure than storing them on your computer’s hard drive—another application could read your SSH keys from the ~/.ssh folder.

Each type of YubiKey supports a variety of different "interfaces," each with different use cases. Many people associate a YubiKey with generating long one-time passwords (OTP) that look like this:

However, generating one-time passwords is just a small slice of what you can do with a YubiKey. In this post, I’ll be talking about the OpenPGP interface and how you can use it for authentication.

OpenPGP is a specification (RFC-4880), which describes a protocol for using public-key cryptography for encryption, signing, and key exchange, based on the original Phil Zimmermann work of Pretty Good Privacy (PGP).

There is often confusion between PGP and Gnu Privacy Guard (GnuPG or GPG), probably because of the inverted acronym. Sometimes these terms are used interchangeably, but GPG is an implementation of the OpenPGP specification (and arguably the most popular one).

You may have seen "Verified" badges on GitHub commits that use OpenPGP to confirm an author’s identity.

First, you need to generate a GPG key. You could do this directly on a YubiKey. However, you can NOT back up the keys once they are on the device. So instead, I’ll generate a GPG key on my computer, and once I have everything working, I’ll permanently move it to my YubiKey.

Start by generating a new key using gpg. If you already have a key, you can skip this first step:

Now you have a key! You can view your secret keys at any time by running:

Add an authentication sub-key for use with SSH for authentication—more on that below.

If you list the secret keys again, you can see the new key and capability:

Now that you have your newly minted key, back them up!

Backups of your GPG keys should be stored offline. You are going through the process of securely storing your keys on a YubiKey, don’t leave your backup hanging around on disk.

Run the following commands to export the keys and trust store.

If you ever need to restore your keys from this backup, you can run:

There are a few moving parts needed to expose your new GPG key in a way that your SSH client will use them. Initially, this part confused me the most and left me jumping between blog posts and various Stack Overflow questions (many of which were out of date).

Working backward from the SSH client: - The SSH client reads the SSH_AUTH_SOCK environment variable; it contains the location of a Unix socket managed by an agent. - A gpg-agent running in the background controls this socket and allows your GPG key to be used for authentication.

Enable SSH support using standard sockets by updating the ~/.gnupg/gpg-agent.conf file:

Next, you will need to find the "keygrip" for the authentication key; this is different from the key id, run:

Update ~/.gnupg/sshcontrol with the authentication "keygrip"; this allows the gpg-agent to use this key with SSH.

Configure your shell environment to use gpg-agent:

Open a new terminal session and run ssh-add -L; if everything is working correctly, your public key in SSH format will be output to your console:

Now that I have GPG configured on my computer, the next thing is to make sure everything is working correctly.

Log in to GitHub and go the Settings → SSH and GPG page. Copy the output from ssh-add -L and add a new SSH key.

On the same page add your GPG key, copy the value from gpg --armor --export {your-key-id}.

Once you have your key configured, you can open an SSH connection to GitHub:

The session will close immediately but will print a message:

Woot! Everything is working!

If you would rather use a graphical application to enter your passphrase, you can install an alternative "pinentry" program. For example, on macOS:

Signing your commits is the only way to prove you are the author. Without a signature, someone could easily impersonate you by setting the name and email on a commit to match your information.

Configure Git to sign commits and tags automatically takes a few global properties; you want that "Verified" label on GitHub, don’t you 😉:

Your next commit will be signed, and you can double-check this by running git log --show-signature:

You didn’t need a YubiKey to complete any of the above GPG setup. Without one, though, I don’t think I’d go through setting up GPG + SSH authentication. Using standard SSH keys will offer the same level of security with less complexity. As I mentioned above, the goal was to move keys off my computer, and into the secure storage of the YubiKey.

One of the first things I do when I get a new YubiKey is to disable the keyboard functions. Unfortunately, I found myself accidentally touching the device, only to have it spew out a long set of characters; this is an excellent feature if you use it, but if you don’t, it can easily be disabled.

Open up the YubiKey Manager Application, select the Interfaces tab, and disable "OTP," "PIV," and "OATH" interfaces, and press the Save Interfaces button; the result will look something like this:

Open up a terminal and run gpg --card-status, to display information about your device.

If you see an "Operation not supported by device" error message, make sure you have a recent version of GPG installed and try again. I’m using version 2.2.27 in this post.

To configure the device with your settings, run:

This command will open an interactive session; type admin to enable setting properties on the devices.

Run the following commands to update the card.

If you run gpg --card-status again you will updated information stored on your card:

Each key will need to be individual, the signature, encryption, and authentication keys. Edit the key by running:

The smart card does NOT store your public key, run the fetch sub command to make sure GPG can fetch your key from the GitHub URL specified above:

One of the great things about storing your GPG keys on a YubiKey is that you can easily bring the keys to a different device. Since the keys are stored on the smartcard, you simply need to "link" the device’s keys:

Finally, you can confirm the keys have been linked by running gpg --list-secret-keys and look to see if the sec entry is marked with a >.

The last thing to do is update the trust store on the new computer:

Your smartcard is now set up on multiple computers!

In this post, I showed you how to set up the OpenPGP interface of a YubiKey and configure it to be used for SSH authentication. There is a lot more you can do with GPG, like encrypt files, publish your keys, and build your web of trust.

If you want to learn more about secure coding practices, check out these other posts!

If you have questions, please leave a comment below. If you liked this tutorial, follow @oktadev on Twitter, follow us on LinkedIn, or subscribe to our YouTube channel.