Firmware Specifics Prior to 5.6.x

This section gives summary descriptions of features that came out with firmware versions prior to the current 5.7.x release.

Secure Channel (Firmware 5.3.0 and later)

Secure channel is used for establishing an authenticated and encrypted communication channel over CCID between a host and the secure element on the YubiKey. The YubiKey security domain can store three concurrent long-lived transport key sets.

SCP03 (Secure Channel Protocol 03), which is part of the GlobalPlatform standard, is a framework for mutual authentication and encrypted transport between hosts and secure elements in smart cards. This protocol for secure channel is implemented on YubiKeys as of Yubico 5.3.0 firmware.

For detailed descriptions of the secure channel feature refer to Yubico Secure Channel Technical Description, Yubico Secure Channel Key Diversification and Programming, and Yubico SCP03 Developer Guidance.

Note

Applications based on PKCS #11 or Microsoft CNG do not usually use the secure channel.

Security Domains & Key Diversification

The authenticated and encrypted communication channel takes place over the CCID interface between a host and the secure element on the YubiKey. This includes configuration of, or communication from, CCID applications. The secure channel feature can therefore be used to load application keys onto the YubiKey to be used with the CCID applications OATH, OpenPGP, or PIV.

_images/writing-CCID-application-keys-over-SCP03.png

Writing CCID Application Keys over SCP03

The YubiKey security domain can store three concurrent transport key sets. A transport key set contains three long-lived AES keys. When a session is established, the session AES keys are derived from the long-lived transport key set.

Key diversification is the process of deriving a secure channel static transport key set from a Batch Master Key (BMK), the YubiKey identifier (part of the device serial number), and additional metadata. Key diversification therefore facilitates secure distribution of key sets over a secure channel. To derive the YubiKey transport key sets, the Batch Master Key (BMK) is shared with the CMS system. If the CMS vendor gives Yubico access to its BMK, Yubico can preprogram the secure channel transport key sets for the YubiKey 5 batches. The BMK could be protected by the YubiHSM2.

In order to import new transport key sets, establish a secure channel with the security domain. Do this with a previously loaded transport key set or the default transport key set. Each secure channel transport key set is protected by being written to the YubiKey security domain in the secure element and stored in a server, typically a CMS system. The host that is accessing the YubiKey has an agent that connects to the CMS system to retrieve the secure channel key set. Based on the secure channel key set, both on the host and the YubiKey, a secure session is established.

_images/establish-SCP03-secure-channel.png

Establish SCP03 Secure Channel

Secure Channel Benefits and Usage

  • Encryption application keys can be stored on the CMS server as well as on the YubiKey. If the YubiKey is lost or compromised, the encryption key can be recovered and loaded onto a replacement YubiKey.
  • Key diversification enables simplified and secured distribution of secure channel transport key sets as only the BMK must be shared with the CMS system to derive the YubiKey transport key sets.
  • The secure channel transport key sets can be preprogrammed at the YubiKey batches by Yubico, if the Yubico supply chain has access to the BMK of the CMS vendor.
  • The CMS system can generate the secure channel transport key sets based on the YubiKey serial numbers, the BMK, and additional metadata. The CMS can then use the initial secure channel transport key set for writing additional secure channel transport key sets to the YubiKeys.
_images/SCP03-key-diversification.png

SCP03 Key Diversification

For more technical information, see Yubico Secure Channel Key Diversification and Programming.

Secure Channel CPLC Data

The Card Production Life Cycle (CPLC) data object is a random dataset that is stored on each YubiKey to assure unique identification of the YubiKeys in CMS. Although it is officially deprecated from the SCP03 standard, it is still widely used to hold card data specific to CMS services or to uniquely identify smart cards. Therefore Yubico has implemented the CPLC data object to provide unique identification of YubiKeys for CMS vendors.

For a more detailed description of CPLC data object, see Secure Channel CPLC Data.

NFC ID: Calculation Changed (5.3.0)

