Skip to content

YubiHSM 2

The YubiHSM 2 is a small Hardware Security Module (HSM) that fits into USB port.

YubiHSM 2 preparation

1) Prepare a YubiHSM2 configuration file

The configuration file yubihsm2_pkcs11.conf must be located in the working directory of TeskaLabs SeaCat PKI microservice.

.../yubihsm2_pkcs11.conf:

connector = http://yubihsm:12345

yubihsm is a host that runs YubiHSM2 software. YubiHSM 2 works in a way that the host with USB runs YubiHSM2 server that provides HTTPS API on a port 12345.

2) Configure SeaCat PKI to use YubiHSM 2 token

seacatpki.conf:

[seacatpki:pkcs11:yubihsm2]
path=.../yubihsm_pkcs11.dylib
tokens=YubiHSM,0001password,mytenant
  • path is the location of the YubiHSM2 PKCS11 library (yubihsm_pkcs11.dylib or yubihsm_pkcs11.so).
  • tokens is the configuration of the YubiHSM2 instance:
    • YubiHSM is a token name
    • 0001password is a PIN (change it to your own, first four digits reffers to a domain on YubiHSM)
    • mytenant is a tenant that has an to the YubiHSM 2 token

Warning

YubiHSM2 offers a single token named "YubiHSM".

3) Restart SeaCat PKI microservice

Multi-tenancy

YubiHSM provides Domains as a means of logical secure storage partitioning. Each domain can be linked with authentication key(s) on the YubiKey, which can be represented by the password. The maximum number of domains on the YubiHSM is 16.

Example of a seacatpki.conf:

[seacatpki:pkcs11:yubihsm2]
session_persistence=false
path=.../yubihsm_pkcs11.dylib
tokens=
    YubiHSM,0001password1,tenant1
    YubiHSM,0002password2,tenant2
    YubiHSM,0003password3,tenant3

The authentication key identifier is captured in the hexadecimal (0000) part (fixed 4 digits) of the PKCS#11 PIN and then mapped to the respective tenant.

Example from yubihsm-shell:

connect
session open 1 password

put authkey 1 2 authkey1 1 all all password1
put authkey 1 3 authkey2 2 all all password2
put authkey 1 4 authkey3 3 all all password3

put authkey 1 2 tenant1 1 all all password1

  • put authkey is a command to insert the authentication key into a YubiHSM
  • 1 is a session number, modify that based on the session number from session open ... command
  • 2 (etc) is a slot number into which the authentication key will be placed
  • authkey1 (etc) is the name of the authentication key
  • 1 (etc) is a domain number
  • all is requesting all YubiHSM2 capabilities; adjust this for lower permissions
  • all is requesting all YubiHSM2 delegated capabilities; adjust this for lower permissions
  • password1 (etc) is the seed for the authentication key, also this is used in PKCS#11 PIN.

Danger

Always use strong passwords when working with YubiHSM2.
Replace `password` in these examples by strong password in your deployment.

The PKCS#11 session persistence (session_persistence) must be disabled since only one session can be in progress when working with YubiHSM over PKCS#11.

Random Number Generator

YubiHSM 2 can be used as random number generator (RNG) in TeskaLabs SeaCat PKI.

secatpki.conf:

[seacatpki:random]
provider=pkcs11:yubihsm2
token_label=YubiHSM

YubiKey

YubiKey token can be also used as a "poor man's" hardware security module (HSM) in TeskaLabs SeaCat PKI.

secatpki.conf:

[seacatpki:pkcs11:yubikey]
path=/usr/local/lib/libykcs11.dylib
tokens=
    YubiKey PIV #xxxxxx,<PIN>,mytenant
session_persistence=false

Danger

session_persistence must be set to false for YubiKey token.