AwsEncryptionSdk.AlgorithmSuite (AWS Encryption SDK v0.7.0)

View Source

Algorithm suite definitions for the AWS Encryption SDK.

Each algorithm suite defines the cryptographic algorithms and parameters used for encryption and decryption operations. The SDK supports 11 ESDK algorithm suites across three categories:

  • Committed suites (recommended): 0x0578, 0x0478 - Include key commitment
  • Legacy HKDF suites: 0x0378, 0x0346, 0x0214, 0x0178, 0x0146, 0x0114
  • Deprecated NO_KDF suites (decrypt only): 0x0078, 0x0046, 0x0014

Default Suite

The default and recommended suite is 0x0578 (AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384), which provides:

  • AES-256-GCM encryption
  • HKDF-SHA512 key derivation
  • Key commitment for enhanced security
  • ECDSA P-384 message signing

Summary

Types

encryption_algorithm()

Encryption algorithm for AES-GCM operations

kdf_hash()

Hash algorithm for KDF operations

kdf_type()

Key derivation function type

signature_algorithm()

ECDSA signature algorithm

signature_hash()

Hash algorithm for signature operations

suite_id()

Algorithm suite identifier (2-byte big-endian integer)

t()

Algorithm suite struct containing all cryptographic parameters.

Functions

aes_128_gcm_iv12_tag16_hkdf_sha256()

Returns the AES_128_GCM_IV12_TAG16_HKDF_SHA256 suite (0x0114).

aes_128_gcm_iv12_tag16_hkdf_sha256_ecdsa_p256()

Returns the AES_128_GCM_IV12_TAG16_HKDF_SHA256_ECDSA_P256 suite (0x0214).

aes_128_gcm_iv12_tag16_no_kdf()

Returns the AES_128_GCM_IV12_TAG16_NO_KDF suite (0x0014).

aes_192_gcm_iv12_tag16_hkdf_sha256()

Returns the AES_192_GCM_IV12_TAG16_HKDF_SHA256 suite (0x0146).

aes_192_gcm_iv12_tag16_hkdf_sha384_ecdsa_p384()

Returns the AES_192_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384 suite (0x0346).

aes_192_gcm_iv12_tag16_no_kdf()

Returns the AES_192_GCM_IV12_TAG16_NO_KDF suite (0x0046).

aes_256_gcm_hkdf_sha512_commit_key()

Returns the AES_256_GCM_HKDF_SHA512_COMMIT_KEY suite (0x0478).

aes_256_gcm_hkdf_sha512_commit_key_ecdsa_p384()

Returns the AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384 suite (0x0578).

aes_256_gcm_iv12_tag16_hkdf_sha256()

Returns the AES_256_GCM_IV12_TAG16_HKDF_SHA256 suite (0x0178).

aes_256_gcm_iv12_tag16_hkdf_sha384_ecdsa_p384()

Returns the AES_256_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384 suite (0x0378).

aes_256_gcm_iv12_tag16_no_kdf()

Returns the AES_256_GCM_IV12_TAG16_NO_KDF suite (0x0078).

allows_encryption?(suite)

Returns true if the suite can be used for encryption.

by_id(arg1)

Looks up an algorithm suite by its ID.

committed?(algorithm_suite)

Returns true if the suite uses key commitment.

default()

Returns the default algorithm suite (0x0578).

deprecated?(algorithm_suite)

Returns true if the suite is deprecated.

signed?(algorithm_suite)

Returns true if the suite uses message signing.

Types

encryption_algorithm()

@type encryption_algorithm() :: :aes_128_gcm | :aes_192_gcm | :aes_256_gcm

Encryption algorithm for AES-GCM operations

kdf_hash()

@type kdf_hash() :: :sha256 | :sha384 | :sha512 | nil

Hash algorithm for KDF operations

kdf_type()

@type kdf_type() :: :hkdf | :identity

Key derivation function type

signature_algorithm()

