The operations in this chapter require the security:manage_certificates capability (security officer role). Examples use curl; exact fields depend on the API version deployed on site.
Entering the HSM Connection Settings
UI path: Cluster Certificate Management → HSM Integration → New Configuration. The PIN is
never displayed.
curl -X POST http://<console>:8081/api/v1/hsm-configs \
-H "Authorization: Bearer <token>" -H 'Content-Type: application/json' \
-d '{
"name": "utimaco-prod-1",
"vendor": "utimaco",
"pkcs11_module_path": "/opt/utimaco/lib/libcs_pkcs11_R3.so",
"slot_label": "CryptoServer PKCS11 Token",
"pin": "<user PIN>",
"key_label_prefix": "stoa-",
"enabled": true,
"cluster_id": "<target cluster UUID, optional>"
}'
Key fields (full list in Appendix B):
-
pkcs11_module_path — absolute path of the vendor library on the gateway node; also the target path when the product delivers the library.
-
slot_label — must be the token's CKA label ( CryptoServer PKCS11 Token by default), not the slot description SLOT_0000.
-
pin — the user PIN from Section 4.3. It is submitted once and immediately encrypted with AES 256-GCM; it is never stored in clear text and never appears in API responses, logs or the UI.
-
cluster_id — the gateway cluster to bind to. Leaving it empty makes the configuration a global fallback, used by any cluster without a dedicated binding.
-
enabled — only enabled configurations are delivered.
Post-quantum mechanism values. For the HSM-managed path, the management console node
also needs the PKCS#11 mechanism value for ML-DSA key generation:
export CS_PKCS11_R3_CFG=/etc/stoa/cs_pkcs11_R3.cfg
export STOA_HSM_CKM_ML_DSA_65=0xFFFFFFFFC0A50001 # must be 64-bit sign-extended
The mechanism value must use the 64-bit sign-extended form. Utimaco's MECH_ML_VDM = (0xC<<28)|(0xA5<<16) = 0xC0A50000 is negative as an int32 and is signextended when converted to CK_ULONG . The correct values are 0xFFFFFFFFC0A50001 (key generation) and 0xFFFFFFFFC0A53001 (signing). The 32-bit value 0xC0A50001 results in CKR_GENERAL_ERROR . Important (decisive pitfall 2): The VDM type of the a5 ML module uses the enumerated values 44→1, 65→2, 87→3 — not the PQMI/CXI values 0x32/0x33/0x35 . ML-DSA-65 must be passed as 2; passing 0x33 yields firmware error 0xB0A5000E .
Testing the Connection
UI path: Configuration card → Test Connection.
curl -X POST http://<console>:8081/api/v1/hsm-configs/<id>/test \
-H "Authorization: Bearer <token>"
# On success: {"ok":true,"message":"...","slot_info":{...}}
The test performs the full sequence — load the library, initialize it, find the slot by token label, log in, read token information. A failure at any step returns a reason precise enough to locate the problem.
Delivering the PKCS#11 Client Library
Required only when using option 2 of Section Placing the PKCS#11 Client Library. Skip if the library is pre-installed on the nodes.
curl -X POST http://<console>:8081/api/v1/hsm-client-libs \
-H "Authorization: Bearer <token>" \
-F "file=@libcs_pkcs11_R3.so" -F "vendor=utimaco" -F "arch=linux-x86-64"
# Maximum 64 MB per file; the server computes the SHA-256 and deduplicates by digest
Then associate the uploaded artifact with the HSM configuration ( client_lib_id ). Each gateway
node fetches it, verifies the SHA-256 and writes the file atomically to pkcs11_module_path .