diff --git a/docs/documentation/platform/kms/hsm-integration.mdx b/docs/documentation/platform/kms/hsm-integration.mdx
index 4f9efe49f..633377b3d 100644
--- a/docs/documentation/platform/kms/hsm-integration.mdx
+++ b/docs/documentation/platform/kms/hsm-integration.mdx
@@ -66,7 +66,7 @@ For organizations that work with US government agencies, FIPS compliance is almo
- Are you using Docker? If you are using Docker, please follow the instructions in the [Using HSM's with Docker](#using-hsms-with-docker) section.
+ Are you using Docker or Kubernetes for your deployment? If you are using Docker or Kubernetes, please follow the instructions in the [Using HSM's in your Deployment](#using-hsms-in-your-deployment) section.
Configuring the HSM on Infisical requires setting a set of environment variables:
@@ -94,165 +94,447 @@ For organizations that work with US government agencies, FIPS compliance is almo
-## Using HSMs with Docker
-When using Docker, you need to mount the path containing the HSM client files. This section covers how to configure your Infisical instance to use an HSM with Docker.
+## Using HSMs In Your Deployment
+
-
-
-
- When using Docker, you are able to set your HSM library path to any location on your machine. In this example, we are going to be using `/etc/luna-docker`.
+
+ When using Docker, you need to mount the path containing the HSM client files. This section covers how to configure your Infisical instance to use an HSM with Docker.
- ```bash
- mkdir /etc/luna-docker
- ```
+
+
+
+
+ When using Docker, you are able to set your HSM library path to any location on your machine. In this example, we are going to be using `/etc/luna-docker`.
- After [setting up your Luna Cloud HSM client](https://thalesdocs.com/gphsm/luna/7/docs/network/Content/install/client_install/add_dpod.htm), you should have a set of files, referred to as the HSM client. You don't need all the files, but for simplicity we recommend copying all the files from the client.
+ ```bash
+ mkdir /etc/luna-docker
+ ```
- A folder structure of a client folder will often look like this:
- ```
- partition-ca-certificate.pem
- partition-certificate.pem
- server-certificate.pem
- Chrystoki.conf
- /plugins
- libcloud.plugin
- /lock
- /libs
- /64
- libCryptoki2.so
- /jsp
- LunaProvider.jar
- /64
- libLunaAPI.so
- /etc
- openssl.cnf
- /bin
- /64
- ckdemo
- lunacm
- multitoken
- vtl
- ```
-
- The most important parts of the client folder is the `Chrystoki.conf` file, and the `libs`, `plugins`, and `jsp` folders. You need to copy these files to the folder you created in the first step.
+ After [setting up your Luna Cloud HSM client](https://thalesdocs.com/gphsm/luna/7/docs/network/Content/install/client_install/add_dpod.htm), you should have a set of files, referred to as the HSM client. You don't need all the files, but for simplicity we recommend copying all the files from the client.
- ```bash
- cp -r / /etc/luna-docker
- ```
+ A folder structure of a client folder will often look like this:
+ ```
+ partition-ca-certificate.pem
+ partition-certificate.pem
+ server-certificate.pem
+ Chrystoki.conf
+ /plugins
+ libcloud.plugin
+ /lock
+ /libs
+ /64
+ libCryptoki2.so
+ /jsp
+ LunaProvider.jar
+ /64
+ libLunaAPI.so
+ /etc
+ openssl.cnf
+ /bin
+ /64
+ ckdemo
+ lunacm
+ multitoken
+ vtl
+ ```
+
+ The most important parts of the client folder is the `Chrystoki.conf` file, and the `libs`, `plugins`, and `jsp` folders. You need to copy these files to the folder you created in the first step.
-
+ ```bash
+ cp -r / /etc/luna-docker
+ ```
-
- The `Chrystoki.conf` file is used to configure the HSM client. You need to update the `Chrystoki.conf` file to point to the correct file paths.
+
- In this example, we will be mounting the `/etc/luna-docker` folder to the Docker container under a different path. The path we will use in this example is `/usr/safenet/lunaclient`. This means `/etc/luna-docker` will be mounted to `/usr/safenet/lunaclient` in the Docker container.
+
+ The `Chrystoki.conf` file is used to configure the HSM client. You need to update the `Chrystoki.conf` file to point to the correct file paths.
- An example config file will look like this:
+ In this example, we will be mounting the `/etc/luna-docker` folder to the Docker container under a different path. The path we will use in this example is `/usr/safenet/lunaclient`. This means `/etc/luna-docker` will be mounted to `/usr/safenet/lunaclient` in the Docker container.
- ```Chrystoki.conf
- Chrystoki2 = {
- # This path points to the mounted path, /usr/safenet/lunaclient
- LibUNIX64 = /usr/safenet/lunaclient/libs/64/libCryptoki2.so;
- }
+ An example config file will look like this:
- Luna = {
- DefaultTimeOut = 500000;
- PEDTimeout1 = 100000;
- PEDTimeout2 = 200000;
- PEDTimeout3 = 20000;
- KeypairGenTimeOut = 2700000;
- CloningCommandTimeOut = 300000;
- CommandTimeOutPedSet = 720000;
- }
+ ```Chrystoki.conf
+ Chrystoki2 = {
+ # This path points to the mounted path, /usr/safenet/lunaclient
+ LibUNIX64 = /usr/safenet/lunaclient/libs/64/libCryptoki2.so;
+ }
- CardReader = {
- LunaG5Slots = 0;
- RemoteCommand = 1;
- }
+ Luna = {
+ DefaultTimeOut = 500000;
+ PEDTimeout1 = 100000;
+ PEDTimeout2 = 200000;
+ PEDTimeout3 = 20000;
+ KeypairGenTimeOut = 2700000;
+ CloningCommandTimeOut = 300000;
+ CommandTimeOutPedSet = 720000;
+ }
- Misc = {
- # Update the paths to point to the mounted path if your folder structure is different from the one mentioned in the previous step.
- PluginModuleDir = /usr/safenet/lunaclient/plugins;
- MutexFolder = /usr/safenet/lunaclient/lock;
- PE1746Enabled = 1;
- ToolsDir = /usr/bin;
+ CardReader = {
+ LunaG5Slots = 0;
+ RemoteCommand = 1;
+ }
- }
+ Misc = {
+ # Update the paths to point to the mounted path if your folder structure is different from the one mentioned in the previous step.
+ PluginModuleDir = /usr/safenet/lunaclient/plugins;
+ MutexFolder = /usr/safenet/lunaclient/lock;
+ PE1746Enabled = 1;
+ ToolsDir = /usr/bin;
- Presentation = {
- ShowEmptySlots = no;
- }
+ }
- LunaSA Client = {
- ReceiveTimeout = 20000;
- # Update the paths to point to the mounted path if your folder structure is different from the one mentioned in the previous step.
- SSLConfigFile = /usr/safenet/lunaclient/etc/openssl.cnf;
- ClientPrivKeyFile = ./etc/ClientNameKey.pem;
- ClientCertFile = ./etc/ClientNameCert.pem;
- ServerCAFile = ./etc/CAFile.pem;
- NetClient = 1;
- TCPKeepAlive = 1;
- }
+ Presentation = {
+ ShowEmptySlots = no;
+ }
+
+ LunaSA Client = {
+ ReceiveTimeout = 20000;
+ # Update the paths to point to the mounted path if your folder structure is different from the one mentioned in the previous step.
+ SSLConfigFile = /usr/safenet/lunaclient/etc/openssl.cnf;
+ ClientPrivKeyFile = ./etc/ClientNameKey.pem;
+ ClientCertFile = ./etc/ClientNameCert.pem;
+ ServerCAFile = ./etc/CAFile.pem;
+ NetClient = 1;
+ TCPKeepAlive = 1;
+ }
- REST = {
- AppLogLevel = error
- ServerName = ;
- ServerPort = 443;
- AuthTokenConfigURI = ;
- AuthTokenClientId = ;
- AuthTokenClientSecret = ;
- RestClient = 1;
- ClientTimeoutSec = 120;
- ClientPoolSize = 32;
- ClientEofRetryCount = 15;
- ClientConnectRetryCount = 900;
- ClientConnectIntervalMs = 1000;
- }
- XTC = {
- Enabled = 1;
- TimeoutSec = 600;
- }
- ```
+ REST = {
+ AppLogLevel = error
+ ServerName = ;
+ ServerPort = 443;
+ AuthTokenConfigURI = ;
+ AuthTokenClientId = ;
+ AuthTokenClientSecret = ;
+ RestClient = 1;
+ ClientTimeoutSec = 120;
+ ClientPoolSize = 32;
+ ClientEofRetryCount = 15;
+ ClientConnectRetryCount = 900;
+ ClientConnectIntervalMs = 1000;
+ }
+ XTC = {
+ Enabled = 1;
+ TimeoutSec = 600;
+ }
+ ```
- Save the file after updating the paths.
-
+ Save the file after updating the paths.
+
-
- Running Docker with HSM encryption requires setting the HSM-related environment variables as mentioned previously in the [HSM setup instructions](#setup-instructions). You can set these environment variables in your Docker run command.
+
+ Running Docker with HSM encryption requires setting the HSM-related environment variables as mentioned previously in the [HSM setup instructions](#setup-instructions). You can set these environment variables in your Docker run command.
- We are setting the environment variables for Docker via the command line in this example, but you can also pass in a `.env` file to set these environment variables.
+ We are setting the environment variables for Docker via the command line in this example, but you can also pass in a `.env` file to set these environment variables.
-
- If no key is found with the provided key label, the HSM will create a new key with the provided label.
- Infisical depends on an AES and HMAC key to be present in the HSM. If these keys are not present, Infisical will create them. The AES key label will be the value of the `HSM_KEY_LABEL` environment variable, and the HMAC key label will be the value of the `HSM_KEY_LABEL` environment variable with the suffix `_HMAC`.
-
+
+ If no key is found with the provided key label, the HSM will create a new key with the provided label.
+ Infisical depends on an AES and HMAC key to be present in the HSM. If these keys are not present, Infisical will create them. The AES key label will be the value of the `HSM_KEY_LABEL` environment variable, and the HMAC key label will be the value of the `HSM_KEY_LABEL` environment variable with the suffix `_HMAC`.
+
- ```bash
- docker run -p 80:8080 \
- -v /etc/luna-docker:/usr/safenet/lunaclient \
- -e HSM_LIB_PATH="/usr/safenet/lunaclient/libs/64/libCryptoki2.so" \
- -e HSM_PIN="" \
- -e HSM_SLOT= \
- -e HSM_KEY_LABEL="" \
-
- # The rest are unrelated to HSM setup...
- -e ENCRYPTION_KEY="<>" \
- -e AUTH_SECRET="<>" \
- -e DB_CONNECTION_URI="<>" \
- -e REDIS_URL="<>" \
- -e SITE_URL="<>" \
- infisical/infisical-fips: # Replace with the version you want to use
- ```
+ ```bash
+ docker run -p 80:8080 \
+ -v /etc/luna-docker:/usr/safenet/lunaclient \
+ -e HSM_LIB_PATH="/usr/safenet/lunaclient/libs/64/libCryptoki2.so" \
+ -e HSM_PIN="" \
+ -e HSM_SLOT= \
+ -e HSM_KEY_LABEL="" \
+
+ # The rest are unrelated to HSM setup...
+ -e ENCRYPTION_KEY="<>" \
+ -e AUTH_SECRET="<>" \
+ -e DB_CONNECTION_URI="<>" \
+ -e REDIS_URL="<>" \
+ -e SITE_URL="<>" \
+ infisical/infisical-fips: # Replace with the version you want to use
+ ```
- We recommend reading further about [using Infisical with Docker](/self-hosting/deployment-options/standalone-infisical).
+ We recommend reading further about [using Infisical with Docker](/self-hosting/deployment-options/standalone-infisical).
-
-
- After following these steps, your Docker setup will be ready to use HSM encryption.
+
+
+ After following these steps, your Docker setup will be ready to use HSM encryption.
+
+
+
+
+ When you are deploying Infisical with the [Kubernetes self-hosting option](/self-hosting/deployment-options/kubernetes-helm), you can still use HSM encryption, but you need to ensure that the HSM client files are present in the container.
+
+
+
+
+ This is only supported on helm chart version `1.4.1` and above. Please see the [Helm Chart Changelog](https://github.com/Infisical/infisical/blob/main/helm-charts/infisical-standalone-postgres/CHANGELOG.md#141-march-19-2025) for more information.
+
+
+
+
+ When using Kubernetes, you need to mount the path containing the HSM client files. This section covers how to configure your Infisical instance to use an HSM with Kubernetes.
+
+
+ ```bash
+ mkdir /etc/hsm-client
+ ```
+
+ After [setting up your Luna Cloud HSM client](https://thalesdocs.com/gphsm/luna/7/docs/network/Content/install/client_install/add_dpod.htm), you should have a set of files, referred to as the HSM client. You don't need all the files, but for simplicity we recommend copying all the files from the client.
+
+ A folder structure of a client folder will often look like this:
+ ```
+ partition-ca-certificate.pem
+ partition-certificate.pem
+ server-certificate.pem
+ Chrystoki.conf
+ /plugins
+ libcloud.plugin
+ /lock
+ /libs
+ /64
+ libCryptoki2.so
+ /jsp
+ LunaProvider.jar
+ /64
+ libLunaAPI.so
+ /etc
+ openssl.cnf
+ /bin
+ /64
+ ckdemo
+ lunacm
+ multitoken
+ vtl
+ ```
+
+ The most important parts of the client folder is the `Chrystoki.conf` file, and the `libs`, `plugins`, and `jsp` folders. You need to copy these files to the folder you created in the first step.
+
+ ```bash
+ cp -r / /etc/hsm-client
+ ```
+
+
+ The `Chrystoki.conf` file is used to configure the HSM client. You need to update the `Chrystoki.conf` file to point to the correct file paths.
+
+ In this example, we will be mounting the `/etc/hsm-client` folder from the host to containers in our deployment's pods at the path `/hsm-client`. This means the contents of `/etc/hsm-client` on the host will be accessible at `/hsm-client` within the containers.
+
+ An example config file will look like this:
+
+ ```Chrystoki.conf
+ Chrystoki2 = {
+ # This path points to the mounted path, /hsm-client
+ LibUNIX64 = /hsm-client/libs/64/libCryptoki2.so;
+ }
+
+ Luna = {
+ DefaultTimeOut = 500000;
+ PEDTimeout1 = 100000;
+ PEDTimeout2 = 200000;
+ PEDTimeout3 = 20000;
+ KeypairGenTimeOut = 2700000;
+ CloningCommandTimeOut = 300000;
+ CommandTimeOutPedSet = 720000;
+ }
+
+ CardReader = {
+ LunaG5Slots = 0;
+ RemoteCommand = 1;
+ }
+
+ Misc = {
+ # Update the paths to point to the mounted path if your folder structure is different from the one mentioned in the previous step.
+ PluginModuleDir = /hsm-client/plugins;
+ MutexFolder = /hsm-client/lock;
+ PE1746Enabled = 1;
+ ToolsDir = /usr/bin;
+
+ }
+
+ Presentation = {
+ ShowEmptySlots = no;
+ }
+
+ LunaSA Client = {
+ ReceiveTimeout = 20000;
+ # Update the paths to point to the mounted path if your folder structure is different from the one mentioned in the previous step.
+ SSLConfigFile = /hsm-client/etc/openssl.cnf;
+ ClientPrivKeyFile = ./etc/ClientNameKey.pem;
+ ClientCertFile = ./etc/ClientNameCert.pem;
+ ServerCAFile = ./etc/CAFile.pem;
+ NetClient = 1;
+ TCPKeepAlive = 1;
+ }
+
+
+ REST = {
+ AppLogLevel = error
+ ServerName = ;
+ ServerPort = 443;
+ AuthTokenConfigURI = ;
+ AuthTokenClientId = ;
+ AuthTokenClientSecret = ;
+ RestClient = 1;
+ ClientTimeoutSec = 120;
+ ClientPoolSize = 32;
+ ClientEofRetryCount = 15;
+ ClientConnectRetryCount = 900;
+ ClientConnectIntervalMs = 1000;
+ }
+ XTC = {
+ Enabled = 1;
+ TimeoutSec = 600;
+ }
+ ```
+
+ Save the file after updating the paths.
+
+
+
+ You need to create a Persistent Volume Claim (PVC) to mount the HSM client files to the Infisical deployment.
+
+
+ ```bash
+ kubectl apply -f - <
+
+
+ Next we need to update the environment variables used for the deployment. If you followed the [setup instructions for Kubernetes deployments](/self-hosting/deployment-options/kubernetes-helm), you should have a Kubernetes secret called `infisical-secrets`.
+ We need to update the secret with the following environment variables:
+
+ - `HSM_LIB_PATH` - The path to the HSM client library _(mapped to `/hsm-client/libs/64/libCryptoki2.so`)_
+ - `HSM_PIN` - The PIN for the HSM device that you created when setting up your Luna Cloud HSM client
+ - `HSM_SLOT` - The slot number for the HSM device that you selected when setting up your Luna Cloud HSM client
+ - `HSM_KEY_LABEL` - The label for the HSM key. If no key is found with the provided key label, the HSM will create a new key with the provided label.
+
+ The following is an example of the secret that you should update:
+
+ ```yaml
+ apiVersion: v1
+ kind: Secret
+ metadata:
+ name: infisical-secrets
+ type: Opaque
+ stringData:
+ # ... Other environment variables ...
+ HSM_LIB_PATH: "/hsm-client/libs/64/libCryptoki2.so" # If you followed this guide, this will be the path of the Luna Cloud HSM client
+ HSM_PIN: ""
+ HSM_SLOT: ""
+ HSM_KEY_LABEL: ""
+ ```
+
+ Save the file after updating the environment variables, and apply the secret changes
+
+ ```bash
+ kubectl apply -f ./secret-file-name.yaml
+ ```
+
+
+
+ After we've successfully configured the PVC and updated our environment variables, we are ready to update the deployment configuration so that the pods it creates can access the HSM client files.
+
+ We need to update the Docker image of the deployment to use `infisical/infisical-fips`. The `infisical/infisical-fips` image is a functionally identical image to the `infisical/infisical` image, but it is built with support for HSM encryption.
+
+ ```yaml
+ # ... The rest of the values.yaml file ...
+
+ image:
+ repository: infisical/infisical-fips # Very important: Must use "infisical/infisical-fips"
+ tag: "v0.117.1-postgres"
+ pullPolicy: IfNotPresent
+
+ extraVolumeMounts:
+ - name: hsm-data
+ mountPath: /hsm-client # The path we will mount the HSM client files to
+ subPath: ./hsm-client
+
+ extraVolumes:
+ - name: hsm-data
+ persistentVolumeClaim:
+ claimName: infisical-data-pvc # The PVC we created in the previous step
+
+ # ... The rest of the values.yaml file ...
+ ```
+
+
+
+
+
+ After updating the values.yaml file, you need to upgrade the Helm chart in order for the changes to take effect.
+
+ ```bash
+ helm upgrade --install infisical infisical-helm-charts/infisical-standalone --values /path/to/values.yaml
+ ```
+
+
+ After upgrading the Helm chart, you need to restart the deployment in order for the changes to take effect.
+
+ ```bash
+ kubectl rollout restart deployment/infisical-infisical
+ ```
+
+
+ After following these steps, your Kubernetes setup will be ready to use HSM encryption.
+
+
+
## Disabling HSM Encryption
To disable HSM encryption, navigate to Infisical's Server Admin Console and set the KMS encryption strategy to `Software-based Encryption`. This will revert the encryption strategy back to the default software-based encryption.