YubiHSM 2 SDK Tools And Libraries

YubiHSM 2 Setup Tool

The SDK ships with a tool called yubihsm-setup that helps with setting up a device for specific use cases. The tool assumes familiarity with the key concepts of YubiHSM such as Domain, Capability and Object ID. It currently supports the following:

• setup for KSP/ADCS and EJBCA;
• restoring a previous configuration
• resetting the device to factory defaults
• exporting all existing objects

The tool is based around the concept of secret-sharing. When setting up Objects, those are exported with a freshly created Wrap Key. The key is never stored on disk, but rather it is printed on the screen as shares. The key concepts here are:

• The number of shares, which is the number of parts the key should be divided into.
• The security threshold, which is the minimum number of shares required to reconstruct the Wrap Key.

Besides splitting the Wrap Key into shares, the tool (by default) also exports under wrap all the newly created objects and saves them in the current directory. This can be used at a later time to “clone” or recover a device. This operation can be performed either with yubihsm-setup or manually if the Wrap Key is known.

By default, the Authentication Key used to establish a Session with the device is also normally deleted at the end of the process.

Default behavior can be altered with command line options. For more information, consult the tool’s help.

Setup for EJBCA

When setting up the device for use by EJBCA, the setup tool will also generate an asymmetric keypair and an X509 certificate suitable for use as a CA key. The setup tool can be re-run as many times as the number of asymmetric keys to be generated since each run will produce only one keypair and one corresponding X509 certificate.

Note

Using the --no-new-authkey flag will prevent generation of a new Wrap Key and a new Authentication Key.

How It Works

For the JAVA implementation, a keypair can be used to perform PKCS#11 operations only if the key and its corresponding X509 certificate are stored under the same ID on the device (the value of their CKA_ID attributes is the same). To store them under the same ID, run the YubiHSM 2 Setup tool with the ejbca subcommand:

1. Generate an Asymmetric Key on the YubiHSM 2.
2. Generate an attestation certificate for the asymmetric key and import it into the YubiHSM 2 under the same ID as the Asymmetric Key.

The attestation certificate stored on the YubiHSM 2 is, in fact, only a placeholder certificate for the public key. It is never used by EJBCA because EJBCA stores the CAs’ certificates in a dedicated database.

YubiHSM Shell

The yubihsm-shell is the administrative and testing tool you can use to interact with and configure the YubiHSM 2 device. All the commands supported by YubiHSM 2 YubiHSM Command Reference can be issued to YubiHSM 2 using YubiHSM 2 Shell.

The Shell can be invoked in two different ways: interactively, or as a command line tool useful for scripting.

Additional information on the various commands can be obtained with the help command in interactive mode or by referring to the --help argument for the command line mode.

Examples of commands can also be found in the YubiHSM Command Reference reference.

YubiHSM Shell Command Syntax

Commands and subcommands require specific arguments to work. The Shell will return an error message if the command syntax is incorrect, pointing at the first invalid argument.

Arguments have different types. In interactive mode pre-defined values for command types can be tab-completed (Tab Completion does not work on Windows). Command arguments are explained in the table below.

Arg	Type	Description
A	Algorithm	An algorithm in string form (ex: ecp256)
B	Byte	A generic (hex or dec) 8-bit unsigned number
C	capabilities	A list of Capabilities in either form: hex (ex: 0xffffffffffffffff) or string (ex: sign-pkcs,sign-pss, get-log-entries)
D	Domains	A list of Domains, either in hex (ex: 0xffff) or string form (ex: 3,5,14)
I	Format	A format specifier in string form (ex: base64)
I	input data	Input data, generally defaults to standard input
U	Number	A generic (hex or dec) unsigned number
O	Option	A device-global option in string form (ex: force-audit)
F	output filename	Output file name, generally defaults to standard output
E	Session	The ID of an already-established Session
S	String	A generic string (use quotes for strings including white spaces)
T	Type	An Object Type in string form (ex: Asymmetric)
W	Word	A generic (hex or dec) 16-bit unsigned number

