Tech Blog.

Thoughts, stories, ideas.

Yubikey configuration

14. October 2016

Yubikeys (manufactured by Yubico) are inexpensive hardware tokens for multi-factor authentication.
In addition to Yubikeys, Yubico also manufactures YubiHSM, which are Hardware Security Modules. HSM are used to store various x509 private keys in hardware, so they cannot be stolen by hackers.

Apart from Yubico, there is also, for example, the manufacturer Nitrokey, who manufactures open-hardware tokens and HSM.

There are currently two Yubico products which are very well suited to two-factor authentication, as they can handle most protocols: On the one hand, Yubikey 4 and on the other, Yubikey Neo.

Functionality

Both products, Yubikey 4 and Yubikey Neo, have two slots each and PIV-compatible storage. These two slots can be used for a range of functions. The following are supported:

Secure static password
Yubico OTP
OATH – HOTP (counter-based)
OATH – TOTP (time-based)
FIDO U2F

The PIV-compatible storage can be used for the following two functions:

PIV-compatible SmartCard (x509 certificates)
OpenPGP SmartCard

Comparison of Yubikey 4 with Yubikey Neo

The Yubikey 4 is a newer product than Yubikey Neo, and in comparison, it has SmartCard storage for 4096-bit RSA keys instead of only 2048-bit. It is, however, missing NFC functionality, which is required for authentication on mobile phones.
Yubikey 4 hardware is so new that current Linux distributions which are not “bleeding edge”, do not yet offer any tools for personalisation. In contrast, Yubikey Neo is well supported in all current distributions.

Configuration

The command line tool ykpersonalize (Source Code, Debian package, ArchLinux package) and the GUI tool yubikey-personalization-gui (Source Code, Debian package, ArchLinux package) can both be used to configure Yubikeys. The packages in Debian Jessie are too old to support Yubikey 4. Yubikey Neo runs without problems, however.

ArchLinux with Yubikey 4 is used below. This should, however, be identical on every system if supported by the software. Regardless if Yubikey 4 or Yubikey Neo are used.

udev

In order to be able to access Yubikeys from the user space, udev must be adapted. To do so, a file is created in each case in the /etc/udev/rules.d directory and then loaded using sudo udevadm control --reload. This is only required to load the new configuration file without rebooting the system.

The following rules are required for FIDO U2F to function:

# FIDO U2F
ACTION!="add|change", GOTO="u2f_end"

# Yubico YubiKey
KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="1050", ATTRS{idProduct}=="0113|0114|0115|0116|0120|0402|0403|0405|0406|0407|0410", TAG+="uaccess"

# Happlink (formerly Plug-Up) Security KEY
KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="2581", ATTRS{idProduct}=="f1d0", TAG+="uaccess"

#  Neowave Keydo and Keydo AES
KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="1e0d", ATTRS{idProduct}=="f1d0|f1ae", TAG+="uaccess"

# HyperSecu HyperFIDO
KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="096e", ATTRS{idProduct}=="0880", TAG+="uaccess"

LABEL="u2f_end"

For personal identity verification (PIV) to work with the SmartCard from the user space, the following udev rules should be added:

ACTION!="add|change", GOTO="yubikey_sc_end"

SUBSYSTEMS=="usb", ATTRS{idVendor}=="1050", ATTRS{idProduct}=="0113|0114|0115|0116|0120|0402|0403|0405|0406|0407|0410", GROUP="users", MODE="0660"

LABEL="yubikey_sc_end"

If FIDO U2F or the SmartCard still does not work afterwards, it should be checked whether the USB vendor and product ID are present in the list above. The vendor and product ID to be entered is displayed with the following command:

lsusb | grep Yubico | awk '{print $6}'

Preconfigure system for SmartCard

Certain conditions are required for the GnuPG to communicate with a SmartCard. Various packages should be installed first:

gnupg-agent (Debian package, ArchLinux package)
pcscd (Debian package, ArchLinux package)
scdaemon (Debian package, ArchLinux package)

Subsequently, various configurations need to be adjusted. It is particularly important that the following line is included in the GnuPG configuration (~/.gnupg/gpg.conf):

use-agent

A slightly more extensive configuration is displayed in the setup below – this is not specific to the Yubikey configuration in this article, but an example of a GnuPG configuration which rectifies some important, but missing options.

keyserver hkp://pool.sks-keyservers.net
default-recipient-self
list-options show-uid-validity show-keyserver-urls
verify-options show-uid-validity
display-charset utf-8
utf8-strings
ask-cert-level
default-cert-level 0
keyid-format 0xLONG
use-agent
no-greeting
armor
fixed-list-mode
personal-digest-preferences SHA512 SHA384 SHA256 SHA224
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 BZIP2 ZLIB ZIP Uncompressed
cert-digest-algo SHA512
no-comments
no-emit-version

The GnuPG agent can also be configured, for example, the SSH agent can be replaced by the GnuPG agent. As a result, the GnuPG key can also be used in the SmartCard, in addition to the keys that were created specifically for SSH.

# enable this if pinentry-gtk is installed
#pinentry-program /usr/bin/pinentry-gtk-2

default-cache-ttl 3600
max-cache-ttl 7200

# for ssh support
enable-ssh-support
default-cache-ttl-ssh 3600
max-cache-ttl-ssh 7200

Configure Yubikey slots

The current slot allocation is displayed with ykinfo-a. Naturally, the AES keys, for example, can no longer be read out then, as security would be lost otherwise.
Yubikeys are not configured for U2F by default. The mode must be switched so this feature can be used. ykpersonalize - m86 is used to do so. The Yubikey then supports Yubico OTP, FIDO U2F, and CCID.

Yubico OTP

When Yubikeys are delivered, they already have a Yubico OTP configuration in the first slot. The corresponding AES key is also already stored in the YubicoCloud, so these validation servers can be used straight away. If own validation servers are to be used, however, the AES key must also be stored on them. As the AES key can no longer be read out from the Yubikey, the slot must be rewritten.

The corresponding configuration should be created with the ykksm-gen-keys tool, the ID must be unique here. The output of the ykksm-gene-keys tool is comma separated in the following order:

Serial number (also called ID)
Identity (also called public name)
Internal UID
AES key (the actual secret)
Lock password
Creation date
Last accessed
Optional fields

Example with ID 1:

$ ykksm-gen-keys 1
1,cccccccccccb,42e31d069785,cf00b1f4c2c80e395b5e7532a5929cba,d05f7e394f0e,2016-03-22T13:12:25,

This information can be written to the Yubikey in slot 1 using the following command:

$ ykpersonalize -1 -acf00b1f4c2c80e395b5e7532a5929cba -o fixed=cccccccccccb -o uid=42e31d069785

FIDO U2F

For U2F to work, either Chrome or Chromium is required, or for Firefox, the u2f4moz extension. Native support in Firefox is currently in process.
The following command can be used to configure U2F in slot 2:

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

U2F is then configured in slot 2 and the Yubikey can be added and used as a security key, for example on GitHub.

Personal identity validation (SmartCard)

The SmartCard is controlled with PKCS #11, as is also the case with other SmartCards. If GnuPG, for example, is meant to communicate with the SmartCard, the gpg is used for this purpose. The command line interface for this can be accessed via gpg2 --card-edit. The status can be queried via gpg2 --card-status. If the status can only be queried as user root and not from the user space, the udev rules have not yet been loaded or added correctly.