nixos-yubikey

Create NixOS images suitable for initializing YubiKeys.

This repository builds a bootable NixOS image that includes all of the software you’ll typically need to initialize a YubiKey, and to configure it for use with GnuPG and SSH. It follows recommended security practices by disabling network interfaces and running the configuration environment from a ramdisk (not only the $GNUPGHOME, but also the entire NixOS filesystem). The only way to write state to persistent storage is by explicit user action.

Requirements

You’ll need the following:

• An environment capable of building Nixpkgs for x86_64-linux hosts.
• At least one YubiKey, preferably a YubiKey 4 or later.
• At least one USB flash drive (preferably 2 or more), for keeping your master GnuPG key offline and secure.
• An x86_64-linux host that you trust, and that can be “airgapped” during the key generation and YubiKey provisioning process. The host should have at least 2GB of RAM, because the NixOS image will copy its filesystem to RAM and run from there to prevent key leakage to persistent storage.

Usage

1. Build the NixOS bootable image.

   nix build -f default.nix nixos-yubikey
       

2. Copy the ISO file in result/iso to a USB stick or CD/DVD.
3. Boot the image on trusted hardware.
4. Follow one of the guides below.

Guides

There are numerous guides on how to initialize YubiKeys and to prepare them for use with GnuPG and SSH. Below are the guides I found most useful and/or prudent, but whether you also find them useful or prudent will depend on your own security preferences and needs. If you have the time, I think it’s a good idea to review each one of them before proceeding with your own YubiKey provisioning, because each guide has at least one or two insights or rationales that the others lack, meaning you’re less likely to miss something important.

As of May 2019, few of the guides below include instructions specific to NixOS, but for the most part you can skip the OS-specific instructions (e.g., which packages you’ll need to install), as this image should include everything you need, and is easy to modify if there’s something missing. Furthermore, because you shouldn’t need to install any additional software, the image disables your machine’s network interfaces from the very beginning of the process, so you can also ignore the bits of the guides that warn you to disable networking after installing packages. (Of course, it’s always a good idea to ensure that all network interfaces are disabled before proceeding with key generation, anyway, in case of a bug or misconfiguration.)

• DrDuh’s YubiKey guide

  This one is my personal favorite. Note that the gpg.conf referred to in this guide is already set up for you when you open a shell in the NixOS YubiKey image.

• Setting up GnuPG + YubiKey on NixoS for SSH authentication

  Contains some NixOS-specific information, all of which has been incorporated into this NixOS YubiKey image.

• GPG/SSH with the YubiKey 5

  Probably the next best guide I found after DrDuh’s guide.

• Configuring an offline GnuPG master key and subkeys on YubiKey
• Starting with GPG and YubiKey

  Probably the most “gentle” of the guides.

Renewing subkeys

DrDuh’s guide now covers subkey renewal, which is much simpler than rotating keys. Note that once you’ve renewed your subkeys, you’ll need to re-export your keys (including the public key, which will need to be updated in all the usual places), but you do not need to update the subkeys on the YubiKey.

Other useful information

Debian’s (and Debian developers’) guides to using subkeys and why they’re useful are probably the best resources on these topics, though they’re not specific to YubiKeys (or even hardware keys at all):

• Using OpenPGP subkeys in Debian development
• Offline master key
• Airgapped master key
• Smartcard keygen

This guide doesn’t cover Yubikeys in any depth, but it does a good job of covering out to create additional GPG ID’s (i.e., additional email addresses associated with your key), and also more information on how to use hopenpgp-tools and pgpdump:

• Create GnuPG with sub-keys to sign, encrypt, authenticate

Everyone recommends using a 2nd YubiKey to make a backup of your primary YubiKey, but in practice, using 2 or more YubiKeys with the same subkeys is tricky. Here are some resources for more information on this subject, plus the currently best-known workarounds:

• Using two yubikeys not covered under guide
• Use PGP keys on multiple yubikeys

If you want to use your Yubikey with VMware Workstation or VMware Fusion, you’ll need to edit your virtual machine’s VMX file:

• Troubleshooting VMWare Workstation Device Passthrough