Different commands have different default formats. These can be listed by invoking help on a specific command. For example, the help sign will display the following message:

pss           Sign data using RSASSA-PSS (default input format: binary)
              e:session,w:key_id,a:algorithm,i:data=-,F:out=-

As can be seen, the input format is binary. Additionally, arguments to a command that have =- after their type and name (like i:data and F:out in the example above), use the standard input or standard output by default for reading data.

Different levels of debug output can be enabled by using the -v flag in command line mode, or by issuing the debug LEVEL command in interactive mode, where LEVEL is one of all, crypto, error, info, intermediate, none, or raw.

The following is a list of supported yubihsm-shell commands and their formats.

Blink Device – Blinks the LED of the device to identify it.

Interactive mode

$ blink <session> <seconds=10>

Command line mode

$ yubihsm-shell -a blink-device [--duration <seconds=10>]

Change Authentication Key – Replaces the Authentication Key used to establish the current Session.

Interactive mode

$ change authkey <session> <key_id> <password=->

Close Session – Closes the current session and releases it for re-use.

Interactive mode

$ session close <session>

Create Otp Aead – Creates a Yubico OTP AEAD using the provided data.

Interactive mode

$ otp aead_create <session> <key_id> <key> <private_id> <aead>

Decrypt AES CBC – Decrypt data in AES CBC mode.

Interactive mode

$ decrypt aescbc  <session> <key_id> <iv> <data=->

Command line mode

$ yubihsm-shell -a decrypt-aescbc -i <key_id> --iv <iv> --in <data>

Decrypt AES ECB – Decrypt data in AES ECB mode.

Interactive mode

$ decrypt aesecb  <session> <key_id> <data=->

Command line mode

$ yubihsm-shell -a decrypt-aesecb -i <key_id> --in <data>

Decrypt Oaep – Decrypts data encrypted with RSA-OAEP.

Interactive mode

$ decrypt oaep <session> <key_id> <algorithm> <in_data=-> <label=>

Command line mode

$ yubihsm-shell –a decrypt-oaep -i <key_id> -A <decrypt_algorithm> [--in <in_data> -l <oaep_label>]

Decrypt Otp – Decrypts a Yubico OTP with an AEAD and returns counters and timer information (default input format in binary).

Interactive mode

$ otp decrypt <session> <key_id> <otp> <aead>

Decrypt Pkcs1 – Decrypts data encrypted with RSA-PKCS#1v1.5.

Interactive mode

decrypt pkcs1v1_5 <session> <key_id> data=->``

Command line mode

$ yubihsm-shell -a decrypt-pkcs1v15 -i <key_id> [--in <data>]

Delete Object – Deletes an object in the device.

Interactive mode

$ delete <session> <object_id> <type>

Command line mode

$ yubihsm-shell -a delete-object -i <object_id> -t <type>``

Derive Ecdh – Performs an ECDH key exchange with the private key in the device.

Interactive mode

$ derive ecdh <session> <key_id> <public_key=->

Command line mode

$ yubihsm-shell -a derive-ecdh -i <key_id> [--in <public_key>]

Encrypt AES CBC – Encrypt data in AES CBC mode.

Interactive mode

$ encrypt aescbc  <session> <key_id> <iv> <data=->

Command line mode

$ yubihsm-shell -a encrypt-aescbc -i <key_id> --iv <iv> --in <data>

Encrypt AES ECB – Encrypt data in AES ECB mode.

Interactive mode

$ encrypt aesecb  <session> <key_id> <data=->

Command line mode

$ yubihsm-shell -a encrypt-aesecb -i <key_id> --in <data>

Export Wrapped – Retrieves an object under wrap from the device. The Object is encrypted using AES-CCM with a 16 bytes MAC and a 13 bytes nonce.

Interactive mode

$ get wrapped <session> <wrapkey_id> <type> <object_id> <file=->

Command line mode

$ yubihsm-shell -a get-wrapped --wrap-id <wrapkey_id> -t <type> -i <object_id> [--out <file>]

