Introduction
Problem
You have encountered issues when using Vault HSM and would like to know how Vault HSM Integration works in general.
Prerequisites
- Vault HSM Support is only available on Vault Enterprise Plus.
- You will need HSM devices that support PKCS#11 version 2.20+ interfaces and provide integration libraries, and is currently available for linux/amd64 platforms only.
- Vault does not provide Configuration Guide for your HSM. Please consult your HSM Provider's documentation for details.
Questions and Answers
Q: When HSMs are unavailable, does Vault go into sealed state right away?
A: If the HSM becomes unhealthy after which Vault is already unsealed it does not go into seal state except for operations that requires the use of HSM.
The common operations that could cause Vault to interact with HSM after unsealed are the following:
- Manual Seal via API
- Server being restarted
-
Vault's storage layer encounters an unrecoverable error
- Seal Wrapping
Note that, if you are using seal wrap, it is strongly recommended that you have a reliable, and highly available HSM to prevent Vault going into sealed state from seal wrap calls.
Q: When HSMs are unavailable during the unsealing process, does Vault automatically restore the connection to the unhealthy HSMs once they are available?
A: The vendor PKCS11 library is responsible for the actual network connection. If the library reports an issue to Vault, Vault will error out and seal itself.
If the vendor library reconnects, then it may be fine. However, note that Vault only looks for the two errors: CKR_TOKEN_NOT_PRESENT and CKR_DEVICE_ERROR and then tries to finalize and reinitialize the pkcs#11 library so if the vendor library throws other errors, a manual restart of Vault would be required as Vault will not talk reinitialize the library again if other errors are being fed to Vault.
Q: How do we monitor connectivity to the HSM?
A: Vault talks to the HSM via the PKCS11 library, the connectivity is done at PKCS11 library, so the connection logging from client end is done at the library side, not at Vault side. However, the syslog should have ERROR entries when Vault is unable to talk to HSM, via the error which the library feeds to Vault. This could be a starting point to set up your own monitoring from Vault end.
Q: I am using generate_key = "true" option in my pkcs11 config. But I am not seeing keys being created in my HSM end.
A: When using generate_key = "true", Vault would try creating a key in that specified slot with the key_label option. However, note that some HSM providers may not allow clients to generate keys, or the PKCS11 library may also not support that operation. In addition, It is mandatory to create keys manually when HSM is in FIPS or CC mode. It is recommended to actually use the default option, which is setting generate_key = "false" and manually create keys on the HSM end. It also helps you to create and manage the correct keys on your HSM end.