Crucial to vendors of physical access control systems and door protection systems utilizing NFC readers, the modification of the YubiKey NFC ID calculation enables NFC readers and access management systems (door locks) using the NFC ID tag to identify NFC-enabled YubiKeys, including those without serial numbers. It is now calculated so that a unique string is returned in the first part of the NFC ID. Until the release of the 5.3.0 firmware, the fact that some access control systems truncate the YubiKey NFC ID meant that YubiKey 5 NFC IDs appeared to be non-unique.

For more technical information on this, see NFC ID Calculation Technical Description.

YubiHSM Auth (5.4.3)

YubiHSM Auth

Introduction

YubiHSM Auth is a YubiKey CCID application that stores the long-lived credentials used to establish secure sessions to a YubiHSM 2. The secure session protocol is based on Secure Channel Protocol 3 (SCP03), see Yubico Secure Channel Technical Description. YubiHSM Auth is supported by YubiKey firmware version 5.4.3 and above.

YubiHSM Auth uses hardware to protect the long-lived credentials for accessing a YubiHSM 2. This increases the security of the authentication credentials, as compared to the authentication solution for the YubiHSM 2 based on software credentials derived from the Password-Based Key Derivation Function 2 (PBKDF2) algorithm with a password as input.

Credentials and PIN Codes

Each YubiHSM Auth credential is comprised of two AES-128 keys which are used to derive the three session-specific AES-128 keys. The YubiHSM Auth application can store up to 32 YubiHSM Auth credentials in the YubiKey.

Each YubiHSM Auth credential is protected by a 16-byte user access code provided to the YubiKey for each YubiHSM Auth operation. The access code is used to access the YubiHSM Auth Credential to derive the session-specific AES-128 keys.

Storing or deleting YubiHSM Auth credentials requires a separate 16-byte admin access code.

Each access code has a limit of eight retries and optionally, verification of user presence (touch).

YubiHSM 2 Secure Channel

Use the YubiKey YubiHSM Auth application to establish an encrypted and authenticated session to a YubiHSM 2. Although the YubiHSM 2 secure channel is based on the protocol Global Platform Secure Channel Protocol ‘03’ (SCP03), there are two important differences:

  • The YubiHSM 2 secure channel protocol does not use APDUs, so the commands and possible options are not those of the complete SCP03 specification.
  • SCP03 uses key sets with three long-lived AES keys, while the YubiHSM 2 secure channel uses key sets with two long-lived AES keys.

The YubiHSM 2 authentication protocol uses a set of static credentials called a long-lived key set. This consists of two AES-128 keys:

  • ENC: Used for deriving keys for command and response encryption, as specified in SCP03.
  • MAC: Used for deriving keys for command and response authentication, as specified in SCP03.

The identical long-lived keyset is protected in the YubiHSM 2 and in the YubiKey YubiHSM Auth application.

Those long-lived key sets are used by the YubiHSM Auth application to derive a set of three session-specific AES-128 keys using the challenge-response protocol as defined in SCP03:

  • Session Secure Channel Encryption Key (S-ENC): Used for data confidentiality.
  • Secure Channel Message Authentication Code Key for Command (S-MAC): Used for data and protocol integrity.
  • Secure Channel Message Authentication Code Key for Response (S-RMAC): Used for data and protocol integrity.

The YubiHSM Auth session-specific keys are output from the YubiKey to the calling library, which uses the session keys to encrypt and authenticate commands and responses during a single session. The session keys are discarded afterwards.

Architecture Overview

The figure below shows how the YubiHSM Auth application fits in to the YubiHSM 2 architecture.

_images/yubihsm-auth-architecture.png

The identical long-lived credentials (key sets) are protected in both the YubiKey YubiHSM Auth application and in the YubiHSM 2. The YubiHSM-Shell software tool can be used for generating the key sets in the YubiHSM 2, and the YubiHSM-Auth software tool can be used for importing the same key sets to the YubiKey YubiHSM Auth application.

