Discussing software, the web, politics, sexuality and the unending supply of human stupidity.

How to use a YubiKey to secure all the things

For a while I’ve been using YubiKey’s blue FIDO key. It enables you to use FIDO U2F for web services. Currently, the main sites that support Universal 2nd Factor (U2F) login are Google, Facebook, GitHub, Dropbox, Fastmail and the password manager Dashlane. It’d be great to see more sites added to this list, but this is a good start.

I upgraded recently from the blue FIDO key to the black YubiKey 4. The full YubiKey can be used for a few things

  • website 2FA using FIDO U2F
  • login to your computer using PIV
  • GPG
  • SSH

It took a while before I got it setup for each of these things.


This is the easy bit. You go to the relevant websites, you activate the U2F mode and you put the key in as required. This works the same whether you use the blue FIDO U2F-only key or the black YubiKey 4.

Generally, the way to use U2F is in addition to TOTP tokens. U2F is a nicer experience than TOTP on laptops and most desktops. (Really, some USB ports are really poorly designed for actually using a YubiKey with. The USB ports on either side of the old Mac keyboards are bad. The two USB ports on my Das mechanical keyboard are perfect.)

Computer login using PIV

To set your Windows or Mac computer up to login, you can do that using the YubiKey PIV Manager app. You can find instructions on the YubiKey website on how to set up key-based authentication on Linux.

The way I’m using the PIV mode is like this. I have a long password for my computer. I can type this in or I can use the YubiKey with a six-digit PIN. If you’ve got a good 20+ character password, you can always use that. But if you also have the USB key, you can use the PIN instead.


With the YubiKey, you can put a number of GPG keys on to it. As with the PIV logins, these are protected with a PIN. My main use case for GPG at the moment is code signing for GitHub. (Alas, nobody seems too bothered about email signing.)

This blog post by Simon Josefsson explains the process of setting up a YubiKey for GPG. The broad approach is you create a GPG key, then you create three subkeys—one for encryption, one for signing, one for authorisation. The private key for each is stored on the YubiKey: once you’ve pushed the private key to the YubiKey, there’s no way to get it back out again. (So, it’s sensible to make a backup of the keys and store them offline on, say, a USB key in a safe.)

If you’ve already got your public key on GitHub, you’ll need to export a new public key containing the subkeys you’ve stored on the YubiKey and paste that up on GitHub. (If you use GitLab, this whole approach doesn’t work… because of this bug I’ve reported.)

Once you’ve got it all set up, when you commit some new code to a Git repository, it’ll ask you for your YubiKey’s six-digit PIN. That is cached for a bit, so it should only interrupt you occasionally. If you remove the YubiKey, you’ll obviously have to put it back in and re-enter the PIN to commit new code.


Now the fiddly bit. The way you use SSH with the YubiKey is to convert your GPG key into an SSH public key. There’s a utility called gpgkey2ssh that does just this for you: you point it to your GPG public key and it’ll turn that into an SSH public key (remember, other than an offline—and hopefully encrypted—backup, you don’t have the private key: it’s stowed away inside the YubiKey).

The problem occurs with the version of GPG. You need to ensure you are running GPG 2.1. You can now get it from Homebrew on the Mac, so do that. You may need to ensure that symlinks are going to GPG 2.1 if you’ve got multiple installs.

This tutorial is the best one for getting gpg-agent setup for doing SSH. I found that it’s a bit of a faff keeping track of which keys are doing what during the process, so I ended up noting them down on a bit of paper.

So, what to do?

If you are an ordinary user and you don’t mind the tradeoffs of having to occasionally plonk a USB key in the side of your computer, get a blue YubiKey FIDO U2F. They’re fantastic.

There are issues: on desktop Macs, you need to ensure you have a USB socket that’s actually available and not a faff to use (i.e. not on the back of a Mac Mini, or tucked away under the edge of a keyboard so you can put the key in… but can’t actually push the button). You may need to get a little bit of USB extension cable to give you somewhere to press, or you might consider getting the YubiKey Nano.

If you are a geek and write software (or software-adjacent products including documentation), and you don’t mind jumping through quite a few more hoops to get the GPG and SSH stuff set up, you should do that too. If you don’t use GPG or SSH, you probably don’t need the black YubiKey and can stick to the blue FIDO U2F device.

You can buy the YubiKey 4 from Amazon UK, or if you prefer, you can get the YubiKey FIDO U2F ‘blue’ key.

Further reading