HSM Connection

An HSM Connection defines the parameters required by USP Server to communicate with an external Hardware Security Module (HSM).

Through an HSM Connection, USP can reference and use Private Keys and TLS Certificates that are securely stored in a hardware device.

Before You Begin

Overview

A Hardware Security Module (HSM) is a dedicated cryptographic device designed to generate, store, and protect private keys and certificates within a secure, tamper-resistant environment.

Unlike file-based storage, keys managed by an HSM never exist in plaintext outside the hardware boundary. All signing and decryption operations occur inside the device, ensuring the highest level of key protection.

USP integrates with HSMs using the industry-standard PKCS#11 interface. Each HSM vendor provides a shared library file (for example, /usr/lib/softhsm/libsofthsm2.so) that implements the PKCS#11 API and allows USP to communicate with the device.

USP supports storing, in an HSM, the Private Keys and TLS Certificates referenced by USP Manager.

HSM integration is not available for certificates configured directly in USP component Configuration Files.

Configuration Steps

To configure USP to use HSM-stored credentials:

1. Add an HSM Connection and assign it to the target Proxy Server.
2. When adding a new Private Key or TLS Certificate, enable the Store in HSM toggle.
3. Enter the corresponding HSM Certificate ID (CKA_ID) and HSM Certificate Label (CKA_LABEL) that identify the object stored in your HSM.
4. Save the configuration and push it to the USP Server to apply the changes.

Once deployed, the USP Server uses the configured HSM Connection and PKCS#11 library to perform all key operations, such as signing during SSH (for Private Keys) or TLS (for TLS Certificates) handshakes, directly inside the HSM, without the key material leaving the device.

HSM Provider Library Path

The HSM Provider Library Path is the absolute path to your vendor's PKCS#11 shared library file (for example, libcknfast.so or libsofthsm2.so) installed on the same host as the USP Server.

This library acts as the driver that allows USP to communicate with your HSM. It implements the PKCS#11 interface and translates USP's cryptographic operations (such as signing or key listing) into commands that the HSM hardware understands.

You must obtain the PKCS#11 shared library file directly from your HSM vendor as part of their client or SDK installation package. Each manufacturer provides its own implementation, and they are not interchangeable.

Vendor	Example Library Path
Thales (nCipher / nShield)	/opt/nfast/toolkits/pkcs11/libcknfast.so
Entrust (SafeNet Luna)	/usr/safenet/lunaclient/lib/libCryptoki2_64.so
Utimaco	/usr/local/lib/libcs_pkcs11_R2.so
FutureX	/usr/lib/fxpkcs11.so
SoftHSM (test only)	/usr/lib/softhsm/libsofthsm2.so

HSM Connection Administration via USP Admin UI

Adding an HSM Connection

To add an HSM Connection, follow these steps:

1. From the Sidebar, click Authentication > HSM.
2. Click Add HSM Connection.
3. Enter the details for the new HSM Connection using the Field Descriptions table as a guide.
4. Click Save.

Field Descriptions

Name	Description	Specifications	Required
Name	The name of the HSM Connection.	Must be unique.	Yes
Description	The description of the HSM Connection.		No
HSM Provider Library Path	Path to your vendor's PKCS#11 shared library. Can be an absolute path or a relative path to the USP Server working directory.		Yes
Token Serial Number	Hardware identifier for the token. Only one token identifier is allowed (Token Serial Number, Token Label, or Slot Number).	Yes, if no Token Label or Slot Number is provided.	No
Token Label	Human-readable label for the token. Only one token identifier is allowed (Token Serial Number, Token Label, or Slot Number).	Yes, if no Token Serial Number or Slot Number is provided.	No
Slot Number	Slot Number of the token's slot (e.g., 0, 123). Only one token identifier is allowed (Token Serial Number, Token Label, or Slot Number).	Yes, if no Token Serial Number or Token Label is provided.	No
Authenticate to the HSM	Only disable if the HSM or Token doesn't require authentication.		Yes
Security PIN	The PIN used to authenticate to the token.		Yes, if Authenticate to the HSM is enabled.
User Type (Role)	Role used to authenticate to the token (e.g., Normal User or Security Officer).		Yes, if Authenticate to the HSM is enabled.
Maximum Concurrent HSM Sessions	Upper bound on how many simultaneous sessions the server will open using the HSM token.	Default value: 1024.	No
Connection Timeout (Seconds)	Time in seconds to wait for an available session when the HSM connection pool is full (e.g., 10, 30, 90). Enter 0 for no timeout.		No

Editing an HSM Connection

To edit an HSM Connection, follow these steps:

1. From the Sidebar, click Authentication > HSM.
2. Click the row of the HSM Connection you want to edit.
3. Click the Edit button above the HSM Connection details.
4. Edit the details of the HSM Connection using the Field Descriptions table as a guide.
5. Click Save.

warning

If you modify an HSM Connection that is currently associated with a USP Server instance, the updated configuration must be manually applied. To do this, follow these steps:

1. Navigate to Monitoring > Status.
2. Click the Name of the associated server.
3. Go to the Configuration tab.
4. Review the pending changes in the Candidate Configuration - Preview section.
5. If the changes are correct, click Push Configuration.

Additionally, you also need to restart the HSM Connection. To do this, follow these steps:

1. Go to the HSM Connection tab.
2. Click the Stop HSM Connection button.
3. Click Start HSM Connection.

The changes do not take effect on the server until these steps are completed.

HSM Connection Metadata

HSM Connection details include all parameters given in the Field Descriptions table above, plus the following read-only metadata:

Name	Description
ID	Universally Unique Identifier of this HSM Connection.
Created At	Date and time this HSM Connection was created.
Updated At	Date and time this HSM Connection was last updated.

Deleting an HSM Connection

To delete an HSM Connection, follow these steps:

1. From the Sidebar, click Authentication > HSM.
2. Click the row of the HSM Connection you want to delete.
3. Click the Delete button above the HSM Connection details.
4. You will be asked to confirm the deletion. Click Delete.

warning

USP Manager prevents deletion of an HSM Connection if it is currently referenced by another Configuration Item.

Additionally, if the HSM Connection is used by a USP Server instance, the updated configuration must be manually applied. To apply the changes:

1. Navigate to Monitoring > Status.
2. Click the Name of the associated USP Server instance.
3. Go to the Configuration tab.
4. Review the pending changes in the Candidate Configuration - Preview section.
5. If the changes are correct, click Push Configuration.

The changes do not take effect on the server until this step is completed.

Managing an HSM Connection

Once an HSM Connection has been configured and assigned to a Proxy Server, administrators can monitor and validate its operation

Managing an HSM Connection involves two primary tasks:

• Testing the HSM Connection to verify communication between the USP Server and the HSM.
• Validating credential availability to confirm that TLS Certificates and Private Keys stored in the HSM are correctly detected and accessible.

Both actions are performed in the HSM Connection tab in the Status section.