aes.h — AES-GCM, AES-CBC, AES-CCM

AES-128, AES-192, and AES-256 are all supported across all three modes. AES-GCM and AES-CCM are authenticated encryption modes — they produce an authentication tag alongside the ciphertext. AES-CBC provides confidentiality only. TLS_AES_BLOCK_SIZE, TLS_AES_IV_SIZE, and TLS_AES_AUTH_TAG_SIZE are all 16 bytes.

Context API

bool tls_aes_init(struct tls_aes_context *ctx, uint8_t mode, const uint8_t *key, size_t key_len, const uint8_t *iv, size_t iv_len)

Initialize an AES context for a single message. Must be called before any other context operation. A new call is required per message — context reuse across messages is not supported. The context is caller-allocated and stack-safe.

Parameters:
  • ctx – Caller-allocated AES context.

  • mode – TLS_AES_GCM, TLS_AES_CBC, or TLS_AES_CCM.

  • key – AES key (16, 24, or 32 bytes for AES-128/192/256).

  • key_len – Length of key in bytes.

  • iv – Initialization vector (16 bytes for GCM/CBC).

  • iv_len – Length of iv in bytes.

Returns:

true on success, false on invalid parameters.

bool tls_aes_update_aad(struct tls_aes_context *ctx, const uint8_t *aad, size_t aad_len)

Feed associated data (AAD) into a GCM or CCM context. Must be called after tls_aes_init() and before any encrypt/decrypt call. AAD is authenticated but not encrypted. Not applicable to CBC.

Parameters:
  • ctx – Initialized AES context.

  • aad – Associated data buffer.

  • aad_len – Length of associated data.

Returns:

true on success, false if the context state does not permit AAD (e.g. encrypt/decrypt already started).

bool tls_aes_encrypt(struct tls_aes_context *ctx, const uint8_t *inbuf, size_t in_len, uint8_t *outbuf)

Encrypt a block of data. May be called multiple times (streaming). For GCM/CCM, call tls_aes_digest() after the final chunk to retrieve the authentication tag.

Parameters:
  • ctx – Initialized AES context.

  • inbuf – Plaintext input.

  • in_len – Length of plaintext.

  • outbuf – Ciphertext output buffer (must be at least in_len bytes).

Returns:

true on success, false on error.

bool tls_aes_decrypt(struct tls_aes_context *ctx, const uint8_t *inbuf, size_t in_len, uint8_t *outbuf)

Decrypt a block of data. For authenticated modes (GCM/CCM), always verify the tag with tls_aes_verify() before calling this — decrypting unauthenticated ciphertext is a security error.

Parameters:
  • ctx – Initialized AES context.

  • inbuf – Ciphertext input.

  • in_len – Length of ciphertext.

  • outbuf – Plaintext output buffer (must be at least in_len bytes).

Returns:

true on success, false on error.

bool tls_aes_digest(struct tls_aes_context *ctx, uint8_t *digest)

Retrieve the authentication tag from a GCM or CCM context after all encrypt/decrypt chunks have been fed. The tag is TLS_AES_AUTH_TAG_SIZE (16) bytes.

Parameters:
  • ctx – Initialized AES context after all data has been processed.

  • digest – Output buffer for the authentication tag (16 bytes).

Returns:

true on success, false if the context is not in a state that permits tag retrieval.

bool tls_aes_verify(struct tls_aes_context *ctx, const uint8_t *aad, size_t aad_len, const uint8_t *ciphertext, size_t ciphertext_len, const uint8_t *tag)

Authenticate ciphertext and AAD against a tag without decrypting. For security, always call this before tls_aes_decrypt() on authenticated modes. Does not produce plaintext.

Parameters:
  • ctx – Initialized AES context.

  • aad – Associated data (NULL if none).

  • aad_len – Length of associated data (0 if none).

  • ciphertext – Ciphertext to authenticate.

  • ciphertext_len – Length of ciphertext.

  • tag – Expected authentication tag.

Returns:

true if the tag is valid, false if authentication fails.

CCM initialization

bool tls_aes_ccm_init(struct tls_aes_context *ctx, const uint8_t *key, size_t key_len, const uint8_t *nonce, size_t nonce_len, uint8_t tag_len, size_t msg_len, size_t aad_len)

Initialize an AES-CCM context for use with the common AES update, encrypt/decrypt, digest, and verify functions. Total msg_len and aad_len must be known up front.

Parameters:
  • ctx – Caller-allocated AES context.

  • key – AES key (16, 24, or 32 bytes).

  • key_len – Length of key.

  • nonce – CCM nonce (7–13 bytes).

  • nonce_len – Length of nonce.

  • tag_len – Authentication tag length in bytes (4, 6, 8, 10, 12, 14, or 16).

  • msg_len – Total plaintext/ciphertext length.

  • aad_len – Total associated data length.

Returns:

true on success, false on invalid parameters.

Examples

Context-based (streaming) GCM encrypt:

struct tls_aes_context ctx;

tls_aes_init(&ctx, TLS_AES_GCM, key, key_len, iv, iv_len);
tls_aes_update_aad(&ctx, aad, aad_len);   /* optional */
tls_aes_encrypt(&ctx, plaintext, pt_len, ciphertext);
uint8_t tag[TLS_AES_AUTH_TAG_SIZE];
tls_aes_digest(&ctx, tag);

GCM decrypt — verify before decrypting:

tls_aes_init(&ctx, TLS_AES_GCM, key, key_len, iv, iv_len);
if (tls_aes_verify(&ctx, aad, aad_len, ciphertext, ct_len, tag)) {
    tls_aes_decrypt(&ctx, ciphertext, ct_len, plaintext);
}

CCM using the common AES operations:

/* Encrypt. tls_aes_digest writes 16 bytes; transmit the configured prefix. */
tls_aes_ccm_init(&ctx, key, key_len, nonce, nonce_len,
                 tag_len, pt_len, aad_len);
tls_aes_update_aad(&ctx, aad, aad_len);
tls_aes_encrypt(&ctx, plaintext, pt_len, ciphertext);
tls_aes_digest(&ctx, full_tag);

/* Decrypt only after the authentication-only pass succeeds. */
tls_aes_ccm_init(&ctx, key, key_len, nonce, nonce_len,
                 tag_len, ct_len, aad_len);
if (tls_aes_verify(&ctx, aad, aad_len, ciphertext, ct_len, tag)) {
    tls_aes_decrypt(&ctx, ciphertext, ct_len, plaintext);
}