Generate Asymmetric Key – Generates an Asymmetric Key in the device.

Interactive mode

$ generate asymmetric session> <object_id> <label> <domains> <capabilities> <algorithm>

Command line mode

$ yubihsm-shell -a generate-asymmetric-key -i <object_id> -l <label> -d <domains> -c <capabilities> -A <algorithm>

Generate Hmac Key – Generates an HMAC Key in the device.

Interactive mode

$ generate hmackey <session> <key_id> <label> <domains> <capabilities> <algorithm>

Command line mode

$ yubihsm-shell -a generate-hmac-key -i <key_id> -l <label> -d <domains> -c <capabilities> -A <algorithm>

Generate Otp Aead Key – Generates an OTP AEAD Key for Yubico OTP decryption.

Interactive mode

$ generate otpaeadkey <session> <key_id> <label> <domains> <capabilities> <algorithm> <nonce_id>

Command line mode

$ yubihsm-shell -a generate-otp-aead-key -i <key_id> -l <label> -d <domains> -c <capabilities> -A <algorithm> --nonce <nonce_id>

Generate Symmetric Key – Generates a symmetric key.

Interactive mode

$ generate symmetric <session> <key_id> <label> <domains> <capabilities> <algorithm>

Command line mode

$ yubihsm-shell -a generate-symmetric-key -i <key_id> -l <label> -d <domains> -c <capabilities> -A <algorithm>

Generate Wrap Key – Generates a Wrap Key that can be used for export, import, wrap data, and unwrap data.

Interactive mode

$ generate wrapkey <session> <key_id> <label> <domains> <capabilities> <delegated_capabilities> <algorithm>

Command line mode

$ yubihsm-shell -a generate-wrap-key -i <key_id> -l <label> -d <domains> -c <capabilities> --delegated <delegated_capabilities> -A <algorithm>

Get Device Info – Gets device version, device serial, supported algorithms and the number of log entries.

Interactive mode

$ get deviceinfo

Command line mode

$ yubihsm-shell -a get-device-info

Get Device Public Key – Retrieves the device’s public key for the purpose of asymmetric authentication.

Interactive mode

$ get devicepubkey

Command line mode

$ yubihsm-shell -a get-public-key

Get Log Entries – Fetches all current entries from the device Log Store.

Interactive mode

$ audit get <session>

Command line mode

$ yubihsm-shell -a get-logs

Get Object Info – Fetches all metadata about an object.

Interactive mode

$ get objectinfo <session> <object_id> <type>

Command line mode

$ yubihsm-shell -a get-object-info -i <object_id> -t <type>

Get Opaque – Retrieves an Opaque object (like an X.509 certificate) from the device.

Interactive mode

$ get opaque <session> <object-id>

Command line mode

$ yubihsm-shell -a get-opaque -i <object-id>

Get Option – Gets device-global options.

Interactive mode

$ get option <session> <option>

Command line mode

$ yubihsm-shell -a get-option --opt-name <option>

Get Pseudo Random – Extracts a fixed number of pseudo-random bytes from the device, using the internal PRNG.

Interactive mode

$ get random <session> <number_of_bytes> <out=->

Command line mode

$ yubihsm-shell -a get-pseudo-random [--count <number_of_bytes=256> --out <out>]

Get Public Key – Fetches the public key of an Asymmetric  Key.

Interactive mode

$ get pubkey <session> <key_id>

Command line mode

$ yubihsm-shell -a get-public-key -i <key_id>

Get Storage Info – Reports currently free storage.

Interactive mode

$ get storage <session>

Get Template – Retrieves a Template object from the device.

Interactive mode

$ put template <session> <object_id> <out_data=->

Command line mode

$ yubihsm-shell -a get-template -i <object_id> [--out <out_data>]

Import Wrapped – Imports a wrapped/encrypted object that was previously exported by an YubiHSM 2 device.

Interactive mode

$ put wrapped <session> <wrapkey_id> <data=->

