HSM deployment runbook

Documentation Index

Fetch the complete documentation index at: https://docs.dfns.co/llms.txt

Use this file to discover all available pages before exploring further.

​

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 PKCS#11-compatible HSM, either physical (e.g. Thales Luna 7, Utimaco CryptoServer, Securosys Primus) or cloud-based (e.g. AWS CloudHSM, Azure Dedicated HSM). 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.

​

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.

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: Generate the master key (also called a wrapping key) within the partition. This key is used to encrypt all wallet private keys.

Losing the master key means losing access to all wallets and the assets they hold. Back it up immediately after generation.

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 master key. Consult your HSM vendor’s documentation for master 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: 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.

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:PKCS#11 settingsThe HSM Driver already embeds IBM and Thales PKCS#11 libraries.

Option	Description	Value
PKCS11_IBM_MODULE	Absolute path to the IBM HPCS (cloud) PKCS#11 library	/usr/local/lib/pkcs11-grep11-amd64.so
PKCS11_THALES_MODULE	Absolute path to the Thales Luna PKCS#11 library	/usr/local/lib/libCryptoki2.so
USER_PIN	The Crypto Officer (or equivalent) PIN for PKCS#11 authentication	(use a secrets manager)

EP11 settings (specific to on-prem IBM HSM)This option conflicts with PKCS#11 settings above.

Option	Description	Value
EP11_IBM_TARGET_HSM	Domain of the HSM	03.01

Database settingsTo store wrapped private keys, the database could be either a PostgreSQL or a SQLite.

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

Exact option names and formats will be provided with the HSM Driver delivery. The above is representative of what to expect.

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.

​

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