Search…
Sealing/Unsealing
A Vault instance contains one or more vaults. Each vault, in turn, securely stores a number of symmetric keys (i.e., AES, ChaCha, etc.), asymmetric key pairs (i.e., secp256k1, Ed25519, Baby Jubjub, RSA. etc.), seeds for hierarchical deterministic wallets (i.e., BIP39, BIP44) and secrets (i.e., arbitrary data such third-party API credentials, container security environment variables, etc.). Each vault instance has an immutable AES-256-GCM master key which is created when the vault is initialized and subsequently used to decrypt sensitive key material to perform secret storage/retrieval, cryptographic sign/verify and encrypt/decrypt operations, provided the vault has been unsealed.
Vault instances ensure all key material and secrets remain encrypted at rest. The master key for a vault is an AES-256-GCM symmetric key which is encrypted, stored immutably in the instance database and required to decrypt key material and secrets stored within that vault. In its initial state after starting, a vault instance is sealed and its master keys remain unusable. A vault is unsealed when its master key is successfully decrypted in-memory by a valid seal/unseal key. When a vault process is in an unsealed state, supported cryptographic operations are permitted (i.e., store/retrieve, sign/verify, encrypt/decrypt).

Unsealing

One sealing key is valid for all vaults within a single instance. The SEAL_UNSEAL_VALIDATION_HASH environment variable contains a SHA-256 hash of the 256-bit entropy BIP39 seed phrase used for the seal/unseal key. When a valid sealing key is presented to the vault (i.e. one that has the same SHA-256 hash value as the SEAL_UNSEAL_VALIDATION_HASH environment variable), the seal/unseal key will then be cloaked (i.e., encrypted with a random, ephemeral, in-memory cloaking key) in memory and decrypted only when required for operations by the cloaking key.
When a Vault is unsealed, the unsealing key is cloaked in-memory by a randomly generated cloaking key. This ensures the unsealing key cannot become compromised while the Vault is unsealed.

Seal/Unseal Key Providers

To provide flexible support for a variety of environments and to ensure maximum security for enterprise use of Vault in production, this simple SealUnsealKeyProvider interface is defined:
1
type SealUnsealKeyProvider interface {
2
Seed() (*string, error)
3
ValidationHash() (*string, error)
4
}
Copied!
The following SealUnsealKeyProvider implementations represent the various seal/unseal strategies currently supported:
Provider
Description
Unsealing
Environment
the seal/unseal validation hash is read from environment variables
Manual via API
Docker Secret
the seal/unseal key is read from a configured Docker secret
Automatic
AWS KMS
the seal/unseal key is read from AWS Key Management Service
Automatic
Azure Key Vault
the seal/unseal key is read from Azure Key Vault
Automatic

Environment

The environment provider uses environment variables to provide a seal/unseal key and validation hash to Vault at runtime.

Configuration

The following environment variables should be set to configure and enable the environment seal/unseal provider:
Environment Variable
Description
SEAL_UNSEAL_PROVIDER
optional; must be set to environment, if provided
SEAL_UNSEAL_KEY¹
optional; the seal/unseal key under test
SEAL_UNSEAL_VALIDATION_HASH
the hex-encoded seal/unseal validation hash
¹ Never provide a SEAL_UNSEAL_KEY via the environment provider in production. When using this provider in production you must manually unseal the vault using this API.

Create a Seal/Unseal Key