At the client, the YubiHSM authentication protocol is implemented in the libykhsmauth library, which derives the three session AES-keys by calling the YubiKey YubiHSM Auth CCID application. The session objects that are created can be used by the libyubihsm in the communication with YubiHSM.

The YubiHSM session keys are therefore generated on the basis of the long-lived credentials that are protected in the YubiHSM 2 and YubiKey YubiHSM Auth in conjunction with the SCP03 derivation scheme.

YubiHSM Auth Flowchart

The flowchart below illustrates the authentication protocol communication with YubiHSM using the static keys on YubiHSM Auth. It is assumed that the YubiHSM and YubiHSM Auth application share the same static keyset. The steps are explained below.

_images/yubihsm-auth-flowchart.png
  1. The user launches YubiHSM-Shell and enters the commands connect and session open, with the flag ykopen that indicates that the YubiKey with YubiHSM Auth shall be used.
  2. The YubiHSM-Shell invokes the libyubihsm library, with a request to open a session to the YubiHSM 2.
  3. The libyubihsm library generates a host challenge, and opens a session to the YubiHSM 2 device.
  4. The YubiHSM 2 device generates an HSM challenge, and generates the session keys based on the HSM challenge, the host challenge, and the static key set in the YubiHSM 2 device. The YubiHSM 2 returns the HSM challenge in an HSM response to the libyubihsm library.
  5. The libyubihsm library propagates the host challenge and HSM challenge to the YubiHSM Shell.
  6. The user enters the Credential password for unlocking the static keyset in the YubiHSM Auth application in the YubiKey. The YubiHSM Shell invokes the libykhsmauth library, with a request to generate session keys.
  7. The libykhsmauth library invokes the YubiHSM Auth application in the YubiKey with the Credential password, the HSM challenge and host challenge are used as input parameters.
  8. The Credential password unlocks the static keyset in the YubiHSM Auth application, and the YubiHSM Auth application generates the session keys based on the static keys, HSM challenge, and host challenge.
  9. The libykhsmauth library returns the session keys to YubiHSM Shell.
  10. The YubiHSM Shell acknowledges the protocol handshake to libyubihsm.
  11. The libyubihsm sends the host response to the YubiHSM 2 device. The session keys can now be used for secure channel communication between YubiHSM-Shell/libyubihsm in the host and the YubiHSM device.

Software and Tools

YubiHSM-Auth Software Tool

The YubiHSM-Auth software tool is part of the YubiHSM Shell, which is installed with the YubiHSM SDK. YubiHSM-Auth tool can be used for:

  • Storing the YubiHSM Auth credentials on a YubiKey
  • Deleting the YubiHSM Auth credentials on a YubiKey
  • Listing the YubiHSM Auth credentials on a YubiKey
  • Changing the YubiHSM Auth management key on a YubiKey
  • Checking the number of retries of the YubiHSM Auth credential password
  • Checking the version of the YubiHSM Auth application
  • Calculating session keys, mainly for debugging and test purposes
  • Resetting the YubiHSM Auth application on a YubiKey

First, the YubiHSM 2 device needs to be configured with an authentication key. The default authentication key password on KeyID=1 is set to password, and this should be changed or replaced with other authentication keys. For the examples in this section, however, it is assumed that the default authentication key is still present on the YubiHSM 2.

To generate and store the equivalent YubiHSM Auth credentials on the YubiKey, use the yubihsm-auth command line tool. To invoke YubiHSM-Auth, simply run yubihsm-auth with the required commands and parameters.

To get a list of available commands, parameters and their syntax, run: yubihsm-auth --help.

An example of how to use yubihsm-auth for storing YubiHSM Auth credentials on a YubiKey is shown below:

$ yubihsm-auth -a put --label="default key" --derivation-password="password" --credpwd="MyPassword" --touch=on --mgmkey="00000000000000000000000000000000" --verbose=5
Credential successfully stored

