Installation

Prerequisites

In order to integrate your Primus HSM keys with the Akeyless Gateway, you need to meet the following requirements:

• An account on the Akeyless platform.
• A Primus HSM running firmware v3.1 or later, or a CloudHSM Partition.
• A license for the Primus PKCS#11 Provider, and the PKCS#11 API enabled on the HSM.

info

This guide assumes you have a running Akeyless platform instance and will only go over the details of the HSM integration.

Step 1: Install the Primus PKCS#11 Provider

First, install and configure the Primus PKCS#11 API provider on your host machine.

Later, we will mount the PKCS#11 provider into the Akeyless Gateway container. Alternatively, you can build your own Docker image that includes Akeyless Gateway as well as the Primus PKCS#11 Provider (not shown in this guide).

Step 2: Create a Customer Fragment Key

Create a new HMAC key. This is the 4th key that will protect your Akeyless secrets store. In the examples below, we will use akeyless-customer-fragment-key as the key name.

Securosys offers multiple ways to create this key:

REST

Create an HMAC key by calling the create /v1/key endpoint with the HMACSHA256 algorithm, as shown in this example.

PKCS#11

Use the pkcs11-tool:

pkcs11-tool --module /usr/local/primus/lib/libprimusP11.so \
            --login --pin <PKCS11 Password> \
            --keygen --key-type generic:32 \
            --label "akeyless-customer-fragment-key"

For more details, see the PKCS#11 tutorial.

Step 3: Create the Customer Fragment

Create a customer fragment using the Akeyless CLI:

akeyless gen-customer-fragment \
    --name "HSM_CF" \  # Name shown in the Akeyless UI
    --type hsm_secured \  # hsm_secured or hsm_wrapped
    --hsm-key-label "akeyless-customer-fragment-key"    # The key created in the previous step

This will create a file called customer_fragments.json. You need this in the next step.

Later, Akeyless will use the HMAC key stored in the HSM to derive the actual secret key using a KDF. The "customer fragment" created in this step is used as a seed for that KDF invocation.

For details, see the Akeyless documentation.

Step 4: Start the Akeyless Gateway

Next, you need to run the Akeyless Gateway. In this example, we will run a simple container locally with Docker:

docker run -d -p 8000:8000 -p 5696:5696 \
    # Replace with your Akeyless Gateway access id and access key
    -e GATEWAY_ACCESS_ID="p-xxxxxxxxxxxxxx" \
    -e GATEWAY_ACCESS_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=" \
    # Replace with your Securosys PKCS#11 password and partition name
    -e HSM_PIN="PKCS11_PASSWORD" \
    -e HSM_TOKEN_LABEL="PARTITION_NAME" \
    -e HSM_USE_RAND="true" \  # Instruct the Gateway to use the HSM as a randomness source
    -e PKCS11_LIB_PATH="/usr/local/primus/lib/libprimusP11.so" \
    # Mount your local Primus PKCS#11 Provider installation into the container
    -v /usr/local/primus/lib:/usr/local/primus/lib:ro \
    -v /etc/primus:/etc/primus:ro \
    # Mount the CF created in the previous step, to the container to be used by the Gateway 
    -v ./customer_fragments.json:/home/akeyless/.akeyless/customer_fragments.json:ro \
    --name akeyless-gw akeyless/base:latest-akeyless

This example assumes that you installed and configured the Primus PKCS#11 Provider locally, and mount it into the container.

info

Make sure that your file system permissions allow the Akeyless Gateway, running inside the container, can read the Primus PKCS#11 config files.

For a production setup, you need to deploy this container as a continuously running service. The Akeyless Gateway will interface between the Akeyless platform and your Primus HSM.

Note that this means you also need to mount (or otherwise include) the PKCS#11 Provider configuration in your production container.

For details, see the Akeyless HSM integration guide.

Step 5: Create a DFC Encryption Key

Finally, we will create a DFC Encryption Key and secure it using the customer fragment stored in the Primus HSM.

1. Open the Akeyless Gateway in a browser: http://localhost:8000
2. Go to the Zero Knowledge Encryption tab. There you will find the CF listed, showing that it is secured by an HSM:
3. Next, navigate to the Gateway Console: http://localhost:8000/console. Go to Items New Encryption Key DFC
4. Give the key a name and a description, and click "Next".
5. Chose a key type (e.g. AES256GCM) and select the customer fragment to be used:

You will see that the newly created encryption key is using Akeyless DFC and Zero Knowledge Encryption:

For more details on creating a DFC Encryption Key, see the Akeyless documentation.

Next steps

You are now able to use the DFC Encryption Key when creating keys, certificates, or other secrets on the Akeyless Gateway platform. Simply select the Securosys-DFC-Key in the "Protected Key" dropdown when creating a new secret: