Integrating with Thales Cloud HSM

The instructions on this page are for use with the Thales Data Protection on Demand (DPoD) service.

These instructions show how to run cascade-hsm-bridge (the tool Cascade uses to connect to PKCS#11 compatible Hardware Security Modules (HSMs)) inside a Docker container and connect to its listen port from a server or another Docker container.

Docker is not required to use Cascade or cascade-hsm-bridge. This example uses Docker because the Thales documentation describes how you can easily get PKCS#11 connectivity to a Thales Luna Cloud HSM working using Docker.

Warning

DPoD is not free. An initial free trial is available but thereafter it is a paid service.

Note

The PKCS#11 specific part of the instructions below is hopefully similar for any modern Thales HSM service whether PCI card, rack unit or cloud service, but we have no access to such HSMs and thus have only been able to test with DPoD.

Tip

When running cascade-hsm-bridge as a systemd service, i.e. not in a Docker container as this page describes, be aware that you will need to use the systemctl edit cascade-hsm-bridge command to set some extra systemd settings that the Thales Luna Cloud HSM PKCS#11 module needs.

[Service]
WorkingDirectory=/usr/local/dpodclient/libs/64
Environment="ChrystokiConfigurationPath=/usr/local/dpodclient"
MemoryDenyWriteExecute=no

Note

We are not Docker or Thales experts. Consult the Thales and Docker documentation and other authoritative sources to learn more.

Acquire the PKCS#11 Module

The first step to using a Thales HSM with Cascade, assuming that the HSM itself is already provisioned, is to acquire the Thales PKCS#11 module that contains the code needed to connect to a Thales Luna Cloud HSM.

Note

Thales HSMs are commercial products and Thales do not make their software developer kit, of which the PKCS#11 module is part, publically available. One version of it is however available via the free trial of the Thales Data Protection on Demand service which we will demonstrate here.

Login to the Thales DPoD portal. This step assumes you already have an account.
Via the Service tab add a Luna Cloud HSM service to your account.
Enter a name for your service.
(optional) Tick the “Remove FIPS restrictions” box. For our test we left the “Remove FIPS restrictions” box unticked.
Click the name of your new Luna Cloud HSM service on the Service tab.
Click the “New Service Client” button.
Give your service client a name when asked.
Click the “Create Service Client” button.
Click the “Download Client” button that appears.

This will download a ZIP archive called “setup-<YOUR_CLIENT_NAME>.zip.

Inside the zip are the files needed to connect to the Luna Cloud HSM using a PKCS#11 client like cascade-hsm-bridge, including client certificates to authenticate, a PKCS#11 module configuration file called Chrystoki.conf`, and a TAR archive containing the PKCS#11 module libs/64/libCryptoki2.so.

Testing the PKCS#11 Module

By this point you should in principle have everything needed to connect cascade-hsm-bridge or any other PKCS#11 client to the Luna Cloud HSM.

However, there are a lot of files in the downloaded service client ZIP and you’ll need to work out which ones you need and how to use them.

Thales provide a guide for using a Docker container to Access a Luna Cloud HSM Service. We use that guide here to demonstrate that Cascade works with the Thales Luna Cloud HSM.

Tip

The following Thales documentation pages are particularly relevant in the next steps:

Create a Docker Container to Access a Luna Cloud HSM Service

Initializing an Application Partition

Partition Roles

Initializing the Crypto Officer Role

Follow the steps below to confirm that you can connect via PKCS#11 to your DPoD Luna Cloud HSM instance.

Build a Docker image as described at Create a Docker Container to Access a Luna Cloud HSM Service.

Note

Replace FROM ubuntu:20.04 in the Docker instructions with FROM ubuntu:22.04.`

When following the instructions to build the Docker image, replace references to setup-myclient.zip with YOUR service client ZIP that you downloaded in step 9 above.

Assuming that you have built your Docker image according to the Thales instructions using your downloaded service client ZIP, run a container based on the image and use the Thales lunacm command to setup access to your Luna Cloud HSM:

Note

The docker command below has an additional --publish argument that is not present in the Thales documentation. This is needed to expose the cascade-hsm-bridge listen port outside the container so that you can connect to it from Cascade running on the host or inside another container.
```
$ docker run -it \
    --name luna \
    --publish 5696:5696 \
    --entrypoint=./bin/64/lunacm \
    myimage
lunacm:> partition init -label MyPartition -password mypartitionsopassword -domain mydomainname
lunacm:> role login -name po
lunacm:> role init -name co
lunacm:> role login -name co
lunacm:> role changepw -name co
```

To test our settings before we use cascade-hsm-bridge we can use the opensc pkcs11-tool program from another shell terminal:

$ docker exec -it luna /bin/bash
# apt update
# apt install -y opensc
# pkcs11-tool --module ./libs/64/libCryptoki2.so -I
Cryptoki version 2.20
Manufacturer     SafeNet
Library          Chrystoki                       (ver 10.9)
Using slot 3 with a present token (0x3)
# pkcs11-tool --module ./libs/64/libCryptoki2.so --login -O
Using slot 3 with a present token (0x3)
Logging in to "MyPartition".
Please enter User PIN: <THE PASSWORD YOU CHOSE IN STEP 11 ABOVE>

Now that that works we can install cascade-hsm-bridge.

Installing and Configuring cascade-hsm-bridge

Continuing from the same /bin/bash session inside the Docker container, follow the Installation steps to install cascade-hsm-bridge for Ubuntu 24.04, the base image used by our DPoD Docker container.

Note

The installation instructions use sudo but this does not usually exist inside a Docker container as typically one executes commands as root. Either remove sudo from any commands you copy-paste, or execute alias sudo= before copy-pasting commands that use sudo. This will ensure that the commands work as intended.

Next, edit the cascade-hsm-bridge configuration file to point it to the Thales Luna Cloud HSM PKCS#11 module, and to listen on all network IPv4 interfaces inside the Docker container:

$ sed -i -e 's|^lib_path =.\+|lib_path = "/usr/local/dpodclient/libs/64/libCryptoki2.so"|' /etc/cascade-hsm-bridge/config.toml
$ sed -i -e 's|addr = .\+|addr = "0.0.0.0"|' /etc/cascade-hsm-bridge/config.toml

Now run cascade-hsm-bridge and send its logs to the terminal so that we can easily verify that it loads the Thales PKCS#11 module correctly.

$ cascade-hsm-bridge -c /etc/cascade-hsm-bridge/config.toml --stderr
$ cat /tmp/cascade-hsm-bridge.log
[2025-10-03T20:48:37] [INFO] Loading and initializing PKCS#11 library /usr/local/dpodclient/libs/64/libCryptoki2.so
[2025-10-03T20:48:37] [INFO] Loaded SafeNet PKCS#11 library v10.9 supporting Cryptoki v2.20: Chrystoki
[2025-10-03T20:48:37] [WARN] Generating self-signed server identity certificate
[2025-10-03T20:48:37] [INFO] Listening on 127.0.0.1:5696`

Here we can see that the PKCS#11 module has been loaded correctly.

This does NOT show that cascade-hsm-bridge is able to connect to the Luna Cloud HSM, but the pkcs11-tool -O command we used above proved that the PKCS#11 module is able to connect and so cascade-hsm-bridge can as well. To demonstrate that, however, you will need to setup Cascade to use this running instance of kmip2pksc11.

Using cascade-hsm-bridge to connect Cascade to the Thales HSM

To learn how to use the cascade-hsm-bridge instance that you just setup with Cascade, visit the Hardware Security Modules (HSMs) page, but skip to the “Using cascade-hsm-bridge with Cascade” section as we have already setup cascade-hsm-bridge on port 5659.

If you have Cascade setup, the command to add the Thales HSM is:

$ cascade hsm add thales 127.0.0.1 \
    --insecure \
    --username MyPartition \
    --password <THE PASSWORD YOU CHOSE IN STEP 11 ABOVE>
[2025-10-03T21:43:43.486Z] INFO cascade::units::http_server: Writing to KMIP server file './kmip/thales
Added KMIP server 'cascade-hsm-bridge 0.1.0-alpha using PKCS#11 token with label MyPartition in slot Net Token Slot via library libCryptoki2.so'.

Note that the username is the PKCS#11 slot label, and the password is the password you chose in step 11 above when setting up the Luna Cloud HSM.

We can see from the output that Cascade made an initial test connection to the Thales HSM via cascade-hsm-bridge to query its identification strings.

For an example of how to associate the HSM with a Cascade policy and use it to sign a zone see the Integrating with SoftHSMv2 page.