Where:

  • -a put is the action to insert a YubiHSM Auth credential on the YubiKey
  • --label is the label of the YubiHSM Auth credential on the YubiKey
  • --derivation-password is used as input to the PBKDF2 algorithm, which is used for generating the two AES-128 keys that constitute the YubiHSM Auth credentials to be stored on the YubiKey
  • --credpwd is the password protecting the YubiHSM Auth credentials on the YubiKey
  • --touch is set to on. This requires the user touch the YubiKey when accessing the YubiHSM Auth credential
  • --mgmkey is the management key that is needed for writing the YubiHSM Auth credentials on the YubiKey
  • --verbose is used to print more information as output

Note

We recommend using an offline air-gapped computer when storing the YubiHSM Auth credentials on the YubiKey.

Now, the YubiKey YubiHSM Auth application can be used with YubiHSM Shell for authentication to the YubiHSM 2.

Using YubiHSM-Auth with YubiHSM Shell

It is possible to authenticate to the YubiHSM 2 device with static credentials that are protected in the YubiKey application called YubiHSM Auth. For more information on this YubiKey feature and how to configure it, see the YubiHSM User Guide, section YubiHSM Auth.

The YubiHSM Shell tool supports authentication with YubiHSM Auth credentials in both interactive mode and command-line mode.

To use yubihsm-shell with the YubiHSM Auth-enabled YubiKey in interactive mode, open a session by executing the following yubihsm-shell command:

yubihsm> session ykopen <authkey> <label> <password>

where, in the context of using YubiHSM-Shell with the YubiHSM Auth application, the following parameters are used:

  • authkey is the identifier of the authentication key in the YubiHSM 2
  • label is the label of the YubiHSM-Auth credentials stored in the YubiKey
  • password is the password that protects the YubiHSM-Auth credentials stored in the YubiKey.

Below is an example of an interactive command with YubiHSM Shell:

yubihsm> session ykopen 1 "default key" "MyPassword"
trying to connect to reader 'Yubico YubiKey OTP+FIDO+CCID 0'
Created session 0

To use yubihsm-shell with YubiHSM Auth in command-line mode, add the parameter --ykhsmauth-label that implicitly invokes the YubiHSM Auth application at the YubiKey. Below is an example of how to use YubiHSM Shell in command-line mode:

$ yubihsm-shell --ykhsmauth-label "default key" -p "MyPassword" -a generate-asymmetric -A rsa2048 -i 11 -c sign-pss -l Signature_Key

If the YubiKey is configured to require touch when accessing the YubiHSM-Auth credentials, the user needs to touch the YubiKey sensor in addition to entering the credential password.

Once the user is authenticated with YubiHSM Auth, all YubiHSM-Shell commands can be used.

YubiHSM Auth is a CCID application that can store long-lived credentials (AES keys) that are used to establish secure sessions to a YubiHSM 2. By providing an external challenge, a derivation scheme that yields three session keys is executed. The session keys are not stored on the YubiKey but simply output as a result. The session keys can be used for authentication to the YubiHSM 2. The authentication scheme is based on SCP03 (see Secure Channel (Firmware 5.3.0 and later) above). Each long-lived YubiHSM Auth credential is protected by a user access code that has to be provided to authenticate each session. Storing and deleting credentials requires a separate admin access code.

Benefits and Usage

YubiHSM Auth enables the secure storage of the long-lived credentials for accessing a YubiHSM 2. The existing authentication solution for the YubiHSM 2 is based on software credentials derived from the Password-Based Key Derivation Function 2 (PBKDF2) algorithm with a password as input.

Generating keys using PBKDF2 is just for convenience. It is preferable - and recommended - to provide AES keys directly to avoid exposing them to attack. Not only is it important to avoid losing the derivation password or the keys themselves (as those are basically the same thing), but those credentials also

  • Exist outside a secure element and
  • Need to be given in clear text to the program that uses them loads them into memory.

With YubiHSM Auth only the ephemeral session keys exist outside a secure environment.

Click for Yubico Support.