Using HSM-protected DEK with VSatellites¶
This topic describes how VSatellites behave when the tenant is configured to use an HSM-protected Data Encryption Key (DEK).
Before you begin¶
Before deploying a VSatellite with an HSM-protected DEK, ensure that:
- The HSM client software is installed on the target host.
- The HSM client is configured and able to authenticate and communicate with the HSM.
- For production deployments, a supported hardware-based HSM is available.
Note
HSM-protected DEK is supported with Thales Luna Network HSM (Series 7).
SoftHSM can be used for development and testing environments only. Other HSMs are not supported at this time.
Switching between DEK protection modes¶
The DEK protection mode (software-based or HSM-protected) is a tenant-level setting.
After at least one VSatellite is deployed, the DEK protection mode cannot be changed. To switch between software-based DEK and HSM-protected DEK, you must first remove all existing VSatellites from the tenant.
After all VSatellites are removed, you can deploy a new VSatellite and select a different DEK protection mode.
HSM configuration parameters¶
What do the HSM configuration parameters mean?
When deploying a VSatellite with HSM-protected DEK, you must supply values that reference components of your HSM client installation. These values are HSM vendor–specific and must already exist on the VSatellite host.
The following table explains what each parameter represents and how it is used.
| Parameter | What it represents | File or directory | Notes and examples |
|---|---|---|---|
HSM client path (--hsm-client-path) | The directory where the HSM vendor’s client software is installed | Directory | This client enables applications to communicate with the HSM. Examples: • Thales Luna: /usr/safenet/lunaclient• SoftHSM (testing only): /usr/local/lib/softhsm |
HSM library path (--hsm-lib-path) | The PKCS#11 shared library used to communicate with the HSM | File (.so) | This must be the full path to the PKCS#11 library file, not a directory. Examples: • Thales Luna: /usr/safenet/lunaclient/lib/libCryptoki2.so• SoftHSM: /usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so |
HSM configuration file (--hsm-config) | Configuration file that defines how the PKCS#11 library connects to HSM slots, tokens, or partitions | File | Created and managed as part of the HSM client setup. The format and contents are vendor-specific. |
Partition label (--partition-label) | Identifies the HSM partition that stores the DEK | Value (string) | Must match the partition label configured in the HSM. Required for all HSM-protected DEK installations. |
Partition serial number (--partition-serial-number) | Disambiguates partitions with the same label | Value (string) | Optional. Required only if multiple HSM partitions share the same label. |
| HSM partition PIN | Authenticates access to the HSM partition | Secret value | Required. During installation, you are prompted to enter the PIN interactively. |
Important
HSM-related values are not fully validated during installation. If incorrect values are supplied, the VSatellite may deploy successfully but enter an Unhealthy state. Detailed error information is available in the VSatellite logs.
Validation and health status behavior¶
When deploying a VSatellite with HSM-protected DEK, some HSM-related configuration values are not fully validated during installation.
As a result:
- The installation command may complete successfully even if HSM values are incorrect.
- Configuration issues are often detected only after the VSatellite starts.
- The VSatellite enters an Unhealthy state when it cannot access the HSM-protected DEK.
Common causes of an Unhealthy state include:
- Incorrect HSM client, library, or configuration file paths.
- An incorrect PIN for the HSM partition.
Note
If the VSatellite is the first one deployed with HSM-protected DEK and no DEK exists yet in the HSM, a new DEK is generated automatically.
In some cases, the VSatellite may automatically return to a healthy state after HSM connectivity or configuration issues are resolved.
Note
Error messages shown in the UI may be generic. Detailed error information is available in the VSatellite logs.
Supported and unsupported operations¶
The following table summarizes which DEK-related operations are supported when VSatellites are deployed with HSM-protected DEK.
| Operation | Supported | Notes |
|---|---|---|
Export DEK (vsatctl export) | No | The DEK is generated and stored in the HSM and cannot be exported. |
Import DEK (vsatctl import) | No | Importing an external DEK is not supported for HSM-protected deployments. |
| Rotate DEK | No | DEK rotation is not supported when using HSM-protected DEK. |
Recovery wizard / vsatctl recover | No | Recovery using the UI or CLI is not supported for HSM-protected DEK. |
| Reinstall VSatellite | Yes | Reinstalling a VSatellite does not remove the DEK from the HSM. |
| Automatic upgrades | Yes | Automatic VSatellite upgrades are supported. |
| Multiple HSMs or partitions | No | All VSatellites must use the same HSM and partition. |
HSM partition and DEK lifecycle behavior¶
When using HSM-protected DEK, the Data Encryption Key is managed entirely within the configured HSM partition. Understanding how the DEK behaves across common lifecycle events helps prevent unintended outages.
Note
For security and operational isolation, it is recommended to use a dedicated HSM partition and a separate PIN for VSatellite DEK protection.
Using a dedicated partition helps isolate VSatellite key material from other HSM workloads and reduces the risk of accidental access or deletion.
Security considerations for HSM-protected DEK
When deploying VSatellites with HSM-protected DEK, customers are responsible for securely configuring and operating their HSM environment. The following security considerations are recommended:
-
Least privilege for the HSM partition
Grant the VSatellite access only to the permissions required to use the DEK. -
Protect access to the HSM
Restrict administrative access to the HSM and protect credentials, certificates, or tokens used for authentication. -
Protect HSM key material
Ensure appropriate backup and recovery practices are in place for HSM-managed key material according to your security policies. -
Ensure integrity of the PKCS#11 library
Use trusted, vendor-provided PKCS#11 libraries and protect them from unauthorized modification. -
Restrict access to VSatellite hosts
Limit access to hosts running VSatellites to reduce the risk of compromise. -
Secure HSM communication
Configure the HSM client and libraries to ensure secure communication between VSatellites and the HSM.
These recommendations are not specific to VSatellite and align with general best practices for operating HSM-backed workloads.
Single HSM and partition requirement¶
- All VSatellites in a tenant must use the same HSM and the same partition.
- Keys created in one HSM partition cannot be accessed from another partition.
- Installing a VSatellite with a different HSM or partition causes the VSatellite to enter an Unhealthy state.
Reinstalling VSatellites¶
- Uninstalling a VSatellite does not delete the DEK from the HSM.
- Reinstalling a VSatellite using the same HSM partition reuses the existing DEK.
- No manual action is required to preserve the DEK during reinstallation.
Deleting the DEK from the HSM¶
- If the DEK is deleted from the HSM while VSatellites are active, the VSatellites enter an Unhealthy state during the next health check.
- Because the DEK cannot be practically restored or regenerated, deleting it results in permanent loss of access to encrypted data.
- Recovery is not supported after the DEK is deleted from the HSM.