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

View Source

Materials required for encryption operations.

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

Summary

Types

t()

Functions

add_encrypted_data_key(materials, edk)

Adds an encrypted data key to the materials.

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

Creates new encryption materials with plaintext data key and encrypted data keys.

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

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

set_plaintext_data_key(materials, key)

Sets the plaintext data key on encryption materials.

Types

t()

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

Functions

add_encrypted_data_key(materials, edk)

@spec add_encrypted_data_key(t(), AwsEncryptionSdk.Materials.EncryptedDataKey.t()) ::
  t()

Adds an encrypted data key to the materials.

Used by keyrings after encrypting the data key.

Examples

iex> suite = AwsEncryptionSdk.AlgorithmSuite.aes_256_gcm_hkdf_sha512_commit_key()
iex> materials = AwsEncryptionSdk.Materials.EncryptionMaterials.new_for_encrypt(suite, %{})
iex> edk = AwsEncryptionSdk.Materials.EncryptedDataKey.new("test", "info", <<1, 2, 3>>)
iex> updated = AwsEncryptionSdk.Materials.EncryptionMaterials.add_encrypted_data_key(materials, edk)
iex> length(updated.encrypted_data_keys)
1

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

@spec new(
  AwsEncryptionSdk.AlgorithmSuite.t(),
  map(),
  [AwsEncryptionSdk.Materials.EncryptedDataKey.t()],
  binary(),
  keyword()
) :: t()

Creates new encryption materials with plaintext data key and encrypted data keys.

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

Parameters

  • algorithm_suite - Algorithm suite to use
  • encryption_context - Encryption context map
  • encrypted_data_keys - List of encrypted data keys
  • plaintext_data_key - Raw data key bytes
  • opts - Optional fields (:signing_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> edk = AwsEncryptionSdk.Materials.EncryptedDataKey.new("test", "info", <<1, 2, 3>>)
iex> materials = AwsEncryptionSdk.Materials.EncryptionMaterials.new(suite, %{}, [edk], key)
iex> is_binary(materials.plaintext_data_key)
true

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

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

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

The keyring will generate and set the plaintext_data_key during on_encrypt.

Parameters

  • algorithm_suite - Algorithm suite to use
  • encryption_context - Encryption context map
  • opts - Optional fields (:signing_key, :required_encryption_context_keys)

Examples

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

set_plaintext_data_key(materials, key)

@spec set_plaintext_data_key(t(), binary()) :: t()

Sets the plaintext data key on encryption materials.

Used by keyrings after generating a data key.

Examples

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