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:

The YubiKey transforms these inputs into outputs:

Depending on the YubiKey model, the device provides up to three different USB interfaces. Two of the interfaces implement the USB HID (Human Interface Device) device class; the third is a smart card interface (CCID). All three can be enabled or disabled independently, allowing control of their associated protocols.

The following table shows which protocols use which interfaces:

All modes are enabled from the factory. To change them:

Here is a table of mode-numbers, if you care to use them:

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:

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 .

On a new YubiKey, Yubico OTP is preconfigured on slot 1. This initial AES symmetric key is stored in the YubiKey and 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).

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.

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.

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

For more information, see .

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.

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.

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.

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

returns a 40-byte SHA1-hash unique to the programmed slot 2. A different challenge produces another unique response.

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 for more.

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

You can also do things manually. Program a TOTP key, requiring a button touch to generate a code:

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 utility:

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

Also see WebAuthn.

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 #Get enabled modes.

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 exact algorithms supported depends on the firmware. For example, only YubiKeys with firmware 5.7 and up support RSA 3072, RSA 4096, Ed25519, and X25519 keys [2]. 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.

The YubiKey can act as a standard OpenPGP smartcard; see GnuPG#Smartcards for instructions on how to set up and use it with GnuPG. Yubico also provides some documentation in https://developers.yubico.com/PGP/.

If you do not want to use the other features (U2F and OTP), the button can be configured to insert and eject it, and an auto-eject timeout can be set as well. See #USB connection modes for more.

The default user pin is and the default admin pin is . The default PUK is also . Remember to change all 3.

This section details how to use your YubiKey for various authentication purposes. It is by no means an exhaustive list.

You must regenerate the initramfs for any configuration changes to take effect.

Users of the hook may install mkinitcpio-ykfde or mkinitcpio-ykfde-git and follow the instruction in the project documentation. The procedure is broadly similar to yubikey-full-disk-encryption.

One tool to accomplish this is initramfs-scencrypt; see its docs for complete instructions. Note that as of October 2022 this package is not in the AUR and is not thoroughly tested, though the GitHub repository offers a PKGBUILD.

The dm-crypt pages offer a few alternatives, though they are mostly links to old forum posts.

Yet another way of using YubiKey for full disk encryption is to utilize HMAC Secret Extension to retrieve the LUKS password from YubiKey. This can be protected by a passphrase. This functionality requires at least YubiKey 5 with firmware 5.2.3+. For a passphrase protected solution, install khefin and follow instructions available in project documentation. For single factor (optionally PIN-protected) solution and starting with systemd 248, it is possible to use your FIDO2 key as LUKS2 keyslot. Instructions available in the author's blog post.

KeePass can be configured for YubiKey support; see the YubiKey section for instructions.

If your YubiKey supports CCID smartcards, you can use it as a hardware-backed SSH key, either based on GPG or PIV keys. Yubico offers good documentation:

You may also use the U2F feature of the YubiKey to create hardware-backed SSH keys. See SSH keys#FIDO/U2F for instructions.

yubikey-agent stores the SSH key as PIV token. See https://github.com/FiloSottile/yubikey-agent#readme for a setup guide.

PAM, and therefore anything which uses PAM for user authentication, can be configured to use a YubiKey as a factor of its user authentication process. This includes sudo, su, ssh, screen lockers, display managers, and nearly every other instance where a Linux system needs to authenticate a user. Its flexible configuration allows you to set whichever authentication requirements fit your needs, for the entire system, a specific application, or for groups of applications. For example, you could accept the YubiKey as an alternative to a password for local sessions, while requiring both for remote sessions. In addition to the Arch Wiki, You are encouraged to read pam(8) and pam.conf(5) to understand how it works and how to configure it.

There are several modules available which integrate YubiKey-supported protocols into PAM:

PAM configuration is beyond the scope of this article, but for a brief overview:

Many web services are beginning to support FIDO hardware tokens. See the U2F and WebAuthn pages for more information, but usually the only thing you need to do is to install libfido2 and try it.

For example, you want to perform an action when you pull your YubiKey out of the USB slot, create and add the following contents:

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.

The authenticator is a long-running GUI process. If run directly in a udev rule, the process would block udev's processing. If forked, udev would unconditionally kill the process after the event handling finishes. Thus you cannot start the authenticator from udev rules. However, systemd.device may be used to handle this case.

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.

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

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:

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

This happens when the CCID driver is not installed. You may need to install the ccid package.

You are probably using the wrong slot. Try the other one.

Because gpg(scdaemon) tries to acquire exclusive access to the yubikey. It needs to be configured to use pscs and use shared access.[5][6]