> ## 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.

# HSM driver

> Release notes for the DFNS HSM driver: vendor support, keystore changes, key pre-generation, and operational tooling.

Current release: **v1.4.2**.

<Update label="v1.4.2" tags={["New Feature", "Blockchain support", "Operational", "Security"]}>
  *Week of August 3rd, 2026*

  *Releases are now numbered `hsm-X.Y.Z` (no `v` prefix). The previous entry, v0.1.46, corresponds to 1.1.0. This entry covers everything delivered since: 1.2.0 through 1.4.2.*

  **HSM vendor support updates:**

  * **AWS CloudHSM** support added, with a deployment runbook. The driver now advertises whether EdDSA is available on the backend.
  * **Thales Luna V1 (SKS)** backend added alongside the existing V0 backend, with on-token HD derivation.
  * **IBM EP11**: on-token HD derivation.

  **HD wallets (BIP-32 / SLIP-0010):**

  * HD key generation and signing: generate an HD master key, sign at a derivation path, and derive child public keys with the new `derive_public_key` RPC. Supported on Thales Luna (V0 and V1) and IBM EP11. Ed25519 derivation is hardened-only. Not available on the OSO path.

  **Keystore:**

  * **Persistent key storage**: HD master keys can live directly on the HSM partition (located by `CKA_LABEL`) instead of as wrapped blobs in the database. Persistent drivers are HD-only, and a new capabilities RPC reports the driver's storage mode. The legacy sealed mode remains the default.

  **Secrets and authentication:**

  * **HashiCorp Vault** secrets retriever added.
  * New Vault authentication providers: in-cluster Kubernetes service account and AWS IRSA.
  * The HSM PIN can be supplied as a Docker Compose secret file (`USER_PIN_FILE`) instead of an environment variable. `USER_PIN` keeps working; the two are mutually exclusive.

  **Security:**

  * **Pre-signature validation gate**: the driver can verify the intent authorizing a signature (payload-hash binding and signing-user proof) before the HSM signs.
  * **Auto-renewing mTLS server identity** for the proxy and secrets retriever, with health exported as OpenTelemetry metrics. The TLS pack can carry only the CA when auto-renew is on.
  * Governance-engine signature attestation passed to the OSO plugin.
  * Fail-closed input handling: exact signing-scheme matching (no silent ECDSA fallback), plus signature-length and maximum-input-size checks.
  * `destroy_all` is gated out of production binaries, production images are distroless, and the Thales driver runs as non-root by default.
  * Bundled IBM `pkcs11-grep11` updated 2.6.11 to 2.6.15, removing 35+ CVEs from the driver image. OpenTelemetry and rustls-webpki updated for upstream advisories.

  **Operational:**

  * Distroless production images for `hsm-driver` and `hsm-cli`, with all vendors bundled. The previous image ships as a `-debug` variant for field diagnosis.
  * Structured logs carrying `trace_id` and `span_id`, propagated from incoming `traceparent` headers (Datadog-compatible).
  * `hsm-cli` disaster recovery: HD key generation, signing, and public-key derivation in persistent mode without a running proxy.
  * arm64 build of `hsm-proxy`.
  * New database migrations must be applied before start, for the driver and, for the first time, the proxy. HD support adds `keys.chain_code`; the proxy adds `derivation_path` to its signature cache.
</Update>

<Update label="v0.1.46" tags={["New Feature", "Operational", "Security"]}>
  *Week of May 25th, 2026*

  **HSM vendor support:**

  * Securosys Primus CloudHSM support added.

  **Operational:**

  * Database migrations now run automatically on startup (Postgres), with a flag to disable them.
  * Response caching added to the HSM proxy.
  * `hsm-cli` is now shipped as a separate image.
  * HPCS (IBM grep11) library updated to 2.6.11.
</Update>

<Update label="v0.1.43" tags={["New Feature", "Operational"]}>
  *Week of May 4th, 2026*

  **HSM vendor support:**

  * IBM EP11 support added: multi-card init, secure-key concept, EdDSA and ECDSA generate/sign, pre-generation.
  * Thales HSM support added (including Cloud Luna), with a dedicated runbook.
  * OpenCryptoki integration reworked, then removed in favor of the higher-level HSM interface.

  **Keystore:**

  * SQLite added as a keystore option, with strict tables and a read-only mode.
  * HA SQLite mode added.
  * Postgres migrations reorganized into a dedicated subfolder.

  **Key pre-generation:**

  * Pre-generation of keys supported on startup, with topup capability.
  * Pre-generation supported in `pkcs11-executor` mode.

  **Signing:**

  * Sign by public key supported as an alternative to signing by `key_id`.
  * Signing integrity verification using ed25519.
  * Returned and stored public keys are now compressed.

  **Operational:**

  * New `hsm-cli` for HSM operations without a proxy connection.
  * New `bench` command on the driver CLI.
  * Async flow: driver can return pending processes to the proxy REST API.
  * Multi-platform `hsm-proxy` images (amd64 and s390x).
  * Version printed at `hsm-driver` and `hsm-proxy` startup.
</Update>

<Update label="v0.1.22" tags={["Operational", "Bug Fix"]}>
  *Week of January 5th, 2026*

  **Operational:**

  * Documented HSM keystore creation in pregen mode.

  **Bug Fixes:**

  * Client cert parsing: customer names containing dots are now accepted.
  * Client cert domain handling is now dynamic.
</Update>

<Update label="v0.1.21" tags={["Operational"]}>
  *Week of December 22nd, 2025*

  **Operational:**

  * Client stale timeout is now a configurable parameter on `hsm-proxy`.
  * Proxy can drop driver connections that have gone stale.
  * IBM runbook updated with HA SQLite instructions.
</Update>

<Update label="v0.1.19" tags={["Initial Release"]}>
  *Week of December 15th, 2025*

  First release of the DFNS HSM signer tracked in this changelog.
</Update>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.