Command line mode

$ yubihsm-shell -a put-wrapped --wrap-id <wrapkey_id> [--in <file>]

List Objects – Gets a filtered list of objects from the device.

Interactive mode

$ list objects <session> <id=0> <type=any> <domains=0> <capabilities=0> <algorithm=any> <label=>

Command line mode

$ yubihsm-shell -a list-objects -t <type> -A <algorithm> [-i <id> -d <domains> -c <capabilities> -l <label>]

Put Asymmetric Key – Imports an Asymmetric Key into the device.

Interactive mode

$ put asymmetric <session> <object_id> <label> <domains> <capabilities> <key=->

Command line mode

$ yubihsm-shell -a put-asymmetric-key -i <object_id> -l <label> -d <domains> -c <capabilities> [--in <key>]

Put Authentication Key – Stores an Authentication Key in the device.

Interactive mode

$ put authkey <session> <object_id> <label> <domains> <capabilities> <delegated_capabilities> <password=->

Command line mode

$ yubihsm-shell -a put-authentication-key -i <object-id> -l <label> -d <domains> -c <capabilities> --delegated <delegated_capabilities> [--new-password <password>]

Put Hmac Key – Stores an HMAC Key in the device.

Interactive mode

$ put hmackey <session> <object_id> <label> <domains> <capabilities> <algorithm> <key>

Put Opaque – Stores Opaque data (like an X.509 certificate) in the device.

Interactive mode

$ put opaque <session> <object_id> <label> <domains> <capabilities> <algorithm> <data=->

Command line mode

$ yubihsm-shell -a put-opaque -i <object-id> -l <label> -d <domains> -c <capabilities> -A <algorithm> [--in <data>]

Put Otp Aead Key – Imports an OTP AEAD Key used for Yubico OTP Decryption.

Interactive mode

$ put otpaeadkey <session> <key_id> <label> <domains> <capabilities> <nonce_id> <key>

Put Symmetric Key – Imports a symmetric key.

Interactive mode

$ put symmetric <session> <key_id> <label> <domains> <capabilities> <algorithm> <key>

Command line mode

$ yubihsm-shell -a put-symmetric-key -i <key_id> -l <label> -d <domains> -c <capabilities> -A <algorithm> --in <key>

Put Template – Stores a Template in the device (like the template used when signing SSH certificate).

Interactive mode

$ put template <session> <object_id> <label> <domains> <capabilities> <algorithm> <in_data=->

Command line mode

$ yubihsm-shell -a put-template -i <object_id> -l <label> -d <domains> -c <capabilities> -A <algorithm> [--in <in_data>]

Put Wrap Key – Imports a key for wrapping into the device.

Interactive mode

$ put wrapkey <session> <object_id> <label> <domains> <capabilities> <delegated_capabilities> <key>

Command line mode

$ yubihsm-shell -a put-wrap-key -i <object_id> -l <label> -d <domains> -c <capabilities> --delegated <delegated_capabilities> --in <key>

Randomize Otp Aead – Creates a new OTP AEAD using random data for key and private ID.

Interactive mode

$ opt aead_random <session> <key_id> <aead>

Command line mode

$ yubihsm-shell -a randomize-otp-aead -i <key_id> --in <aead>

Reset Device – Resets and reboots the device, deletes all Objects and restores the default Options and Authentication Key.

Interactive mode

$ reset <session>``

Command line mode

$ yubihsm-shell -a reset

Rewrap Otp Aead – Re-encrypts a Yubico OTP AEAD from one OTP AEAD Key to another OTP AEAD Key.

Interactive mode

$ otp rewrap <session> <key_id_from> <key_id_to> <aead_in> <aead_out>

Session Message – Sends a wrapped command for a previously established session. The command is encrypted and authenticated.

Set Log Index – Informs the device what the last extracted log entry is so logs can be reused.

Interactive mode

$ audit set <session> <index>

Command line mode

$ yubihsm-shell -a set-log-index --log-index <index>

Set Option – Sets device-global options that affect general behavior.

