docs/documentation/platform/pki/settings/hsm-connectors.mdx
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 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 is 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.
Have these on hand before you create a Connector:
--pkcs11-module=<absolute path> so it loads your HSM's PKCS#11 driver..so) provided by your HSM vendor. Gateway HSM support runs on Linux only.At the top level there are three actors:
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:
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:
--pkcs11-module=<path to vendor .so>. See Gateway Deployment.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 is not eligible for HSM Connectors and is skipped automatically.
If you have never deployed a Gateway before, read Gateway Deployment first for the general install and auth flow, then return here for the HSM-specific flag.
<Steps> <Step title="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 will 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 <driver> --list-slots` returns the expected slot label.
<Tabs>
<Tab title="Linux (Production)">
```bash
sudo infisical gateway systemd install <gateway-name> \
--enroll-method=token \
--token=<enrollment-token> \
--domain=<your-infisical-domain> \
--pkcs11-module=/opt/fortanix/pkcs11/fortanix_pkcs11.so
sudo systemctl start <gateway-name>
```
The systemd unit captures the `--pkcs11-module` flag, so restarts pick up the same driver.
</Tab>
<Tab title="Foreground">
```bash
infisical gateway start <gateway-name> \
--enroll-method=token \
--token=<enrollment-token> \
--domain=<your-infisical-domain> \
--pkcs11-module=/opt/fortanix/pkcs11/fortanix_pkcs11.so
```
</Tab>
</Tabs>
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.
Once you have a PKCS#11-enabled Gateway running, create the Connector in Cert Manager.
In Certificate Manager > Settings > HSM Connectors, click Add HSM Connector. The wizard walks you through three steps.
<Steps> <Step title="Basics"> | Field | Description | |-------|-------------| | **Name** | Slug-friendly identifier (lowercase, dashes). Example: `fortanix-prod`. | | **Description** | Optional. Context for your team. Example: *Fortanix DSM, production keys*. | </Step> <Step title="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`.
| 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.
| 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 |
Key algorithms supported for generation: RSA 2048-bit, RSA 4096-bit, ECDSA P-256, and ECDSA P-384.