AwsEncryptionSdk.Cmm.RequiredEncryptionContext (AWS Encryption SDK v0.7.0)

View Source

Required Encryption Context CMM implementation.

This CMM wraps another CMM and enforces that specific encryption context keys are present throughout encryption and decryption operations. It provides:

  • Encryption validation: Ensures required keys exist in caller's encryption context
  • Decryption validation: Ensures required keys exist in reproduced encryption context
  • Key propagation: Marks required keys in materials for downstream tracking
  • Security enforcement: Prevents accidental removal of critical AAD components

Example

# Create with a keyring (auto-wraps in Default CMM)
{:ok, keyring} = RawAes.new("namespace", "key-name", key_bytes, :aes_256_gcm)
cmm = RequiredEncryptionContext.new_with_keyring(["tenant-id", "purpose"], keyring)

# Or wrap an existing CMM
default_cmm = Default.new(keyring)
cmm = RequiredEncryptionContext.new(["tenant-id"], default_cmm)

# Use with Client
client = Client.new(cmm)

# Encrypt - will fail if context missing required keys
{:ok, result} = Client.encrypt(client, plaintext,
  encryption_context: %{"tenant-id" => "acme", "purpose" => "backup"}
)

# Decrypt - must provide required keys in reproduced context
{:ok, decrypted} = Client.decrypt(client, result.ciphertext,
  encryption_context: %{"tenant-id" => "acme", "purpose" => "backup"}
)

Spec Reference

https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/framework/required-encryption-context-cmm.md

Summary

Types

t()

Functions

new(required_keys, underlying_cmm)

Creates a new Required Encryption Context CMM wrapping an existing CMM.

new_with_keyring(required_keys, keyring)

Creates a new Required Encryption Context CMM from a keyring.

Types

t()

@type t() :: %AwsEncryptionSdk.Cmm.RequiredEncryptionContext{
  required_encryption_context_keys: [String.t()],
  underlying_cmm: AwsEncryptionSdk.Cmm.Behaviour.t()
}

Functions

new(required_keys, underlying_cmm)

@spec new([String.t()], AwsEncryptionSdk.Cmm.Behaviour.t()) :: t()

Creates a new Required Encryption Context CMM wrapping an existing CMM.

Parameters

  • required_keys - List of encryption context keys that must be present
  • underlying_cmm - The CMM to wrap (e.g., Default CMM)

Examples

iex> key = :crypto.strong_rand_bytes(32)
iex> {:ok, keyring} = AwsEncryptionSdk.Keyring.RawAes.new("ns", "key", key, :aes_256_gcm)
iex> default_cmm = AwsEncryptionSdk.Cmm.Default.new(keyring)
iex> cmm = AwsEncryptionSdk.Cmm.RequiredEncryptionContext.new(["tenant-id"], default_cmm)
iex> cmm.required_encryption_context_keys
["tenant-id"]

new_with_keyring(required_keys, keyring)

@spec new_with_keyring([String.t()], AwsEncryptionSdk.Cmm.Default.keyring()) :: t()

Creates a new Required Encryption Context CMM from a keyring.

The keyring is automatically wrapped in a Default CMM.

Parameters

  • required_keys - List of encryption context keys that must be present
  • keyring - A keyring struct (RawAes, RawRsa, Multi, AwsKms, etc.)

Examples

iex> key = :crypto.strong_rand_bytes(32)
iex> {:ok, keyring} = AwsEncryptionSdk.Keyring.RawAes.new("ns", "key", key, :aes_256_gcm)
iex> cmm = AwsEncryptionSdk.Cmm.RequiredEncryptionContext.new_with_keyring(["tenant-id"], keyring)
iex> cmm.required_encryption_context_keys
["tenant-id"]