AwsEncryptionSdk.Materials.DecryptionMaterials (AWS Encryption SDK v0.7.0)

Materials required for decryption operations.

These materials are typically provided by a Cryptographic Materials Manager (CMM) or can be constructed directly for testing purposes.

Summary

Types

t()

Functions

new(algorithm_suite, encryption_context, plaintext_data_key, opts \\ [])

Creates new decryption materials with a plaintext data key.

new_for_decrypt(algorithm_suite, encryption_context, opts \\ [])

Creates decryption materials for keyring/CMM use (without plaintext data key).

set_plaintext_data_key(materials, key)

Sets the plaintext data key on decryption materials.

Types

t()

@type t() :: %AwsEncryptionSdk.Materials.DecryptionMaterials{
  algorithm_suite: AwsEncryptionSdk.AlgorithmSuite.t(),
  encryption_context: %{required(String.t()) => String.t()},
  plaintext_data_key: binary() | nil,
  required_encryption_context_keys: [String.t()],
  verification_key: binary() | nil
}

Functions

new(algorithm_suite, encryption_context, plaintext_data_key, opts \\ [])

@spec new(AwsEncryptionSdk.AlgorithmSuite.t(), map(), binary(), keyword()) :: t()

Creates new decryption materials with a plaintext data key.

Use this constructor when you already have a decrypted data key (e.g., for testing or when bypassing the keyring/CMM flow).

Parameters

algorithm_suite - Algorithm suite from message header
encryption_context - Encryption context from message header
plaintext_data_key - Decrypted data key
opts - Optional fields (:verification_key, :required_encryption_context_keys)

Examples

iex> suite = AwsEncryptionSdk.AlgorithmSuite.aes_256_gcm_hkdf_sha512_commit_key()
iex> key = :crypto.strong_rand_bytes(32)
iex> materials = AwsEncryptionSdk.Materials.DecryptionMaterials.new(suite, %{}, key)
iex> is_binary(materials.plaintext_data_key)
true

new_for_decrypt(algorithm_suite, encryption_context, opts \\ [])

@spec new_for_decrypt(AwsEncryptionSdk.AlgorithmSuite.t(), map(), keyword()) :: t()

Creates decryption materials for keyring/CMM use (without plaintext data key).

The keyring will set the plaintext_data_key during on_decrypt.

Parameters

algorithm_suite - Algorithm suite from message header
encryption_context - Encryption context from message header
opts - Optional fields (:verification_key, :required_encryption_context_keys)

Examples

iex> suite = AwsEncryptionSdk.AlgorithmSuite.aes_256_gcm_hkdf_sha512_commit_key()
iex> materials = AwsEncryptionSdk.Materials.DecryptionMaterials.new_for_decrypt(suite, %{})
iex> materials.plaintext_data_key
nil

set_plaintext_data_key(materials, key)

@spec set_plaintext_data_key(t(), binary()) ::
  {:ok, t()} | {:error, :plaintext_data_key_already_set}

Sets the plaintext data key on decryption materials.

Used by keyrings after successfully decrypting an EDK.

Returns

{:ok, updated_materials} - Data key was set
{:error, :plaintext_data_key_already_set} - Data key was already present

Examples

iex> suite = AwsEncryptionSdk.AlgorithmSuite.aes_256_gcm_hkdf_sha512_commit_key()
iex> materials = AwsEncryptionSdk.Materials.DecryptionMaterials.new_for_decrypt(suite, %{})
iex> key = :crypto.strong_rand_bytes(32)
iex> {:ok, updated} = AwsEncryptionSdk.Materials.DecryptionMaterials.set_plaintext_data_key(materials, key)
iex> updated.plaintext_data_key == key
true