Auto Unsealing Vault

Vault’s auto-unseal feature streamlines the unsealing process by replacing manual Shamir key entry with cloud-based key management services (KMS). This guide covers how auto-unseal works, supported mechanisms, configuration examples, migration strategies, and design considerations.

What Is Auto-Unseal?

By default, Vault uses Shamir’s Secret Sharing to protect its master key. Administrators must supply a threshold of unseal key shares (e.g., 3 out of 5) each time Vault starts. Auto-unseal simplifies this by delegating master key encryption and decryption to a trusted cloud KMS. When Vault launches, it contacts the configured KMS to decrypt the master key, avoiding manual key entry.

Vault’s data encryption key encrypts all backend data (Raft, Consul, S3, etc.). Under auto-unseal, the master key protecting the data key is encrypted by the cloud KMS instead of Shamir shards.

Supported Auto-Unseal Mechanisms

Vault natively integrates with multiple cloud KMS providers and on-prem HSMs:

† Regional key outage can affect unseal. See Design Considerations.

How Auto-Unseal Works

1. You create a key (or HSM object) in your cloud KMS.
2. Configure Vault’s seal stanza with the KMS details.
3. On initialization, Vault encrypts its master key with the KMS key and stores the ciphertext under core/master.
4. At each startup, Vault automatically requests a decrypt operation from the KMS to recover the master key.

Design Considerations

• Key Rotation

  Note

  Vault supports automatic rotation of cloud-managed keys (e.g., AWS KMS annual rotation). Ensure Vault’s service account has decrypt permissions on new key versions.

• Regional Outages

  Warning

  Some KMS providers are regional. A full-region outage can prevent Vault from unsealing. Consider multi-region keys or Transit auto-unseal for high availability.

• Health Checks
  Vault pings the KMS every 10 minutes; on failure, it logs warnings and retries every minute. A loss of access only impacts restarts, not normal operations.

For on-premises or multi-region failover, you can import the same external key into multiple regions or use a Transit Secrets Engine in another Vault cluster.

Enabling Auto-Unseal

Add a seal block to your Vault HCL configuration:

listener "tcp" {
  address         = "0.0.0.0:8200"
  cluster_address = "0.0.0.0:8201"
  tls_disable     = 0
}

seal "awskms" {
  region     = "us-east-1"
  kms_key_id = "12345678-abcd-1234-abcd-123456789101"
  endpoint   = "example.kms.us-east-1.vpce.amazonaws.com"
}

api_addr     = "https://vault-us-east-1.example.com:8200"
cluster_addr = "https://node-a-us-east-1.example.com:8201"
cluster_name = "vault-prod-us-east-1"
ui           = true
log_level    = "INFO"

Authentication methods:

• AWS: IAM instance role (preferred) or environment variables ([AWS_ACCESS_KEY_ID], [AWS_SECRET_ACCESS_KEY]).
• Azure: Managed identity or AZURE_CLIENT_ID, AZURE_CLIENT_SECRET.
• GCP: Service account JSON (GOOGLE_APPLICATION_CREDENTIALS) or instance default credentials.

Example: Azure Key Vault

seal "azurekeyvault" {
  vault_name    = "vault-hashicorp"
  key_name      = "hashicorp-vault-key"
  tenant_id     = "8427464-8963-6422-example"
  client_id     = "03dc33fc-16d9-example"
  client_secret = "DKEMCI8…."
}

Example: GCP Cloud KMS

seal "gcpckms" {
  project     = "vault-project"
  region      = "global"
  key_ring    = "hashicorp-vault-keyring"
  crypto_key  = "hashicorp-vault-key"
  credentials = "/usr/gcp.json"
}

Auto-Unsealing with Transit

Use a highly available Vault cluster running the Transit Secrets Engine:

seal "transit" {
  address         = "https://vault.example.com:8200"
  token           = "s.Qf1s5zigZ40X6akYexample"
  key_name        = "auto-unseal-key"
  mount_path      = "/transit"
  tls_ca_cert     = "/etc/vault/ca.pem"
  tls_client_cert = "/etc/vault/client.pem"
  tls_client_key  = "/etc/vault/key.pem"
}

Other Options

Vault Enterprise also provides:

• HSM integration via PKCS#11 (FIPS 140-2)
• AliCloud KMS
• Oracle Cloud Infrastructure KMS

Seal Migration

You can migrate between seal methods (e.g., Shamir ↔ AWS KMS) with minimal downtime. Vault must be restarted on each node.

Example: Shamir → AWS KMS

1. Add the AWS KMS seal stanza.
2. Restart Vault on a node:

   systemctl restart vault.service
   

3. Monitor logs for migration mode:

   2022-12-25T10:47:09.295-0400 [WARN] core: entering seal migration mode; Vault will not automatically unseal even if using an autoseal: from_barrier_type=shamir to_barrier_type=awskms
   

4. Unseal with migration:

   vault operator unseal -migrate
   

5. Verify status:

   Recovery Seal Type         shamir
   Sealed                     false
   Seal Migration in Progress true
   

6. Repeat on each node (Standby nodes → Leader).

Example: Auto-Unseal → Shamir Keys

1. Add disabled = true to the active seal stanza.
2. Restart Vault and run:

   vault operator unseal -migrate
   

3. Apply across all nodes.

Example: Rotating Auto-Unseal Keys

Rotate from one KMS key to another:

seal "awskms" {
  disabled   = true
  region     = "us-east-1"
  kms_key_id = "12345678-abcd-1234-abcd-123456789101"
}

seal "awskms" {
  region     = "us-east-1"
  kms_key_id = "98765432-dcba-4321-dcba-10987654321"
}

1. Restart Vault and run vault operator unseal -migrate with recovery keys.
2. Repeat on each node.

Links and References

• Vault Auto-Unseal Documentation
• AWS KMS Overview
• Azure Key Vault Documentation
• GCP Cloud KMS Documentation