HSM deployment runbook

​

Prerequisites

• DFNS account: An active DFNS organization with the HSM deployment model enabled. Contact our if this has not been configured.
• HSM hardware or service: A supported HSM, either physical (e.g. Thales Luna 7, Securosys Primus) or cloud-based (e.g. Thales Luna Cloud HSM, Securosys Primus CloudHSM, IBM HPCS, AWS CloudHSM). If using a physical HSM, it should be mounted and network-accessible.
• Host server: A server (physical or virtual) that can run the HSM Driver:
  • Network connectivity to the HSM (e.g. TCP port 1792 for Thales Luna).
  • Outbound HTTPS connectivity to the internet (to reach DFNS APIs).
  • A supported OS: Linux (x86_64) or Windows Server (x64).
  • Sufficient resources to run the HSM Driver process and a database instance.
• Database: A PostgreSQL instance (or equivalent supported database) accessible from the host server. This can be co-located on the same host or run separately. The database is required in the default sealed key-storage mode; in persistent mode keys live on the HSM partition and no database is used (see configuration).

​

Implementation steps

1

Provision the HSM

This step is your responsibility. To maintain clear separation of concerns, DFNS does not participate in HSM procurement, setup, key ceremony, or administration.For Cloud HSM, ensure you can perform key export (i.e. for Thales Cloud HSM select “Luna Cloud HSM with Key Export”).

1. Provision the HSM: For a physical HSM, get the appliance ready. For a cloud-based HSM (e.g. AWS CloudHSM, Azure Dedicated HSM), provision the cluster in your cloud account.
2. Initialize the HSM: Set Security Officer credentials, create an application partition, initialize it for PKCS#11, and set the Crypto Officer PIN.
3. Perform the key ceremony: What this involves depends on the HSM backend:
   • Most backends (Thales Luna standard partitions, Securosys Primus, IBM HPCS, AWS CloudHSM): you do not generate the wrapping key yourself. The HSM Driver automatically provisions an AES wrapping key inside the partition the first time it connects. Your ceremony consists of initializing the partition and setting the Security Officer and Crypto Officer credentials (for Thales, this includes the cloning domain used for replication).
   • Thales Luna with Scalable Key Storage (SKS) and on-prem IBM EP11: wallet keys are sealed to the partition’s internal master key, which is created when you initialize the partition.

Losing the wrapping key (or the partition master key it is sealed to) means losing access to all wallets and the assets they hold. Back up the partition as soon as the key exists — for auto-provisioned backends, that is after the HSM Driver’s first successful connection.

4. Connect the host server to the HSM: Establish a secure connection, including any required certificate exchange (e.g. NTLS for Thales Luna). For cloud-based HSMs, this typically involves VPC networking and the vendor’s client agent.

If using multiple HSMs for redundancy, all HSMs must share the same wrapping key (or partition master key). Consult your HSM vendor’s documentation for key replication or cloning procedures.

2

Provision the host server

Each HSM requires a dedicated host server running the HSM Driver. If you deploy multiple HSMs for redundancy, provision one host server per HSM.The HSM and its host server should be deployed in a physically secure, access-controlled environment (e.g. a private data center, a secured server room, or an equivalent cloud environment with strict network isolation).

1. Network connectivity:
   • The host must reach its paired HSM over the network via PKCS#11 (e.g. TCP 1792 for Thales Luna NTLS).
   • The host must have outbound HTTPS (TCP 443) access to the internet to reach DFNS APIs.
   • If your security policy requires it, configure firewall rules to restrict outbound traffic to DFNS API endpoints only.
2. Operating system: Install a supported Linux distribution (e.g. Ubuntu 22.04+, RHEL 8+) or Windows Server.
3. Database (sealed key-storage mode, the default): Set up a PostgreSQL instance accessible from all host servers. This can run on one of the hosts or on a dedicated database server. Ensure the database is backed up regularly. Skip this step if you deploy in persistent mode.

3

Obtain the HSM Driver from DFNS

Contact our to obtain the HSM Driver. It is available in the following formats:

• Docker container image: for containerized environments (Kubernetes, Docker Compose, ECS, etc.)
• Standalone binary: for bare-metal or VM deployments without container orchestration

DFNS will provide access to the appropriate artifact along with configuration documentation.

4

Obtain PKCS#11 library and configuration

HSM Driver needs to use HSM PKCS#11 library and its associated configuration file to communicate with the HSM.Contact HSM’s vendor to obtain the PKCS#11 library:

1. PKCS#11 library: download the PKCS#11 library from vendor’s support website
2. Generate configuration file: use vendor’s HSM tooling to generate configuration file (e.g. clientConfig for Thales Luna). The configuration file points to the right HSM and partition.

Library and configuration file are passed to HSM Driver as arguments.

5

Set up mTLS certificates

Communication between the HSM Driver and DFNS APIs is secured with mutual TLS (mTLS). The certificate setup is a collaborative process between you and DFNS.Detailed procedure:

1. DFNS provides a CSR template: DFNS sends you a Certificate Signing Request template specifying the required fields (subject, extensions, key usage, etc.).
2. You generate an intermediate certificate signing request: Using the CSR template, you generate a private key and create a signing request for an intermediate certificate.
3. You send the intermediate CSR to DFNS: DFNS reviews and signs the intermediate certificate, chaining it to the DFNS trust root.
4. DFNS returns the signed intermediate certificate: You now have a signed intermediate certificate that is trusted by the DFNS API.
5. You generate leaf certificates: For each HSM Driver instance, you generate a leaf certificate signed by your intermediate certificate. This allows you to independently add or rotate HSM Driver instances without involving DFNS each time.
6. Configure the HSM Driver: Install the leaf certificate, its private key, and the certificate chain on each HSM Driver host.

