How HashiCorp Vault auto-unseal with an HSM works: the PKCS#11 seal, Enterprise requirement, recovery keys, seal wrap, and an HSM-free option using MPC.
Vault auto-unseal with an HSM lets HashiCorp Vault decrypt its root key at startup by calling a hardware security module through PKCS#11, instead of waiting for operators to enter Shamir key shares. You configure it with a seal "pkcs11" block, and Vault returns recovery keys instead of unseal keys at initialization. In HashiCorp Vault, the PKCS#11 seal is a Vault Enterprise feature.
This guide explains how the seal works, which options Vault Community and Vault Enterprise offer, what the PKCS#11 configuration needs, and how DuoKey can sit behind the same PKCS#11 interface with the key held in MPC, an HSM or a software vault. If you run OpenBao rather than Vault, read the OpenBao auto-unseal guide instead: there, the PKCS#11 seal is part of the open-source project.
Vault stores its data encrypted. The encryption key is protected by a root key, and the root key is protected by the seal. A sealed Vault can reach its storage but cannot decrypt anything until the root key is back in memory.
With the default Shamir seal, the key that protects the root key is split into shares held by people. After every restart, on every node, a threshold of those people has to submit their shares. HashiCorp describes auto-unseal as a feature that "delegates the responsibility of securing the unseal key from users to a trusted device or service" (Vault seal concepts). Vault asks that service to decrypt the root key and unseals itself.
The trade-off is a hard dependency. HashiCorp warns that "if the seal mechanism or its keys are permanently deleted, then the Vault cluster cannot be recovered, even from backups."
| Seal | Where the unseal key lives | Vault edition |
|---|---|---|
| Shamir (default) | Shares held by operators | Community and Enterprise |
| Cloud KMS (AWS KMS, Azure Key Vault, Google Cloud KMS and others) | The cloud provider's KMS | Community and Enterprise |
| Transit | Another Vault cluster's Transit engine | Community and Enterprise |
| PKCS#11 (HSM) | Inside the HSM or the service behind the PKCS#11 library | Enterprise only |
| Seal high availability (more than one seal) | Several of the above | Enterprise only |
HashiCorp's PKCS#11 page states it directly: "Auto-unseal and seal wrapping for PKCS11 require Vault Enterprise" (PKCS#11 seal). If you run Vault Community and want an HSM-backed unseal, your options are a cloud KMS backed by the provider's own HSMs, or OpenBao, whose PKCS#11 seal is open source.
PKCS#11 (Cryptoki) is the standard C interface that HSM vendors ship as a shared library. Vault loads that library, opens a session on a slot or token, and uses a key held behind it to encrypt and decrypt the root key.
Teams choose the HSM seal for three reasons:
The cost is that the HSM becomes part of Vault's availability path. If the module or its network path is down, a restarted Vault node stays sealed.
You enable the seal in the server configuration file, or with environment variables (VAULT_SEAL_TYPE=pkcs11 plus the VAULT_HSM_* variables). The parameters HashiCorp's documentation marks as required are:
lib: path to the vendor's PKCS#11 libraryslot or token_label: which slot or token to usepin: the PIN for that slot or tokenkey_label: label of the encryption keyhmac_key_label: label of the HMAC keyA minimal block looks like this (placeholder values):
seal "pkcs11" {
lib = "/usr/vault/lib/libvendor_pkcs11.so"
slot = "0"
pin = "AAAA-BBBB-CCCC-DDDD"
key_label = "vault-hsm-key"
hmac_key_label = "vault-hsm-hmac-key"
}
Other points from the same page:
mechanism is not set, Vault picks the best available one. The supported list, in order of precedence, is CKM_AES_CBC_PAD and CKM_AES_CBC (both need an HMAC mechanism), CKM_AES_GCM, CKM_RSA_PKCS_OAEP and CKM_RSA_PKCS. HashiCorp calls CKM_RSA_PKCS less secure than OAEP.generate_key = true, Vault creates the key at initialization if it does not exist and marks it non-exportable. HashiCorp advises disabling the flag after the first creation. If your backup plan needs an exportable key, create it yourself in the HSM before initializing.max_parallel limits concurrent requests to the HSM (default 1).Keep the PIN out of the file where you can: the VAULT_HSM_PIN environment variable avoids writing it to disk.
Recovery keys. When Vault is initialized with an HSM or KMS seal, it returns recovery keys to the operators. They authorize operations that need a quorum, such as generating a root token. HashiCorp is explicit that "recovery keys cannot decrypt the root key" and are "not sufficient to unseal Vault if the auto unseal mechanism isn't working." Store them as carefully as Shamir shares, but do not count on them as a backup for the seal.
Seal wrap. Vault Enterprise can encrypt selected values a second time with the seal before writing them to storage. HashiCorp notes that "Shamir seals do not support seal wrap", so you need an auto-unseal seal to use it (seal wrap tutorial).
Entropy augmentation. Vault Enterprise can take random data from the PKCS#11 provider for selected operations instead of relying only on the host (entropy augmentation).
Every node in a Vault cluster unseals itself, so every node needs the PKCS#11 library and a path to the HSM. A HashiCorp support article on Luna HSMs stresses that the PKCS#11 seal stanza and the HSM client configuration must be identical on all nodes, and warns that mismatched configurations could result in data loss (HashiCorp support).
In practice:
An existing Shamir cluster does not need to be reinitialized. Add the seal "pkcs11" block, restart, and unseal each node with vault operator unseal -migrate and the existing Shamir shares. HashiCorp notes that seal migration cannot be done without downtime, except between auto-unseal types with Enterprise seal high availability (seal concepts). Take a snapshot first and keep the old shares until every node has unsealed under the new seal.
From Vault's point of view, DuoKey is a PKCS#11 library like any HSM vendor's. What sits behind it is different. According to DuoKey's Vault documentation:
The DuoKey PKCS#11 library holds no keys and runs no cryptography on the Vault host. It forwards each operation to Cockpit over HTTPS with a bearer token. DuoKey's documentation describes the wrapping key as an Active AES-256 key; in the OpenBao integration, which uses the same library, deactivating that key in Cockpit blocks unsealing, which gives the security team a central off-switch.
DuoKey's OpenBao documentation states that its seal integration supports CKM_AES_GCM with an AES-256 key only. The Vault page does not list mechanisms, so confirm the mechanism and the values for key_label and hmac_key_label with DuoKey when you set up the Cockpit side.
When MPC instead of a hardware HSM makes sense. If the only reason to buy an HSM is to unseal Vault, MPC removes the single appliance that holds the key without adding hardware to rack and patch. If a regulation requires a specific certified hardware module, point the same Cockpit integration at that HSM. The trade-offs are covered in MPC vs HSM.
generate_key is enabled once and then disabledvault operator init are distributed to named holdersQ: Does HashiCorp Vault Community support HSM auto-unseal?
No. HashiCorp's documentation states that auto-unseal and seal wrapping for PKCS#11 require Vault Enterprise. Vault Community supports auto-unseal with a cloud KMS or the Transit engine of another Vault cluster. OpenBao, a fork of Vault, includes a PKCS#11 seal in its open-source edition.
Q: What is the difference between unseal keys and recovery keys?
Unseal keys (Shamir shares) rebuild the key that decrypts Vault's root key. Recovery keys, issued when you use auto-unseal, only authorize sensitive operations. They cannot decrypt the root key, so they cannot unseal Vault if the HSM or KMS is unavailable.
Q: Which PKCS#11 mechanism should I use?
Vault supports AES-CBC with HMAC, AES-GCM, RSA-OAEP and RSA-PKCS, and picks the best available one if you do not set mechanism. Prefer an AES mechanism or RSA-OAEP over RSA-PKCS. Check which mechanisms your provider supports; DuoKey's documented seal mechanism is AES-GCM with an AES-256 key.
Q: Can I auto-unseal Vault without buying an HSM?
Yes. Vault Community can use a cloud KMS or Transit. With Vault Enterprise, the PKCS#11 seal can point at DuoKey, which keeps the AES-256 wrapping key in MPC, so no physical HSM is needed for unsealing.
Q: What happens if the HSM is unavailable when Vault restarts?
A restarted node stays sealed until the HSM is reachable again. Nodes that are already unsealed keep the root key in memory, but anything that uses the seal, such as seal-wrapped values, still needs the HSM. Plan HSM availability as part of Vault's availability, and test a full cluster restart.
Q: Can I move an existing Vault from Shamir to HSM auto-unseal?
Yes, with seal migration: add the PKCS#11 seal block, restart, and unseal each node with -migrate and the existing Shamir shares. Take a snapshot first and plan for downtime.
Written by
DuoKey Team
Related Resources
Tell us where control is difficult today. We will help you identify a practical next step.
