Skip to content

Yubikey#

The Yubikey is a hardware security device designed to simplifly authentication across large number of authentication protocols. The Platform team uses Yubikeys to manage cryptographic keys facilitating file encryption/decryption, secure authentication to various Platform components, and code signing with Git.

Installation#

macOS Requirements#

  • Homebrew
  • A compatible YubiKey
  • Gnu Privacy Guard
  • Pre-existing signing, authentication, and encryption keys

macOS Install#

Install Yubikey Manager(ykman) and remaining dependencies with Homebrew

$ brew install yubikey-personalization hopenpgp-tools ykman pinentry-mac

Linux Requirements#

  • A compatible YubiKey
  • Gnu Privacy Guard
  • Pre-existing signing, authentication, and encryption keys

Ubuntu/Debian Install#

Install the rest of the requirements with apt 

$ sudo apt -y install wget gnupg2 gnupg-agent dirmngr cryptsetup scdaemon \
pcscd secure-delete hopenpgp-tools yubikey-personalization

Fedora Install#

Install the rest of the requirements with dnf 

$ sudo dnf install gnupg2 dirmngr cryptsetup gnupg2-smime pcsc-tools opensc \
pcsc-lite secure-delete pgp-tools yubikey-personalization-gui

Configure YubiKey as a Smartcard#

  1. With the YubiKey plugged in, use GPG to edit the smartcard config 
    $ gpg --card-edit
    and entire administrative mode 
    gpg/card> admin
  2. Enable Key Dervide Function (KDF) to protect against exposing PINs 
    gpg/card> kdf-setup
  3. By default the GPG interface on a Yubikey is configured to have a PIN of 123456 and an Admin PIN of 12345678. These should be changed, and a reset code should be set. 
    gpg/card> passwd
gpg: OpenPGP card no. D2760001240103040006191504550000 detected

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

Your selection? 3
PIN changed.

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

Your selection? 1
PIN changed.

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

Your selection? q

Unblocking your YubiKey

Certain of the YubiKey's funtions will require the PIN to be entered, though it will be cached for a period to prevent constant reentry. If the PIN is entered incorectly 3 times then it becomes blocked, and can be unblocked with the Admin PIN. Entering the Admin PIN incorrectly 3 times will destroy all GPG data on the YubiKey, and it will need to be reconfigured.

Import Keys#

Pre-existing Keys

For the safe of simplicity, this guide describes a configuration where pre-existing keys are being imported to the YubiKey. Optionally, some combination of the necessary cryptographic keys can be generated on the Yubikey itself, ensuring those private keys have (and will) never be accessible apart from the YubiKey. However, any such implementation presents additional challenges regarding management and backup of keys.

Moving your keys to the Yubikey is a permanent, one-way transaction. It is strongly recommended to have backups of your keys before beginning this process.

  1. With the YubiKey plugged in, use GPG to move your keys to the Yubikey 
    gpg --edit-key <your keyid>
  2. Enter the command: keytocard When prompted if you really want to move your primary key, enter y (yes). When prompted where to store the key, select 1. This will move the signature subkey to the PGP signature slot of the YubiKey.
  3. Enter the command: key 1 Enter the command: keytocard When prompted where to store the key, select 2. This will move the encryption subkey to the YubiKey.
  4. Enter the command: key 1 Enter the command: key 2 Enter the command: keytocard When prompted where to store the key, select 3. This will move the authentication subkey to the YubiKey.
  5. Enter the command: quit When prompted to save your changes, enter y (yes).