YubiKey 5 Series Configuration Reference Guide

This document describes how the YubiKey Capabilities work and the commands that can be used to set and read the current state. The format described below is only available on YubiKey 5 Series and above, and the Security Key by Yubico.



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.

Supported Capabilities

Supported Capabilities are set during manufacturing. They determine the functionalities of a device. Supported Capabilities cannot be modified.

Enabled Capabilities

Enabled Capabilities are those that are currently available on the device. They are user-configurable and supersede the concept of mode-switching. Modifying Enabled Capabilities can be prevented by setting a Configuration Lock (described below).

List of Capabilities

Each Application is defined as a single bit and is enabled if the bit is set and disabled if not. The list of Capabilities is the following:

Denomination Value Description



Application bit for OTP



Application bit for U2F



Application bit for CCID interface (not settable)



Application bit for OpenPGP



Application bit for PIV



Application bit for OATH



Unused bit



Unused bit



Unused bit



Application bit for CTAP 2

The Enabled Capabilities are always masked with the Supported Capabilities. For example, this means that even if a user sets the bit corresponding to NFC, this won’t take effect if NFC is not supported in the device.

Configuration Lock

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

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

Form Factor Standard YubiKey Value Security Key Value (FW 5.4+) FIPS YubiKey Value (FW 5.4+)





Keychain with USB-A




Nano with USB-A




Keychain with USB-C




Nano with USB-C




Keychain with Lightning and USB-C




Auto-Eject Timeout

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

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

Device Flags control device-global behavior:

Denomination Value Description



In pure CCID mode eject/inject the card with button



Enable remote wakeup

Reading Information

Device Information

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:

Interface Method


Sent as instruction 0x1d to the Management applet


Sent as SLOT 0x13


Sent as HID command 0xc2 (2nd vendor command with INIT set)

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 Name Description


Supported USB Capabilities

Supported USB Applications


Enabled USB Capabilities

Currently enabled USB Applications



Only present if serial is set, 4 Bytes big-endian




Firmware version

Encoded as three Bytes, major-minor-build


Auto-eject timeout

2 Bytes big-endian


Challenge-response timeout


Device flags


Supported NFC Capabilities

Supported NFC Applications, can be none


Enabled NFC Capabilities

Currently enabled NFC Applications


Device is locked

1 if Configuration Lock is set, 0 otherwise

Writing Information

All interfaces support writing information using one of the following commands:

Interface Method


Sent as instruction 0x1c to the Management applet


Sent as SLOT 0x15


Sent as HID command 0xc3 (3rd vendor command with INIT set)

The format for providing the data to be written is a one Byte total length followed by a list of TAG-LENGTH-VALUE (TLV) triplets as the payload of the interface-specific command shown in the previous table. Multiple information can be set as part of the same interface command simply by concatenating several TLVs.

Enabled USB Capabilities

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.

Enabled NFC Capabilities

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.

Set Configuration Lock

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:

  • If the payload is the Byte 00 repeated 16 times, the Configuration Lock is disabled

  • If the payload is anything other than Byte 00 repeated 16 times, the value is stored as the Configuration Lock

Unlock Configuration Lock

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.

Auto-Eject Timeout

TAG = 0x06

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

Challenge-Response Timeout

TAG = 0x07

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

Device Flags

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).

Device Configuration Concepts

Yubico provides ykman which can be used both as a command line configuration tool, and as a python library to interact with the YubiKey.

Ykman represents a YubiKey as a YubiKey object. The YubiKey class is defined in the device module. Each instance of a YubiKey object has an associated driver. The driver module defines the interface for communication with an Application on the device. It specifies the read_config() and write_config() methods. Under the covers, these methods use the TAG-LENGTH-VALUE format, defined in the Capabilities reference, to build the payload that is sent to the device to read and write configuration.

There is a driver implementation for each Application on the device, e.g. FIDO, OATH, OpenPGP, OTP, and PIV. These drivers can communicate with the device over the various interfaces such as CCID, HID, or in the case of OTP, wrap a native c library for reading and writing.

When creating a custom YubiKey configuration software in the python language, use the ykman source code as a guide for reading and writing configurations. If you’d rather integrate with libraries in other languages:

  • Libfido2 C library communicates with the FIDO2/WebAuthn and U2F Applications

  • Ykpiv C library communicates with the PIV Application

  • Ykpers C library communicates with the OTP Application

  • Yubico Authenticator for Desktop and Android Flutter app for desktop and Android platforms, communicates with the OATH Application