YubiHSM Admin Guide

This document defines the concept of operations pertaining to the initial provisioning and deployment of YubiHSM 2 devices.

Familiarity with the device, its features and capabilities is assumed.

Important
Note that the YubiHSM 2 ships with a default Authentication Key with a well-known password. It is imperative to remove it prior to production deployment.

Known usage cases

When only a single application needs to be provisioned Yubico recommends that all Authentication Keys and material be provisioned only with Capabilities specific to that use case.

Note, this type of deployment requires devices to be physically reset and re-provisioned should a new use case arise.

HMAC

# Establish a session with the default Authentication Key
yubihsm> connect
Session keepalive set up to run every 15 seconds
yubihsm> session open 1 password
Created session 0

# Create an Authentication Key for Auditing
yubihsm> put authkey 0 0 "Audit auth key" all audit none $AUDIT_PASS
Stored Authentication key 0xd054

# Create a Wrap Key for importing application Authentication Keys and secrets
yubihsm> get random 0 16
5b61e89468cc8f2a274715c78c3d4753
yubihsm> put wrapkey 0 0 "HMAC wrap Key" all import-wrapped sign-hmac:verify-hmac 5b61e89468cc8f2a274715c78c3d4753
Stored Wrap key 0xf09a

# Create an Authentication Key for use with the above Wrap Key
yubihsm> put authkey 0 0 "Provisioning HMAC wrap auth key" all import-wrapped none $WRAP_PASS
Stored Authentication key 0xf10f

# Delete the default Authentication Key
yubihsm> delete 0 1 authentication-key

# Create a wrapped Authentication Key and HMAC Key for the application
$ echo -ne '\x5b\x61\xe8\x94\x68\xcc\x8f\x2a\x27\x47\x15\xc7\x8c\x3d\x47\x53' > wrap.key
$ echo $HMAC_PASS | yubihsm-wrap -a aes128-yubico-authentication -c sign-hmac,verify-hmac -d 1 -l "HMAC auth key" -k wrap.key --in - --out auth.out -e none
$ echo -ne '\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b' > hmac.key
$ yubihsm-wrap -a hmac-sha256 -c sign-hmac,verify-hmac -d 1 -l "HMAC key" -k wrap.key --in hmac.key --out hmac.out

# Open a Session with the wrap Authentication Key
yubihsm> session open 0xf10f $WRAP_PASS
Created session 1

# Import the two wrapped keys in the new Session
yubihsm> put wrapped 1 0xf09a auth.out
Object imported as 0x2a74 of type authentication-key
yubihsm> put wrapped 1 0xf09a hmac.out
Object imported as 0xd1a2 of type hmac-key

# Open a session with the new application Authentication Key
yubihsm> session open 0x2a74 $HMAC_PASS
Created session 2

# Run HMAC-SHA256 Test vector #1 and get expected output
yubihsm> hmac 2 0xd1a2 4869205468657265
b0344c61d8db38535ca8afceaf0bf12b881dc200c9833da726e9376c2e32cff7
$ echo -ne '\x48\x69\x20\x54\x68\x65\x72\x65' | openssl dgst -hex -mac hmac -macopt hexkey:0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b -sha256
(stdin)= b0344c61d8db38535ca8afceaf0bf12b881dc200c9833da726e9376c2e32cff7

PKCS11 / RSA

This example assumes that only RSA operations will be performed and that RSA keys will be generated on device over PKCS#11. For using the PKCS#11 module a yubihsm\_pkcs11.conf file will need to exist and point at the desired connector.

# Establish a Session with the default Authentication Key
yubihsm> connect
Session keepalive set up to run every 15 seconds
yubihsm> session open 1 password
Created session 0

# Create an Authentication Key for Auditing
yubihsm> put authkey 0 0 "Audit auth key" all audit none $AUDIT_PASS
Stored Authentication key 0xd054

# Optionally enable forced audits
yubihsm> put option 0 force-audit 01

# Create an Authentication Key for usage with the PKCS11 module
yubihsm> put authkey 0 0 "PKCS11 RSA" 1 delete-asymmetric:generate-asymmetric-key:sign-pkcs:sign-pss sign-pkcs:sign-pss $PKCS11_PASS
Stored Authentication key 0xf10f

# Delete the default Authentication Key
yubihsm> delete 0 1 authentication-key

# Use pkcs11-tool to generate an RSA key
$ pkcs11-tool --module /path/to/yubihsm_pkcs11.so -l --pin f10f${PKCS11_PASS} -k --key-type rsa:2048 --usage-sign --label "RSA key"
Using slot 0 with a present token (0x0)
Key pair generated:
Private Key Object; RSA
  label:      RSA key
  ID:         e77d
  Usage:      sign
Public Key Object; RSA 2048 bits
  label:      RSA key
  ID:         e77d
  Usage:      none