docs: hardware security module

docs/documentation/platform/kms/encryption-strategies.mdx

@@ -0,0 +1,171 @@
+---
+title: "Encryption Strategies"
+description: "Learn more about the encryption strategies used by Infisical KMS."
+---
+
+<Note>
+  Changing the encryption strategy for your instance is an Enterprise-only feature.
+  This section is intended for users who have obtained an Enterprise license and are on-premise.
+</Note>
+
+## Overview
+
+Infisical KMS currently supports two encryption strategies.
+1. **Regular Encryption**: This is the default encryption strategy used by Infisical KMS. It uses a root encryption key to encrypt all the data. The root encryption key is defined by setting the `ENCRYPTION_KEY` environment variable.
+2. **Hardware Security Module (HSM)**: This encryption strategy uses a Hardware Security Module (HSM) to create a root encryption key, which is used to encrypt the KMS keys.
+
+
+## Hardware Security Module (HSM)
+
+![HSM Illustration](/images/platform/kms/hsm/hsm-illustration.png)
+
+Using a hardware security module comes with the added benefit of having a secure and tamper-proof device to store your encryption keys. This ensures that your data is secure and protected from unauthorized access.
+
+<Warning>
+  All encryption keys used for cryptographic operations are stored within the HSM. This means that if the HSM is lost or destroyed, you will no longer be able to decrypt your data stored within Infisical. Most providers offer recovery options for HSM devices, which you should consider when setting up an HSM device.
+</Warning>
+
+Enabling HSM encryption has has a set of key benefits:
+1. **Root Key Wrapping**: The root KMS encryption key that is used to secure your Infisical instance, will be encrypted using the HSM device rather than encrypting with a software key.
+2. **FIPS 140-2/3 Compliance**: Using an HSM device ensures that your Infisical instance is FIPS 140-2 or FIPS 140-3 compliant. For FIPS 140-3, ensure that your HSM is FIPS 140-3 validated.
+
+### Requirements
+- Infisical instance with version that is equal to or greater than `v0.91.0`. 
+- HSM device from a provider such as [Thales Luna HSM](https://cpl.thalesgroup.com/encryption/data-protection-on-demand/services/luna-cloud-hsm), [AWS CloudHSM](https://aws.amazon.com/cloudhsm/), or others.
+
+
+### FIPS Compliance
+FIPS, also known as the Federal Information Processing Standard, is a set of standards that are used to accredit cryptographic modules. FIPS 140-2 and FIPS 140-3 are the two most common standards used for cryptographic modules. If your HSM uses FIPS 140-3 validated hardware, Infisical will automatically be FIPS 140-3 compliant. If your HSM uses FIPS 140-2 validated hardware, Infisical will be FIPS 140-2 compliant.
+
+HSM devices are especially useful for organizations that operate in regulated industries such as healthcare, finance, and government, where data security and compliance are of utmost importance.
+
+For organizations that work with US goverment agencies, FIPS compliance is almost always a requirement when dealing with sensitive information. FIPS compliance ensures that the cryptographic modules used by the organization meet the security requirements set by the US government.
+
+## Setup Instructions
+<Tabs>
+    <Tab title="Regular Encryption">
+        <Note>
+            Regular Encryption is the default encryption strategy used by Infisical KMS.
+        </Note>
+        <Steps>
+            <Step title="Setting up Regular Encryption">
+                To set up regular encryption, you need to define the `ENCRYPTION_KEY` environment variable. This key is used to encrypt all the data in Infisical KMS.
+
+                If this is not set correctly, your Infisical instance will not be able to start. You can read more about the [default instance configurations](/self-hosting/configuration/envars) here.
+            </Step>
+        </Steps>
+    </Tab>
+    <Tab title="Hardware Security Module (HSM)">
+        <Warning>
+            HSM Encryption is an Enterprise-only feature.
+        </Warning>
+        <Steps>
+            <Step title="Setting up an HSM Device">
+                To set up HSM encryption, you need to configure the HSM provider and the HSM key. The HSM provider is used to connect to the HSM device, and the HSM key is used to encrypt the KMS keys. We recommend using a Cloud HSM provider such as [Thales Luna HSM](https://cpl.thalesgroup.com/encryption/data-protection-on-demand/services/luna-cloud-hsm) or [AWS CloudHSM](https://aws.amazon.com/cloudhsm/).
+
+                You need to follow the instructions provided by the HSM provider to set up the HSM device. Once the HSM device is set up, the HSM device can be used within Infisical.
+
+                After setting up the HSM from your provider, you will be given a PKCS#11 library that will be used to interface with the HSM. This library should be placed in a secure location on the same machine as the Infisical instance(s).
+            </Step>
+            <Step title="Configure HSM on Infisical">
+                Configuring the HSM on Infisical requires setting a set of environment variables.
+                - `HSM_LIB_PATH`: The path to the PKCS#11 library provided by the HSM provider. This usually comes in the form of a `.so` for Linux and MacOS, or a `.dll` file for Windows. For Docker, you need to mount the library path as a volume. Further instructions can be found below.
+                - `HSM_PIN`: The PKCS#11 PIN to use for authentication with the HSM device.
+                - `HSM_SLOT`: The slot number to use for the HSM device. This is usually `0` for most HSM devices.
+                - `HSM_KEY_LABEL`: The label of the key to use for encryption. **Please note that if no key is found with the provided label, the HSM will create a new key with the provided label.**
+
+                You can read more about the [default instance configurations](/self-hosting/configuration/envars) here.
+            </Step>
+
+            <Step title="Restart Instance">
+                After setting up the HSM, you need to restart the Infisical instance for the changes to take effect.
+            </Step>
+
+            <Step title="Set encryption strategy to HSM">
+                After restarting the Infisical instance, you need to navigate to your Infisical Console, and head into the Server Admin Console. In the Server Admin Console, open the Encryption section, and set the KMS encryption strategy to HSM.
+
+                <Steps>
+                    <Step title="Navigate to admin console">
+                        ![Server Admin Console](/images/platform/kms/hsm/server-admin-console.png)
+                    </Step>
+                    <Step title="Update encryption strategy">
+                        ![Set Encryption Strategy](/images/platform/kms/hsm/encryption-strategy.png)
+
+                        Once you press the 'Save' button, your Infisical instance will immediately switch to the HSM encryption strategy. This will re-encrypt your KMS key with keys from the HSM device.
+                    </Step>
+                </Steps>
+            </Step>
+
+            <Step title="Verify Encryption Strategy">
+                To verify that the HSM was correctly configured, you can try creating a new secret in one of your projects. If the secret is created successfully, the HSM is now being used for encryption.
+            </Step>
+        </Steps>
+    </Tab>
+</Tabs>
+
+## Attaching HSM to Docker
+<Tabs>
+  <Tab title="Docker">
+    To use HSM encryption with Docker, you need to mount the path of the HSM library as a volume. This is required because the HSM library needs to be accessible by the Infisical instance.
+
+    To use the HSM with Docker, follow these steps:
+    <Steps>
+      <Step title="Create HSM folder">
+        When using Docker, you are able to set your HSM library path to any location on your machine. We recommend creating a folder called `/opt/infisical-hsm`, and placing your HSM library file in this folder. This guide will assume that you have placed your HSM library file in this folder.
+      </Step>
+      <Step title="Run Docker">
+        Running Docker with HSM encryption requires setting the HSM-related environment variables like 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.
+
+        ```bash
+        docker run -p 80:8080 \
+          -v /opt/infisical-hsm:/opt/infisical-hsm \
+          -e HSM_LIB_PATH="/opt/infisical-hsm/<your-library-file-name.so>" \
+          -e HSM_PIN="<your-hsm-device-pin>" \
+          -e HSM_SLOT=0 \
+          -e HSM_KEY_LABEL="<your-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:<version> # Replace <version> with the version you want to use
+        ```
+
+        We recommend reading further about [using Infisical with Docker](/self-hosting/deployment-options/standalone-infisical).
+
+      </Step>
+    </Steps>
+    After following these steps, your Docker setup will be ready to use HSM encryption.
+  </Tab>
+  <Tab title="Docker Compose">
+    Using HSM encryption with a Docker Compose setup requires mounting the HSM library path as a volume. For this purpose we have created a seperate Docker Compose file that you need to use if you want to use HSM's with Infisical.
+
+    The setup process is mostly identical to the [Non-HSM Docker Compose setup](/self-hosting/deployment-options/docker-compose), with the only difference being that you need to use the `docker-compose.hsm.prod.yml` file instead of the `docker-compose.prod.yml` file.
+
+    To use the HSM with Docker Compose, follow these steps:
+    <Steps>
+      <Step title="Create HSM folder">
+        When using Docker Compose, it's required to follow a predefined folder structure.
+        Create a folder called `/opt/infisical-hsm`, and place your HSM library file in this folder.
+      </Step>
+      <Step title="Set `HSM_LIB_PATH` environment variable">
+        Set your environment variable `HSM_LIB_PATH` to `/opt/infisical-hsm/<YOUR_LIBARY_FILE_NAME>.so/dll`, where `<YOUR_LIBARY_FILE_NAME>` is the name of your HSM library file.
+      </Step>
+      <Step title="Start Docker Compose">
+        Start your Infisical instance with Docker Compose.
+
+        `docker-compose -f docker-compose.hsm.prod.yml up`
+      </Step>
+    </Steps>
+    After following these steps, your Docker Compose setup will be ready to use HSM encryption.
+  </Tab>
+</Tabs>
+
+## Disabling HSM Encryption
+
+If you for whatever reason wish to move away from using HSM encryption, you can disable it very easily. To disable HSM encryption, you need to go to your Infisical Console, and head into the Server Admin Console.
+In the Server Admin Console, open the Encryption section, and set the KMS encryption strategy to Regular Encryption.

docs/documentation/platform/kms/overview.mdx

@@ -8,6 +8,10 @@ description: "Learn how to manage and use cryptographic keys with Infisical."
 
 Infisical can be used as a Key Management System (KMS), referred to as Infisical KMS, to centralize management of keys to be used for cryptographic operations like encryption/decryption.
 
+By default your Infisical data such as projects and the data within them are encrypted at rest using Infisical's own KMS. This ensures that your data is secure and protected from unauthorized access.
+
+If you are on-premise, your KMS root key will be created at random with the `ROOT_ENCRYPTION_KEY` environment variable. You can also use a Hardware Security Module (HSM), to create the root key. Read more about [HSM](/docs/documentation/platform/kms/encryption-strategies). 
+
 <Note>
   Keys managed in KMS are not extractable from the platform. Additionally, data
   is never stored when performing cryptographic operations.

docs/mint.json

@@ -118,6 +118,7 @@
           "group": "Key Management (KMS)",
           "pages": [
             "documentation/platform/kms/overview",
+            "documentation/platform/kms/encryption-strategies",
             "documentation/platform/kms/kubernetes-encryption"
           ]
         },