Hashicorp Vault Auto-Unseal using Builder Vault

This page is a tutorial that shows how the Builder Vault PKCS #11 library can be used to auto-unseal Hashicorp Vault.

Prerequisites:

An instance of Builder Vault
The file pkcs11.toml, protected with a user-defined PIN
The pkcs11.amd64.so library
A Hashicorp Vault Entreprise license
The Hashicorp Vault entreprise+hsm binary. This can be obtained from https://releases.hashicorp.com/vault/<version>+ent.hsm/.

Configure Hashicorp Vault to run with Blockdaemon Builder Vault

Create the vault_config.hcl and add the following contents:

storage "file" {
  path = "/opt/vault/vault-data"
}

disable_mlock = true

ui = true

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = true
}

seal "pkcs11" {
  lib            = "/opt/blockdaemon/tsm-pkcs11.amd64.so"
  slot           = "0"
  pin            = <user-defined PIN>
  key_label      = "bv-demo"
  generate_key   = "true"
  mechanism      = 0x1087
}

Note that currently the Builder Vault PKCS#11 interface only supports the CKM_AES_GCM (0x1087) mechanism.

Set the following environment variables:

export VAULT_ADDR=http://127.0.0.1:8200
export VAULT_LICENSE_PATH="<path_to_your_license.hclic"

Then start the Hashicorp Vault with:

./vault server -config ./vault_config.hcl

Initialize the Hashicorp Vault with:

./vault operator init -recovery-shares=1 -recovery-threshold=1

Note the Initial Root token. Check the Hashicorp Vault status to see that it has been initialized and unsealed:

$ vault status

Key                      Value
---                      -----
Seal Type                pkcs11
Recovery Seal Type       shamir
Initialized              true
Sealed                   false
Total Recovery Shares    1
Threshold                1
Version                  1.17.5+ent.hsm
Build Date               2024-08-30T15:55:00Z
Storage Type             file
Cluster Name             vault-cluster-8e18e2e5
Cluster ID               9d6703ad-41e3-0c37-7693-bd6940baf8a2
HA Enabled               false

$ vault login hvs.lv1zu1GiK3BDcGkfFOKTSc25
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.

Key                  Value
---                  -----
token                hvs.lv1zu1GiK3BDcGkfFOKTSc25
token_accessor       0JJ0gCWmDbqR3N0Yq02cW8uz
token_duration       ∞
token_renewable      false
token_policies       ["root"]
identity_policies    []
policies             ["root"]