Skip to main content

Auto Unsealing using Wrapped Master Key from HSM

A Vault server usually starts in a sealed state. Unsealing is the process of obtaining the master key to decrypt the vault data. The default Vault configuration uses Shamir’s Secret Sharing to reconstruct the unseal key from multiple split key parts (shards). Auto Unseal using an HSM, reduces the operational complexity of keeping the unseal key secure and allows an instant unsealing process, using the wrapped master key from the HSM.

note

The command line extracts in this document are using RHEL platform (Linux) syntax.

Seal Migration to Auto Unseal​

When a Vault server is started, it normally starts in a sealed state where a quorum of existing unseal keys is required to unseal it. By integrating Vault with an HSM, your Vault server can be automatically unsealed by the trusted HSM key provider.

  1. Stop the Vault by executing the command:
systemctl stop vault
  1. To integrate your Vault Enterprise server with an HSM cluster, the configuration file must define the PKCS11 seal stanza.providing necessary connection information. Use below shown Vault configuration block example to enable initial generation of keys by the Vault. Replace your parameters according the parameter description.
seal "pkcs11" {
lib 	= "/usr/local/primus/lib/libprimusP11.so"
slot 	= "0"	# slot id
pin 	= "PRIMUSDEV"	# PKCS11 password
key_label 	= "Vault-01-20210622"
mechanism 	= "0x1087"	# CKM_AES_GCM
generate_key 	= "true"	# generate if not existing
}

Parameter description:

  • lib Primus PKCS#11 library file including path,
  • slot PKCS#11 partition slot id,
  • token_label PKCS#11 partition name (slot or token_label is required),
  • pin PKCS#11 password,
  • key_label name of the key to use,
  • mechanism cryptographic mechanism to use for encryption/decryption,
  • generate_key true: instructs Vault to generate a key “key_label” if none is found.
info

Alternatively, the parameters can also be defined using environment variables. For details and more parameters see https://www.vaultproject.io/docs/configuration/seal/pkcs11#pkcs11-parameters.

  1. Optionally, the wrapping key can be pre-generated using other tools. Example provided below uses pkcs11-tools utility with example parameters. Adapt these according your utility of choice and configured parameters.
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
  1. Use the below commands to restart the vault:
systemctl start vault

and then unseal it, and migrate to auto unseal.

vault operator unseal -migrate
note

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