YubiKey

From ArchWiki
(Redirected from Yubikey)
Jump to navigation Jump to search

Tango-inaccurate.pngThe factual accuracy of this article or section is disputed.Tango-inaccurate.png

Reason: The article lacks sources, is interspersed with TODOs and probably out of date. (Discuss in Talk:YubiKey#)

Tango-edit-clear.pngThis article or section needs language, wiki syntax or style improvements. See Help:Style for reference.Tango-edit-clear.png

Reason: ykman-specifics should be grouped together. (Discuss in Talk:YubiKey#)

The YubiKey is a small USB Security token that can:

While offering many features, newer versions of the YubiKey are not released as open source. An alternative is the Solo.

Note: Before you overwrite the initial configuration of slot 1, please be aware of the warning under #Factory configuration.

Contents

Installation

There are several packages available:

  • Yubico PAM — Module to integrate the YubiKey into PAM.
https://developers.yubico.com/yubico-pam/ || yubico-pam
  • YubiKey Manager — Python library and command-line tool (ykman) for configuring a YubiKey over all USB connections. Has optional GUI.
https://developers.yubico.com/yubikey-manager/ || yubikey-manager, yubikey-manager-qt
Note: After you install the yubikey-manager (which can be called by ykman in CLI), you need to enable pcscd.service to get it running
  • Yubikey Personalization — Library and tool to configure slot features over the OTP USB connection. Has optional GUI.
https://developers.yubico.com/yubikey-personalization/ || yubikey-personalization, yubikey-personalization-gui
  • Yubico Authenticator for Desktop — Lets you read OATH codes from your YubiKey over USB. Support the newer OATH implementation (YubiKey NEO and 4) as well as the older slot-based implementation (YubiKey Standard and Edge).
https://developers.yubico.com/OATH/YubiKey_OATH_software.html || yubioath-desktop

Inputs

The YubiKey takes inputs in the form of API calls over USB and button presses.

The button is very sensitive. Depending on the context, touching it does one of these things:

  • Trigger a static password or one-time password (OTP) (Short press for slot 1, long press for slot 2). This is the default behavior, and easy to trigger inadvertently.
  • Confirm / allow a function or access. The LED will illuminate to prompt the user.
  • Insert / eject the smartcard

Outputs

The YubiKey transforms these inputs into outputs:

  • Keystrokes (emulating a USB keyboard), used to type static passwords and OTPs. (Note that static passwords are vulnerable to keyloggers.)
  • The built-in LED:
    • Blinks once when plugged in, useful for troubleshooting.
    • Blinks steadily when a button press is required to permit an API response.
  • API responses over USB. This is used for:
    • Challenge-Response requests (calculated using either Yubico OTP mode or HMAC-SHA1 mode)
    • U2F Challenge-Response requests
    • CCID Smartcard related requests

USB connection modes

Depending on the YubiKey model, the device provides up to three different USB interfaces with their associated protocols. Two of the interfaces implement the USB HID (Human Interface Device) device class; the third is a smart card interface (CCID). The YubiKey is a multi-function USB device, just like a USB printer that can also function as a scanner.

The following table shows which interfaces the different applications use:

Application USB Interface
OTP Keyboard HID
FIDO Other HID
PIV CCID
OpenPGP CCID
OATH CCID

All three interfaces can be independently enabled or disabled. The ykman program uses the term "manage connection modes" and uses OTP, FIDO, and CCID as selectors for which modes should be enabled.

Note: The old U2F mode has been renamed and is now called FIDO in ykman 0.6.1 and later (released 2018-04-16) https://developers.yubico.com/yubikey-manager/Release_Notes.html

The set of enabled USB interfaces affects which applications on the key can be accessed. As an example, if only the HID interfaces are enabled, the applications dependent on the CCID interface are unavailable.

Which application on the key is chosen is determined by the host application and is a combination of USB interface and an application selection mechanism. For example, if the host application wants to communicate with the PIV application on the key, it accesses the key using the CCID interface and using the protocols defined by CCID sends a 'select application' command to the key selecting the PIV application.

Get enabled modes

ykman mode will tell you what modes are currently activated/enabled/available. This could output something like

Current connection mode is: OTP+FIDO+CCID

Meaning that currently the OTP, FIDO and CCID subsystem of the key are enabled.

Set the enabled modes

ykman mode <MODE> will allow you to define which modes should be activated/enabled/available.

  • <MODE> can be a string, such as OTP+FIDO+CCID, or a shortened form o+f+c.
    With "+" you can combine multiple modes that you wish to be enabled.
  • <MODE> can be a mode-number, which is one number that encodes several enabled modes (like flags) into one value.
    The only valid modes when using numbers is 0 - 6 (see here). The extra flags are not part of the mode in that sense, they just need to be set at the same time as the mode is set.

Usually what you want is to make all functionality available (you will still need to potentially configure stuff, see functionality sections below for more details). In order to do so you can use:

ykman mode c+f+o or ykman mode 6

Note: Using the "80" mode-number or the corresponding --touch-eject parameter of ykman mode can only be used when the device is only in CCID mode (by running ykman mode ccid --touch-eject for instance).

Once the --touch-eject flag is set, you should be able to eject/insert the smartcard by pressing the button. The LED should indicate if the card is inserted or not as well.

Warning: But using the 80 mode-number or the corresponding --touch-eject is not recommend as it would prevent you from using the U2F/FIDO and OTP features of the YubiKey.
Note: The often seen:

ykman mode c+f+o --touch-eject or ykman mode 86

will ignore the --touch-eject and be identical to the above recommended ykman mode 6.

86 is not a valid mode. It might be a bug that the tool accepts higher values (see here).

One-time password

This feature has a somewhat misleading name, because it also encompasses the static password and challenge-response functions.

2 slots are provided for this feature, accessible by short and long button presses respectively. Each can be configured with one of the following:

  • Yubico OTP
  • OATH-HOTP
  • OATH-TOTP
  • Challenge-response
  • Static Password

Each function has several configuration options provided at the time of creation, but once set they cannot be read back. It is possible to swap slots 1 and 2, with $ ykman otp swap .

Factory configuration

On a new YubiKey, Yubico OTP is preconfigured on slot 1. This initial AES symmetric key is stored in the YubiKey on the Yubico Authentication server. This allows validating against YubiCloud, allowing the use of Yubico OTP in combination with the Yubico Forum website for instance or on https://demo.yubico.com).

Warning: Before you overwrite slot 1, be aware that you cannot create a new key of the same trust level. (see here) You may think it is a good idea to reset configuration slot 1 to a new OTP. But then a "VV" prefix in your credentials must be used, whereas the factory credentials on your Yubikey use a "CC" prefix. You can upload a "VV" credential using the Yubico personalization tool GUI or manually upload the new AES key to upload.yubico.com in order to regain the same functionality as the original factory configuration. VV credentials are not less secure than CC. However, some services may only trust CC credentials as they believe that the user process is more prone to security vulnerabilities.

Yubico OTP

The Yubico OTP is based on symmetric cryptography. More specifically, each YubiKey contains a 128-bit AES key unique to that device, which is also stored on a validation server. When asked for a password, the YubiKey will create a token by concatenating different fields such as the ID of the key, a counter, and a random number, and encrypting the result.

This OTP is sent to the target system, which passes it to a validation server. The validation server (also in posession of the secret key) decrypts it and verifies the information inside. The result is returned to the target system, which can then decide whether to grant access.

YubiCloud and validation servers

Yubico provides a validation server with free unlimited access, called YubiCloud. YubiCloud knows the factory configuration of all Yubikeys, and is the "default" validation service used by (for example) yubico-pam. Yubico also offers open-source implementations of the server.

Note: To authenticate the Yubico validation server, you can use:

Configuration and Usage

Generate a new key in slot 2, and upload it to YubiCloud (opens in a browser):

$ ykman otp yubiotp --generate-key --upload 2

For more information, see $ ykman otp yubiotp --help

Security risks

AES key compromise

As you can imagine, the AES key should be kept secret. It cannot be retrieved from the YubiKey itself (or it should not, at least not with software). It is also present in the validation server, so the security of this server is very important.

Validation requests/responses tampering

Since the target system relies on a validation server, a possible attack would be to impersonate it. To prevent this, the target system needs to authenticate the validation server, either using HMAC or HTTPS.

OATH

https://developers.yubico.com/OATH/

OATH comes in 2 flavors:

  • HMAC (Hash-based message authentication code) based one-time-password (HOTP), which uses a counter that is incremented each time it's used.
  • Time-based one-time-password (TOTP), which is based on the current time.

HOTP

Every time a key is generated, the yubikey increments a counter. It concatenates a secret key and this counter, and hashes this result. The server increments a counter every time a key is successfully authenticated. To handle desynchronization, the server can also check several (30-100) additional values beyond its current counter state.

To program an HOTP slot in slot 2:

 $ ykman otp hotp 2 (key)

The key must be a base32-encoded value of arbitrary length. To generate one, you can use something like the following:

 $ head -c 256 /dev/urandom | base32 --wrap 0

TOTP

This is the same algorithm that Google Authenticator and other common 2-factor applications use. It works much like HOTP, except it uses the current time instead of a counter. Since the Yubikey doesn't have an internal clock, special software is required to get passwords.

Note that programming TOTP keys uses the challenge-response mode, not the OATH mode. To generate your own key, use a command like the one above. To use a provided key, you will firstly need to aquire the base32 secret key. One way to do this is to decode the provded QR code, which is left as an exercise to the reader. This is what you're looking for:

  otpauth://totp/label%3Ausername?secret=ABCD1234AAAAAAAA&issuer=issuer
                                         ^^^^^^^^^^^^^^^^

To add it to your yubikey:

 $ ykman otp chalresp --totp (slot number) (key)

To generate passwords:

 $ ykman otp calculate --totp (slot number)

If you prefer a GUI to accomplish all of the above, you can use yubioath-desktop.

Challenge-Response

A challenge is sent to the YubiKey, which calculates a response based on some secret. The same challenge always results in the same response. Without the secret this calculation is not feasible, even with many challenge-response pairs.

This can be used for

  • True 2-factor authentication: The user is provided a challenge, they must provide the correct response in addition to a password. Both parties must have the secret key.
  • "Semi" 2-factor authentication: the challenge acts as a password, and the server stores the correct response. This is not an OTP, and if anyone can obtain the response they will gain access, but it is simpler as the server does not need the secret key.

There are two Challenge-Response algorithms:

  • HMAC-SHA1
  • Yubico OTP

You can set them up with a GUI using the yubikey-personalization-gui, or with the following instructions:

HMAC-SHA1 algorithm

Set up slot 2 in challenge response mode with a generated key:

 $ ykman otp chalresp --generate 2

You can omit the --generate flag in order to provide a key. For more information, see $ ykman otp chalresp --help

Yubico OTP algorithm

ykman Does not appear to support setting the chal-yubico algorithm, but you can use ykpersonalize. Generate a random key in slot 2:

 $ ykpersonalize -2 -ochal-resp -ochal-yubico

For more information, see ykpersonalize(1).

Sending a challenge

To send a challenge and get a response:

ykchalresp -<SLOT NUMBER> <CHALLENGE>

Static Password

You can either generate a static password:

 ykman otp static --generate <SLOT NUMBER>

or provide one:

 ykman otp static <SLOT NUMBER> <PASSWORD>

You have several options; you can set the length and character set of the generated password, and whether or not to send an Enter keystroke. See ykman otp static --help for more.

Emulated USB Keyboard limitations, or "Why does my password look so weak?"

In order for the YubiKey to work with most keyboard layouts, passwords are by default limited to the ModHex alphabet (cbdefghijklnrtuv), digits 0-9, and !. These characters use the same scan codes across a very large number of keyboard layouts, ensuring compatibility with most computers.

Yubico has provided a whitepaper on the subject.

U2F

Universal 2nd Factor (U2F) with a Yubikey is very simple, requiring no configuration for the key itself. Note that this mode is also referred to as 'FIDO' in some documentation and utilities. You have a few limited management options through the ykman utility:

  • Set a PIN: $ ykman fido set-pin
  • delete individual credentials: $ ykman fido delete <QUERY>
  • Reset all credentials and PIN: $ ykman fido reset

To use U2F for authentication, see the instructions in U2F.

CCID Smartcard

CCID (Chip Card Interface Device) is a USB standard device class for use by USB devices that act as smart card readers or with security tokens that connect directly via USB, like the Yubikey. HID (Human Interface Device) and CCID are both USB device classes, i.e. they are in the same category of USB specifications. HID is a specification for computer peripherals, like keyboards. The Yubikey works like a USB (HID) keyboard when used in the OTP and FIDO modes, but switches to the CCID protocol when using the PIV application, or as an OpenPGP device.

CCID mode should be enabled by default on all YubiKeys shipped since November 2015 [1]. Enable at least the CCID mode. Please see #Set the enabled modes.

PIV

Starting with the YubiKey NEO, the Yubikeys contain a PIV (Personal Identity Verification) application on the chip. PIV is a US government standard (FIPS 201) that specifies how a token using RSA or ECC (Elliptic Curve Cryptography) is used for personal electronic identification. The YubiKey NEO only supports RSA encryption, later models (YubiKey 4 and 5) support both RSA and ECC. The distinguishing characteristic of a PIV token is that it is built to protect private keys and operate on-chip. A private key never leaves the token after it has been installed on it. Optionally, the private key can even be generated on-chip with the aid of an on-chip random number generator. If generated on-chip, the private key is never handled outside of the chip, and there is no way to recover it from the token. When using the PIV mechanism, the Yubikey functions as a CCID device.

Use OpenPGP smartcard mode

See GnuPG#Smartcards

Using a YubiKey with SSH

The following example describes how to use a YubiKey for SSH keys. A YubiKey with the PIV (Personal Identification Verification) application is required; this means you need a YubiKey NEO or YubiKey 4 or later.

Generating a key pair on the YubiKey

A private key and associated certificate need to be either generated on the YubiKey or imported to it. Install the yubikey-manager package. Insert the YubiKey in a USB port and check that it is recognized:

$ ykman list
YubiKey 4 [OTP+FIDO+CCID] Serial: 1234567

The following two commands (generate-key and generate-certificate) require providing the PIV application's 24-byte management key, if it has been changed from its default value (recommended). The examples below assume the shell variable MK has been set in advance to the 48 character hex string representation of the management key. For example:

$ MK=AB019982CA48BDC6776B1F9A0A3E129FDE0705D219AF0037

Generate a 2048-bit RSA key pair on the YubiKey. The private key will be stored in key slot 9a on the YubiKey, and the public key will be written to the file pubkey.pem.

$ ykman piv generate-key -m $MK -a RSA2048 9a pubkey.pem

Next, use the YubiKey to generate a self-signed certificate for the public key:

$ ykman piv generate-certificate -m $MK -d 1826 -s "SSH Key" 9a pubkey.pem

The Subject field in the certificate will be set to "SSH Key" with the -s option. This field will be included in the prompt for PIN to help identify which key is used for authentication. The example command also specifies the -d option to set the number of days until the certificate expires. If the -d option is omitted, a default value of 365 days is used.

Note that the last parameter in the generate-key command is the file name where the public key is written to, whereas the last parameter in the generate-certificate command specifies where the public key is read from. The certificate is constructed and signed on the YubiKey and stored alongside the private key; the command does not output the certificate.

At this point the YubiKey is ready for authenticating to a SSH server. For this to happen, some additional configuration on both the client and the server is required.

Client configuration

The standard API used to communicate with cryptographic tokens is defined by PKCS#11. Install the opensc package which provides this API in the form of the shared library /usr/lib/opensc-pkcs11.so. The ssh client should be configured to use this library with the directive PKCS11Provider in ~/.ssh/config:

~/.ssh/config
PKCS11Provider /usr/lib/opensc-pkcs11.so

Public key conversion

The pubkey.pem file contains the public key in PEM (Privacy Enhanced Mail) format. OpenSSH uses a different format defined in RFC 4253, section 6.6, so the PEM formatted key should be converted to the format OpenSSH understands. This can be done using ssh-keygen:

$ ssh-keygen -i -m PKCS8 -f pubkey.pem > pubkey.txt

This command uses the import (-i) function of the ssh-keygen, specifies PKCS8 as the input file format (-m), and reads the input from the (-f) file pubkey.pem. The converted key is written on standard output, which is the example is redirected to the file pubkey.txt.

The converted public key should now be copied to the remote server as described in SSH keys#Copying the public key to the remote server.

Initiating an SSH session with the YubiKey

To authenticate a SSH connection using the YubiKey, just use ssh normally. You will be prompted for the PIN instead of a password:

$ ssh remote
Enter PIN for 'SSH Key' 
[user@remote ~]$ 

Using ssh-agent to cache the PIN

ssh-agent (see SSH keys#SSH agents) can also be used with the PKCS#11 library; in this case the PIN code is cached instead of the private key.

$ ssh-add -s /usr/lib/opensc-pkcs11.so

As long as the PIN is cached in by the agent, the cached value is used and the user is not prompted for it.

Further reading

The default PIN code of the PIV application on the YubiKey is 123456; you may want to change it. The YubiKey also requires a 24-byte management key for administrative functions like key generation. If the management key has been changed from its default value, the new value needs to be specified using the -m option on the command line for certain commands. See What is PIV?

Tips and tricks

YubiKey and LUKS encrypted partition/disk

YubiKey can be used to strengthen the security of your LUKS encrypted partition/disk. There are multiple ways to achieve it. But before enabling Yubikey as a 2FA device it is recommended to setup plain LUKS encryption first and make sure it works correctly.

Challenge-Response mode for LUKS passphrase (udev/encrypt)

One way to do it is to use a Challenge-Response mode for creating strong LUKS passphrases. First, install yubikey-full-disk-encryption package. Using this tool you can add/modify/remove Yubikey-protected passphrases.

Make changes to /etc/ykfde.conf configuration file as as:

  • choose Yubikey slot to use for LUKS (YKFDE_CHALLENGE_SLOT)
  • whether you want to type a password at boot (YKFDE_CHALLENGE_PASSWORD_NEEDED) or use predefined password (YKFDE_CHALLENGE) which essentially means you check for Yubikey hardware presence only.

LUKS supports multiple password so you need to select a slot that is going to store Yubikey-protected passphrase. Inspect existing slots using command:

# cryptsetup luksDump /dev/<DISK>

Check entries under Keyslots: section. And then pick an unused slot.

Enroll your new passphrase:

# ykfde-enroll -d /dev/<DISK> -s <LUKS_SLOT>

It will require the new and existing passphrases.

And the last step is to add ykfde hook to /etc/mkinitcpio.conf file before or instead of encrypt hook. Then regenerate initramfs with mkinitcpio -P.

Warning: Plymouth Users: Replace your plymouth-encrypt hook with the ykfde hook. Failure to do so may result in you being locked out of your system.
Warning: As of December 2019 `sd-encrypt` enabled boot is not supported by yubikey-full-disk-encryption.

Challenge-Response mode for LUKS passphrase (systemd/sd-encrypt)

On systems which use systemd instead of udev hook in initramfs, full disk encryption can be served by the mkinitcpio-ykfdeAUR package. Using this tool you can add Yubikey-protected luks slots. Note that this is similar but different project than one mentioned in paragraph above and they aren't compatible with each other.

Make changes to /etc/ykfde.conf configuration file as as:

  • general/device name: devicename (rd.luks.name) defined in /etc/default/grub
  • key specific sections: map individual YubiKeys / slots to luks slots.

Add ykfde challenges file to grub initrd /etc/default/grub:

 GRUB_EARLY_INITRD_LINUX_CUSTOM="ykfde-challenges.img"

Add ykfde hook to /etc/mkinitcpio.conf file before sd-encrypt hook.

Enroll new luks slot:

# ykfde --ask-2nd-factor

Push challenges to /boot partition:

# ykfde-cpio

Rebuild initrd and update grub config:

 # mkinitcpio -P
 # grub-mkconfig -o /boot/grub/grub.cfg

If you want to unlock one single luks slot using multiple YubiKeys sharing the same challenge response configuration you have to enure ykfde uses the same challenge (stored in /etc/ykfde.d/).

For further details please see the project documentation.

OpenPGP applet

Another way of using YubiKey for full disk encryption is to utilize its OpenPGP applet to decrypt the LUKS keyfile during boot. initramfs-scencrypt is a set of hooks for initramfs that automate this process.

HMAC Secret Extension of FIDO2 protocol

Yet another way of using YubiKey for full disk encryption is to utilize HMAC Secret Extension to retrieve the LUKS password from YubiKey which is protected by passphrase supplied by user. This functionality requires at least YubiKey 5 with firmware 5.2.3+.

In order to use this install fido2-hmac-secretAUR and follow instructions available in project documentation.

Yubikey and KeePass

Tango-edit-clear.pngThis article or section needs language, wiki syntax or style improvements. See Help:Style for reference.Tango-edit-clear.png

Reason: Duplicates KeePass. (Discuss in Talk:YubiKey#)

Yubikey can be integrated with KeePass using plugins.

For a native open-source implementation of KeePass have a look at:

keepassx2

keepassx2AUR (see keepassx.org) a keepass QT FOSS reimplementation, extremely stable and available for Windows, MacOSX and Linux.

KeePassXC

keepassxc (see keepassxc.org) a KeePassX fork that integrated YubiKey into KeePassX v2.
The integration covers Challenge-Response as security factor to open the database, but also the generation of OTP using the YubiKey.

In order to have a KeePassXC database work on Android (using the Keepass2Android app), you need to use version 1.06 of the app. You also need to save the database file in the KDBX 4 format, since Keepass2Android do not support the KDBX 3 format.

YubiKey support in Keepass2Android (which is compatible with KeePassXC) is tracked on GitHub.

Two-factor authentication with SSH

This details how to use a Yubikey to have two-factor authentication with SSH, that is, to use both a password and a YubiKey OTP.

Prerequisites

Note: If you are configuring a distant server to use YubiKey, you should open at least one additional, rescue SSH session, so that you are not locked out if the configuration fails and you inadvertently exit your main session.
Note: The following assumes you are using the default Yubico servers. See the yubico-pam documentation for options relevant to using your own server.

Install yubico-pam on the server.

Configuration

Authorization Mapping Files

A mapping must be made between the YubiKey token ID and the user ID it is attached to. There are two ways to do this, either centrally in one file, or individually, where users can create the mapping in their home directories.

If the central authorization mapping file is being used, user home directory mappings will not be used and vice versa.

Central authorization mapping

Create a file (for example, /etc/yubico/authorized_yubikeys) containing a user name and the YubiKey token ID(s) separated by colons for each user you want to allow onto the system using a YubiKey.

<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:...
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:...

You can specify multiple key tokens per user, but only one is required.

Per-user authorization mapping

Each user creates ~/.yubico/authorized_yubikeys and places the mapping in that file, the file must have only one line:

<user name>:<Yubikey token ID1>:<Yubikey token ID2>:...

This is much the same concept as the SSH authorized_keys file.

Note that this file must be readable by the pam_yubico module when the user is authenticated, otherwise login will fail. If this is not possible or desired, use the global mapping file instead.

Obtaining the YubiKey token ID (a.k.a. public ID)

You can obtain the YubiKey token ID in several ways. One is by removing the last 32 characters of any OTP (One Time Password) generated with your YubiKey. Another is by using the modhex calculator.

Enter your YubiKey OTP and convert it, your Yubikey token ID is 12 characters and listed as:

Modhex encoded: XXXXXXX
PAM configuration

Having installed the pam_yubico module, you next need to tell PAM to use it when logging in via SSH. There are several ways of doing this.

The default way

Obtain HMAC credentials from Yubico as described in #YubiCloud and validation servers. You will receive a Client ID and a secret key.

Add one of the two following lines to the beginning of /etc/pam.d/sshd:

auth required pam_yubico.so id=CLIENTID authfile=[/YOUR/AUTH/FILE]

if you are using a central authorization mapping file, or

auth required pam_yubico.so id=CLIENTID

if you are using per-user authorization mapping, where CLIENTID is your Client ID. This method utilizes your ID and the server's certificate to authenticate the connection.

Note: This will authenticate via Yubico's free YubiCloud servers. If you want to use a different server, add it via the urllist parameter.
Using pure HMAC to authenticate the validation server

Add key to the above lines in /etc/pam.d/sshd:

auth required pam_yubico.so id=CLIENTID key=SECRETKEY ...

where CLIENTID and SECRETKEY are your HMAC ID and key.

You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:

# chmod o-r /etc/pam.d/sshd
Note: HMAC credentials should be unique to a single target server. That way, if an attacker finds them, he will not be able to craft responses to authenticate to other target servers you own.
Using pure HTTPS to authenticate the validation server
Warning: While this "old" method of using a dummy id still works, it is unknown how secure and/or future-proof it is, as Yubico no longer describes it in their documentation. Proceed at your own risk. At the very least you should ensure that only HTTPS servers with valid certificates are used for authentication.

If you do not want to use HMAC credentials from Yubico, it is still possible to authenticate via the Yubico server by setting

Template error: are you trying to use the = sign? Visit Help:Template#Escape template-breaking characters for workarounds.

instead of your own ID. Although pam_yubico's default server uses HTTPS already, for security reasons you should specify it manually via the urllist parameter, as the server's certificate is the only way in which the connection is authenticated. You can find the keyserver URL by adding the debug parameter to the auth line.

SSHD configuration

You should check that /etc/ssh/sshd_config contains these lines and that they are not commented. The sshd_config shipped with openssh has these set correctly by default.

ChallengeResponseAuthentication no
UsePAM yes

That is it!

You should not need to restart anything if you did not change the SSHD config file.

To log in, at the Password: prompt of SSH, you have to type your password without pressing enter and touch the YubiKey's button. The YubiKey should send a return at the end of the OTP so you do not need to touch the enter key at all.

You can display information about the login data generated by pam_yubico by adding the debug option to the auth line in/etc/pam.d/sshd. However, if you are using a central authorization file, you should remove that option once finished testing, as it causes pam_yubico to display the entire content of the central file to every user who logs in using a YubiKey.

Explanation

This works because the prompt is pam_yubico.so's one, since this module is before pam_unix.so, which normally does basic password authentication. So, you are giving a string that is the concatenation of your password and the OTP to pam_yubico.so. Since the OTPs have a fixed length (let us call this size N), it just has to get the last N characters to retrieve the OTP, and it assumes that the other characters at the start are the password. It tries to validate the OTP, and in case of success, sends the password to the next PAM module. In Archlinux' default PAM stack, pam_unix.so is instructed to try receiving a password from the previous module with try_first_pass, so it automatically uses the password sent by pam_yubico.so.

Executing actions on insertion/removal of YubiKey device

For example, you want to perform an action when you pull your YubiKey out of the USB slot, create /etc/udev/rules.d/80-yubikey-actions.rules and add the following contents:

ACTION=="remove", ENV{ID_VENDOR}=="Yubico", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0010|0111|0112|0113|0114|0115|0116|0401|0402|0403|0404|0405|0406|0407|0410", RUN+="/usr/local/bin/script args"

Please note, most keys are covered within this example but it may not work for all versions of YubiKey. You will have to look at the output of lsusb to get the vendor and model ID's, along with the description of the device or you could use udevadm to get information. Of course, to execute a script on insertion, you would change the action to 'add' instead of remove.

Maintenance / Upgrades

Installing the OATH Applet for a YubiKey NEO

These steps will allow you to install the OATH applet onto your YubiKey NEO. This allows the use of Yubico Authenticator in the Google Play Store.

Note: These steps are only for NEOs with a firmware version <= 3.1.2. The current generation NEOs (with U2F) come with the OpenPGP applet already installed)

Configure the NEO as a CCID Device

  1. Install yubikey-personalization-gui (yubikey-personalization-gui-gitAUR).
  2. Add the udev rules and reboot so you can manage the YubiKey without needing to be root
  3. Run ykpersonalize -m82, enter y, and hit enter.

Install the Applet

  1. Install gpshellAUR, gppcscconnectionpluginAUR, globalplatformAUR, and pcsclite.
  2. Start pcscd.service.
  3. Download the most recent CAP file from the ykneo-oath site.
  4. Download gpinstall.txt from GitHub.
  5. Edit the line in gpinstall.txt beginning with install -file to reflect the path where the CAP file is located.
  6. Open a terminal and run gpshell <location of gpinstall.txt>
  7. Ideally, a bunch of text will scroll by and it ends saying something like
 Command --> 80E88013D7C000C400BE00C700CA00CA00B400BE00CE00D200D500D700B000DB00C700DF00BEFFFF00BE00E400AC00AE00AE00DB00E700A
A00EA00ED00ED00ED00BE00EF00F100F400F100F700FA00FF00BE00F700AA01010103010700CA00C400B400AA00F700B400AA00B600C7010C
010C00AA0140012001B0056810B0013005600000056810E0011006B4B44304B44404B44106B44B4405B443400343B002410636810E06B4B44
407326810B004B43103441003334002B102B404B3B403BB4003B440076820A4100221024405B4341008B44600000231066820A100
Wrapped command --> 84E88013DFC000C400BE00C700CA00CA00B400BE00CE00D200D500D700B000DB00C700DF00BEFFFF00BE00E400AC00AE00AE00DB00E700A
A00EA00ED00ED00ED00BE00EF00F100F400F100F700FA00FF00BE00F700AA01010103010700CA00C400B400AA00F700B400AA00B600C7010C
010C00AA0140012001B0056810B0013005600000056810E0011006B4B44304B44404B44106B44B4405B443400343B002410636810E06B4B44
407326810B004B43103441003334002B102B404B3B403BB4003B440076820A4100221024405B4341008B44600000231066820A15D848CB77
27D0EDA00
Response <-- 009000
Command --> 80E60C002107A000000527210108A00000052721010108A000000527210101010003C901000000
Wrapped command --> 84E60C002907A000000527210108A00000052721010108A000000527210101010003C9010000B4648127914A4C7C00
Response <-- 009000
card_disconnect
release_context
  1. Unplug the NEO and try it with the Yubico Authenticator app

(Optional) Install the Yubico Authenticator Desktop client

You can get the desktop version of the Yubico Authenticator by installing yubioath-desktop.

While pcscd.service is running, run yubioath-desktop and insert your Yubikey when prompted.

Troubleshooting

Restart, especially if you have completed updates since your YubiKey last worked. Do this even if some functions appear to be functioning.

YubiKey not acting as HID device

Add udev rule as described in this article:

/etc/udev/rules.d/10-security-key.rules
KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0664", GROUP="users", ATTRS{idVendor}=="2581", ATTRS{idProduct}=="f1d0"

Run udevadm trigger afterwards.

You may also need to install the package libu2f-host if you want support in chrome.

ykman fails to connect to the YubiKey

If the manager fails to connect to the YubiKey, make sure you have started pcscd.service or pcscd.socket.

Error: Failed connecting to YubiKey 5 [OTP+FIDO+CCID]. Make sure the application have the required permissions.

This can occur when using ykman to access the oath credentials on the device if scdaemon has already taken exclusive control of the device. [2]

To fix this you can set the reader-port option with the correct value for your device in ~/.gnupg/scdaemon.conf. [3]

Note: This will cause the gpgagent to re-prompt you to unlock the YubiKey after each time you access the YubiKey through ykman.

For YubiKey NEO and YubiKey 4:

reader-port Yubico Yubikey

or for YubiKey 5

reader-port Yubico Yubi

YubiKey fails to bind within a guest VM

Assuming the YubiKey is available to the guest, the issue results from a driver binding to the device on the host. To unbind the device, the bus and port information is needed from dmesg on the host:

$ dmesg | grep -B1 Yubico | tail -n 2 | head -n 1 | sed -E 's/^\[[^]]+\] usb ([^:]*):.*/\1/'

The resulting USB id should be of the form X-Y.Z or X-Y. Then, on the host, use find to search /sys/bus/usb/drivers for which driver the YubiKey is binded to (e.g. usbhid or usbfs).

$ find /sys/bus/usb/drivers -name "*X-Y.Z*"

To unbind the device, use the result from the previous command (i.e. /sys/bus/usb/drivers/<DRIVER>/X-Y.Z:1.0):

# echo 'X-Y.Z:1.0' > /sys/bus/usb/drivers/<DRIVER>/unbind

Error: [key] could not be locally signed or gpg: No default secret key: No public key

Occurs when attempting to sign keys on a non-standard keyring while a YubiKey is plugged in, e.g. as Pacman does in pacman-key --populate archlinux. The solution is to remove the offending YubiKey and start over.

YubiKey disappears and reappears in Yubico Authenticator

This happens when the CCID driver isn't installed. You may need to install the ccid package.