Interactive mode

$ put option <session> <option> <value>

Command line mode

$ yubihsm-shell -a put-option --opt-name <option> --opt-value <value>

Sign Attestation Certificate – Gets attestation of an Asymmetric Key in the form of an X.509 certificate.

Interactive mode

$ attest asymmetric <session> <key_id> <attest_id=0 <file=->

Command line mode

$ yubihsm-shell -a sign-attestation-certificate -i <key_id> --attestation-id <attest_id> [--out <file>]

Sign Ecdsa – Computes a digital signature using ECDSA on the provided data.

Interactive mode

$ sign ecdsa <session> <key_id> <signing_algorithm> <in_data=-> <out-data=->

Command line mode

$ yubihsm-shell -a sign-ecdsa -i <key_id> -A <signing_algorithm> [--in <in_data> --out <out_data>]

Sign Eddsa – Computes a digital signature using EdDSA on the provided data.

Interactive mode

$ sign eddsa <session> <key_id> <algorithm> <data=-> <out=->

Command line mode

$ yubihsm-shell -a sign-eddsa -i <key_id> -A <algorithm> [--in <data> --out <out>]

Sign Hmac – Performs an HMAC operation in the device and returns the result.

Interactive mode

$ hmac <session> <object_id> <data_to_sign=- in hex> <out=->

Command line mode

$ yubihsm-shell -a sign-hmac -i <object_id> [--in <data_to_sign_in_hex> --in <out_data>]

Sign Pkcs1 – Computes a digital signature using RSA-PKCS1v1.5 on the provided data.

Interactive mode

$ sign pkcs1v1_5 <session> <object_id> <algorithm> <data=-> <out=->

Command line mode

$ yubihsm-shell -a sign-pkcs1v15 -i <object_id> -A <algorithm> [--in <data> --out <out>]

Sign Pss – Computes a digital signature using RSA-PSS on the provided data.

Interactive mode

$ sign pss <session> <key_id> <signing_algorithm> <in_data=-> <out_file=->

Command line mode

$ yubihsm-shell -a sign-pss -i <key_id> -A <signing_algorith> [--in <in_data> --out <out_file>]

Sign Ssh Certificate – Produces an SSH Certificate signature (only works with RSA keys).

Interactive mode

$ certify <session> <key_id> <template_id> <algorithm> <in_data_in_binary_format=-> <out_data=->

Command line mode

$ yubihsm-shell -a sign-ssh-certificate -i <key_id> --template-id <template_id> -A <algorithm> [--in <in_data_in_binary_format> --out <out_data>]

Unwrap Data – Decrypts (unwraps) data using a Wrap Key.

Interactive mode

$ decrypt aesccm <session> <key_id> <data=->

Verify Hmac – Verifies a generated HMAC

Wrap Data – Encrypts (wraps) data using a Wrap Key.

Interactive mode

$ encrypt aesccm <session> <key_id> <data=->

YubiHSM 2 Shell Algorithm Names

Following table describes algorithm names to be used with YubiHSM Shell for the algorithms supported by YubiHSM 2.

