Sealing/Unsealing

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).

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:

type SealUnsealKeyProvider interface {
	Seed() (*string, error)
	ValidationHash() (*string, error)
}

The following SealUnsealKeyProvider implementations represent the various seal/unseal strategies currently supported:

ProviderDescriptionUnsealing

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 VariableDescription

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:

Create Seal/Unseal Key

POST https://vault.provide.services/api/v1/unsealerkey

Generates a seal/unseal key for seal and unsealing a

Vault

Headers

NameTypeDescription

authorization*

string

bearer scoped to an

Application

,

Organization

or

User

{
    "key": "quick brown fox narrow pig company soap book broken monitor keen hover salon trophy stadium exotic potato snack exercise mutual derive quick habit where"    "validation_hash": "0x0f9c1a7217593aa8a2c5b65cedf69d4cecb26e6e20f8c5d102db0b0caf7f255b"}
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.

Unsealing

To unseal a vault after startup, use this API:

Unseal Vault

POST https://vault.provide.services/api/v1/unseal

Unseals a

Vault

Headers

NameTypeDescription

authorization*

string

bearer scoped to an

Application

,

Organization

or

User

Request Body

NameTypeDescription

unsealer_key*

string

key required to unseal

Vault

#!/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.

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 VariableDescription

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 VariableDescription

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.

PreviousReplication

Last updated