I’m a big fan of the YubiKey 4.

The YubiKey is a security device that originally outputted a 44-character “one time password” that could be decoded and mathematically verified and used as a second factor for authentication. Over the last few years, improvements to the devices mean that they can also perform other important functions, such as storing:

  • Identity, Signature, and Encryption Certificates
  • U2F data for websites (GitHub and GMail, among others, support this)
  • GPG Keys

If you’re looking to set this up on your own, read on to learn how this extra functionality helps your security game, and how you can configure services to use it.

What’s In An Identity?

The YubiKey 4 can store four types of certificates — authentication (identity), digital signature, key management (encryption), and card authentication. Each of these has a different use as prescribed by the National Institute of Technology FIPS 200-2 standard. That’s because YubiKey’s certificate support is implemented in a way that’s similar to the way smart card certificate support works.

The identity certificate can be used for authenticating to any service that supports another standard: PKCS11. PKCS11 describes an interface to be used (regardless of platform) to talk to cryptographic tokens such as smart cards, YubiKeys, or Hardware Security Modules (HSMs). Fortunately, software such as OpenVPN, SSH, and MacOS Sierra have support for talking to such devices — which means you can move your SSH key off the laptop and onto a physical device.

These identity certificates don’t need to be kept in escrow (unlike an encryption certificate, for example) since they aren’t storing data to be retrieved and decrypted later — they’re just making a point-in-time assertion that the certificate is present on the hardware device. We’re not going to cover making encryption certificates, but the main point to remember is to have a safe place to store such keys in escrow.

Managing Your Keys

To begin, you’ll need to create a PKI. While we won’t get into too much detail here, there are tools that make this easier than it was once upon a time. CFSSL is a handy tool to help create a PKI. While making a PKI isn’t necessary for SSH or MacOS support, it is important if you want to use your certificates with tools like OpenVPN that rely on a Certificate Authority to authenticate clients.

It’s worth thinking about the physical security of your CA — any compromise to your CA can result in an adversary generating valid certificates to access your infrastructure. Using a machine that restores from an original state each time it boots is a good first step, with state stored on a secure external drive like an IronKey. A Live CD with the tooling you need on it would work; guides exist for customizing an Ubuntu LiveCD.

These instructions for provisioning the key work on a Linux machine with the most recent version of the yubico-piv-tool application (1.4 or greater). On a Mac you can install this tool with brew install yubico-piv-tool.

To begin, we’re going to initialize the YubiKey with a set of IDs for the card itself. We’ll also block resetting the PIN. It’s easy enough to provision keys and reset them so that it makes more sense to reprovision the key in the event someone enters the PIN incorrectly a number of times:

yubico-piv-tool -a set-chuid -a set-ccc
yubico-piv-tool -a unblock-pin -P 000000 -N 000000
yubico-piv-tool -a unblock-pin -P 000000 -N 000000
yubico-piv-tool -a unblock-pin -P 000000 -N 000000

Next, we’ll tell the key to generate a new private key. The public key will be pasted to standard out. Keep that key (for now).

Caution: Following this procedure may overwrite your existing setup.

yubico-piv-tool -a generate -s 9a -A RSA2048 -o pubkey.temp

You’ll then want to generate a certificate signing request:

yubico-piv-tool -s 9a -S "/C=US/ST=STATE_NAME/L=CITY_NAME/O=ORG_NAME/CN=USER_NAME" -a verify -a request -i pubkey.temp -o username.csr

Now, we mentioned having a CSR. We’re going to sign this with our Users CA. It is possible to create a self-signed certificate as well, using a different set of yubico-piv-tool options — some documentation is available as well. The CA configuration that CFSSL provides out of the box has a client option that should work for this purpose.

cfssl sign -ca ca.pem -ca-key ca-key.pem -config ca-config.json -profile client username.csr | cfssljson -bare username

Add the certificate to the card:

yubico-piv-tool -a import-certificate -s 9a -i username.pem

Finally, set a management key for the card and change the PIN. The management key will be required to make future device changes unless you reset the device:

yubico-piv-tool -a change-pin

(The default pin is: 123456)

yubico-piv-tool -a set-mgm-key -n (48 character 0-9a-f string)

At this point, you will have a key that can be used to provide identity for SSH and/or MacOS Sierra.

Configuring MacOS Sierra This part is easy — pull the YubiKey out and reinsert it into the computer. MacOS will ask if you want to pair the key with your local account, and you’ll be good to go. You’ll notice that authentication boxes ask for the PIN you set earlier, rather than an account password. If you run into issues, the sc_auth command can be helpful.

Configuring SSH

SSH requires a PKCS11 provider — fortunately, when we installed the yubico-piv-tool we installed a provider as well. The easiest way to use SSH with a PKCS11 provider is to use an ssh-agent.

To get your SSH key, run:

ssh-keygen -D /usr/local/opt/yubico-piv-tool/lib/libykcs11.dylib

To add the identity to your SSH agent, run:

ssh-add -e /usr/local/opt/yubico-piv-tool/lib/libykcs11.dylib

Once you’ve done that, try connecting to another machine. You should be authenticated and ready to go.

Configuring OpenVPN

On the server side, you’ll need to point the OpenVPN server towards your CA and any applicable CRL, as you would do if you weren’t using tokens. This configuration doesn’t change.

OpenVPN does support using PKCS11 identities. We found that it works better on Macintosh and Windows clients by using the 32-bit OpenSC PKCS11 provider and a GUI client like Viscosity. The OpenSC libraries are available via homebrew, or directly from them.

Wrapping Up

Moving user credentials off the laptop and onto dedicated hardware provides you and your users with peace of mind. Since the token generates the actual private key, you can be confident that the key is not floating around your client endpoint. There’s a little more user education involved in the proper use of the security token, but we’ve found this to be a small cost for a big security win.

This was originally posted on the Threat Stack blog.