diff --git a/backend/src/ee/services/hsm/hsm-fns.ts b/backend/src/ee/services/hsm/hsm-fns.ts index 8eec7ceb7..54c2f5f23 100644 --- a/backend/src/ee/services/hsm/hsm-fns.ts +++ b/backend/src/ee/services/hsm/hsm-fns.ts @@ -25,7 +25,7 @@ export const initializeHsmModule = (envConfig: Pick # Replace with the version you want to use + infisical/infisical: # Replace with the version you want to use ``` We recommend reading further about [using Infisical with Docker](/self-hosting/deployment-options/standalone-infisical). @@ -309,7 +308,7 @@ Enabling HSM encryption has a set of key benefits: -e DB_CONNECTION_URI="<>" \ -e REDIS_URL="<>" \ -e SITE_URL="<>" \ - infisical/infisical-fips: # Replace with the version you want to use + infisical/infisical: # Replace with the version you want to use ``` @@ -319,6 +318,192 @@ Enabling HSM encryption has a set of key benefits: After following these steps, your Docker setup will be ready to use Fortanix HSM encryption. + + + + + + ### Prerequisites + + - An [activated AWS CloudHSM cluster](https://docs.aws.amazon.com/cloudhsm/latest/userguide/activate-cluster.html) with at least 1 HSM device. + - A [HSM user with the `Crypto User` role](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-create.html). In this guide we are using a user with the username `testUser` and the password `testPassword`. + + + + + + Before using the CloudHSM client, it must be configured properly so Infisical can use it for cryptographic operations. + + + **1. Download the AWS CloudHSM client** + + You can download the AWS CloudHSM client from [the AWS documentation](https://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-library-install.html). + + + Note that the AWS CloudHSM client is only available for Linux and Windows. + If you're on a different operating system, you'll need to access a Linux machine to configure the client, such as an AWS EC2 Debian instance. + + + **2. Configure the CloudHSM client** + + After installing the CloudHSM client, you should see all related files in the `/opt/cloudhsm/` directory on your machine. + + You need to run the `configure-pkcs11` binary which will configure the client to connect with your AWS CloudHSM cluster. Depending on if you have multiple HSM's inside your cluster, you'll need to run the command with different arguments. Below you'll find the appropriate command for your use case: + + + + + + ```bash + sudo /opt/cloudhsm/bin/configure-pkcs11 -a --disable-key-availability-check + ``` + + + To use a single HSM, you must first manage client key durability settings by setting `disable_key_availability_check` to true by passing the `--disable-key-availability-check` flag. For more information read the [Key Synchronization](https://docs.aws.amazon.com/cloudhsm/latest/userguide/manage-key-sync.html) section in the AWS CloudHSM documentation. + + + + + ```bash + sudo /opt/cloudhsm/bin/configure-pkcs11 -a ... --disable-key-availability-check + ``` + + + + At this point it is assumed that you have: + 1. [Activated the CloudHSM cluster](https://docs.aws.amazon.com/cloudhsm/latest/userguide/activate-cluster.html) + 2. [Created a Crypto User HSM user](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-create.html) + 3. Downloaded and configured the CloudHSM client as described in the previous steps. + + **3. Download the configured HSM client files** + + After configuring the CloudHSM client, you should notice that the PKCS11 configuration file has been updated to include the HSM's ENI IP address. You can find this file in the `/opt/cloudhsm/etc/cloudhsm-pkcs11.cfg` directory, and it should look like this: + + ```json cloudhsm-pkcs11.cfg + { + "clusters": [ + { + "type": "hsm1", + "cluster": { + // Your issuing CA certificate. + // As per AWS documentation, this defaults to `/opt/cloudhsm/etc/customerCA.crt`. + "hsm_ca_file": "/opt/cloudhsm/etc/customerCA.crt", + "servers": [ + { + "hostname": "", + "port": 2223, + "enable": true + }, + { + "hostname": "", + "port": 2223, + "enable": true + } + ], + // Only relevant if you passed the --disable-key-availability-check flag + "options": { + "disable_key_availability_check": true + } + } + } + ], + "logging": { + "log_type": "file", + "log_file": "/opt/cloudhsm/run/cloudhsm-pkcs11.log", + "log_level": "info", + "log_interval": "daily" + } + } + ``` + + Save the entire `/opt/cloudhsm` folder, as you will need to mount this to your Infisical Docker container in the later steps. In this guide we will be saving all the files from the folder as `/etc/cloudhsm` and mounting it to the `/etc/cloudhsm` directory in the Docker container. + + + + + On the same machine that you configured the CloudHSM client, you can use `pkcs11-tool` to find the HSM slot number and to verify that the client is working correctly. + + First, install the `pkcs11-tool` package: + + ```bash + sudo apt-get install opensc -y + ``` + + Then, run the following command to find the HSM slot number: + + ```bash + pkcs11-tool --module /opt/cloudhsm/lib/libcloudhsm_pkcs11.so --list-slots --login + ``` + + It'll prompt you to log in with your PIN, which is your username and password seperated by a colon. Example: `testUser:testPassword`. + + This will output the HSM slot number like so: + + ```bash + ubuntu@ec-2:~$ pkcs11-tool --module /opt/cloudhsm/lib/libcloudhsm_pkcs11.so --list-slots + Available slots: + Slot 0 (0x2000000000000001): hsm1 + token label : hsm1 + token manufacturer : Marvell Semiconductors, Inc. + token model : LS2 + token flags : login required, rng, token initialized + hardware version : 66.48 + firmware version : 10.2 + serial num : + pin min/max : 8/32 + ``` + + In this case we see that the HSM has a slot in the position of `0`. This slot number will be used in the later steps to set the `HSM_SLOT` environment variable. + + + + When you initialized your HSM, you were prompted to download the cluster CSR and sign it. + In order to use the HSM with Infisical, you need to obtain the issuer CA certificate that was used to sign the cluster CSR. + + If you followed [the official AWS documentation](https://docs.aws.amazon.com/cloudhsm/latest/userguide/initialize-cluster.html), you should have a CA certificate called `customerCA.crt`. + + Save the CA certificate to a path, as this will need to be mounted as a Docker volume in the next step. For this example, we'll save it to `/aws-files/customerCA.crt`. + + + + 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. + + + 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 \ + + # Mount the HSM client files to "/opt/cloudhsm" + -v /etc/cloudhsm:/opt/cloudhsm \ + # Mount the issuer CA certificate to "/opt/cloudhsm/etc/customerCA.crt" + -v /aws-files/customerCA.crt:/opt/cloudhsm/etc/customerCA.crt \ + + # Set the HSM library path to whats expected within Docker (/opt/cloudhsm/lib/libcloudhsm_pkcs11.so) + -e HSM_LIB_PATH="/opt/cloudhsm/lib/libcloudhsm_pkcs11.so" \ + # Set the HSM PIN to the username and password of the HSM user, seperated by a colon + -e HSM_PIN=CryptoUserUsername:CryptoUserPassword \ + # Set the HSM slot number to the slot number of the HSM device as found in the previous step + -e HSM_SLOT= \ + # Set the HSM key label to a label that will be used to identify the encryption key in the HSM. This key label does not need to exist before hand. + -e HSM_KEY_LABEL=infisical-crypto-key \ + + # The rest of your environment variables ... + # -e ... + infisical/infisical: # Replace with the version you want to use + ``` + + 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. + + @@ -326,6 +511,7 @@ Enabling HSM encryption has a set of key benefits: + 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. @@ -591,13 +777,11 @@ Enabling HSM encryption has a set of key benefits: 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 HSM support. - ```yaml # ... The rest of the values.yaml file ... image: - repository: infisical/infisical-fips # Very important: Must use "infisical/infisical-fips" + repository: infisical/infisical tag: "v0.117.1-postgres" pullPolicy: IfNotPresent @@ -757,13 +941,13 @@ Enabling HSM encryption has a set of key benefits: - Update your Helm values to use the FIPS-compliant image and mount the Fortanix HSM files: + Update your Helm values to mount the Fortanix HSM files: ```yaml # ... The rest of the values.yaml file ... image: - repository: infisical/infisical-fips # Must use "infisical/infisical-fips" + repository: infisical/infisical tag: "v0.117.1-postgres" pullPolicy: IfNotPresent @@ -800,6 +984,314 @@ Enabling HSM encryption has a set of key benefits: After following these steps, your Kubernetes setup will be ready to use Fortanix HSM encryption. + + + + ### Prerequisites + + - An [activated AWS CloudHSM cluster](https://docs.aws.amazon.com/cloudhsm/latest/userguide/activate-cluster.html) with at least 1 HSM device. + - A [HSM user with the `Crypto User` role](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-create.html). In this guide we are using a user with the username `testUser` and the password `testPassword`. + - A Kubernetes cluster + + + AWS CloudHSM is 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. + + + + + + Before using the CloudHSM client with Kubernetes, it must be configured properly so Infisical can use it for cryptographic operations. + + **1. Download and configure the AWS CloudHSM client** + + You can download the AWS CloudHSM client from [the AWS documentation](https://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-library-install.html). + + + Note that the AWS CloudHSM client is only available for Linux and Windows. + If you're on a different operating system, you'll need to access a Linux machine to configure the client, such as an AWS EC2 Debian instance. + + + After installing the CloudHSM client, you should see all related files in the `/opt/cloudhsm/` directory on your machine. + + You need to run the `configure-pkcs11` binary which will configure the client to connect with your AWS CloudHSM cluster. Depending on if you have multiple HSM's inside your cluster, you'll need to run the command with different arguments. Below you'll find the appropriate command for your use case: + + + + + ```bash + sudo /opt/cloudhsm/bin/configure-pkcs11 -a --disable-key-availability-check + ``` + + + To use a single HSM, you must first manage client key durability settings by setting `disable_key_availability_check` to true by passing the `--disable-key-availability-check` flag. For more information read the [Key Synchronization](https://docs.aws.amazon.com/cloudhsm/latest/userguide/manage-key-sync.html) section in the AWS CloudHSM documentation. + + + + + ```bash + sudo /opt/cloudhsm/bin/configure-pkcs11 -a ... --disable-key-availability-check + ``` + + + + At this point it is assumed that you have: + 1. [Activated the CloudHSM cluster](https://docs.aws.amazon.com/cloudhsm/latest/userguide/activate-cluster.html) + 2. [Created a Crypto User HSM user](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-create.html) + 3. Downloaded and configured the CloudHSM client as described in the previous steps. + + **2. Verify the configuration file** + + After configuring the CloudHSM client, you should notice that the PKCS11 configuration file has been updated to include the HSM's ENI IP address. You can find this file in the `/opt/cloudhsm/etc/cloudhsm-pkcs11.cfg` directory, and it should look like this: + + ```json cloudhsm-pkcs11.cfg + { + "clusters": [ + { + "type": "hsm1", + "cluster": { + // Your issuing CA certificate. + // As per AWS documentation, this defaults to `/opt/cloudhsm/etc/customerCA.crt`. + "hsm_ca_file": "/opt/cloudhsm/etc/customerCA.crt", + "servers": [ + { + "hostname": "", + "port": 2223, + "enable": true + }, + { + "hostname": "", + "port": 2223, + "enable": true + } + ], + // Only relevant if you passed the --disable-key-availability-check flag + "options": { + "disable_key_availability_check": true + } + } + } + ], + "logging": { + "log_type": "file", + "log_file": "/opt/cloudhsm/run/cloudhsm-pkcs11.log", + "log_level": "info", + "log_interval": "daily" + } + } + ``` + + **3. Copy the CloudHSM client files to a staging directory** + + Create a directory to stage the CloudHSM client files for Kubernetes: + + ```bash + mkdir -p /etc/cloudhsm-k8s + ``` + + Copy the entire `/opt/cloudhsm` directory to your staging location: + + ```bash + cp -r /opt/cloudhsm/* /etc/cloudhsm-k8s/ + ``` + + Ensure the configuration file paths are correct. The `cloudhsm-pkcs11.cfg` file should reference `/opt/cloudhsm/etc/customerCA.crt` as shown above, since this is where files will be mounted inside the Kubernetes container. + + + + + On the same machine that you configured the CloudHSM client, you can use `pkcs11-tool` to find the HSM slot number and to verify that the client is working correctly. + + First, install the `pkcs11-tool` package: + + ```bash + sudo apt-get install opensc -y + ``` + + Then, run the following command to find the HSM slot number: + + ```bash + pkcs11-tool --module /opt/cloudhsm/lib/libcloudhsm_pkcs11.so --list-slots --login + ``` + + It'll prompt you to log in with your PIN, which is your username and password separated by a colon. Example: `testUser:testPassword`. + + This will output the HSM slot number like so: + + ```bash + ubuntu@ec-2:~$ pkcs11-tool --module /opt/cloudhsm/lib/libcloudhsm_pkcs11.so --list-slots + Available slots: + Slot 0 (0x2000000000000001): hsm1 + token label : hsm1 + token manufacturer : Marvell Semiconductors, Inc. + token model : LS2 + token flags : login required, rng, token initialized + hardware version : 66.48 + firmware version : 10.2 + serial num : + pin min/max : 8/32 + ``` + + In this case we see that the HSM has a slot in the position of `0`. This slot number will be used in the later steps to set the `HSM_SLOT` environment variable. + + + + When you initialized your HSM, you were prompted to download the cluster CSR and sign it. + In order to use the HSM with Infisical, you need to obtain the issuer CA certificate that was used to sign the cluster CSR. + + If you followed [the official AWS documentation](https://docs.aws.amazon.com/cloudhsm/latest/userguide/initialize-cluster.html), you should have a CA certificate called `customerCA.crt`. + + Copy the CA certificate to your staging directory: + + ```bash + cp /path/to/customerCA.crt /etc/cloudhsm-k8s/etc/customerCA.crt + ``` + + Ensure the file is at `/etc/cloudhsm-k8s/etc/customerCA.crt` as this is what the configuration file expects. + + + + 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 CloudHSM PKCS#11 library _(mapped to `/opt/cloudhsm/lib/libcloudhsm_pkcs11.so`)_ + - `HSM_PIN` - The PIN for the HSM device, which is the username and password of your Crypto User separated by a colon (e.g., `testUser:testPassword`) + - `HSM_SLOT` - The slot number for the HSM device that you found in the previous step + - `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: "/opt/cloudhsm/lib/libcloudhsm_pkcs11.so" + HSM_PIN: "testUser:testPassword" # Replace with your actual Crypto User credentials + HSM_SLOT: "0" # Replace with your actual slot number + HSM_KEY_LABEL: "infisical-crypto-key" + ``` + + 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. + + ```yaml + # ... The rest of the values.yaml file ... + + image: + repository: infisical/infisical + tag: "v0.117.1-postgres" + pullPolicy: IfNotPresent + + extraVolumeMounts: + - name: cloudhsm-data + mountPath: /opt/cloudhsm # The path we will mount the HSM client files to + + extraVolumes: + - name: cloudhsm-data + persistentVolumeClaim: + claimName: cloudhsm-data-pvc # The PVC we created in the previous step + + # ... The rest of the values.yaml file ... + ``` + + + Ensure that the configuration file at `/opt/cloudhsm/etc/cloudhsm-pkcs11.cfg` references the correct path for the issuer CA certificate (`/opt/cloudhsm/etc/customerCA.crt`). This should already be configured correctly if you followed the previous steps. + + + + + + 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 AWS CloudHSM encryption. +