Initial Provisioning and Deployment Guide

This topic covers operations pertaining to the initial provisioning and deployment of YubiHSM 2 devices.

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

Important

The YubiHSM 2 ships with a default Authentication Key with a well-known password. It is imperative that it is removed (single use case) or changed 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 (single use case) or changed should a new use case arise.

HMAC

Step 1:

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

Step 2:

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

Step 3:

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

Step 4:

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

Step 5:

Delete the default Authentication Key.

yubihsm> delete 0 1 authentication-key

Step 6:

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

Step 7:

Open a Session with the wrap Authentication Key.

yubihsm> session open 0xf10f $WRAP_PASS
         Created session 1

Step 8:

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

Step 9:

Open a session with the new application Authentication Key.

yubihsm> session open 0x2a74 $HMAC_PASS
         Created session 2

Step 10:

Run HMAC-SHA256 Test vector #1 and get expected output.

yubihsm> hmac 2 0xd1a2b0344c61d8db38535ca8afceaf0bf12b881dc200c9833
         da726e9376c2e32cff7
echo -ne '\x48\x69\x20\x54\x68\x65\x72\x65' | openssl dgst -hex -mac
    hmac -macopt hexkey:0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b
    -sha256 (stdin)= b0344c61d8db38535ca8afceaf0bf12b881dc200c
    9833da726e9376c2e32cff7

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 with YubiHSM 2 a yubihsm\_pkcs11.conf file needs to exist and point at the desired connector.

Step 1:

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

Step 2:

Create an Authentication Key for Auditing.

yubihsm> put authkey 0 0 "Audit auth key" all audit none $AUDIT_PASS
         Stored Authentication key 0xd054

Step 3:

Optionally enable forced audits.

yubihsm> put option 0 force-audit 01

Step 4:

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

Step 5:

Delete the default Authentication Key.

yubihsm> delete 0 1 authentication-key

Step 6:

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