Sealing/Unsealing
Last updated
Last updated
Sealing/UnsealingA 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:
The following SealUnsealKeyProvider
implementations represent the various seal/unseal strategies currently supported:
Provider | Description | Unsealing |
---|---|---|
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:
¹ 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:
POST
https://vault.provide.services/api/v1/unsealerkey
Generates a seal/unseal key for seal and unsealing a
Vault
The seal/unseal __ key is returned alongside its validation hash:
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:
POST
https://vault.provide.services/api/v1/unseal
Unseals a
Vault
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:
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:
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
.
Environment Variable | Description |
---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Environment Variable | Description |
---|---|
Environment Variable | Description |
---|---|
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
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
authorization*
string
bearer scoped to an
Application
,
Organization
or
User
authorization*
string
bearer scoped to an
Application
,
Organization
or
User
unsealer_key*
string
key required to unseal
Vault
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
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