Name	yubihsm-shell name	Comment
AES 128	aes128
AES 192	aes192
AES 256	aes256
AES CBC	aes-cbc
AES ECB	aes-ecb
AES128 CCM WRAP	aes128-ccm-wrap
AES192 CCM WRAP	aes192-ccm-wrap
AES256 CCM WRAP	aes256-ccm-wrap
EC BP256	ecbp256	brainpool256r1
EC BP384	ecbp384	brainpool384r1
EC BP512	ecbp512	brainpool512r1
EC ECDH	ecdh
EC K256	eck256	secp256k1
EC P224	ecp224	secp224r1
EC P256	ecp256	secp256r1
EC P384	ecp384	secp384r1
EC P521	ecp521	secp521r1
ECDSA SHA1	ecdsa-sha1
ECDSA SHA256	ecdsa-sha256
ECDSA SHA384	ecdsa-sha384
ECDSA SHA512	ecdsa-sha512
ED25519	ed25519
HMAC SHA1	hmac-sha1
HMAC SHA256	hmac-sha256
HMAC SHA384	hmac-sha384
HMAC SHA512	hmac-sha512
MGF1 SHA1	mgf1-sha1
MGF1 SHA256	mgf1-sha256
MGF1 SHA384	mgf1-sha384
MGF1 SHA512	mgf1-sha512
Opaque Data	opaque-data
Opaque X509 Certificate	opaque-x509-certificate
RSA 2048	rsa2048
RSA 3072	rsa3072
RSA 4096	rsa4096
RSA OAEP SHA1	rsa-oaep-sha1
RSA OAEP SHA256	rsa-oaep-sha256
RSA OAEP SHA384	rsa-oaep-sha384
RSA OAEP SHA512	rsa-oaep-sha512
RSA PKCS1 SHA1	rsa-pkcs1-sha1
RSA PKCS1 SHA256	rsa-pkcs1-sha256
RSA PKCS1 SHA384	rsa-pkcs1-sha384
RSA PKCS1 SHA512	rsa-pkcs1-sha512
RSA PSS SHA1	rsa-pss-sha1
RSA PSS SHA256	rsa-pss-sha256
RSA PSS SHA384	rsa-pss-sha384
RSA PSS SHA512	rsa-pss-sha512
SSH Template	template-ssh
Yubico AES Authentication	aes128-yubico-authentication
Yubico Asymmetric Authentication	ecp256-yubico-authentication
Yubico OTP AES128	aes128-yubico-otp
Yubico OTP AES192	aes192-yubico-otp
Yubico OTP AES256	aes256-yubico-otp

YubiHSM 2 Connector

The yubihsm-connector performs the communication between the YubiHSM 2 and the applications that use it.

The Connector must have permissions to access the USB device, and different operating systems behave differently in this regard. The easiest way to get started is to run the Connector with Administrator privileges (e.g. with sudo), but the safest way to run the Connector is to use your operating system’s configuration to give it only the privileges necessary to access the YubiHSM 2 USB device.

The Connector is not a trusted component. Sessions are established cryptographically between the application and the YubiHSM 2 using a symmetric mutual authentication scheme that is both encrypted and authenticated.

The Connector is not required to run on the same host as the applications which access it. In that case, configure the Connector to listen on a different address rather than the default localhost:12345. Make sure that the client has access. The port number does not need to change, only the address. Also, make sure that OS firewalls are configured properly to allow access to the host machine on the specified port.

To get information regarding the Connector issue a GET request on the /connector/status URI.

HTTPS Connections

As mentioned earlier, the Connector is not meant to be a trusted component. For this reason it defaults to HTTP connections. It is possible to use HTTPS, however this requires providing a key and a certificate to the Connector.

Another option is to use a reverse proxy such as nginx before the Connector and have that handle TLS.

Sample Configuration

Sample configuration for the Connector: yubihsm-connector-config.yaml

# Certificate (X.509)
cert: ""

# Certificate key
key: ""

# Listening address. Defaults to "localhost:12345".
listen: localhost:12345

# Device serial in case of multiple devices
serial: ""

# Log to syslog/eventlog. Defaults to "false".
syslog: false

# Use to enable host header filtering. Default to "false".
# Use this if there is an absolute need to use a web browser on the
# host where the YubiHSM 2 is installed to connect to untrusted web
# sites on the Internet.
enable-host-whitelist: false

# Default list for the host header filter
host-whitelist: localhost,localhost.,127.0.0.1,[::1]

Sample udev rule to be placed into /etc/udev/rules.d/

#This udev file should be used with udev 188 and newer
ACTION!="add|change", GOTO="yubihsm2_connector_end"

# Yubico YubiHSM 2
# The OWNER attribute here has to match the uid of the process
# running the Connector
SUBSYSTEM=="usb", ATTRS{idVendor}=="1050", ATTRS{idProduct}=="0030",
  OWNER="yubihsm-connector"

