Skip to content

File syn_aes.h

FileList > crypto > syn_aes.h

Go to the source code of this file

Unified AES cipher engine (128/192/256-bit keys, ECB, CBC, CTR, and GCM AEAD). More...

  • #include "../common/syn_defs.h"
  • #include <stdbool.h>
  • #include <stddef.h>
  • #include <stdint.h>

Classes

Type Name
struct SYN_AES_Context
AES context containing expanded round keys.
struct SYN_AES_GCM_Context
AES-GCM AEAD context — wraps AES key schedule and GHASH subkey/tables.

Public Functions

Type Name
SYN_Status syn_aes_cbc_decrypt (const SYN_AES_Context * ctx, const uint8_t iv, const uint8_t * in, size_t in_len, uint8_t * out, size_t out_capacity, size_t * out_len)
Decrypt data using AES-CBC with PKCS#7 unpadding.
SYN_Status syn_aes_cbc_encrypt (const SYN_AES_Context * ctx, const uint8_t iv, const uint8_t * in, size_t in_len, uint8_t * out, size_t out_capacity, size_t * out_len)
Encrypt data using AES-CBC with PKCS#7 padding.
SYN_Status syn_aes_ccm_decrypt (const SYN_AES_Context * ctx, const uint8_t * nonce, size_t nonce_len, const uint8_t * aad, size_t aad_len, const uint8_t * in, size_t in_len, const uint8_t * tag, size_t tag_len, uint8_t * out)
AES-CCM authenticated decryption and tag verification (NIST SP 800-38C / RFC 3610).
SYN_Status syn_aes_ccm_encrypt (const SYN_AES_Context * ctx, const uint8_t * nonce, size_t nonce_len, const uint8_t * aad, size_t aad_len, const uint8_t * in, size_t in_len, uint8_t * out, uint8_t * tag, size_t tag_len)
AES-CCM authenticated encryption (NIST SP 800-38C / RFC 3610).
SYN_Status syn_aes_ctr (const SYN_AES_Context * ctx, const uint8_t nonce, const uint8_t * in, size_t len, uint8_t * out)
Encrypt/decrypt arbitrary length data using AES-CTR stream mode (NIST SP 800-38A).
void syn_aes_decrypt_block (const SYN_AES_Context * ctx, const uint8_t in, uint8_t out)
Decrypt a single 16-byte block (ECB mode).
void syn_aes_encrypt_block (const SYN_AES_Context * ctx, const uint8_t in, uint8_t out)
Encrypt a single 16-byte block (ECB mode).
SYN_Status syn_aes_gcm_decrypt (const SYN_AES_GCM_Context * ctx, const uint8_t * nonce, size_t nonce_len, const uint8_t * aad, size_t aad_len, const uint8_t * in, size_t in_len, uint8_t * out, const uint8_t tag)
AES-GCM authenticated decryption and tag verification (NIST SP 800-38D).
SYN_Status syn_aes_gcm_encrypt (const SYN_AES_GCM_Context * ctx, const uint8_t * nonce, size_t nonce_len, const uint8_t * aad, size_t aad_len, const uint8_t * in, size_t in_len, uint8_t * out, uint8_t tag)
AES-GCM authenticated encryption (NIST SP 800-38D).
SYN_Status syn_aes_gcm_init (SYN_AES_GCM_Context * ctx, const uint8_t * key, size_t key_len)
Initialize AES-GCM AEAD context (expands key and computes GHASH subkey H).
void syn_aes_ghash_mult (const uint8_t x, const uint8_t h, uint8_t out)
Multiply 16-byte block by GHASH subkey H in GF(2^128).
SYN_Status syn_aes_init (SYN_AES_Context * ctx, const uint8_t * key, size_t key_len)
Initialize AES context and perform key expansion for 128/192/256-bit key.

Macros

