Integrating Para Vault with the Utimaco HSM

This chapter uses the epv-hsm management tool shipped with Para Vault to complete the integration and verification. epv-hsm runs on the host where Para Vault runs and provides the following subcommands:

Configuring Para Vault to Enable HSM Protection

Para Vault's HSM configuration is managed by the epv-hsm tool; operators do not need to manually edit any Para Vault configuration file. The HSM address is in the Utimaco driver configuration cs_pkcs11_R3.cfg (see Configuring cs_pkcs11_R3.cfg section); all other parameters (driver path, token label, key label, algorithm) have default values and can be overridden with command-line options during enable / migrate in advanced scenarios.

For a standard deployment, operators need only three steps:

1. Ensure that the host (or container) running Para Vault can reach the HSM over the network (network type), or that the PCIe device has been passed through; confirm that Para Vault uses an HSM capable image and has mounted the Utimaco PKCS#11 driver library (libcs_pkcs11_R3.so) and configuration file (cs_pkcs11_R3.cfg). The HSM address is already configured in cs_pkcs11_R3.cfg . For details, see Configuring cs_pkcs11_R3.cfg section.

2. Store the HSM PIN (as ciphertext: first encrypt it to obtain the ciphertext, then pass it to set-pin, which saves it as ciphertext with 600 permissions — both what the operator handles and what is stored are ciphertext):

# 1) Encrypt the PIN; enter it when prompted to obtain a ciphertext string
sudo epv-hsm encrypt-pin

# 2) Pass the ciphertext from the previous step to set-pin for storage
sudo epv-hsm set-pin <ciphertext from the previous step>

3. Run the pre-check to confirm the basic prerequisites are in place (PIN configured, HSM driver mounted into the container, orchestration file present, Para Vault container running):

sudo epv-hsm check

Enabling HSM Protection on a New Para Vault

In the most secure deployment method, the server key is generated directly within the HSM's secure environment and stored as a non-exportable key in the HSM's PKCS#11 slot for Para Vault to use.

1. Complete the configuration in the Configuring Para Vault to Enable HSM Protection section.

2. Enable HSM protection (upon first initialization, the server key is generated inside the HSM). After enabling, this command automatically runs component-level verification:

sudo epv-hsm enable

3. Keep the recovery key safe: the recovery key is used for disaster recovery and for re-issuing the administrative token. Store it in a distributed manner according to your organization's key custody policy.

4. Confirm the verification result at the end of the command (enable runs it automatically; example, tool output is in English):

== HSM protection verification ==
[1/4] HSM key check ........... PASS (server key is in the HSM and was used to start successfully)
[2/4] Protection mode ......... HSM-based hardware protection
[3/4] Auto-start on restart ... PASS (no manual key entry required)
[4/4] Data read-write check ... PASS
Conclusion: Para Vault is protected by the HSM and operating normally.

Migrating an Existing Para Vault's Server Key to the HSM

To migrate a Para Vault that is already running to HSM hardware protection:

1. Complete the configuration in the Configuring Para Vault to Enable HSM Protection section.

2. Perform the migration (the tool automatically obtains the key and switches over, with no manual key entry; the command can be run repeatedly and is idempotent). After the migration completes, this command automatically runs component-level verification:

sudo epv-hsm migrate

3. Keep the recovery key safe: after the migration completes, the credentials previously used for software protection become the recovery key (for disaster recovery). Store it safely.

4. Confirm the verification result at the end of the command (migrate runs it automatically; output is the same as Enabling HSM Protection on a New Para Vault section). To re-check at any time, you can run sudo epv-hsm verify on its own.