Skip to main content

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.

Dfns supports Hardware Security Modules (HSMs) as an alternative to MPC for securing wallet keys. By leveraging an HSM, your cryptographic keys are generated and protected within tamper-resistant hardware that you own and operate. The HSM integration is seamless: all Dfns APIs, SDKs, policies, and features work identically regardless of the underlying key storage. Once the HSM is deployed, no changes are required to your integration.
HSM on-premise architecture

​
Architecture

The HSM deployment consists of four components running in your infrastructure:
ComponentDescription
HSMA Hardware Security Module that you procure and manage. It performs cryptographic operations and protects the master key. Any HSM supporting PKCS#11 is compatible.
Host serverThe machine running the HSM Driver and database. It must have network connectivity to both the internet (to reach Dfns APIs) and the HSM.
HSM DriverSoftware provided by Dfns that bridges the Dfns API and the HSM. It polls the API for key generation and signing requests, and translates them into PKCS#11 commands.
DatabaseStores wrapped (encrypted) keys. Private keys are not stored inside the HSM. The HSM only holds the master key used to wrap and unwrap them, so key storage capacity is not limited by the HSM.
You are responsible for procuring, provisioning, and operating all of these components. Dfns provides the HSM Driver software and coordinates mTLS certificate setup, but does not have access to your infrastructure or keys.
Dfns does not participate in the administration or management of your HSM. All HSM-related operations, including provisioning, configuration, and master key management, are handled exclusively by you. This ensures that Dfns personnel have no access to the cryptographic keys.

​
HSM usage

Dfns employs a stateless approach to HSM usage. Private keys are never stored persistently inside the HSM. Instead, they are wrapped (encrypted) by the HSM’s master key and stored in the database. The HSM unwraps them in-memory only when needed for cryptographic operations. This design simplifies integration, enhances disaster recovery, and ensures compatibility with a broad range of HSMs.

​
Key generation

  1. Your application requests a new wallet through the Dfns API.
  2. The HSM Driver polls the Dfns API over mTLS and picks up the key generation request.
  3. The Driver forwards the request to the HSM via PKCS#11.
  4. The HSM generates a new key pair, wraps the private key with its master key, and returns the wrapped key.
  5. The Driver stores the wrapped key in the database and returns the public key to your application.

​
Transaction signing

  1. Your application submits a transaction through the Dfns API.
  2. The HSM Driver polls the Dfns API over mTLS and picks up the signing request with the payload.
  3. The Driver retrieves the corresponding wrapped key from the database.
  4. The Driver sends the wrapped key and payload to the HSM. The HSM unwraps the key in-memory, signs the payload, and returns the signature.
  5. The Driver forwards the signature to your application.

​
HSM Driver

The HSM Driver is software provided by Dfns that bridges the Dfns API and your HSM. It has two primary functions:
  1. Polling Dfns APIs: The HSM Driver continuously polls the Dfns API to retrieve requests for generating new keys or signing transactions. The connection is secured using mutual TLS (mTLS).
  2. Interfacing with HSMs via PKCS#11: The HSM Driver translates API requests into PKCS#11 commands. This abstraction supports diverse HSM models without requiring specific hardware configurations.
The HSM Driver is available as a Docker container image or a standalone binary. It can be co-located with the HSM or run on a separate host.

​
Horizontal scaling and redundancy

The architecture supports active-active configurations with multiple HSM + HSM Driver pairs:
  • Queue-based load distribution: The Dfns API maintains a request queue. Each HSM Driver independently polls for the next available job. Work is naturally distributed across all healthy instances.
  • Fault tolerance: If an HSM Driver or HSM fails, it stops polling. The remaining instances continue processing without interruption or manual failover.
  • Automatic recovery: A repaired HSM Driver simply resumes polling and re-joins the processing pool with no manual intervention.
Requirements for scaling:
  • All HSMs must be provisioned with the same master key.
  • All HSM Driver instances must access the same database.
HSM high-availability architecture

​
Deploying an HSM integration

For the complete implementation guide, including prerequisites, mTLS certificate setup, HSM Driver configuration, RACI matrix, and operational procedures, contact the Dfns support team at https://support.dfns.co.
Last modified on April 9, 2026