LABEL="yubihsm2_connector_end"

YubiHSM Wrap

Yubihsm Wrap is a tool that allows the creation of importable objects offline. This is useful when bootstrapping secrets, for example on an air-gapped computer.

The tool requires an unencrypted Wrap Key in binary format and uses that to wrap objects with given Type, Objects, ALGORITHMS, Object ID, Capability and, where applicable, Delegated Capabilities.

For the resulting Object to be successfully imported on a YubiHSM 2, the Wrap Key used by yubihsm-wrap must already be present on the device.

Currently not all Object Types are supported. Refer to Known Issues and Limitations for more information.

Libyubihsm

Libyubihsm is the C library used to communicate natively with a YubiHSM 2. It implements and exposes convenience functions for all the commands supported by the device. It also allows the sending of unformatted “raw” messages over an established session or in plain text.

The library is used by:

• yubihsm-shell, see YubiHSM Shell Reference
• PKCS#11 module, see PKCS#11 with YubiHSM 2 Reference
• KSP, see Key Storage Provider Reference

Documentation of the library API can be found as comments within the header file (yubihsm.h) in the SDK, or as a pre-built Doxygen bundle.

Libyubihsm includes a connector component to talk to a YubiHSM device. This connector is different from the yubihsm-connector discussed earlier. This component can be one of the following two types.

HTTP Connector

This kind of Connector talks to yubihsm-connector over http(s), allowing remote access to a YubiHSM2, see Connector Reference

In order to select this type of backend the connector URL should use the http or https scheme; for example, to use a local HTTP Connector use http://127.0.0.1:12345.

USB Connector

This kind of Connector is a direct-access USB backend that talks directly with a YubiHSM device. The USB Connector is built into libyubihsm. This renders it unnecessary to run an additional component (i.e., the external Connector) at the cost of requiring exclusive access to a YubiHSM device.

To select this type of backend the connector URL should use the yhusb scheme. For example, to use a local device with serial number 123456 use yhusb://serial=123456.

Python Library

The Python library allows you to interface with a YubiHSM 2 through both the Connector service and direct USB connection using the Python programming language. It supports Python 3.8 or later.

The recommended way to install the library is by using pip inside a virtualenv. To create and activate a virtualenv, run:

$ virtualenv yubihsm
Running virtualenv with interpreter /usr/bin/python3
New python executable in /home/user/yubihsm/bin/python3
Also creating executable in /home/user/yubihsm/bin/python
Installing setuptools, pkg_resources, pip, wheel...done.

$ source yubihsm/bin/activate
(yubihsm) $ pip install yubihsm[http,usb]
Collecting yubihsm-2.0.0
...
Successfully installed asn1crypto-0.22.0 cffi-1.10.0 cryptography-1.8.1
   enum34-1.1.6 idna-2.5 ipaddress-1.0.18 pycparser-2.17 pyusb-1.0.2
   requests-2.13.0 yubihsm-2.0.0
(yubihsm) $

Note

The cryptography dependency uses C extensions, and therefore has some build dependencies. For detailed instructions, see: https://cryptography.io/en/latest/installation/

from yubihsm import YubiHsm
from yubihsm.objects import AsymmetricKey
from yubihsm.defs import ALGORITHM, CAPABILITY

# Connect to the Connector and establish a session using the default
# auth key:
hsm = YubiHsm.connect("http://localhost:12345/connector/api")
session = hsm.create_session_derived(1, "password")

# Create a new EC key for signing:
key = AsymmetricKey.generate(session, 0, "EC Key", 1, CAPABILITY.SIGN_ECDSA, ALGORITHM.EC_P256)

# Sign a message
data = b'Hello world!'
signature = key.sign_ecdsa(data)

# Delete the key from the YubiHSM 2
key.delete()

# Close session and connection:
session.close()
hsm.close()

Key Storage Provider (KSP) – Windows Only

