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, orTLS_AES_CCM.key – AES key (16, 24, or 32 bytes for AES-128/192/256).
key_len – Length of
keyin bytes.iv – Initialization vector (16 bytes for GCM/CBC).
iv_len – Length of
ivin bytes.
- Returns:
trueon success,falseon 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:
trueon success,falseif 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_lenbytes).
- Returns:
trueon success,falseon 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_lenbytes).
- Returns:
trueon success,falseon 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:
trueon success,falseif 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 (
NULLif none).aad_len – Length of associated data (
0if none).ciphertext – Ciphertext to authenticate.
ciphertext_len – Length of ciphertext.
tag – Expected authentication tag.
- Returns:
trueif the tag is valid,falseif 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_lenandaad_lenmust 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:
trueon success,falseon 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);
}