Why envelope encryption?

Storing secrets encrypted with a single key creates a single point of failure. If that key is compromised, every secret is exposed. Vault uses envelope encryption to limit the blast radius of any key compromise. Each credential is encrypted with its own data encryption key (DEK), and DEKs are themselves encrypted by tenant-scoped key encryption keys (KEKs).

The three-layer hierarchy

Vault’s encryption uses three layers of keys:

Root Key — The top-level key, stored in a hardware security module (HSM) or a cloud KMS provider. It never leaves the secure boundary. The root key encrypts tenant KEKs.

Key Encryption Key (KEK) — Each tenant has its own KEK, derived from the root key using the tenant ID as input. The KEK encrypts the DEKs for that tenant’s credentials. If a tenant is deleted, their KEK is destroyed and all their credential ciphertext becomes unrecoverable.

Data Encryption Key (DEK) — Each credential has its own DEK, generated as a random 256-bit key when the credential is created. The DEK encrypts the credential value using AES-256-GCM. The DEK is then encrypted (wrapped) with the tenant’s KEK and stored alongside the ciphertext.

Encryption process

When a credential is stored:

1. Vault generates a random 256-bit DEK and a random 96-bit initialization vector (IV).
2. The credential value is encrypted with AES-256-GCM using the DEK and IV, producing ciphertext and a 128-bit authentication tag.
3. The DEK is encrypted (wrapped) with the tenant’s KEK using AES-256-GCM, producing a wrapped DEK.
4. Vault stores the wrapped DEK, IV, ciphertext, and authentication tag together as the encryption envelope.

{
  "envelope": {
    "wrappedDek": "base64...",
    "iv": "base64...",
    "ciphertext": "base64...",
    "authTag": "base64...",
    "algorithm": "aes-256-gcm",
    "kekVersion": 1
  }
}

Decryption process

When a lease is granted:

1. Vault retrieves the encryption envelope for the credential.
2. The wrapped DEK is decrypted using the tenant’s KEK (which itself is derived from the root key).
3. The credential value is decrypted using the unwrapped DEK, IV, and authentication tag.
4. The plaintext credential value is returned to the caller over a TLS connection.
5. The unwrapped DEK is held only in memory for the duration of the decryption operation and is zeroed afterward.

Key rotation

KEK rotation is performed per tenant. When a tenant’s KEK is rotated:

1. A new KEK version is derived from the root key.
2. All DEKs for that tenant are unwrapped with the old KEK and re-wrapped with the new KEK.
3. The credential ciphertext itself does not change, because the DEKs remain the same. Only the DEK wrapping changes.
4. The old KEK version is marked as retired and retained only for audit verification purposes.

This design means KEK rotation is fast. It rewraps DEKs without re-encrypting credential values, so even tenants with thousands of credentials can rotate their KEK in seconds.

Cryptographic choices

Parameter	Value
Cipher	AES-256-GCM
DEK size	256 bits
IV size	96 bits (per NIST SP 800-38D)
Auth tag size	128 bits
KEK derivation	HKDF-SHA-256 with tenant ID
Root key storage	HSM or cloud KMS

For more on how these encryption boundaries map to organizational separation, see Tenant Isolation.