This document describes general concepts of a YubiKey, how to use them, as well as the functionality they provide. These concepts are used throughout our SDKs.
A YubiKey refers to the physical device. Sometimes referred to as a Security Key or an Authenticator. A YubiKey has one or more Transports available which allow it to be connected to a host device, such as a desktop computer, or a mobile smart phone.
A Transport is a mechanism for communicating with a YubiKey. Different models of YubiKeys support different Transports. Examples include: USB, NFC, and Lightning.
The USB transport can be used with YubiKeys having a physical USB A or C connector. When connected via USB, the YubiKey will present a Vendor ID and Product ID. The Vendor ID (VID) for Yubico is 0x1050 (decimal 4176) and the Product ID (PID) will vary depending on the model and configuration of the YubiKey.
Communication over the USB transport is done via one of three USB Interfaces.
The HID based OTP USB interface (sometimes referred to as the keyboard interface) causes the YubiKey to act as a USB keyboard. It is used to communicate with the YubiOTP Application, and to output keyboard sequences when triggered via the touch sensor (short or long press).
The CCID USB interface causes the YubiKey to act as a smart card reader. It can be used to communicate with several of the YubiKey Applications.
The HID-based FIDO USB interface causes the YubiKey to act as a FIDO Authenticator, for use with FIDO protocols and WebAuthn. This interface was previously referred to as the "U2F" interface.
Note: USB Interfaces will deactivate if their Applications are disabled or unsupported, and will, in such a case, not be present in the USB Descriptor.
The NFC transport can be used with YubiKeys having a built-in NFC antenna. The host device needs an NFC reader, and communication is done via the "contactless smart card" protocol (ISO/IEC 14443).
The Lightning transport can be used with YubiKeys having a Lightning connector, such as the YubiKey 5Ci. Similar to USB, the Lightning transport provides multiple interfaces, which allow iOS to interact with the YubiKey as a FIDO Authenticator and a keyboard, but only one of the interfaces is directly accessible to client applications, which is the Accessory interface. The protocol used for this is proprietary and can be accessed via the Yubico Mobile SDK for iOS.
A Connection is an open link to the YubiKey, via one of its transports. Generally, the YubiKey will only support one concurrent connection at a time. Depending on the transport used (and for the USB transport, which USB interface is used) different types of connections may be available.
This connection is available over the NFC and Lightning transports, as well as by connecting to the CCID interface over the USB transport. It allows the host to exchange smart card messages with the YubiKey, using APDU message command-response pairs.
This connection is available over the USB transport by using the FIDO USB interface, as well as over the Lightning transport. For NFC, this connection type is not available (FIDO protocols use the Smart Card connection over NFC). It allows communication with the YubiKey using the FIDO CTAP HID protocol.
This connection is available over the USB transport by using the OTP USB interface. It allows communication with the YubiKey by sending and reading HID feature reports, for communicating with the YubiOTP Application.
A Session is established over a Connection, with a specific Application. The session has state, which is shared between the YubiKey itself, and the host application. Generally, only one Session may be active at one time. A Session is active until the underlying Connection is closed, or until a different Application is selected (as when a new Session is started).
The YubiKey supports multiple protocols and features, and this is segmented into a number of Applications which run inside the YubiKey. Not all Applications may be available on all YubiKeys, and not all Applications may be accessible over all Transports.
The Management application is used to manage configuration related to the YubiKey itself, and cannot be disabled. It can be accessed over any of the defined connection types, using any transport.
An identifier for a YubiKey Application which can be managed. A Management Session can be used to see if a YubiKey supports a specific Application (eg. "does the YubiKey have the PIV capability"), and if so, if it is enabled or not.
A Management Session can be used to update the Device Configuration, which holds user-modifiable configuration for the YubiKey. The Device Configuration contains:
|
Enabled Capabilities
|
Which of the supported Applications are enabled, and over which transports. |
|
Timeouts and flags
|
General settings in the YubiKey, such as the timeout for waiting for touch. |
|
Configuration Lock
|
An optional lock code which, if set, is required to change the Device Configuration. |
The Management application can be used to read out information about the YubiKey, including its current configuration. The Device Info contains:
|
Device Config
|
The current device configuration. |
|
Supported Capabilities
|
The set of Application Capabilities which are supported by the YubiKey, and over which Transports. |
|
Serial Number
|
The serial number of the YubiKey, if available. |
|
Firmware version
|
A 3-part version number of the firmware. |
|
Form Factor
|
An identifier indicating the form factor of the YubiKey. |
|
Configuration lock status
|
Whether or not a Configuration Lock code is set. |
The USB mode was an older concept from before the introduction of the Device Configuration. The older command was used to enable and disable USB interfaces. This command is available on YubiKey 3 and 4. It was removed in YubiKey 5, where it has been replaced by the Device Configuration.
The YubiOTP application (sometimes referred to simply as the "OTP Application") is used to manage the two keyboard configuration slots, generally triggered by a short or long press on the touch sensor. Each slot can be configured independently of the other, and supports multiple protocols. This application can be accessed over the OTP connection when using the USB transport, and over the Smart Card connection when using the NFC and Lightning transports.
A keyboard configuration slot, numbered 1 (short press) or 2 (long press). A slot may be either unconfigured (empty) or configured. Activating a slot via the touch sensor generally causes the YubiKey to output a string of characters via the keyboard USB interface, as defined by the slots Configuration.
The Configuration comprises key material and parameters for how a slot is used. There are various types of configurations:
|
Yubico OTP
|
A One-Time Password algorithm developed by Yubico, typically using 44 characters, Modhex encoded. |
|
OATH-HOTP
|
The event-based 6-8 digit OTP algorithm as specified in RFC-4226. |
|
Static password
|
A static (non-changing) password. |
|
Challenge-Response
|
A HMAC-SHA1 key for use with challenge-response protocols (programmatically activated, can require touch). |
When writing a configuration to a Slot, any previous configuration in that slot is overwritten. However, it is also possible to update an existing slot with new flags, which alters the parameters used for it. Whether a slot is updatable or not is itself defined by a flag, which must have been set during previous configuration for this command to work.
Each slot can optionally have a 6 byte access code. If set, any modification of the configuration (including overwriting or deleting it) requires the access code to be provided.
The state of the slots, with indication of if each slot is configured or empty, and if it requires touch for activation or not (applicable to Challenge-Response).
For YubiKeys with the NFC transport, one of the two slots can be used as the NFC NDEF output. A static URL prefix is set, and a slot is associated with it, causing NDEF payload to contain the slot output. By default, slot 1 is configured with the "https://my.yubico.com/yk/#" prefix.
The OATH application allows the YubiKey to store multiple OATH credentials, which can be programmatically used via a client app, such as Yubico Authenticator. The application supports storing up to 32 different credentials, supporting both HOTP and TOTP variants. This application can be accessed over the Smart Card connection when using any transport.
A unique random value specific to the YubiKey, which can be used to identify the YubiKey. The Device ID is randomly re-generated if the Application is reset.
An optional access key used to prevent unauthorized use of the Application. Typically this key is derived from a password. If set, almost all commands will require the OATH Session to be unlocked before being invoked. An unlocked Session remains unlocked until it is closed.
The OATH algorithm to use for a Credential. Supported types are TOTP (time based), and HOTP (counter based). Hash Algorithm The hash algorithm to use when calculating Codes. Supported algorithms are SHA-1, SHA-256, and SHA-512.
An OATH credential. Each Credential has a unique ID, comprising its (optional) Issuer, Name and (optional) validity period. The Credential also has an OATH type, hash algorithm, OTP length, and whether or not it requires a user presence (touch) check to be used.
A single use OATH code, 6-8 digits. Can be calculated from a Credential. TOTP codes are typically valid for up to 30 seconds past time of calculation.
Perform a "factory reset" of the OATH application. All credentials are deleted, access key removed, and a new device ID is generated.
The PIV application implements PIV, or FIPS 201, which is a US government standard. It enables RSA or ECC sign/decrypt operations using a private key stored on a smartcard, as well as the storage of X.509 certificates. This application can be accessed over the Smart Card connection when using any transport.
You can read more about the PIV standards here: https://csrc.nist.gov/groups/SNS/piv/standards.html
6-8 character value which unlocks the usage of private keys for the Session. If the wrong PIN is entered too many times (3 by default), the PIN becomes blocked, and cannot be used. The number of allowed attempts can be changed by the user.
6-8 character value which can be used to reset a blocked PIN. Like the PIN, the PUK also becomes blocked if entered incorrectly too many times (3 by default). The number of allowed attempts can be changed by the user.
A 24 byte 3-DES key used to authenticate the PIV Session. This allows writing to Data Objects as well as importing/generating private keys.
PIV allows a number of private keys to be stored and used, identified by Slot IDs. Each slot can hold a single key. While functionally the same, different Slots have different intended uses, and different PIN Policy defaults. Key A private key stored in a Slot. Each key is of one of the supported key types, which are: RSA 1024, RSA 2048, ECC P-256, ECC P-384.
Each private key has a PIN policy, which determines what PIN verification (if any) is required to use the key. Available policies are: DEFAULT (different Slots have different defaults), NEVER, ONCE, ALWAYS.
Each private key has a touch policy, which determines if user presence verification (touch) is required to use the key. Available policies are: DEFAULT (same as NEVER), NEVER, ALWAYS, CACHED.
PIV allows a number of data objects to be stored on a YubiKey, identified by an object ID.
Each key slot has an accompanying data object ID, which is typically used to store a corresponding X.509 certificate.
Any key that was generated within the YubiKey can be attested, using a factory-installed attestation certificate. This allows a third party to verify that a public key corresponds to a private key from a specific YubiKey (identified by serial number).
Perform a "factory reset" of the PIV application. This deletes all keys and data objects, with the exception of the attestation key and certificate. It also resets the PIN, PUK, and management key to their default values, as well as the number of allowed attempts for PIN and PUK.
The OpenPGP application implements the OpenPGP card standard, compatible with GnuPG. OpenPGP is an open standard for signing and encrypting files and messages. This application can be accessed over the Smart Card connection when using any transport.
The protocol specification can be found here: https://gnupg.org/ftp/specs/.
The FIDO application implements both the U2F and FIDO2 protocols, for use with WebAuthn. This application can be accessed over the FIDO connection when using the USB transport, and over the Smart Card connection when using the NFC and Lightning transports.
You can find the WebAuthn specification here: https://www.w3.org/TR/webauthn/ For help getting started, go here: https://developers.yubico.com/WebAuthn/
To learn more about the ways you can secure your service, mobile app, or dive deeper into the YubiKey hardware go to https://developers.yubico.com/Developer_Program/Guides/