The following example shows how to create a new seal/unseal key, which can then be used as described above to configure the environment provider:
curl
1
curl -i -XPOST \
2
-H 'authorization: bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwOjJlOmQ5OmUxOmI4OmEyOjM0OjM3Ojk5OjNhOjI0OmZjOmFhOmQxOmM4OjU5IiwidHlwIjoiSldUIn0.eyJhdWQiOiJodHRwczovL3Byb3ZpZGUuc2VydmljZXMvYXBpL3YxIiwiZXhwIjoxNTk5OTI1NDI4LCJpYXQiOjE1OTk4MzkwMjgsImlzcyI6Imh0dHBzOi8vaWRlbnQucHJvdmlkZS5zZXJ2aWNlcyIsImp0aSI6IjJmZjE2YzczLTczOWItNDFmZi04MTM1LTM1NTQxOWY2M2RiMCIsIm5hdHMiOnsicGVybWlzc2lvbnMiOnsic3Vic2NyaWJlIjp7ImFsbG93IjpbInVzZXIuNGM1ZDI5NjktYTQwYy00ZjZkLWFhMDItMjEzNTVmM2M5MDkxIiwibmV0d29yay4qLmNvbm5lY3Rvci4qIiwibmV0d29yay4qLnN0YXR1cyIsInBsYXRmb3JtLlx1MDAzZSJdfX19LCJwcnZkIjp7InBlcm1pc3Npb25zIjo3NTUzLCJ1c2VyX2lkIjoiNGM1ZDI5NjktYTQwYy00ZjZkLWFhMDItMjEzNTVmM2M5MDkxIn0sInN1YiI6InVzZXI6NGM1ZDI5NjktYTQwYy00ZjZkLWFhMDItMjEzNTVmM2M5MDkxIn0.YlS8eQA1b9GjWhHjef08m0UQFg6nyQgvw34fPCEglfp48wWlLAwnLOmVZT0O3nHAf5f9XJljjLchGkS_vBqzs6xy39Paq81ywxJLU5PdNJFY13bhVjwTJCGWzL2pE8T5by2zaDHEjrsYfCr32ZY0o94pTzQEJ7f0TvjnyuE3l3B584u50d5gss_MOpf44-kOcX6T0KQwJmKA1rCWNrMQ4Hh3i1B-LoysGcOJhDJpuHCD6loijNIxvkjndQ2PeQXHqZ4ZKr0p4pIsexYflLdT1Szl59lpFipgCTomPVYAmBZX0MfZPlt30Pp62ANDs4qttH7-OrnK4m2_p6yeYGiRsf7TUj9NAYdHVetEYeu8oSgpQfmr0Z3jTxXFEY9t1cBPMB5zyBwzCMsTVjlG3xhGxr9SQ26uheMy7M-u9_8Kq-riZv2W79ALm22MSyYi7y0UeC3wG-hO8jrxns3kzV4heI3upwhXS2ccEZrpWbJe4S17egjpEDYAI3JIuWkggEzr_snB8xCV1-ZB2_r6aqdfmsj3QIZQK4U2c6Wa27NBA4hzE45qp_RMyiY7PZOzv0315TYa6qrio2qyUWRr29nHPOEAufg9L-aMYVKBOieL8VIWKw3RBVSDABN1sFWbFfiX0Pd5jny7zMxjHtoae5B-jgAzijIcH7xnvzkCBIySlhI' \
3
-H 'Content-Type: application/json' \
4
https://vault.provide.services/api/v1/unsealerkey
5
HTTP/2 201
Copied!
The seal/unseal key is returned alongside its validation hash:
1
{
2
"key": "pilot deputy flat want coil bleak minor have anger claim dinner furnace alone borrow draw east asset main sausage stomach gold omit sign globe",
3
"validation_hash": "0x211336e67a5dd50bc1a6ab973fcb18a8a56f8591a9e2e2372a435d67ae073cc9"
4
}
Copied!
Note that the seal/unseal key generated is intended for the bootstrapping of another secure Vault instance. Calling this API does not have a side effect of changing the Vault seal/unseal key at runtime. This API call is only supported when the SEAL_UNSEAL_PROVIDER is set to environment.

Unsealing

