Admin guide

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 get-log-entries 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 get-log-entries 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-key: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

Note about meta objects and PKCS11

After an object is created on the YubiHSM2, whether by generation or import, it is not possible to change any of its properties. However, when using PKCS11, it is possible to change the attributes CKA_ID and CKA_LABEL. This is done by having the new values of those attributes stored in a separate object of type opaque. This opaque object is referred to as a meta object and is marked by its label that starts with "Meta object for" followed by a hex value representing the sequence number, type and object ID of the original object these attribute values belong to. Meta objects are automatically deleted when the original object it belongs to is deleted.

This feature is only available when using the PKCS11 module yubihsm_pkcs11 that comes with yubihsm-shell 2.4.0 and for the following object types: Asymmetric key, Opaque object with algorithm opaque-x509-certificate, Wrap key and HMAC key.