@type signature_algorithm() :: :ecdsa_p256 | :ecdsa_p384 | nil

ECDSA signature algorithm

signature_hash()

@type signature_hash() :: :sha256 | :sha384 | nil

Hash algorithm for signature operations

suite_id()

@type suite_id() :: non_neg_integer()

Algorithm suite identifier (2-byte big-endian integer)

t()

@type t() :: %AwsEncryptionSdk.AlgorithmSuite{
  auth_tag_length: 16,
  commitment_length: 0 | 32,
  data_key_length: 128 | 192 | 256,
  encryption_algorithm: encryption_algorithm(),
  id: suite_id(),
  iv_length: 12,
  kdf_hash: kdf_hash(),
  kdf_input_length: pos_integer(),
  kdf_type: kdf_type(),
  message_format_version: 1 | 2,
  name: String.t(),
  signature_algorithm: signature_algorithm(),
  signature_hash: signature_hash(),
  suite_data_length: 0 | 32
}

Algorithm suite struct containing all cryptographic parameters.

Fields

  • :id - Suite identifier (e.g., 0x0578)
  • :name - Human-readable name
  • :message_format_version - Message format version (1 or 2)
  • :encryption_algorithm - AES-GCM variant for Erlang :crypto
  • :data_key_length - Data key length in bits (128, 192, or 256)
  • :iv_length - Initialization vector length in bytes (always 12)
  • :auth_tag_length - Authentication tag length in bytes (always 16)
  • :kdf_type - Key derivation function (:hkdf or :identity)
  • :kdf_hash - Hash algorithm for HKDF (nil for identity KDF)
  • :kdf_input_length - KDF input key length in bytes
  • :signature_algorithm - ECDSA curve (nil if unsigned)
  • :signature_hash - Hash for signatures (nil if unsigned)
  • :suite_data_length - Suite data in header (32 for committed, 0 otherwise)
  • :commitment_length - Commitment key length (32 for committed, 0 otherwise)

Functions

aes_128_gcm_iv12_tag16_hkdf_sha256()

@spec aes_128_gcm_iv12_tag16_hkdf_sha256() :: t()

Returns the AES_128_GCM_IV12_TAG16_HKDF_SHA256 suite (0x0114).

A legacy 128-bit suite without message signing.

aes_128_gcm_iv12_tag16_hkdf_sha256_ecdsa_p256()

@spec aes_128_gcm_iv12_tag16_hkdf_sha256_ecdsa_p256() :: t()

Returns the AES_128_GCM_IV12_TAG16_HKDF_SHA256_ECDSA_P256 suite (0x0214).

A legacy 128-bit suite with ECDSA P-256 message signing.

aes_128_gcm_iv12_tag16_no_kdf()

@spec aes_128_gcm_iv12_tag16_no_kdf() :: t()

Returns the AES_128_GCM_IV12_TAG16_NO_KDF suite (0x0014).

DEPRECATED: This suite does not use key derivation and should only be used for decrypting legacy messages. Use a committed suite for new encryptions.

aes_192_gcm_iv12_tag16_hkdf_sha256()

@spec aes_192_gcm_iv12_tag16_hkdf_sha256() :: t()

Returns the AES_192_GCM_IV12_TAG16_HKDF_SHA256 suite (0x0146).

A legacy 192-bit suite without message signing.

aes_192_gcm_iv12_tag16_hkdf_sha384_ecdsa_p384()

@spec aes_192_gcm_iv12_tag16_hkdf_sha384_ecdsa_p384() :: t()

Returns the AES_192_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384 suite (0x0346).

A legacy 192-bit suite with message signing.

aes_192_gcm_iv12_tag16_no_kdf()

@spec aes_192_gcm_iv12_tag16_no_kdf() :: t()

Returns the AES_192_GCM_IV12_TAG16_NO_KDF suite (0x0046).

DEPRECATED: This suite does not use key derivation and should only be used for decrypting legacy messages. Use a committed suite for new encryptions.

