Goal of this chapter: Bring the HSM into a ready state and provide a Cryptographic User that the product can log in with. Keys are not created here — on the HSM-managed path they are generated inside the HSM when triggered from the management console in HSM-Managed-ML-DSA-65.
Install the SecurityServer software as described in the SecurityServer Manual; we recommend
uninstalling any earlier version first. libcs_pkcs11_R3.so is found under Software/Linux/Crypto_APIs/PKCS11_R3/lib/ in the product package — it belongs to the base
software package, not to the Quantum Protect add-on.
Confirming the Post-Quantum Firmware Modules
# <DEVICE> is <port>@<HSM-IP> (LAN), /dev/cs2.0 (PCIe), or 3001@127.0.0.1 (simulator) csadm dev=<DEVICE> listfirmware
All three modules must report INIT_OK:
a2 HBS ... INIT_OK
a5 ML ... INIT_OK ← FIPS 204 ML-DSA / FIPS 203 ML-KEM
a6 PQMI ... INIT_OK ← post-quantum mechanism distribution
If the post-quantum modules are missing on a physical device, the HSM administrator must load the Quantum Protect firmware before you continue: csadm dev=<DEVICE> LogonSign <ADMIN>, <ADMIN.key> LoadFile=hbs.mtc LoadFile=ml.mtc LoadFile=pqmi.mtc Restart
The bl_sim5 simulator in the Quantum Protect evaluation package already contains the PQC firmware. That binary is 32-bit i386, so on a 64-bit host install the 32-bit runtime first ( libc6:i386 , libstdc++6:i386 , libgcc-s1:i386 ), then start it with ./cs_sim.sh & rom\ linux/sim5_linux/bin — it listens on 3001@127.0.0.1 by default.
Configuring cs_pkcs11_R3.cfg
The Utimaco PKCS#11 library is not self-contained: once loaded, it still needs a configuration file giving the HSM device address, and the environment variable CS_PKCS11_R3_CFG must point to that file.
Place cs_pkcs11_R3.cfg on every node whose processes access the HSM — the management
console node and each gateway node, or inside the deployment image.
[Global]
Logging = 0 ; temporarily set to 4 when troubleshooting
LogFile = /var/log/stoa/cs_pkcs11_R3.log
[CryptoServer]
Device = <DEVICE> ; LAN: <port>@<HSM-IP>; PCIe: /dev/cs2.0
ConnectionTimeout = 5000
CommandTimeout = 60000
-
LAN models: Device = <port>@<HSM-IP> (for example 288@10.10.x.x ). In containerized
deployments the container network must be able to route to the HSM. -
PCIe cards: Device = /dev/cs2.0 . In containerized deployments the device must be passed
through into the container.
export CS_PKCS11_R3_CFG=/etc/stoa/cs_pkcs11_R3.cfg
Deployment on the HSM device side — firmware initialization, exposure as a network
service, clustering and high availability — is performed by HSM operations according to the on-site architecture and the official Utimaco documentation, and is out of scope for this guide.
Creating a Cryptographic User and Initializing the Slot
Critical privilege requirement: ML-DSA key generation requires a Cryptographic User (privilege bit 0x02 ) whose CXI_GROUP covers the group holding the key ( SLOT_0000 by default). Logging in as ADMIN succeeds, but key generation then fails with 0xB0A60001 (PQMI permission denied).
Use p11tool2 with the ADMIN key to initialize slot 0. This also creates the security officer SO_0000 and the cryptographic user USR_0000 ( CXI_GROUP=SLOT_0000 ).
export CS_PKCS11_R3_CFG=/etc/stoa/cs_pkcs11_R3.cfg
# 1) Initialize the token as administrator, setting an initial SO PIN
p11tool2 Slot=0 Login=ADMIN,<ADMIN.key> InitToken=<initial PIN>
# 2) Change the initial SO PIN to the formal SO PIN
p11tool2 Slot=0 LoginSO=<initial PIN> SetPIN=<initial PIN>,<SO-PIN>
# 3) Initialize the user PIN as SO
p11tool2 Slot=0 LoginSO=<SO-PIN> InitPIN=<initial user PIN>
# 4) Change the initial user PIN to the formal user PIN
p11tool2 Slot=0 LoginUser=<initial user PIN> SetPIN=<initial user PIN>,<user PIN>
# Verify: USER_PIN_INITIALIZED must be CK_TRUE
p11tool2 Slot=0 LoginUser=<user PIN> GetTokenInfo
# Verify privileges and group: USR_0000 must show 00000002 and group SLOT_0000
csadm dev=<DEVICE> LogonSign=ADMIN,<ADMIN.key> ListUsers
# USR_0000 00000002 HMAC passwd ...A[CXI_GROUP=SLOT_0000]
InitToken and InitPIN set only an initial PIN. You must run SetPIN again to change
it to a formal PIN, otherwise firmware policy may cause later operations to fail with
CKR_PIN_TOO_WEAK . Note: The user PIN length must be between 8 and 255 characters. This <user PIN> is the value you later enter as pin in the HSM connection settings (Section 6.1). Security note: All PINs above are placeholders. In production, set strong PINs and store them only encrypted, through the management console; never write them in clear text into configuration files or logs. We recommend the ask interactive mode of p11tool2 so PINs do not enter the shell history.
Checking the Slot and Token
CS_PKCS11_R3_CFG=/etc/stoa/cs_pkcs11_R3.cfg \
pkcs11-tool --module /opt/utimaco/lib/libcs_pkcs11_R3.so -L
The output should show slot 0 with token label CryptoServer PKCS11 Token and manufacturer Utimaco IS GmbH.
The slot_label you enter in the HSM connection settings must be the token's CKA label ( CryptoServer PKCS11 Token by default), not the slot description SLOT_0000. Slots are matched by token label; an incorrect value produces the error "no token slot found with label X".