@spec decrypt(t(), binary(), decrypt_opts()) ::
  {:ok, AwsEncryptionSdk.Decrypt.decrypt_result()} | {:error, term()}

Decrypts ciphertext using the client's CMM and commitment policy.

This is the primary decryption API that enforces commitment policy and integrates with the CMM to obtain decryption materials.

Parameters

• client - Client configuration with CMM and policy
• ciphertext - Complete encrypted message (header + body + footer)
• opts - Options:
  • :encryption_context - Reproduced context to validate against (default: nil)

Returns

• {:ok, result} - Decryption succeeded with %{plaintext: binary, encryption_context: map, algorithm_suite: AlgorithmSuite.t(), header: Header.t()}
• {:error, reason} - Decryption failed

Errors

• :commitment_policy_requires_committed_suite - Non-committed suite with strict policy
• :too_many_encrypted_data_keys - EDK count exceeds limit
• :base64_encoded_message - Message appears to be Base64 encoded
• Other errors from CMM, keyring, or decryption operations

Examples

# Decrypt with default strict policy
{:ok, result} = Client.decrypt(client, ciphertext)

# Decrypt with reproduced encryption context validation
{:ok, result} = Client.decrypt(client, ciphertext,
  encryption_context: %{"purpose" => "example"}
)

@spec decrypt_with_keyring(
  AwsEncryptionSdk.Cmm.Default.keyring(),
  binary(),
  decrypt_opts()
) ::
  {:ok, AwsEncryptionSdk.Decrypt.decrypt_result()} | {:error, term()}

Decrypts ciphertext using a keyring directly.

Convenience function that wraps the keyring in a Default CMM before decrypting. Equivalent to creating a client with Cmm.Default.new(keyring).

Parameters

• keyring - A keyring struct (RawAes, RawRsa, or Multi)
• ciphertext - Complete encrypted message
• opts - Same options as decrypt/3, plus:
  • :commitment_policy - Override default policy
  • :max_encrypted_data_keys - Override default limit

Examples

keyring = RawAes.new("ns", "key", key_bytes, :aes_256_gcm)

{:ok, result} = Client.decrypt_with_keyring(keyring, ciphertext,
  encryption_context: %{"purpose" => "test"},
  commitment_policy: :require_encrypt_allow_decrypt
)

@spec encrypt(t(), binary(), encrypt_opts()) ::
  {:ok, AwsEncryptionSdk.Encrypt.encrypt_result()} | {:error, term()}

Encrypts plaintext using the client's CMM and commitment policy.

This is the primary encryption API that enforces commitment policy and integrates with the CMM to obtain encryption materials.

Parameters

• client - Client configuration with CMM and policy
• plaintext - Binary data to encrypt
• opts - Options:
  • :encryption_context - Key-value pairs for AAD (default: %{})
  • :algorithm_suite - Override default suite (validated against policy)
  • :frame_length - Frame size in bytes (default: 4096)

Returns

• {:ok, result} - Encryption succeeded
• {:error, reason} - Encryption failed

Errors

• :commitment_policy_requires_committed_suite - Non-committed suite with require policy
• :commitment_policy_forbids_committed_suite - Committed suite with forbid policy
• :max_encrypted_data_keys_exceeded - Too many EDKs generated
• Other errors from CMM or encryption operations

Examples

# Encrypt with default committed suite
{:ok, result} = Client.encrypt(client, "secret data",
  encryption_context: %{"purpose" => "example"}
)

# Encrypt with specific algorithm suite (must match policy)
suite = AlgorithmSuite.aes_256_gcm_hkdf_sha512_commit_key()
{:ok, result} = Client.encrypt(client, "data",
  algorithm_suite: suite
)

@spec encrypt_with_keyring(
  AwsEncryptionSdk.Cmm.Default.keyring(),
  binary(),
  encrypt_opts()
) ::
  {:ok, AwsEncryptionSdk.Encrypt.encrypt_result()} | {:error, term()}

Encrypts plaintext using a keyring directly.

Convenience function that wraps the keyring in a Default CMM before encrypting. Equivalent to creating a client with Cmm.Default.new(keyring).

Parameters

• keyring - A keyring struct (RawAes, RawRsa, or Multi)
• plaintext - Binary data to encrypt
• opts - Same options as encrypt/3, plus:
  • :commitment_policy - Override default policy
  • :max_encrypted_data_keys - Override default limit

Examples

keyring = RawAes.new("ns", "key", key_bytes, :aes_256_gcm)

{:ok, result} = Client.encrypt_with_keyring(keyring, "secret",
  encryption_context: %{"purpose" => "test"},
  commitment_policy: :require_encrypt_allow_decrypt
)

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

Creates a new Client with the given CMM and options.

Parameters

• cmm - A Cryptographic Materials Manager (required)
• opts - Options (optional):
  • :commitment_policy - One of :forbid_encrypt_allow_decrypt, :require_encrypt_allow_decrypt, :require_encrypt_require_decrypt (default: :require_encrypt_require_decrypt)
  • :max_encrypted_data_keys - Maximum number of EDKs allowed (default: nil for unlimited)

Examples

iex> key = :crypto.strong_rand_bytes(32)
iex> {:ok, keyring} = AwsEncryptionSdk.Keyring.RawAes.new("test-ns", "test-key", key, :aes_256_gcm)
iex> cmm = AwsEncryptionSdk.Cmm.Default.new(keyring)
iex> client = AwsEncryptionSdk.Client.new(cmm)
iex> client.commitment_policy
:require_encrypt_require_decrypt

iex> key = :crypto.strong_rand_bytes(32)
iex> {:ok, keyring} = AwsEncryptionSdk.Keyring.RawAes.new("test-ns", "test-key", key, :aes_256_gcm)
iex> cmm = AwsEncryptionSdk.Cmm.Default.new(keyring)
iex> client = AwsEncryptionSdk.Client.new(cmm, commitment_policy: :forbid_encrypt_allow_decrypt)
iex> client.commitment_policy
:forbid_encrypt_allow_decrypt

iex> key = :crypto.strong_rand_bytes(32)
iex> {:ok, keyring} = AwsEncryptionSdk.Keyring.RawAes.new("test-ns", "test-key", key, :aes_256_gcm)
iex> cmm = AwsEncryptionSdk.Cmm.Default.new(keyring)
iex> client = AwsEncryptionSdk.Client.new(cmm, max_encrypted_data_keys: 5)
iex> client.max_encrypted_data_keys
5