Configure auto-unseal using your HSM

A Vault server starts in a sealed state, where all data is encrypted. Unsealing is the process of obtaining the root key to decrypt the vault data.

Out-of-the-box Vault uses Shamir's Secret Sharing to reconstruct the unseal key from multiple split key parts (shards). By integrating with an HSM, your vault can be automatically unsealed using a key in the HSM. This simplifies and automates the process of unsealing, while still providing strong security.

This guide shows how to migrate from Shamir's secret sharing to auto-unseal.

1. Stop the Vault:

   systemctl stop vault

2. Configure the PKCS#11 seal stanza. This tells Vault where to find the PKCS#11 provider, how to connect to the HSM, and which key it should use.

   seal "pkcs11" {
   lib    = "/usr/local/primus/lib/libprimusP11.so"
   slot   = "0"            # slot id
   pin    = "PRIMUSDEV"    # PKCS11 password
   key_label    = "Vault-01-20210622" # label of the key to use
   mechanism    = "0x1087" # CKM_AES_GCM
   generate_key = "true"   # generate if not existing
   }

   For details, see the parameter description. Alternatively, the parameters can also be specified using environment variables.

3. If the wrapping key that you specified above does not exist, Vault will automatically create it. If you prefer, you can pre-generate the key manually. For example:

   pkcs11-tool --module /usr/local/prius/lib/libprimusP11.so --slot 0 -l -p PRIMUSDEV --keygen --key-type aes:32 --id 2 --label Vault-01-20210628 -y secrkey --sensitive

4. Restart the vault:

   systemctl start vault

5. Unseal the vault and migrate to auto-unseal:

   vault operator unseal -migrate

tip

For more details about seal migration to auto unseal consult the HashiCorp Vault documentation.