Downloading and Installing the Utimaco Software
If you have not registered yet, first register an account on the Utimaco support portal to download the required software components. If you purchased the HSM from Utimaco, locate the corresponding software package in the accompanying product bundle. Install the latest SecurityServer software according to the SecurityServer manual. It is recommended to uninstall any existing SecurityServer software before installing a new version.
Configuring cs_pkcs11_R3.cfg
The PKCS#11 library locates the HSM through the configuration file cs_pkcs11_R3.cfg. Edit its Devices entry according to the HSM form factor:
[Global]
Logging = 1
Logpath = <writable log directory>
ConnectionTimeout = 5000
CommandTimeout = 60000
[HSMCluster]
# Network type (LAN appliance):
Devices = 288@<HSM-IP>
# PCIe card: Devices = /dev/cs2.0
-
Network type (LAN): Devices = <port>@<HSM-IP> (for example,
288@10.10.x.x); the container network must be able to route to the HSM. -
PCIe card: Devices =
/dev/cs2.0(local device); the device must be passed through to the container.
During debugging, you can raise Logging to 4 for more detailed logs; set it back to 1 afterward. The log file is cs_pkcs11_R3.log in the Logpath directory.
Deployment on the HSM appliance side (firmware initialization, exposure as a network service, clustering/HA) is handled by HSM operations according to your deployment architecture and the official Utimaco documentation, and is out of scope for this guide.
Creating the SO User and Initializing the Slot
Use p11tool2 to initialize the slot and set the SO (Security Officer) and user PINs. This guide creates a token on slot 0 with the label EPV-HSM. Para Vault locates the key by token label; the default label is EPV-HSM (matching the one here; if you use a different label, override it in Chapter 5 with --token-label).
# 1) Authorize as administrator, create the SO, and set the initial token PIN
p11tool2 Slot=0 Label=EPV-HSM Login=ADMIN,<ADMIN.key> InitToken=<initial PIN>
# 2) Change the initial SO PIN to the formal PIN
p11tool2 Slot=0 LoginSO=<initial PIN> SetPIN=<initial PIN>,<SO-PIN>
# 3) Initialize the user PIN
p11tool2 Slot=0 LoginSO=<SO-PIN> InitPIN=<initial PIN>
# 4) Change the initial user PIN to the formal PIN
p11tool2 Slot=0 LoginUser=<initial PIN> SetPIN=<initial PIN>,<user-PIN>
# Verify: should return USER_PIN_INITIALIZED = CK_TRUE
p11tool2 Slot=0 LoginUser=<user-PIN> GetTokenInfo
InitToken/InitPIN set only an "initial PIN"; you must run SetPIN again to change it to a formal PIN before you can log in and operate normally. Otherwise, subsequent operations may fail with CKR_PIN_TOO_WEAK due to firmware policy.
This step only initializes the slot; it does not create a key. The server key will be generated directly by the HSM in Chapter 5. <user-PIN> is the PIN used later when configuring Para Vault.
Security Note: The PINs above are shown as placeholders. In production, it is recommended to use p11tool2's ask mode for interactive PIN entry (to keep PINs out of the command history); see the Utimaco p11tool2 manual for usage.