Type Name
define SYN_AES_BLOCK_SIZE 16U
AES cipher block size in bytes (16 bytes / 128 bits).
define SYN_AES_GCM_IV_DEFAULT_SIZE 12U
Recommended GCM initialization vector size in bytes (12 bytes / 96 bits).
define SYN_AES_GCM_TABLE 0
GCM GHASH acceleration table strategy. 0 = bit-by-bit Shoup (0 bytes table, low footprint), 4 = 4-bit nibble table (256 bytes per GCM context), 8 = 8-bit byte table (4096 bytes per GCM context).
define SYN_AES_GCM_TAG_SIZE 16U
Standard GCM authentication tag size in bytes (16 bytes / 128 bits).
define SYN_AES_KEY_SIZE_128 16U
AES-128 key size in bytes (16 bytes / 128 bits).
define SYN_AES_KEY_SIZE_192 24U
AES-192 key size in bytes (24 bytes / 192 bits).
define SYN_AES_KEY_SIZE_256 32U
AES-256 key size in bytes (32 bytes / 256 bits).
define SYN_AES_MAX_EXPANDED_KEY 240U
Maximum expanded round keys storage size in bytes.
define SYN_AES_MAX_KEY_BITS 256
Maximum key size in bits (128, 192, or 256). Controls context RAM footprint.
define SYN_AES_MAX_ROUNDS 14U
Maximum rounds for configured key size.
define SYN_USE_AES_CBC 1
Enable CBC mode encryption and decryption with PKCS#7 padding.
define SYN_USE_AES_CTR 1
Enable CTR stream cipher mode.
define SYN_USE_AES_DECRYPT 1
Enable ECB and CBC decryption functions (pulls rsbox, +256B Flash).
define SYN_USE_AES_GCM 1
Enable GCM AEAD authenticated encryption and decryption.

Detailed Description

Zero-heap, constant-time implementation supporting AES-128, AES-192, and AES-256 with configurable compile-time memory footprint guardrails.

Public Functions Documentation

function syn_aes_cbc_decrypt

Decrypt data using AES-CBC with PKCS#7 unpadding. 

SYN_Status syn_aes_cbc_decrypt (
    const SYN_AES_Context * ctx,
    const uint8_t iv,
    const uint8_t * in,
    size_t in_len,
    uint8_t * out,
    size_t out_capacity,
    size_t * out_len
)

Parameters:

  • ctx Initialized AES context.
  • iv 16-byte initialization vector.
  • in Ciphertext buffer (must be non-empty multiple of 16 bytes).
  • in_len Ciphertext length in bytes.
  • out Plaintext output buffer.
  • out_capacity Capacity of plaintext output buffer.
  • out_len Number of plaintext bytes written.

Returns:

SYN_OK on success, or SYN_INVALID_PARAM on invalid padding or parameters.

function syn_aes_cbc_encrypt

Encrypt data using AES-CBC with PKCS#7 padding. 

SYN_Status syn_aes_cbc_encrypt (
    const SYN_AES_Context * ctx,
    const uint8_t iv,
    const uint8_t * in,
    size_t in_len,
    uint8_t * out,
    size_t out_capacity,
    size_t * out_len
)

