HSM Connection Settings (/api/v1/hsm-configs)
|
Field |
Type |
Description |
|---|---|---|
|
name |
string, required |
Configuration name (1–128 characters). |
|
vendor |
string |
Vendor; currently only utimaco. |
|
pkcs11_module_path |
string, required |
Absolute path of the PKCS#11 shared library on the gateway node; also the delivery target path. |
|
slot_label |
string |
The PKCS#11 token CKA label (CryptoServer PKCS11 Token by default); up to 128 characters. |
|
pin |
string, required |
Cryptographic User PIN. Submitted once, then stored AES-256-GCM encrypted; never appears in responses, logs, or the UI. |
|
key_label_prefix |
string |
Prefix for key labels inside the HSM (stoa- by default); up to 64 characters. |
|
gm_enabled |
bool |
Chinese-national-algorithm firmware capability flag (connection level; signature algorithm is chosen per certificate). |
|
enabled |
bool |
Whether the configuration is active; only enabled configurations are delivered. |
|
cluster_id |
UUID |
Gateway cluster to bind to; empty means global fallback. |
|
client_lib_id |
UUID |
Referenced PKCS#11 client library artifact. |
HSM connection settings
Certificate Key Fields (/api/v1/certificates)
|
Field |
Values |
Description |
|---|---|---|
|
key_source |
local (default) / utimaco_hsm |
Private key source. With utimaco_hsm the key is generated inside the HSM and a key reference is recorded. |
|
key_algorithm |
rsa / ecdsa / sm2 / ml-dsa-65 |
Key algorithm family. Defaults to ecdsa for HSM-managed certificates, so ml-dsa-65 must be given explicitly for post-quantum. With local it is implied by the PEM and may be omitted. |
|
hsm_key_label |
string |
Key label inside the HSM; defaults to <key_label_prefix><name>. |
|
key_pem |
string |
Only for key_source=local; stored and delivered encrypted. |
|
cluster_id |
UUID |
Gateway cluster binding, which determines the delivery scope. |
Certificate key fields
PKCS#11 Client Library (/api/v1/hsm-client-libs )
|
Field |
Description |
|---|---|
|
file |
Multipart file field, up to 64 MB. |
|
filename |
File name written on the gateway node (for example, libcs_pkcs11_R3.so). |
|
vendor |
Currently only Utimaco. |
|
arch |
Target architecture; currently only linux-x86-64. |
|
version |
Version marker (optional, up to 64 characters). |
|
sha256 |
Computed by the server; used for upload idempotency and integrity verification. |
PKCS#11 Client Library