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). YubiHSM Auth is supported by YubiKey v5.4.0 and higher.
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.
The figure below shows how the YubiHSM Auth application fits in to the YubiHSM 2 architecture.
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.
- The user launches YubiHSM-Shell and enters the commands
session open, with the flag
ykopenthat indicates that the YubiKey with YubiHSM Auth shall be used.
- The YubiHSM-Shell invokes the
libyubihsmlibrary, with a request to open a session to the YubiHSM 2.
libyubihsmlibrary generates a host challenge, and opens a session to the YubiHSM 2 device.
- 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
libyubihsmlibrary propagates the host challenge and HSM challenge to the YubiHSM Shell.
- The user enters the Credential password for unlocking the static keyset in the YubiHSM Auth application in the YubiKey. The YubiHSM Shell invokes the
libykhsmauthlibrary, with a request to generate session keys.
libykhsmauthlibrary invokes the YubiHSM Auth application in the YubiKey with the Credential password, the HSM challenge and host challenge are used as input parameters.
- 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.
libykhsmauthlibrary returns the session keys to YubiHSM Shell.
- The YubiHSM Shell acknowledges the protocol handshake to
libyubihsmsends the host response to the YubiHSM 2 device. The session keys can now be used for secure channel communication between
YubiHSM-Shell/libyubihsmin the host and the YubiHSM device.
Software and Tools¶
YubiHSM-Auth Software Tool¶
- 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.
In order to generate and store the equivalent YubiHSM Auth credentials on the YubiKey, the
yubihsm-auth command line tool can be used. 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:
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
-a putis the action to insert a YubiHSM Auth credential on the YubiKey
--labelis the label of the YubiHSM Auth credential on the YubiKey
--derivation-passwordis 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
--credpwdis the password protecting the YubiHSM Auth credentials on the YubiKey
--touchis set to ‘on’, which requires the user to touch the YubiKey when accessing the YubiHSM Auth credential
--mgmkeyis the management key that is needed for writing the YubiHSM Auth credentials on the YubiKey
--verboseis used to print more information as output
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 now 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 Using YubiHSM Auth.
The YubiHSM Shell tool supports authentication with YubiHSM Auth credentials in both interactive mode and command-line mode.
In order 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:
authkeyis the identifier of the authentication key in the YubiHSM 2
labelis the label of the YubiHSM-Auth credentials stored in the YubiKey
passwordis 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.