YubiKey 5 Series Configuration Reference Guide

The physical interfaces available on a device: USB/Lightning and NFC.

The individual Applications available on a YubiKey device: OTP, U2F, WebAuthn, OpenPGP, PIV, and OATH.

Capabilities^[1] is the collective name used to describe which Applications are and are not enabled on a specific Interface. There are two types of Capabilities: Supported Capabilities and Enabled Capabilities.

[1] Note: YubiHSM 2 has the concept of a Capability which differs from this definition.

The Configuration Lock is a 16 Byte value that can be set by the user or an administrator/crypto officer. If set, changing any user-configurable device information described in this document will not be allowed. The Configuration Lock has to be supplied when sending the SET DEVICE INFORMATION command. By default, the Configuration Lock is disabled with a default value of 00000000000000000000000000000000 (Byte 00, 16 times).

Form factor is set during manufacturing and returned as a one-Byte value. Currently defined values for this are:

Auto-Eject Timeout controls the period of inactivity (in seconds) after which the CCID card should be considered ejected. This is only meaningful if the Device Flag, MODE_FLAG_EJECT, is set.

Challenge-Response Timeout controls the period of time (in seconds) after which the OTP module Challenge-Response should timeout. The default is 15 seconds.

Device Flags control device-global behavior:

In order to obtain the current Device Information, a GET DEVICE INFORMATION command can be sent. The way the command is specified depends on the interface:

The format described above is compatible with the Capabilities interface available in YubiKey 4 and expands upon it.

The data returned by the GET DEVICE INFORMATION command always has the same format, regardless of the interface used to obtain it.

The format is:

TOTAL-LENGTH (1 Byte) TAG (1 Byte) LENGTH (1 Byte) VALUE (LENGTH Bytes)

The triplet TAG-LENGTH-VALUE is repeated several times, once for each TAG in the table below. All fields are always present, with the exception of Serial, which is present only if a serial number is set, and the NFC related Capabilities, which are only present if NFC has been enabled during the manufacturing process.

TAG = 0x03

Enabled USB Capabilities are set by supplying the complete list of packed bits. A set bit means that the related Application is enabled, a cleared bit means that the related Application is not available through the interface.

TAG = 0x0c

Enabled USB Capabilities are set by supplying the complete list of packed bits. A set bit means that the related Application is enabled, a cleared bit means that the related Application is not available through the interface.

TAG = 0x0a

This is used to set the Configuration Lock. The payload is a 16 Byte value and, depending on the value, one of the following operations is performed:

TAG = 0x0b

This is used to provide the Configuration Lock and to allow changing user-configurable values. The payload has to be the correct 16 Byte Configuration Lock. If the Configuration Lock is disabled, this TAG-LENGTH-VALUE (TLV) has no effect. The Unlock Configuration Lock TLV can be present anywhere in the list of TLVs sent as part of the interface command, but it can not be part of a separate command. All interface commands requiring the Configuration Lock must contain an Unlock Configuration Lock TLV.

TAG = 0x06

Auto-Eject Timeout is set by supplying a 2 Bytes Big-Endian value.

TAG = 0x07

Challenge-Response Timeout is set by supplying a 1 Byte value.

TAG = 0x08

Device Flags is set by supplying a 1 Byte value.

TAG = 0x0c

This TLV doesn’t require a payload (its length can be zero). If present as part of a list of TLVs forces the device to reboot if all the other TLVs have been correctly parsed. This is useful when enabling or disabling interface. Reboot is determined by the Configuration Lock (missing/wrong Configuration Lock will produce an error and not reboot).