To unseal a vault after startup, use this API:
1
#!/bin/bash
2
3
curl -i -XPOST \
4
-H 'authorization: bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwOjJlOmQ5OmUxOmI4OmEyOjM0OjM3Ojk5OjNhOjI0OmZjOmFhOmQxOmM4OjU5IiwidHlwIjoiSldUIn0.eyJhdWQiOiJodHRwczovL3Byb3ZpZGUuc2VydmljZXMvYXBpL3YxIiwiZXhwIjoxNTk5OTI1NDI4LCJpYXQiOjE1OTk4MzkwMjgsImlzcyI6Imh0dHBzOi8vaWRlbnQucHJvdmlkZS5zZXJ2aWNlcyIsImp0aSI6IjJmZjE2YzczLTczOWItNDFmZi04MTM1LTM1NTQxOWY2M2RiMCIsIm5hdHMiOnsicGVybWlzc2lvbnMiOnsic3Vic2NyaWJlIjp7ImFsbG93IjpbInVzZXIuNGM1ZDI5NjktYTQwYy00ZjZkLWFhMDItMjEzNTVmM2M5MDkxIiwibmV0d29yay4qLmNvbm5lY3Rvci4qIiwibmV0d29yay4qLnN0YXR1cyIsInBsYXRmb3JtLlx1MDAzZSJdfX19LCJwcnZkIjp7InBlcm1pc3Npb25zIjo3NTUzLCJ1c2VyX2lkIjoiNGM1ZDI5NjktYTQwYy00ZjZkLWFhMDItMjEzNTVmM2M5MDkxIn0sInN1YiI6InVzZXI6NGM1ZDI5NjktYTQwYy00ZjZkLWFhMDItMjEzNTVmM2M5MDkxIn0.YlS8eQA1b9GjWhHjef08m0UQFg6nyQgvw34fPCEglfp48wWlLAwnLOmVZT0O3nHAf5f9XJljjLchGkS_vBqzs6xy39Paq81ywxJLU5PdNJFY13bhVjwTJCGWzL2pE8T5by2zaDHEjrsYfCr32ZY0o94pTzQEJ7f0TvjnyuE3l3B584u50d5gss_MOpf44-kOcX6T0KQwJmKA1rCWNrMQ4Hh3i1B-LoysGcOJhDJpuHCD6loijNIxvkjndQ2PeQXHqZ4ZKr0p4pIsexYflLdT1Szl59lpFipgCTomPVYAmBZX0MfZPlt30Pp62ANDs4qttH7-OrnK4m2_p6yeYGiRsf7TUj9NAYdHVetEYeu8oSgpQfmr0Z3jTxXFEY9t1cBPMB5zyBwzCMsTVjlG3xhGxr9SQ26uheMy7M-u9_8Kq-riZv2W79ALm22MSyYi7y0UeC3wG-hO8jrxns3kzV4heI3upwhXS2ccEZrpWbJe4S17egjpEDYAI3JIuWkggEzr_snB8xCV1-ZB2_r6aqdfmsj3QIZQK4U2c6Wa27NBA4hzE45qp_RMyiY7PZOzv0315TYa6qrio2qyUWRr29nHPOEAufg9L-aMYVKBOieL8VIWKw3RBVSDABN1sFWbFfiX0Pd5jny7zMxjHtoae5B-jgAzijIcH7xnvzkCBIySlhI' \
5
-H 'Content-Type: application/json' \
6
https://vault.provide.services/api/v1/unseal \
7
-d '{
8
"key": "traffic charge swing glimpse will citizen push mutual embrace volcano siege identify gossip battle casual exit enrich unlock muscle vast female initial please day"
9
}'
10
Copied!
204 No Content is returned if the Vault is successfully unsealed.
Note that other, more secure seal/unseal providers can be used to automatically unseal a Vault instance upon startup. The Azure Key Vault seal/unseal provider is a good example of such a provider.

Docker Secrets

The docker provider allows a Docker secret to provide the seal/unseal key to Vault at runtime.
The docker seal/unseal provider must not be used on public cloud infrastructure.

Configuration

The following environment variables should be set to configure and enable the docker seal/unseal provider:
Environment Variable
Description
SEAL_UNSEAL_PROVIDER
must be set to docker
SEAL_UNSEAL_KEY_SECRET_PATH
the seal/unseal secret path; i.e., /run/secrets/unsealkey
SEAL_UNSEAL_VALIDATION_HASH
the hex-encoded seal/unseal validation hash

Amazon Key Management Service

Documentation forthcoming.

Azure Key Vault

The azure_key_vault provider allows the seal/unseal key to be provided automatically to Vault by an Azure Key Vault instance.
When configured to leverage managed identity within a specific Azure region, a Vault instance can securely retrieve the seal/unseal key from a FIPS 140-2 level 2 compliant Azure Key Vault instance. The key is stored as a secret within Azure Key Vault.
The azure_key_vault seal/unseal provider is ideal for enterprise-grade production environments.

Configuration

The following environment variables should be set to configure and enable the azure_key_vault seal/unseal provider:
Environment Variable
Description
SEAL_UNSEAL_PROVIDER
must be set to azure_key_vault
SEAL_UNSEAL_VAULT_SUBSCRIPTION_ID
the subscription identifier of the Azure Key Vault instance
SEAL_UNSEAL_VAULT_TENANT_ID
the tenant identifier of the Azure Key Vault instance
SEAL_UNSEAL_VAULT_REGION
the region in which the Azure Key Vault instance is deployed
SEAL_UNSEAL_VAULT_NAME
the unique name of the Azure Key Vault instance
SEAL_UNSEAL_SECRET_NAME
the name of the secret within the Azure Key Vault instance

Autonomous Seal/Unseal Lifecycle

The azure_key_vault provider supports an autonomous seal/unseal key creation and unsealing lifecycle. The first time a Vault runs, a secret is created in the configured Azure Key Vault instance. On subsequent runs, the secret is used to automatically unseal the Vault.
Last modified 2mo ago