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

View Source

Caching Cryptographic Materials Manager implementation.

The Caching CMM wraps another CMM and caches cryptographic materials to reduce expensive calls to key providers. It provides:

  • Performance: Caches generated data keys and EDKs
  • Security: Enforces key rotation via TTL and usage limits
  • Sharing: Multiple Caching CMMs can share cache via Partition IDs

Example

# Create cache
{:ok, cache} = LocalCache.start_link([])

# Create caching CMM with keyring
{:ok, keyring} = RawAes.new("ns", "key", key_bytes, :aes_256_gcm)
cmm = Caching.new_with_keyring(keyring, cache, max_age: 300)

# Or wrap an existing CMM
default_cmm = Default.new(keyring)
cmm = Caching.new(default_cmm, cache, max_age: 300)

Spec Reference

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

Summary

Types

cache()
t()

Functions

new(underlying_cmm, cache, opts)

Creates a new Caching CMM wrapping an existing CMM.

new_with_keyring(keyring, cache, opts)

Creates a new Caching CMM from a keyring.

Types

cache()

@type cache() :: AwsEncryptionSdk.Cache.LocalCache.t()

t()

@type t() :: %AwsEncryptionSdk.Cmm.Caching{
  cache: cache(),
  max_age: pos_integer(),
  max_bytes: non_neg_integer(),
  max_messages: non_neg_integer(),
  partition_id: binary(),
  underlying_cmm: AwsEncryptionSdk.Cmm.Behaviour.t()
}

Functions

new(underlying_cmm, cache, opts)

@spec new(AwsEncryptionSdk.Cmm.Behaviour.t(), cache(), keyword()) :: t()

Creates a new Caching CMM wrapping an existing CMM.

Parameters

  • underlying_cmm - The CMM to wrap (Default, RequiredEncryptionContext, etc.)
  • cache - A CMC implementation (e.g., LocalCache pid)
  • opts - Options:
    • :max_age - Required. TTL in seconds (must be > 0)
    • :partition_id - Optional. UUID for cache partitioning (auto-generated if omitted)
    • :max_bytes - Optional. Maximum bytes to encrypt per entry (default: 2^63-1)
    • :max_messages - Optional. Maximum messages per entry (default: 2^32)

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> {:ok, cache} = AwsEncryptionSdk.Cache.LocalCache.start_link([])
iex> cmm = AwsEncryptionSdk.Cmm.Caching.new(default_cmm, cache, max_age: 300)
iex> is_struct(cmm, AwsEncryptionSdk.Cmm.Caching)
true

new_with_keyring(keyring, cache, opts)

@spec new_with_keyring(AwsEncryptionSdk.Cmm.Default.keyring(), cache(), keyword()) ::
  t()

Creates a new Caching CMM from a keyring.

The keyring is automatically wrapped in a Default CMM.

Parameters

  • keyring - A keyring struct
  • cache - A CMC implementation
  • opts - Same as new/3

Examples

iex> key = :crypto.strong_rand_bytes(32)
iex> {:ok, keyring} = AwsEncryptionSdk.Keyring.RawAes.new("ns", "key", key, :aes_256_gcm)
iex> {:ok, cache} = AwsEncryptionSdk.Cache.LocalCache.start_link([])
iex> cmm = AwsEncryptionSdk.Cmm.Caching.new_with_keyring(keyring, cache, max_age: 300)
iex> is_struct(cmm, AwsEncryptionSdk.Cmm.Caching)
true