Stackbook Logo
security-complianceestablished · medium operational burden

Envelope Encryption

Also known as: data-key-wrapping, kms-data-keys

Intent

Encrypt large data with local data keys and protect those keys with a master key held in a KMS or HSM.

Problem

Sending all data to a KMS for encryption is slow and hits size and rate limits, while embedding a single key in the app exposes everything if it leaks. Rotating a key that directly encrypted terabytes means re-encrypting all of it.

Forces

  • •Bulk data needs fast symmetric encryption
  • •Master keys must never leave the HSM boundary
  • •Key rotation should be cheap
  • •Access to keys must be auditable and revocable

Solution

Overview

Envelope encryption uses two layers of keys. A fast symmetric DEK encrypts data; a KEK that never leaves the KMS encrypts the DEK. Cloud storage services, databases and backup tools all use this under the hood.

Cloud providers already implement this for object and disk encryption, but application-level envelope encryption adds tenant-specific control. Use well-reviewed libraries such as the AWS Encryption SDK or Tink instead of composing primitives yourself, and test the full restore path including KEK access.

How it works

encrypt(plaintext):
  dek = kms.GenerateDataKey(kekId)    # returns plaintext + wrapped copy
  nonce = random(12B)
  ct = AES-GCM(dek.plain, nonce, plaintext, aad=tenantId)
  wipe(dek.plain)
  store { ct, nonce, dek.wrapped, kekId }

decrypt(record):
  dek = kms.Decrypt(record.dek.wrapped)
  return AES-GCM-open(dek, record.nonce, record.ct, aad)

Binding additional authenticated data such as tenant id prevents moving ciphertext between tenants.

Pitfalls

  • Reusing a nonce under the same DEK. Use random nonces with per-object DEKs, or a counter.
  • Logging or persisting plaintext DEKs.
  • Scheduling KEK deletion without verifying nothing still depends on it.
  • Not caching unwrapped DEKs briefly, causing KMS throttling under load.
  • Granting the application broad Decrypt permission instead of scoping by encryption context.

Key takeaways

  • Encrypt data with local DEKs, wrap DEKs with a KMS-held KEK.
  • Rotate cheaply by re-wrapping; use per-tenant keys for crypto-shredding.
  • Bind context via AAD and key policy.
  • Plan for KMS availability and quotas.
  • Review key and token policies on a schedule, and alert on unusual access volume or new callers.
  • Run restore, rotation and failover drills so the control proves itself before an incident does.

✓ When to Use

  • •Encrypting objects, files or database fields at rest
  • •Multi-tenant systems needing per-tenant keys
  • •Compliance requiring customer-managed keys

✗ When Not to Use

  • •Small secrets better stored in a secret manager
  • •Storage already encrypted transparently with adequate controls
  • •Ultra-low-latency paths where KMS calls cannot be cached

Pros

  • +Cheap KEK rotation by re-wrapping
  • +KMS sees only small keys, not bulk data
  • +Per-tenant keys enable crypto-shredding

Cons

  • −KMS availability affects reads
  • −Metadata handling adds complexity
  • −KMS call costs and quotas

Cost Profile

Infrastructure

Medium — KMS or HSM

Operational

Medium — key policies and rotation

Cognitive

Medium

Failure Modes

  • KMS outage or throttling blocks decryption

  • Deleted KEK makes all wrapped data permanently unrecoverable

  • Nonce reuse with AES-GCM breaks confidentiality

Real-World Examples

Alternatives

    Related Patterns

      Competency Domains

      security compliancedata state