HSM Integration

In any encryption system, the ability to generate pseudo-random numbers is crucial, particularly for tasks like creating encryption keys. Akeyless addresses this need by offering a solution that not only generates pseudo-random numbers, but also enhances overall data security by leveraging Hardware Security Modules (HSMs) to generate and securely store these pseudo-random numbers for encryption keys, ensuring maximum data security.

The integration of the Akeyless Gateway with an HSM utilizes the PKCS#11 protocol to provide a seamless solution. This integration can also be leveraged for the derivation of Zero-Knowledge Customer Fragments from the HSM to the Gateway, using the HKDF function - currently supporting Standalone Gateway deployments only.

📘

HSM Entropy

For setting the HSM to generate random numbers for the cryptographic operations, the HSM must support the C_GenerateRandom operation.

Prerequisites

• HSM configured to work with PKCS#11.

• An AES encryption key that supports the hmac 256 mechanism (Relevant for Customer Fragment )

HSM Configuration

To configure the Gateway to work with your HSM, add the following parameters as part of the deployment:

Shell

docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 \
-e ADMIN_ACCESS_ID="p-xxxxxxx" \
-e HSM_PIN="<HSM PIN>" \
-e HSM_SLOT="<Slot Number>" \
-e HSM_USE_RAND="true" \
-e PKCS11_LIB_PATH="/opt/cloudhsm/lib/libcloudhsm_pkcs11.so" \
-v /opt/cloudhsm:/opt/cloudhsm \
--name akeyless-gw akeyless/base:latest-akeyless

Where:

• HSM_PIN - The HSM PIN for login, for example: a user:pass or wwwww-xxxx-yyyy-zzzz.

• HSM_SLOT - The slot number to use within the HSM that holds cryptographic objects.

• HSM_USE_RAND - Boolean flag, setting this to true will direct the Gateway to get the entropy randomness of the pseudo-random numbers from the HSM.

• PKCS11_LIB_PATH - The path to a PKCS#11 library file which should be mounted to the container filesystem. Must be a fixed path and imported along with the entire folder, since it contains configuration information. In our example, the source folder /opt/cloudhsm is mounted completely with all subdirectories.

Customer Fragments

To derive the Customer Fragment into the Gateway from the HSM, generate the Customer Fragment using the following command:

Shell

akeyless gen-customer-fragment \
--name HSM_CF \
--type <hsm_wrapped|hsm_secured> \
--hsm-key-label <"akeyless_hsm">

Where:

• name: Customer Fragment name.

• type: The HSM mode for the Customer Framgent either:

  • hsm_wrapped: On startup, the Gateway will establish a connection to the HSM. During the first time, it will store the Customer Fragment inside the HSM, and upon any future startups - the fragment will be derived from the HSM and will be stored in the Gateway's memory for use.

  • hsm_secured: On startup, the Gateway will establish a connection to the HSM. The Customer Fragment is derived from the HSM during any operation, which means that the fragment will not be saved in the Gateway's memory.

• hsm-key-label: The label of the key inside the HSM.

Save the output in a new file called customer_fragments.json in a directory of your choice. Once you have your customer_fragments.json file saved, you'll need to provide a path to the file containing your fragment as part of the Gateway installation command, as described in this guide.