aes_256_gcm_hkdf_sha512_commit_key()

@spec aes_256_gcm_hkdf_sha512_commit_key() :: t()

Returns the AES_256_GCM_HKDF_SHA512_COMMIT_KEY suite (0x0478).

A committed suite without message signing:

  • AES-256-GCM encryption
  • HKDF-SHA512 key derivation with 32-byte input
  • Key commitment (32 bytes)
  • No message signing

aes_256_gcm_hkdf_sha512_commit_key_ecdsa_p384()

@spec aes_256_gcm_hkdf_sha512_commit_key_ecdsa_p384() :: t()

Returns the AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384 suite (0x0578).

This is the recommended suite providing:

  • AES-256-GCM encryption
  • HKDF-SHA512 key derivation with 32-byte input
  • Key commitment (32 bytes)
  • ECDSA P-384 message signing

aes_256_gcm_iv12_tag16_hkdf_sha256()

@spec aes_256_gcm_iv12_tag16_hkdf_sha256() :: t()

Returns the AES_256_GCM_IV12_TAG16_HKDF_SHA256 suite (0x0178).

A common legacy suite without signing or commitment:

  • AES-256-GCM encryption
  • HKDF-SHA256 key derivation
  • No key commitment
  • No message signing

aes_256_gcm_iv12_tag16_hkdf_sha384_ecdsa_p384()

@spec aes_256_gcm_iv12_tag16_hkdf_sha384_ecdsa_p384() :: t()

Returns the AES_256_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384 suite (0x0378).

A legacy suite with message signing (no commitment):

  • AES-256-GCM encryption
  • HKDF-SHA384 key derivation
  • No key commitment
  • ECDSA P-384 message signing

aes_256_gcm_iv12_tag16_no_kdf()

@spec aes_256_gcm_iv12_tag16_no_kdf() :: t()

Returns the AES_256_GCM_IV12_TAG16_NO_KDF suite (0x0078).

DEPRECATED: This suite does not use key derivation and should only be used for decrypting legacy messages. Use a committed suite for new encryptions.

allows_encryption?(suite)

@spec allows_encryption?(t()) :: boolean()

Returns true if the suite can be used for encryption.

Deprecated suites (NO_KDF) should only be used for decryption of existing messages, not for encrypting new messages.

by_id(arg1)

@spec by_id(suite_id()) ::
  {:ok, t()} | {:error, :reserved_suite_id | :unknown_suite_id}

Looks up an algorithm suite by its ID.

Returns {:ok, suite} if found, or {:error, reason} if the ID is invalid or reserved.

Examples

iex> AwsEncryptionSdk.AlgorithmSuite.by_id(0x0578)
{:ok, %AwsEncryptionSdk.AlgorithmSuite{id: 0x0578}}

iex> AwsEncryptionSdk.AlgorithmSuite.by_id(0x0000)
{:error, :reserved_suite_id}

iex> AwsEncryptionSdk.AlgorithmSuite.by_id(0x9999)
{:error, :unknown_suite_id}

Note: Accessing deprecated suites (NO_KDF) will log a warning.

committed?(algorithm_suite)

@spec committed?(t()) :: boolean()

Returns true if the suite uses key commitment.

Committed suites (0x0478, 0x0578) use message format version 2 and include a 32-byte commitment value that binds the data key to the message.

default()

@spec default() :: t()

Returns the default algorithm suite (0x0578).

The default suite is AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384, which provides the highest level of security with key commitment and message signing.

deprecated?(algorithm_suite)

@spec deprecated?(t()) :: boolean()

Returns true if the suite is deprecated.

Deprecated suites are the NO_KDF suites (0x0014, 0x0046, 0x0078) which do not use key derivation. These should only be used for decrypting legacy messages.

signed?(algorithm_suite)

@spec signed?(t()) :: boolean()

Returns true if the suite uses message signing.

Signed suites include an ECDSA signature in the message footer that authenticates the entire message.