> ## Documentation Index > Fetch the complete documentation index at: https://infisical.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # HSM connectors > Register a Hardware Security Module that Infisical reaches through one of your Gateways. An **HSM Connector** is the resource you create in Infisical to register a slot on your Hardware Security Module. It holds the slot's credentials (slot label, PIN) and a reference to a [Gateway](https://infisical.com/docs/documentation/platform/gateways/overview.md) running inside your network that can talk to the HSM. Infisical features that support HSM-backed keys reference the Connector when they need to perform PKCS#11 operations on your HSM. The Connector itself stores no key material. It's a credentials and routing record. Infisical never talks to the HSM directly. Instead, a Gateway acts as the bridge, loading your HSM vendor's PKCS#11 driver in the network where the HSM lives. ## Before you start Have these on hand before you create a Connector: * A **running, HSM-capable Gateway** on a host that can reach your HSM. New to Gateways? Start at [Gateway Deployment](https://infisical.com/docs/documentation/platform/gateways/gateway-deployment.md), then come back. The Gateway must be started with `--pkcs11-module=` so it loads your HSM's PKCS#11 driver. * The **absolute path to the PKCS#11 driver** (`.so`) provided by your HSM vendor. Gateway HSM support runs on Linux only. * The **slot label** and **PIN** of the HSM slot Infisical should use. Both come from your HSM provider. ## How it fits together At the top level there are three actors: ```mermaid theme={"dark"} graph LR A[Infisical] --> B[Gateway
on your network] B --> C[Your HSM] ``` The detailed exchange Infisical performs against the HSM through the Gateway looks like this: ```mermaid theme={"dark"} sequenceDiagram participant Infisical as Infisical participant Gateway as Gateway
(HSM-enabled) participant HSM as Your HSM Infisical->>Gateway: PKCS#11 request via HSM Connector Gateway->>HSM: C_* call via vendor driver HSM-->>Gateway: Result Gateway-->>Infisical: Result ``` Three pieces have to be in place for an HSM Connector to be usable: 1. **A Gateway** running on a Linux host that can talk to your HSM, started with `--pkcs11-module=`. See [Gateway Deployment](https://infisical.com/docs/documentation/platform/gateways/gateway-deployment.md). 2. **An HSM Connector** that points at that Gateway (or a Pool that contains it) and carries the slot credentials. 3. **A consumer**, a feature that supports HSM-backed keys. See the feature's own docs for how it references an HSM Connector. ## Run a Gateway with PKCS#11 enabled The Gateway is the agent Infisical talks to when it needs your HSM. You install it once on a host inside your network, start it with your HSM's PKCS#11 driver path, and Infisical routes every HSM operation through it. A Gateway started without the PKCS#11 driver path isn't eligible for HSM Connectors and is skipped automatically. If you have never deployed a Gateway before, read [Gateway Deployment](https://infisical.com/docs/documentation/platform/gateways/gateway-deployment.md) first for the general install and auth flow, then return here for the HSM-specific flag. **1. Install your HSM's PKCS#11 driver on the Gateway host** Install the PKCS#11 library shipped by your HSM vendor on the Linux machine where the Gateway will run. Note the absolute path to the `.so`. You'll pass it to the Gateway in the next step. For example, the Fortanix DSM PKCS#11 driver is commonly placed at `/opt/fortanix/pkcs11/fortanix_pkcs11.so` by Fortanix's installer, though you can put it anywhere the Gateway process can read. Follow the vendor's onboarding to provision a slot, configure operator credentials, and confirm `pkcs11-tool --module --list-slots` returns the expected slot label. **2. Create the Gateway in the Infisical UI** Go to **Organization Settings > Networking > Gateways**, select **Create Gateway**, name it, and pick an auth method. Then select **Show deploy command** and copy the install command for your platform. See [Gateway Deployment](https://infisical.com/docs/documentation/platform/gateways/gateway-deployment.md) for full setup detail (relay, firewall, AWS or token auth). **3. Start the Gateway with --pkcs11-module** Append `--pkcs11-module=` to the start command. The Gateway loads the driver once on startup and serves HSM operations alongside its other traffic. > [tab] Linux (Production) > > ```bash theme={"dark"} > sudo infisical gateway systemd install \ > --enroll-method=token \ > --token= \ > --domain= \ > --pkcs11-module=/opt/fortanix/pkcs11/fortanix_pkcs11.so > sudo systemctl start > ``` > > The systemd unit captures the `--pkcs11-module` flag, so restarts pick up the same driver. > [tab] Foreground > > ```bash theme={"dark"} > infisical gateway start \ > --enroll-method=token \ > --token= \ > --domain= \ > --pkcs11-module=/opt/fortanix/pkcs11/fortanix_pkcs11.so > ``` On startup you should see a log line confirming the PKCS#11 module loaded. If the driver path is wrong or unreadable, the Gateway exits with an error before connecting. **4. (Optional) Add the Gateway to a Pool** For high availability, deploy two or more PKCS#11-enabled Gateways and add them to the same [Gateway Pool](https://infisical.com/docs/documentation/platform/gateways/gateway-pools.md). HSM Connectors that target the pool route each request to a randomly chosen, healthy, PKCS#11-capable member. Non-capable members in the same pool are silently skipped. > [!NOTE] > > PKCS#11 driver libraries are vendor-specific binaries. Make sure the file is readable by the user running the Gateway (typically owner-only readable, mode 0640 with the Gateway user in the owning group, or 0644 if simpler). Verify the driver matches your HSM firmware version before connecting it to production traffic. ## Create an HSM connector Once you have a PKCS#11-enabled Gateway running, create the Connector in Cert Manager. In **Certificate Manager > Settings > HSM Connectors**, select **Add HSM Connector**. The wizard walks you through three steps. **1. Basics** | Field | Description | | - | - | | **Name** | Slug-friendly identifier (lowercase, dashes). Example: `fortanix-prod`. | | **Description** | Optional. Context for your team. Example: *Fortanix DSM, production keys*. | **2. Connection** Pick the **Gateway** Infisical uses to reach your HSM: * **Gateway**: route every operation through one specific Gateway. Use this if you have a single PKCS#11-enabled Gateway, or if you want strict routing. * **Gateway Pool**: route through any healthy, PKCS#11-capable member of the pool. Recommended for production so a single Gateway outage doesn't stop operations. Pool members without PKCS#11 enabled are skipped automatically. Only HSM-capable Gateways are eligible. The Gateway dropdown shows the filtered list. If it's empty, double-check the Gateway is running with `--pkcs11-module`. **3. Credentials** Supply the credentials Infisical uses to authenticate to the HSM slot through the Gateway. | Field | Description | | - | - | | **Slot label** | The PKCS#11 token label of the slot to use. | | **PIN** | The PKCS#11 user PIN for that slot. Stored encrypted with your KMS key, sent to the Gateway over the proxied TLS channel on every request. | | **Key label prefix** | Optional prefix prepended to every key label Infisical creates in this slot. Example: `infisical-` produces labels like `infisical-{id}`. Useful when the HSM hosts keys for multiple applications. | Click **Add HSM Connector**. Infisical runs a Verify against the HSM before persisting the Connector. Wrong PIN, unknown slot label, or unreachable Gateway are caught at this point and the Connector is not saved. ## FAQ > [accordion] What happens to keys on the HSM when I delete a referencing resource? > > Nothing. Infisical removes its reference to the key label. The actual key object remains on your HSM. Delete it through your HSM's own tooling if you want to free the slot. > [accordion] Can I route HSM traffic through the same Gateway that serves my databases or app connections? > > Yes. Append `--pkcs11-module` to the start command of an existing Gateway and that Gateway will serve HSM operations alongside its other traffic. Restart is required for the driver to load. > [accordion] Does a Gateway Pool need every member to be PKCS#11-capable? > > No. Connectors routed through a pool ignore non-capable members. You can mix one or two PKCS#11-enabled Gateways with the rest of your pool freely. For ML-DSA keys, at least one PKCS#11 Gateway in the pool must meet the requirements listed under [HSM-backed internal CAs](https://infisical.com/docs/documentation/platform/pki/ca/private-ca#hsm-backed-internal-cas). > [accordion] Which mechanisms are supported? > > The PKCS#11 bridge supports the following signing mechanisms: > > | Mechanism | What it does | > | - | - | > | RSA PKCS#1 v1.5 | Raw RSA signing of a pre-hashed digest | > | SHA-256 with RSA PKCS#1 v1.5 | RSA signing with SHA-256 inside the HSM | > | SHA-384 with RSA PKCS#1 v1.5 | RSA signing with SHA-384 inside the HSM | > | SHA-512 with RSA PKCS#1 v1.5 | RSA signing with SHA-512 inside the HSM | > | ECDSA with SHA-256 | ECDSA signing with SHA-256 inside the HSM | > | ECDSA with SHA-384 | ECDSA signing with SHA-384 inside the HSM | > | ECDSA with SHA-512 | ECDSA signing with SHA-512 inside the HSM | > | ML-DSA | ML-DSA signing inside the HSM | > > Key algorithms supported for generation: RSA 2048-bit, RSA 4096-bit, ECDSA P-256, ECDSA P-384, ML-DSA-44, ML-DSA-65, and ML-DSA-87. ML-DSA keys work with HSM-backed CAs only, not code signers. > [accordion] Can I rotate the PIN without recreating resources that reference the Connector? > > Yes. Edit the Connector and update the PIN. The next operation uses the new credential. Existing references continue to work unchanged. ## What's next? > [card] [Fortanix DSM](https://infisical.com/docs/documentation/platform/pki/settings/hsm-connectors-fortanix-dsm.md) > > Step-by-step Fortanix Data Security Manager setup. > [card] [Gateway Deployment](https://infisical.com/docs/documentation/platform/gateways/gateway-deployment.md) > > Full Gateway setup including relay, firewall, and AWS auth. > [card] [Gateway Pools](https://infisical.com/docs/documentation/platform/gateways/gateway-pools.md) > > Group HSM-capable Gateways for high availability. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.