Interacting with a YubiHSM 2

Yubico.YubiKey.YubiHsmAuth provides an easy way to programmatically manage the YubiHSM Auth application on the YubiKey. While this SDK also supports the calculation of session keys, it is instead recommended for developers to rely on the YubiHSM SDK for interactions with the YubiHSM 2.

YubiHSM SDK

Once credentials are added to the YubiHSM Auth application, use the YubiHSM SDK (and bundled tools) to establish a secure session with a YubiHSM 2 device and perform operations on it.

The YubiHSM Shell tool supports authentication with YubiHSM Auth credentials in both interactive mode and command-line mode. Once the user is authenticated, all YubiHSM Shell commands can be used. Refer to this guide for more information.

It is also possible to use low-level commands to communicate natively with a YubiHSM 2. The individual commands ( documented here) are implemented by the libyubihsm C library.

YubiHSM 2 secure channel

In order to establish an encrypted and authenticated session with a YubiHSM 2, the YubiHSM Auth application must follow the YubiHSM 2 secure channel protocol. This protocol is based on the Global Platform Secure Channel Protocol 03 (SCP03), but there are two important differences:

  • The YubiHSM 2 secure channel protocol does not use APDUs, so the commands and possible options do not match the complete SCP03 specification.
  • SCP03 uses a set of three long-lived AES keys, while the YubiHSM 2 secure channel uses a set of two long-lived AES keys.

The two long-lived keys used in the YubiHSM 2 authentication protocol include an ENC key and a MAC key. In order to successfully create a secure channel, the long-lived keys in the YubiHSM Auth credential and YubiHSM 2 device must be identical.

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.

Session-specific keys can be requested from the YubiHSM Auth application and are returned to the caller. These session-specific keys are used to encrypt and authenticate commands and responses with a YubiHSM 2 device during a single session. The session keys are discarded afterwards.