6

Configure and deploy the HSM Driver

1. ConfigurationThe HSM Driver is configured via environment variables or command line arguments. The following options are available:HSM backend settingsThe HSM Driver embeds the IBM, Thales, Securosys and AWS CloudHSM PKCS#11 libraries, so --vendor-target is usually not needed.

Option	Environment variable	Description
--vendor	HSM_VENDOR	HSM backend selector. One of: ibm-hpcs, ibm-ep11, thales-app-aes-key, thales-master-key (Luna SKS), securosys, aws-cloudhsm, softhsm (test only)
--vendor-target	HSM_VENDOR_TARGET	Path to the vendor’s PKCS#11 library, or the target HSM domain (e.g. 03.01) when --vendor=ibm-ep11. Optional for PKCS#11 vendors (defaults to the embedded library); required for ibm-ep11
--user-pin	USER_PIN	The Crypto Officer (or equivalent) PIN for PKCS#11 authentication
--user-pin-file	USER_PIN_FILE	Read the PIN from a file (e.g. a mounted Docker secret). Mutually exclusive with --user-pin
--key-storage-mode	HSM_KEY_STORAGE_MODE	sealed (default): keys are wrapped and stored in the database. persistent: keys reside on the HSM partition and no database is used
--wrapping-cbc	—	Force AES-CBC-PAD key wrapping instead of default AES-GCM (see key wrapping requirements)

Earlier driver versions were configured with per-vendor options (PKCS11_IBM_MODULE, PKCS11_THALES_MODULE, PKCS11_SECUROSYS_MODULE, EP11_IBM_TARGET_HSM). They still work but are deprecated and log a warning at startup — use --vendor and --vendor-target instead.

Database settings (sealed mode only)To store wrapped private keys, the database can be either a PostgreSQL or a SQLite. Do not configure a database in persistent mode — the driver refuses to start.

Option	Description	Example
--postgres-url	Connection string to the Postgres database	postgresql://user:pass@localhost:5432/hsm_keys
--sqlite-path	Absolute path to the database file	/local/database/sqlite.db

mTLS settings

Option	Description	Example
--client-cert	Path to the leaf certificate file (PEM).	/etc/hsm-driver/certs/leaf.pem
--client-key	Path to the leaf certificate private key (PEM).	/etc/hsm-driver/certs/leaf-key.pem
--ca-cert	Path to the certificate chain file (PEM), including the intermediate certificate.	/etc/hsm-driver/certs/chain.pem

DFNS API settings

Option	Description	Example
--proxy-addr	The DFNS Proxy endpoint to poll for requests.	hsm-proxy.dfns.io:8443
--corporate-proxy-addr	Address and port of an HTTP CONNECT corporate proxy to tunnel through, if your network requires one.	proxy.internal:3128

The full option reference for your driver version is provided with the HSM Driver delivery.

2. Deployment

• Container: Pull the Docker image and run it with the configuration and user pin mounted as file.

Docker compose files are provided with the HSM Driver delivery

• Binary: Place the binary on the host, provide the configuration, and run it (directly or as a systemd service).

3. VerificationOnce started, the HSM Driver will connect to the DFNS API over mTLS and begin polling for requests. You can verify the integration by creating a test wallet through the DFNS API and confirming it completes successfully.

7

Set up redundancy (recommended)

For production deployments, deploy at least two HSM Driver instances, each paired with an HSM (or connecting to an HSM cluster):

1. Ensure all HSMs share the same master key.
2. Ensure all HSM Drivers connect to the same database.
3. Generate a separate leaf mTLS certificate for each HSM Driver instance (signed by your intermediate certificate from step 4).
4. Start all HSM Driver instances. They will independently poll the DFNS API and automatically distribute the workload.

No load balancer or failover configuration is required. The queue-based pull model handles distribution and fault tolerance natively.

​

Key wrapping requirements

​

Responsibility matrix (RACI)

• R = Responsible (does the work)
• A = Accountable (owns the outcome)
• C = Consulted (provides input)
• I = Informed (kept up to date)

​

Backup and disaster recovery

• HSM master key is the most critical asset. Loss is unrecoverable.
• Wrapped-key database should be backed up regularly. Wallets created after the last backup are lost if the database fails.
• mTLS intermediate certificate private key is especially critical. Without it, you cannot generate new leaf certificates for additional or replacement HSM Drivers.

​

Security considerations

• mTLS authentication: All communication between the HSM Driver and DFNS APIs is encrypted and mutually authenticated. Only HSM Drivers with valid leaf certificates (chained to the DFNS-signed intermediate) can connect.
• Wrapped key encryption: Private keys stored in the database are encrypted with the HSM’s master key. They are unusable without access to an HSM holding that master key.
• No DFNS access to keys: DFNS never has access to the HSM, the master key, the wrapped keys, or the database. DFNS only sees public keys and signed payloads.
• Stateless HSM usage: Private keys exist in plaintext only inside the HSM during cryptographic operations, and are never persisted in the clear.
• Customer-controlled infrastructure: You retain full control over the HSM, host server, database, and network configuration.

​

Contact