SoftHSM2 as a HSM Provider

This document provides instructions for setting up SoftHSM2 as a HSM provider for PrivX. This integration allows PrivX to store and/or encrypt its cryptographic keys with HSM.

These instructions are only applicable to fresh deployments: existing PrivX deployments cannot be integrated with HSM.

These instructions are to be used together with the PrivX-setup instructions at Setting up PrivX components.

Prerequisites

• SoftHSM2 version is 2.6.1 or later
• SoftHSM2 is built with AES-GCM support

📘

Note

Some OS vendor distributed SoftHSM2 packages have not been built with AES-GCM support. Those SoftHSM2 packages cannot be used with PrivX.

Integration Steps

The high-level workflow for SoftHSM" integration involves:

1. Setting up SoftHSM2 HSM slot on a shared file system
2. Setting up PrivX-server software on PrivX machines.
   These steps are described in more detail in the following sections.

Setting Up SoftHSM2 HSM Slot

1. Create a token directory on a shared file system accessible by all PrivX nodes. Configure this directory as the directories.tokendir in the softhsm2.conf configuration file. Make sure the directory is readable and writable by user privx and group privx.
2. Use the softhsm-util tool to initialize a new HSM token and then extract the slot number of the created token. The slot number and the pin are needed when configuring PrivX in the next steps.

Setting Up PrivX-Server Software on PrivX Machines

Set up PrivX-server software on a PrivX machine according to the PrivX Administrator Manual, while paying attention to the following points.

You will be prompted for HSM settings during postinstall. Provide them as follows:

Enable pkcs11 keyvault support? [y/N]
To enable, enter y
Select pkcs11 provider [1-6]:
To select SoftHSM2, enter 3
Enter pkcs11 provider library file path:
Enter the full file path to libsofthsm2.so
Enter pkcs11 slot:
Enter the slot number of the HSM token
Enter pkcs11 pin: and Enter pkcs11 pin again:
Enter and verify the pin for the HSM token

After this, proceed with setup as normal. You should have access to the PrivX GUI after postinstall completes.

If you need to set up additional PrivX servers, duplicate the PrivX-server setup to other PrivX machines as described in High-Availability Deployment.