The YubiKey 4 is a multi-purpose USB key produced by Yubico.

It can be used for 2-factor authentication (OTP, U2F, OATH and static password) and as a CCID smartcard (both PIV and OpenPGP), visit the Yubico product page for a full list of features and a comparison with previous versions.

udev

If you have libu2f-host0 installed, you do not need the modification below, see 846359.

Up to jessie, to use the card as a non-root users, you need to add a line to /etc/udev/rules.d/99-yubikeys.rules to the tell udev either

# YubiKey 4 OTP+U2F+CCID
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1050", ATTRS{idProduct}=="0407", GROUP="plugdev"

# YubiKey 4 OTP+U2F+CCID
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1050", ATTRS{idProduct}=="0407", TAG+="uaccess"

By default, an even better configuration would be to merge the two lines:

# YubiKey 4 OTP+U2F+CCID
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1050", ATTRS{idProduct}=="0407", GROUP="plugdev", TAG+="uaccess"

Configuration

Yubico develops various software to access the key, among them:

OTP

The key does not have a battery, so for TOTP you need an external tools:

Reset

If the Admin PIN counter reaches 0, the card is not bricked, but it can be reset to factory defaults. ATTENTION, this clear everything on the card!

See https://lists.gnupg.org/pipermail/gnupg-users/2013-March/046261.html (via https://lists.gnupg.org/pipermail/gnupg-users/2015-February/052378.html).

PIV

Check also Debian SSO (Single Sign-On) with a YubiKey.

OpenPGP

Various interesting HowTo, especially useful if you are new to OpenPGP subkeys:

Needed packages

To access the card you need GnuPG, the version in wheezy is fine for signing/encrypting.

However, if you want to use 4096-bits RSA keys, you need GnuPG 2.x, with the corresponding gpg-agent and scdaemon, at least the version in wheezy-backports, i.e. 2.0.25-1~bpo70+1.

GNOME Keyring

Please note that you need at least gnome-keyring 3.16.0-3 which disables the internal gpg-agent and relies on pinentry-gnome/gnupg-agent instead, see 773304.

For previous gnome-keyring versions, you should manually disables the internal gpg-agent and ssh-agent (if needed), see 623539:

$ mkdir -p ~/.config/autostart
$ echo 'X-GNOME-Autostart-enabled=false' \
  | cat /etc/xdg/autostart/gnome-keyring-gpg.desktop - \
  >>~/.config/autostart/gnome-keyring-gpg.desktop
$ echo 'X-GNOME-Autostart-enabled=false' \
  | cat /etc/xdg/autostart/gnome-keyring-ssh.desktop - \
  >>~/.config/autostart/gnome-keyring-ssh.desktop

OpenSSH authentication

This works out-of-the box on wheezy with GnuPG Agent and the corresponding scdaemon. You need to configure:

use-agent

enable-ssh-support

Once the agent started and the key plugged in, you can check if its authentication key has been added to the agent via the ssh-add -l command and then export the public key via the ssh-add -L command.

However, if you use GNOME Keyring, read this note.

Using a Yubikey to unlock a luks encrypted hard drive at boot time

Starting with Buster, it's possible to use a challenge / responce HMAC-SHA1 slot of a Yubikey for unlocking a luks key. It's not available before Stretch, my advice is not to try, as many components needs to be updated for this support.

Normally, the yubikey-luks package's README.md advises to use /usr/bin/yubikey-luks-enroll, but in practice, it's only adapted for some situation (the script hardcodes values like hard drive names and such which may or may not match your setup), so it's best to do things by hand the way I describe. Anyway, let's start.

The first thing to do is to install the necessary software:

apt-get install yubikey-luks yubikey-personalization

With Luks, your device contains a key, which is decrypted using one of the 8 slots of Luks. If you've installed Debian on a crypted device the normal way with the Debian Installer, the slot 0 will contain a simple key that is unlocked with a passphrase. We're going to use another slot that will contain a much stronger passphrase, which will be calculated with the passphrase you type at boot time, and then goes through the yubikey to be transformed into a much harder to guess password. This stronger passphrase will be harder (or almost impossible) to brute-force, while it still ca be easy for you to remember.

In my case, I use LVM over RAID, so my encrypted device is /dev/md1. You should adapt what's below with the device that you use for your drive (maybe /dev/sda2?).

The first step is to check the current state of your crypto device and its slots:

cryptsetup luksDump /dev/md1

Puis on installe les outils necessaires:

Then make sure your Yubikey is ready with an HMAC-SHA1 slot. If you haven't do it yet, you can use the yubikey-personalization (the package name is yubikey-personalization-gui). Using it, click on "Challenge-Response", then select a slot (on top of the screen), for example slot 2, then click on "Generate". WARNING: the GUI doesn't display clearly if a slot already contains a key. Using the shell too, you can do like this (package name is yubikey-personalization):

ykpersonalize -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible

Then calculate the result of the password through the Yubikey:

ykchalresp -2 VOTRE_MOT_DE_PASSE

Then, if your luks slot 7 is empty, you can put the calculated passphrase there:

cryptsetup --key-slot=7 luksAddKey /dev/md1

Take care, here you'll be typing the result of the "ykchalresp" command, and not the password you've typed.

Now, we got to replace the script that asks for a password on boot, so it uses the HMAC-SHA1 slot of the Yubikey when we type. We just need to edit /etc/crypttab and recalculate the initrd: Maintenant, il faut ajouter le support de la yubikey au boot. Il suffit d'ajouter "keyscript" dans /etc/crypttab et de recalculer le ramdisk, comme ceci:

{{{cat /etc/crypttab md1_crypt UUID=VALID-UUID none luks,discard,keyscript=/usr/share/yubikey-luks/ykluks-keyscript}}}

Then:

update-initramfs -u

Normally, after a reboot, cryptsetup will ask for a password that will then be passed on the Yubikey's HMAC-SHA1. Your slot 0 password still exists, but it wont be accessible unless you fix the initrd so it doesn't use the Yubikey HMAC-SHA1 thing. So, even if you loose your yubikey, you can still recover your system, for example booting on a live system. Best is still to kill your old password if you think you wont loose your key:

cryptsetup luksKillSlot /dev/md1 0

and then generate a stronger recovery password (think: openssl rand -hex 32), printed somewhere safe. Let's put that in slot 1:

cryptsetup --key-slot=1 luksAddKey /dev/md1

License

This document is licensed under the terms of the GNU General Public License (GPL), version 2 or (at your option) any later version.