The Key Storage Provider (KSP) for Windows Cryptography API: Next Generation (CNG) has been thoroughly tested with Active Directory Certificate Services (AD CS) plus 2048-bit, 3072-bit, and 4096-bit keys. It also works with other types of keys, but those have not been tested to the same extent.

The following installs the KSP and the Connector Service, using them for ADCS with the default Authentication Key (1) and password (password).

When you run the Install-AdcsCertificationAuthority command, you should see the YubiHSM 2 light flash rapidly, because AD CS uses the KSP to generate a 2048-bit key in hardware. For AD CS to work properly, Restart-Computer may be needed.

PS1> msiexec /i "yubihsm-connector-windows-amd64.msi" /passive ACCEPT=yes
PS1> msiexec /i "yubihsm-cngprovider-windows-amd64.msi" /passive  ACCEPT=yes
PS1> Install-WindowsFeature AD-Certificate -Verbose
PS1> Install-AdcsCertificationAuthority -CAType EnterpriseRootCa    \
    -CryptoProviderName "RSA#YubiHSM Key Storage Provider"          \
    -KeyLength 2048 -HashAlgorithmName SHA256 -ValidityPeriod Years \
    -ValidityPeriodUnits 5
PS1> Install-AdcsOnlineResponder

If you are using a different Authentication Key, password, or Connector for the KSP, you can specify them as follows (defaults are shown):

PS1> Set-ItemProperty -path HKLM:\SOFTWARE\Yubico\YubiHSM \
    -name ConnectorURL -Type String -Value http://127.0.0.1:12345
PS1> Set-ItemProperty -path HKLM:\SOFTWARE\Yubico\YubiHSM \
    -name AuthKeysetPassword -Type String -Value password
PS1> Set-ItemProperty -path HKLM:\SOFTWARE\Yubico\YubiHSM \
    -name AuthKeysetID -Type DWord -Value 1

Warning

Design considerations for Key Storage Providers in Windows prevent the direct USB functionality of libyubihsm (Connector URL yhusb://), therefore it is not supported in this version of the YubiHSM KSP.

The default configuration for the connector is: ProgramData\YubiHSM\yubihsm-connector.yaml - Administrator rights are required to access the file.

Additional Documentation for YubiHSM Key Storage Provider

• For instructions on how to move a software-based key into the YubiHSM 2 for use with the KSP, see Move Software Keys to Key Storage Provider.
• For an example of how to create an HSM-backed code signing certificate for Windows through the KSP, see Example: Creating a Code-Signing Certificate using the Key Storage Provider.
• For more information about status codes, see YubiHSM 2 status codes in Windows.
• For details on how to configure the 32-bit and 64-bit KSP DLLs, please see YubiHSM 2 with Key Storage Provider for Windows Server.

YubiHSM Auth

YubiHSM Auth is a new YubiKey module that serves as a key storage for authenticating against a YubiHSM 2 with a YubiKey instead of just using a session password alone. To leverage this functionality, use the latest release of YubiHSM 2 SDK.

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.

Note

SCP03 is always used, with yubihsm-auth or not. This means that authentication is always based on a pair of 128 bit AES keys. These keys can be derived from a password on the client side, using authentication in the Yubico command line tools.

Credentials and PIN Codes

Each YubiHSM Auth credential consists 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

YubiKey YubiHSM Auth application can be used 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. Two of these long-lived keys are used for authentication and the third is used to encrypt new long-lived keys when they’re transferred to the device. Since YubiHSM handles authentication keys like any other keys, the third SCP03 long-lived key is not required therefore YubiHSM 2 secure channel uses key sets with two long-lived AES keys  which are required for authentication.

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. After the session is over the session keys are discarded. Session keys are only used for a single session and are not sensitive after the session is over.

Architecture Overview

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

Figure: Architecture Overview

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.

Figure: YubiHSM Auth Flowchart

The following is a description of the steps in the flowchart.

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.

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.

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:

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’, which requires the user to 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 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:

• authkey is the identifier of the authentication key in the YubiHSM 2
• label is the label of the YubiHSM-Auth credetnials 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.