Parameters:

  • ctx Initialized AES context.
  • iv 16-byte initialization vector.
  • in Plaintext buffer (may be NULL if in_len is 0).
  • in_len Plaintext length in bytes.
  • out Ciphertext output buffer.
  • out_capacity Maximum capacity of output buffer (must be >= in_len + PKCS#7 pad).
  • out_len Number of ciphertext bytes written.

Returns:

SYN_OK on success, or SYN_INVALID_PARAM on failure.

function syn_aes_ccm_decrypt

AES-CCM authenticated decryption and tag verification (NIST SP 800-38C / RFC 3610). 

SYN_Status syn_aes_ccm_decrypt (
    const SYN_AES_Context * ctx,
    const uint8_t * nonce,
    size_t nonce_len,
    const uint8_t * aad,
    size_t aad_len,
    const uint8_t * in,
    size_t in_len,
    const uint8_t * tag,
    size_t tag_len,
    uint8_t * out
)

Decrypts ciphertext in CTR mode and verifies CBC-MAC authentication tag in constant time. If verification fails, plaintext buffer is zeroed (if out != in) and SYN_ERROR is returned.

Parameters:

  • ctx Initialized AES context.
  • nonce Nonce buffer (length must be 7..13 bytes).
  • nonce_len Nonce length in bytes (7 to 13).
  • aad Additional authenticated data (may be NULL if aad_len is 0).
  • aad_len AAD length in bytes.
  • in Ciphertext buffer to decrypt (may be NULL if in_len is 0).
  • in_len Ciphertext length in bytes.
  • tag Authentication tag to verify against.
  • tag_len Length of authentication tag in bytes (4, 6, 8, 10, 12, 14, or 16).
  • out Plaintext output buffer (must be at least in_len bytes).

Returns:

SYN_OK on success, SYN_ERROR on tag mismatch, or SYN_INVALID_PARAM on invalid params.

function syn_aes_ccm_encrypt

AES-CCM authenticated encryption (NIST SP 800-38C / RFC 3610). 

SYN_Status syn_aes_ccm_encrypt (
    const SYN_AES_Context * ctx,
    const uint8_t * nonce,
    size_t nonce_len,
    const uint8_t * aad,
    size_t aad_len,
    const uint8_t * in,
    size_t in_len,
    uint8_t * out,
    uint8_t * tag,
    size_t tag_len
)

Computes CBC-MAC authentication tag and encrypts payload in CTR mode.

Parameters:

  • ctx Initialized AES context.
  • nonce Nonce buffer (length must be 7..13 bytes).
  • nonce_len Nonce length in bytes (7 to 13).
  • aad Additional authenticated data (may be NULL if aad_len is 0).
  • aad_len AAD length in bytes.
  • in Plaintext buffer to encrypt (may be NULL if in_len is 0).
  • in_len Plaintext length in bytes.
  • out Ciphertext output buffer (must be at least in_len bytes).
  • tag Authentication tag output buffer.
  • tag_len Length of authentication tag in bytes (4, 6, 8, 10, 12, 14, or 16).

Returns:

SYN_OK on success, or SYN_INVALID_PARAM on invalid parameters.

function syn_aes_ctr

Encrypt/decrypt arbitrary length data using AES-CTR stream mode (NIST SP 800-38A). 

SYN_Status syn_aes_ctr (
    const SYN_AES_Context * ctx,
    const uint8_t nonce,
    const uint8_t * in,
    size_t len,
    uint8_t * out
)

Parameters:

  • ctx Initialized AES context.
  • nonce 16-byte initial counter block (incremented as 128-bit big-endian).
  • in Input data buffer (plaintext for encrypt, ciphertext for decrypt).
  • len Length of input and output data in bytes.
  • out Output data buffer.

Returns:

SYN_OK on success, or SYN_INVALID_PARAM on NULL pointers.

function syn_aes_decrypt_block

Decrypt a single 16-byte block (ECB mode). 

void syn_aes_decrypt_block (
    const SYN_AES_Context * ctx,
    const uint8_t in,
    uint8_t out
)

Parameters:

  • ctx Initialized AES context.
  • in 16-byte ciphertext input block.
  • out 16-byte plaintext output block.

function syn_aes_encrypt_block

Encrypt a single 16-byte block (ECB mode). 

void syn_aes_encrypt_block (
    const SYN_AES_Context * ctx,
    const uint8_t in,
    uint8_t out
)

Parameters:

  • ctx Initialized AES context.
  • in 16-byte plaintext input block.
  • out 16-byte ciphertext output block.

function syn_aes_gcm_decrypt

AES-GCM authenticated decryption and tag verification (NIST SP 800-38D). 

SYN_Status syn_aes_gcm_decrypt (
    const SYN_AES_GCM_Context * ctx,
    const uint8_t * nonce,
    size_t nonce_len,
    const uint8_t * aad,
    size_t aad_len,
    const uint8_t * in,
    size_t in_len,
    uint8_t * out,
    const uint8_t tag
)

Decrypts ciphertext and verifies the authentication tag in constant time. If authentication fails, plaintext output is zeroed and SYN_AUTH_FAILED is returned.

Parameters:

  • ctx Initialized AES-GCM context.
  • nonce Initialization vector / nonce buffer.
  • nonce_len Nonce length in bytes.
  • aad Additional authenticated data (may be NULL if aad_len is 0).
  • aad_len AAD length in bytes.
  • in Ciphertext buffer to decrypt (may be NULL if in_len is 0).
  • in_len Ciphertext length in bytes.
  • out Plaintext output buffer (must be at least in_len bytes).
  • tag 16-byte expected authentication tag to verify against.

Returns:

SYN_OK on successful verification, SYN_ERROR on tag mismatch, or SYN_INVALID_PARAM on invalid parameters.

function syn_aes_gcm_encrypt

AES-GCM authenticated encryption (NIST SP 800-38D). 

SYN_Status syn_aes_gcm_encrypt (
    const SYN_AES_GCM_Context * ctx,
    const uint8_t * nonce,
    size_t nonce_len,
    const uint8_t * aad,
    size_t aad_len,
    const uint8_t * in,
    size_t in_len,
    uint8_t * out,
    uint8_t tag
)

Parameters:

  • ctx Initialized AES-GCM context.
  • nonce Initialization vector / nonce buffer.
  • nonce_len Nonce length in bytes (standard is 12 bytes).
  • aad Additional authenticated data (may be NULL if aad_len is 0).
  • aad_len AAD length in bytes.
  • in Plaintext buffer to encrypt (may be NULL if in_len is 0).
  • in_len Plaintext length in bytes.
  • out Ciphertext output buffer (must be at least in_len bytes).
  • tag 16-byte authentication tag output buffer.

Returns:

SYN_OK on success, or SYN_INVALID_PARAM on NULL pointers or invalid params.

function syn_aes_gcm_init

Initialize AES-GCM AEAD context (expands key and computes GHASH subkey H). 

SYN_Status syn_aes_gcm_init (
    SYN_AES_GCM_Context * ctx,
    const uint8_t * key,
    size_t key_len
)

Parameters:

  • ctx Pointer to GCM context to initialize.
  • key Secret key buffer.
  • key_len Length of secret key in bytes (16, 24, or 32).

Returns:

SYN_OK on success, or SYN_INVALID_PARAM on failure.

function syn_aes_ghash_mult

Multiply 16-byte block by GHASH subkey H in GF(2^128). 

void syn_aes_ghash_mult (
    const uint8_t x,
    const uint8_t h,
    uint8_t out
)

Parameters:

  • x Input 16-byte field element.
  • h Input 16-byte GHASH subkey H.
  • out Output 16-byte product block.

function syn_aes_init

Initialize AES context and perform key expansion for 128/192/256-bit key. 

SYN_Status syn_aes_init (
    SYN_AES_Context * ctx,
    const uint8_t * key,
    size_t key_len
)

Parameters:

  • ctx Pointer to AES context to initialize.
  • key Secret key buffer.
  • key_len Length of secret key in bytes (16, 24, or 32).

Returns:

SYN_OK on success, or SYN_INVALID_PARAM on invalid key size or NULL pointers.

Macro Definition Documentation

define SYN_AES_BLOCK_SIZE

AES cipher block size in bytes (16 bytes / 128 bits). 

#define SYN_AES_BLOCK_SIZE `16U`

define SYN_AES_GCM_IV_DEFAULT_SIZE

Recommended GCM initialization vector size in bytes (12 bytes / 96 bits). 

#define SYN_AES_GCM_IV_DEFAULT_SIZE `12U`

define SYN_AES_GCM_TABLE

GCM GHASH acceleration table strategy. 0 = bit-by-bit Shoup (0 bytes table, low footprint), 4 = 4-bit nibble table (256 bytes per GCM context), 8 = 8-bit byte table (4096 bytes per GCM context). 

#define SYN_AES_GCM_TABLE `0`

define SYN_AES_GCM_TAG_SIZE

Standard GCM authentication tag size in bytes (16 bytes / 128 bits). 

#define SYN_AES_GCM_TAG_SIZE `16U`

define SYN_AES_KEY_SIZE_128

AES-128 key size in bytes (16 bytes / 128 bits). 

#define SYN_AES_KEY_SIZE_128 `16U`

define SYN_AES_KEY_SIZE_192

AES-192 key size in bytes (24 bytes / 192 bits). 

#define SYN_AES_KEY_SIZE_192 `24U`

define SYN_AES_KEY_SIZE_256

AES-256 key size in bytes (32 bytes / 256 bits). 

#define SYN_AES_KEY_SIZE_256 `32U`

define SYN_AES_MAX_EXPANDED_KEY

Maximum expanded round keys storage size in bytes. 

#define SYN_AES_MAX_EXPANDED_KEY `240U`

define SYN_AES_MAX_KEY_BITS

Maximum key size in bits (128, 192, or 256). Controls context RAM footprint. 

#define SYN_AES_MAX_KEY_BITS `256`

define SYN_AES_MAX_ROUNDS

Maximum rounds for configured key size. 

#define SYN_AES_MAX_ROUNDS `14U`

define SYN_USE_AES_CBC

Enable CBC mode encryption and decryption with PKCS#7 padding. 

#define SYN_USE_AES_CBC `1`

define SYN_USE_AES_CTR

Enable CTR stream cipher mode. 

#define SYN_USE_AES_CTR `1`

define SYN_USE_AES_DECRYPT

Enable ECB and CBC decryption functions (pulls rsbox, +256B Flash). 

#define SYN_USE_AES_DECRYPT `1`

define SYN_USE_AES_GCM

Enable GCM AEAD authenticated encryption and decryption. 

#define SYN_USE_AES_GCM `1`

The documentation for this class was generated from the following file src/syntropic/crypto/syn_aes.h