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).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.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:type SealUnsealKeyProvider interface {
Seed() (*string, error)
ValidationHash() (*string, error)
}
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 |
The
environment provider uses environment variables to provide a seal/unseal key and validation hash to Vault at runtime.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.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
curl -i -XPOST \
-H 'authorization: bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwOjJlOmQ5OmUxOmI4OmEyOjM0OjM3Ojk5OjNhOjI0OmZjOmFhOmQxOmM4OjU5IiwidHlwIjoiSldUIn0.eyJhdWQiOiJodHRwczovL3Byb3ZpZGUuc2VydmljZXMvYXBpL3YxIiwiZXhwIjoxNTk5OTI1NDI4LCJpYXQiOjE1OTk4MzkwMjgsImlzcyI6Imh0dHBzOi8vaWRlbnQucHJvdmlkZS5zZXJ2aWNlcyIsImp0aSI6IjJmZjE2YzczLTczOWItNDFmZi04MTM1LTM1NTQxOWY2M2RiMCIsIm5hdHMiOnsicGVybWlzc2lvbnMiOnsic3Vic2NyaWJlIjp7ImFsbG93IjpbInVzZXIuNGM1ZDI5NjktYTQwYy00ZjZkLWFhMDItMjEzNTVmM2M5MDkxIiwibmV0d29yay4qLmNvbm5lY3Rvci4qIiwibmV0d29yay4qLnN0YXR1cyIsInBsYXRmb3JtLlx1MDAzZSJdfX19LCJwcnZkIjp7InBlcm1pc3Npb25zIjo3NTUzLCJ1c2VyX2lkIjoiNGM1ZDI5NjktYTQwYy00ZjZkLWFhMDItMjEzNTVmM2M5MDkxIn0sInN1YiI6InVzZXI6NGM1ZDI5NjktYTQwYy00ZjZkLWFhMDItMjEzNTVmM2M5MDkxIn0.YlS8eQA1b9GjWhHjef08m0UQFg6nyQgvw34fPCEglfp48wWlLAwnLOmVZT0O3nHAf5f9XJljjLchGkS_vBqzs6xy39Paq81ywxJLU5PdNJFY13bhVjwTJCGWzL2pE8T5by2zaDHEjrsYfCr32ZY0o94pTzQEJ7f0TvjnyuE3l3B584u50d5gss_MOpf44-kOcX6T0KQwJmKA1rCWNrMQ4Hh3i1B-LoysGcOJhDJpuHCD6loijNIxvkjndQ2PeQXHqZ4ZKr0p4pIsexYflLdT1Szl59lpFipgCTomPVYAmBZX0MfZPlt30Pp62ANDs4qttH7-OrnK4m2_p6yeYGiRsf7TUj9NAYdHVetEYeu8oSgpQfmr0Z3jTxXFEY9t1cBPMB5zyBwzCMsTVjlG3xhGxr9SQ26uheMy7M-u9_8Kq-riZv2W79ALm22MSyYi7y0UeC3wG-hO8jrxns3kzV4heI3upwhXS2ccEZrpWbJe4S17egjpEDYAI3JIuWkggEzr_snB8xCV1-ZB2_r6aqdfmsj3QIZQK4U2c6Wa27NBA4hzE45qp_RMyiY7PZOzv0315TYa6qrio2qyUWRr29nHPOEAufg9L-aMYVKBOieL8VIWKw3RBVSDABN1sFWbFfiX0Pd5jny7zMxjHtoae5B-jgAzijIcH7xnvzkCBIySlhI' \
-H 'Content-Type: application/json' \
https://vault.provide.services/api/v1/unsealerkey
HTTP/2 201
The seal/unseal key is returned alongside its validation hash:
{
"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",
"validation_hash": "0x211336e67a5dd50bc1a6ab973fcb18a8a56f8591a9e2e2372a435d67ae073cc9"
}
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.To unseal a vault after startup, use this API:
#!/bin/bash
curl -i -XPOST \
-H 'authorization: bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwOjJlOmQ5OmUxOmI4OmEyOjM0OjM3Ojk5OjNhOjI0OmZjOmFhOmQxOmM4OjU5IiwidHlwIjoiSldUIn0.eyJhdWQiOiJodHRwczovL3Byb3ZpZGUuc2VydmljZXMvYXBpL3YxIiwiZXhwIjoxNTk5OTI1NDI4LCJpYXQiOjE1OTk4MzkwMjgsImlzcyI6Imh0dHBzOi8vaWRlbnQucHJvdmlkZS5zZXJ2aWNlcyIsImp0aSI6IjJmZjE2YzczLTczOWItNDFmZi04MTM1LTM1NTQxOWY2M2RiMCIsIm5hdHMiOnsicGVybWlzc2lvbnMiOnsic3Vic2NyaWJlIjp7ImFsbG93IjpbInVzZXIuNGM1ZDI5NjktYTQwYy00ZjZkLWFhMDItMjEzNTVmM2M5MDkxIiwibmV0d29yay4qLmNvbm5lY3Rvci4qIiwibmV0d29yay4qLnN0YXR1cyIsInBsYXRmb3JtLlx1MDAzZSJdfX19LCJwcnZkIjp7InBlcm1pc3Npb25zIjo3NTUzLCJ1c2VyX2lkIjoiNGM1ZDI5NjktYTQwYy00ZjZkLWFhMDItMjEzNTVmM2M5MDkxIn0sInN1YiI6InVzZXI6NGM1ZDI5NjktYTQwYy00ZjZkLWFhMDItMjEzNTVmM2M5MDkxIn0.YlS8eQA1b9GjWhHjef08m0UQFg6nyQgvw34fPCEglfp48wWlLAwnLOmVZT0O3nHAf5f9XJljjLchGkS_vBqzs6xy39Paq81ywxJLU5PdNJFY13bhVjwTJCGWzL2pE8T5by2zaDHEjrsYfCr32ZY0o94pTzQEJ7f0TvjnyuE3l3B584u50d5gss_MOpf44-kOcX6T0KQwJmKA1rCWNrMQ4Hh3i1B-LoysGcOJhDJpuHCD6loijNIxvkjndQ2PeQXHqZ4ZKr0p4pIsexYflLdT1Szl59lpFipgCTomPVYAmBZX0MfZPlt30Pp62ANDs4qttH7-OrnK4m2_p6yeYGiRsf7TUj9NAYdHVetEYeu8oSgpQfmr0Z3jTxXFEY9t1cBPMB5zyBwzCMsTVjlG3xhGxr9SQ26uheMy7M-u9_8Kq-riZv2W79ALm22MSyYi7y0UeC3wG-hO8jrxns3kzV4heI3upwhXS2ccEZrpWbJe4S17egjpEDYAI3JIuWkggEzr_snB8xCV1-ZB2_r6aqdfmsj3QIZQK4U2c6Wa27NBA4hzE45qp_RMyiY7PZOzv0315TYa6qrio2qyUWRr29nHPOEAufg9L-aMYVKBOieL8VIWKw3RBVSDABN1sFWbFfiX0Pd5jny7zMxjHtoae5B-jgAzijIcH7xnvzkCBIySlhI' \
-H 'Content-Type: application/json' \
https://vault.provide.services/api/v1/unseal \
-d '{
"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"
}'
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.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.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 |
Documentation forthcoming.
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.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 |
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 1yr ago