Using HSM-protected DEK with VSatellites
Table of Contents
Expand all | Collapse all
-
- Activate Next-Generation Trust Security
-
-
- Configure AWS connection
- Configure Azure Key Vault connection
-
- Workload Identity Federation authentication
- Workload Identity Federation - Azure Identity Provider authentication
- Next-Gen Trust Security Generated Key authentication
- User permissions
- Workload Identity Federation authentication
- Next-Gen Trust Security Generated Key authentication
- User permissions
- Supported OIDC claims
-
-
-
-
- Create an F5 BIG-IP LTM machine
- Create a Microsoft Azure Private Key Vault machine
- Create a Microsoft IIS machine
- Create a Microsoft Windows (PowerShell) machine
- Create a Microsoft SQL Server machine
- Create a Common KeyStore machine
- Create a Citrix ADC machine
- Create an Imperva WAF machine
- Create a VMware NSX Advanced Load Balancer (AVI) machine
- Create an A10 Thunder ADC machine
- Create a Cloudflare machine
- Create Kemp Virtual LoadMaster machine
- Create a Palo Alto Panorama machine
-
- Provision to an F5 BIG-IP LTM
- Provision to a Microsoft Azure Private Key Vault
- Provision to Microsoft IIS
- Provision to Microsoft Windows (PowerShell)
- Provision to Microsoft SQL Server
- Provision to a Common KeyStore
- Provision to a Citrix ADC
- Provision to an Imperva WAF
- Provision to VMware NSX Advanced Load Balancer (AVI)
- Provision to an A10 Thunder ADC
- Provision to Cloudflare
- Provision to a Kemp Virtual LoadMaster
- Provision to Palo Alto Panorama
-
-
- 47-Day Validity Readiness TLS Certificates dashboard
- About the Certificate Inventory
- Managing certificate lifecycle settings
- Reissuing certificates in Next-Gen Trust Security
- Downloading certificates, certificate chains, and keystores
- Retiring, recovering, and deleting certificates
- Finding certificates in the certificate inventory
- Importing certificates from a CA using EJBCA
- Notification Center overview
- Domain-based validation for external emails
- Managing user accounts
- Troubleshooting
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
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) | Directory where the HSM vendor’s client software is installed | Directory | 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) | PKCS#11 shared library used to communicate with the HSM | File (.so) | Must be the full path to the PKCS#11 library file. 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 defining how the PKCS#11 library connects to slots or partitions | File | Created and managed as part of the HSM client setup. Format is vendor-specific. |
| Partition label (--partition-label) | Identifies the HSM partition that stores the DEK | String | Must match the partition label configured in the HSM. Required. |
| Partition serial number (--partition-serial-number) | Disambiguates partitions with the same label | String | Optional. Required only if multiple partitions share the same label. |
| HSM partition PIN | Authenticates access to the HSM partition | Secret | Required. Entered interactively during installation. |
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:
- Installation 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 include:
- Incorrect HSM client, library, or configuration file paths.
- Incorrect HSM partition PIN.
Note:If the VSatellite is the first 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 return to a healthy state automatically after HSM connectivity or configuration issues are resolved.
Note:UI error messages may be generic. Detailed error information is available in the VSatellite logs.
Supported and unsupported operations
The following table summarizes DEK-related operations when using HSM-protected DEK.
| Operation | Supported | Notes |
|---|---|---|
| Export DEK (vsatctl export) | No | The DEK is stored in the HSM and cannot be exported. |
| Import DEK (vsatctl import) | No | Importing an external DEK is not supported. |
| Rotate DEK | No | DEK rotation is not supported with HSM-protected DEK. |
| Recovery wizard / vsatctl recover | No | Recovery using UI or CLI is not supported. |
| Reinstall VSatellite | Yes | Reinstallation 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 DEK is managed entirely within the configured HSM partition.
Note:For security and operational isolation, use a dedicated HSM partition and a separate PIN for VSatellite DEK protection.
Using a dedicated partition isolates VSatellite key material from other workloads and reduces the risk of accidental access or deletion.
Note (Security considerations for HSM-protected DEK):When deploying VSatellites with HSM-protected DEK, you are responsible for securely configuring and operating your HSM environment. Recommended practices include:
- Least privilege for the HSM partitionGrant only the permissions required to use the DEK.
- Protect access to the HSMRestrict administrative access and protect authentication credentials.
- Protect HSM key materialEnsure appropriate backup and recovery practices per your security policies.
- Ensure integrity of the PKCS#11 libraryUse trusted vendor libraries and protect them from modification.
- Restrict access to VSatellite hostsLimit host access to reduce compromise risk.
- Secure HSM communicationConfigure clients and libraries for secure communication.
These recommendations align with general best practices for HSM-backed workloads.
Single HSM and partition requirement
- All VSatellites in a tenant must use the same HSM and partition.
- Keys created in one partition cannot be accessed from another.
- Using 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 with the same HSM partition reuses the existing DEK.
- No manual action is required.
Deleting the DEK from the HSM
- If the DEK is deleted while VSatellites are active, they enter an Unhealthy state.
- Because the DEK cannot be restored or regenerated, deleting it causes permanent data loss.
- Recovery is not supported after the DEK is deleted from the HSM.