HSM Integration - Infisical

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.Please reach out to sales@infisical.com if you have any questions.

Overview

Infisical KMS currently supports two encryption strategies:

Standard Encryption: This is the default encryption strategy used by Infisical KMS. It uses a software-protected encryption key to encrypt KMS keys within your Infisical instance. The root encryption key is defined by setting the ENCRYPTION_KEY environment variable.
Hardware Security Module (HSM): This encryption strategy uses a Hardware Security Module (HSM) to create a root encryption key that is stored on a physical device to encrypt the KMS keys within your instance.

Hardware Security Module (HSM)

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 protected from unauthorized access.

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.

Enabling HSM encryption has a set of key benefits:

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 the standard software-protected key.

Caveats

Performance: Using an HSM device can have a performance impact on your Infisical instance. This is due to the additional latency introduced by the HSM device. This is however only noticeable when your instance(s) start up or when the encryption strategy is changed.
Key Recovery: If the HSM device is lost or destroyed, you will no longer be able to decrypt your data stored within Infisical. Most HSM providers offer recovery options, which you should consider when setting up an HSM device.

Requirements

An HSM device (PKCS#11 compatible library) from a compatible provider such as Thales Luna HSM, AWS CloudHSM, Fortanix HSM, or others. Infisical is validated to work with PKCS#11 2.30 and newer. If your HSM device doesn’t follow the >=2.30 PKCS#11 standard you may see degraded performance.

Environment Variable Configuration

To configure your Infisical instance to use an HSM, you must set the required environment variables. Below you’ll find an example of the required environment variables. For further instructions on how to configure the HSM device for your Infisical instance, please see the Setup Instructions section.

HSM_LIB_PATH=/usr/local/lib/cloudhsm/cloudhsm.so
HSM_SLOT=1
HSM_KEY_LABEL=infisical-key
HSM_PIN=your:pin

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. If you are using Docker, make sure to set the HSM_LIB_PATH environment variable to the path where the library is mounted in the container.
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 typically between 0 and 5 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 here.

PKCS#11 Key Attributes

If no AES key or HMAC key already exists with the label you defined on the HSM_KEY_LABEL environment variable, then Infisical will create one for you automatically using the label specified on HSM_KEY_LABEL. Below you’ll find a list of the attributes each key will be created with.

AES Key

Bring your own key minimum requirements (optional)

If you bring your own AES key and don’t let Infisical create it for you it must have at least the following attributes:

CKA_CLASS: CKO_SECRET_KEY — Defines the key class (secret key).
CKA_KEY_TYPE: CKO_AES — Defines the key type (AES key).
CKA_VALUE_LEN: 32 — 256-bit key size.
CKA_ENCRYPT: true — Encryption capabilities enabled.
CKA_DECRYPT: true — Decryption capabilities enabled.
CKA_TOKEN: true — The key material will persist in your HSM so it can be reused.

Note that for security reasons it is highly recommended to create an AES key with the full set of key attributes seen below if you’re going to bring your own key.

CKA_CLASS: CKO_SECRET_KEY — Defines the key class (secret key).
CKA_KEY_TYPE: CKO_AES — Defines the key type (AES key).
CKA_VALUE_LEN: 32 — 256-bit key size.
CKA_LABEL: Your specified label in the HSM_KEY_LABEL environment variable.
CKA_ENCRYPT: true — Encryption capabilities enabled.
CKA_DECRYPT: true — Decryption capabilities enabled.
CKA_TOKEN: true — The key material will persist in your HSM so it can be reused.
CKA_EXTRACTABLE: false — The key material is not extractable from the HSM.
CKA_SENSITIVE: true — The key material is marked as sensitive.
CKA_PRIVATE: true — The key material is marked as private to the slot and can’t be accessed from other slots.

HMAC Key

Bring your own key minimum requirements (optional)

If you bring your own HMAC key and don’t let Infisical create it for you it must have at least the following attributes:

CKA_CLASS: CKO_SECRET_KEY — Defines the key class (secret key).
CKA_KEY_TYPE: CKO_GENERIC_SECRET — Defines the key class (generic secret key).
CKA_VALUE_LEN: 32 — 256-bit key size
CKA_SIGN: true — Signing capabilities enabled
CKA_VERIFY: true — Verifying capabilities enabled.
CKA_TOKEN: true — The key material will persist in your HSM so it can be reused.

Note that for security reasons it is highly recommended to create an HMAC key with the full set of key attributes seen below if you’re going to bring your own key.

CKA_CLASS: CKO_SECRET_KEY — Defines the key class (secret key).
CKA_KEY_TYPE: CKO_GENERIC_SECRET — Defines the key class (generic secret key).
CKA_VALUE_LEN: 32 — 256-bit key size.
CKA_LABEL: Your specified label in the HSM_KEY_LABEL environment variable, suffixed with _HMAC. If you specify infisical-key-v1, then the HMAC key label will become infisical-key-v1_HMAC.
CKA_SIGN: true — Signing capabilities enabled
CKA_VERIFY: true — Verifying capabilities enabled.
CKA_TOKEN: true — The key material will persist in your HSM so it can be reused.
CKA_EXTRACTABLE: false — The key material is not extractable from the HSM.
CKA_SENSITIVE: true — The key material is marked as sensitive.
CKA_PRIVATE: true — The key material is marked as private to the slot and can’t be accessed from other slots.

Setup Instructions

Setting up an HSM Device

To set up HSM encryption, you need to configure an HSM provider and HSM key. The HSM provider is used to connect to the HSM device, and the HSM key is used to encrypt Infisical’s KMS keys. We recommend using a Cloud HSM provider such as Thales Luna HSM, AWS CloudHSM, or Fortanix HSM.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 have a set of files that you can use to access the HSM. These files need to be present on the machine where Infisical is running. If you are using containers, you will need to mount the folder where these files are stored as a volume in the container.The setup process for an HSM device varies depending on the provider. We have created guides for Thales Luna Cloud HSM and Fortanix HSM, which you can find below.

Configure HSM on Infisical

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 section.

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. If you are using Docker, make sure to set the HSM_LIB_PATH environment variable to the path where the library is mounted in the container.
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 typically between 0 and 5 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 here.

Restart Instance

After setting up the HSM, you need to restart the Infisical instance for the changes to take effect.

Navigate to the Server Admin Console

Update the KMS Encryption Strategy to HSM

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.

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.

Using HSMs In Your Deployment

Docker
Kubernetes

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.

Thales Luna Cloud HSM
Fortanix HSM
AWS CloudHSM

Create HSM client folder

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.

  mkdir /etc/luna-docker

After setting up your Luna Cloud HSM client, 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.

  cp -r /<path-to-where-your-luna-client-is-located> /etc/luna-docker

Update Chrystoki.conf

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.An example config file will look like this:

    Chrystoki2 = {
      # This path points to the mounted path, /usr/safenet/lunaclient
      LibUNIX64 = /usr/safenet/lunaclient/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 = /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;
    }


    REST = {
      AppLogLevel = error
      ServerName = <REDACTED>;
      ServerPort = 443;
      AuthTokenConfigURI = <REDACTED>;
      AuthTokenClientId = <REDACTED>;
      AuthTokenClientSecret = <REDACTED>;
      RestClient = 1;
      ClientTimeoutSec = 120;
      ClientPoolSize = 32;
      ClientEofRetryCount = 15;
      ClientConnectRetryCount = 900;
      ClientConnectIntervalMs = 1000;
    }
    XTC = {
      Enabled = 1;
      TimeoutSec = 600;
    }

Save the file after updating the paths.

Run Docker

Running Docker with HSM encryption requires setting the HSM-related environment variables as mentioned previously in the HSM 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.

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="<your-hsm-device-pin>" \
  -e HSM_SLOT=<hsm-device-slot> \
  -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.

After following these steps, your Docker 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.

In order to disable HSM encryption, the Infisical instance must be able to access the HSM device. If the HSM device is no longer accessible, you will not be able to disable HSM encryption.

Infisical KMS

​Overview

​Hardware Security Module (HSM)

​Caveats

​Requirements

​Environment Variable Configuration

​PKCS#11 Key Attributes

​AES Key

​HMAC Key

​Setup Instructions

​Using HSMs In Your Deployment

​Disabling HSM Encryption

Overview

Hardware Security Module (HSM)

Caveats

Requirements

Environment Variable Configuration

PKCS#11 Key Attributes

AES Key

HMAC Key

Setup Instructions

Using HSMs In Your Deployment

Disabling HSM Encryption