AES#

The functions to test AES implementations share the same parameters:

  • mode is a required parameter. Its possible values are:
    • Classic modes: ECB, CBC, CBCPKCS7, CFB8, CFB128, CTR

    • AEAD modes: CCM, GCM

  • key size is an optional parameter. If omitted, the implementation is considered to support all three key sizes. Its possible values are:
    • 128, 192, 256

Encrypt#

To test a function that encrypts with AES, its name must conform to the following convention:

CC_AES_<mode>_[key size]_encrypt

Its signature must conform to either encrypt() or encrypt_aead() depending on the mode of operation:

void encrypt(
uint8_t *buffer,
size_t buffer_size,
const uint8_t *key,
size_t key_size,
const uint8_t *iv,
size_t iv_size,
)#

Encrypts a plaintext with AES using a classic mode of operation.

Parameters:
  • buffer[In/Out] A buffer containing the plaintext to encrypt, and where the ciphertext should be copied to.

  • buffer_size[In] The size of the buffer in bytes.

  • key[In] The symmetric key.

  • key_size[In] The size of the key in bytes. Even when specifying a key size, this argument is passed but can be safely ignored.

  • iv[In] The IV. NULL if no IV is used.

  • iv_size[In] The size of the IV in bytes. 0 if no IV is used.

void encrypt_aead(
uint8_t *buffer,
size_t buffer_size,
uint8_t *mac,
size_t mac_size,
const uint8_t *key,
size_t key_size,
const uint8_t *iv,
size_t iv_size,
const uint8_t *aad,
size_t aad_size,
)#

Encrypts a plaintext with AES using an authenticated mode of operation.

Parameters:
  • buffer[In/Out] A buffer containing the plaintext to encrypt, and where the ciphertext should be copied to.

  • buffer_size[In] The size of the buffer in bytes.

  • mac[In/Out] A buffer to return the MAC tag.

  • mac_size[In] The expected size of the MAC tag in bytes.

  • key[In] The symmetric key.

  • key_size[In] The size of the key in bytes. Even when specifying a key size this argument is passed but can be safely ignored.

  • nonce[In] The nonce.

  • nonce_size[In] The size of the nonce in bytes.

  • aad[In] The optional associated data. NULL if not used.

  • aad_size[In] The size of the associated data in bytes. 0 if not used.

Examples:

  • AES-ECB:

void CC_AES_ECB_encrypt(uint8_t *buffer, size_t buffer_size,
                        const uint8_t *key, size_t key_size,
                        const uint8_t *iv, size_t iv_size) {
     struct AES_ctx ctx;
     AES_init_ctx(&ctx, key, key_size);
     AES_ECB_encrypt_buffer(&ctx, buffer, buffer_size);
}
  • AES-128-CBC:

void CC_AES_CBC_128_encrypt(uint8_t *buffer, size_t buffer_size,
                           const uint8_t *key, size_t key_size,
                           const uint8_t *iv, size_t iv_size);
  • AES-CCM:

void CC_AES_CCM_encrypt(uint8_t *buffer, size_t buffer_size,
                       uint8_t *mac, size_t mac_size,
                       const uint8_t *key, size_t key_size,
                       const uint8_t *nonce, size_t nonce_size,
                       const uint8_t *aad, size_t aad_size);
  • AES-256-GCM:

void CC_AES_GCM_256_encrypt(uint8_t *buffer, size_t buffer_size,
                           uint8_t *mac, size_t mac_size,
                           const uint8_t *key, size_t key_size,
                           const uint8_t *nonce, size_t nonce_size,
                           const uint8_t *aad, size_t aad_size);

Decrypt#

To test a function that decrypts with AES, its name must conform to the following convention:

CC_AES_<mode>_[key size]_decrypt

Its signature must conform to either decrypt() or decrypt_aead() depending on the mode of operation:

void decrypt(
uint8_t *buffer,
size_t buffer_size,
const uint8_t *key,
size_t key_size,
const uint8_t *iv,
size_t iv_size,
)#

Decrypts a ciphertext with AES using a classic mode of operation.

Parameters:
  • buffer[In/Out] A buffer containing the ciphertext to decrypt, and where the plaintext should be copied to.

  • buffer_size[In] The size of the buffer in bytes.

  • key[In] The symmetric key.

  • key_size[In] The size of the key in bytes. Even when specifying a key size this argument is passed but can be safely ignored.

  • iv[In] The IV, NULL if no IV is used.

  • iv_size[In] The size of the IV in bytes, 0 if no IV is used.

  • plaintext[Out] A buffer to store the resulting plaintext. It has the same size as the ciphertext.

int decrypt_aead(
uint8_t *buffer,
size_t buffer_size,
const uint8_t *key,
size_t key_size,
const uint8_t *ciphertext,
size_t ciphertext_size,
const uint8_t *iv,
size_t iv_size,
const uint8_t *aad,
size_t aad_size,
const uint8_t *mac,
size_t mac_size,
)#

Authenticates and decrypts a ciphertext with AES using an authenticated mode of operation.

Parameters:
  • buffer[In/Out] A buffer containing the ciphertext to decrypt, and where the plaintext should be copied to.

  • buffer_size[In] The size of the buffer in bytes.

  • key[In] The symmetric key.

  • key_size[In] The size of the key in bytes. Even when specifying a key size this argument is passed but can be safely ignored.

  • nonce[In] The nonce.

  • nonce_size[In] The size of the nonce in bytes.

  • aad[In] The optional associated data. NULL if not used.

  • aad_size[In] The size of the associated data in bytes. 0 if not used.

  • mac[In] The MAC tag to use to authenticate the ciphertext.

  • mac_size[In] The size of the MAC tag in bytes.

Returns:

A status value.

Return values:
  • 0 – OK.

  • -1 – The MAC verification failed.

Examples:

  • AES-ECB:

void CC_AES_ECB_decrypt(uint8_t *buffer, size_t buffer_size,
                       const uint8_t *key, size_t key_size,
                       const uint8_t *iv, size_t iv_size);
  • AES-128-CBC:

void CC_AES_CBC_128_decrypt(uint8_t *buffer, size_t buffer_size,
                           const uint8_t *key, size_t key_size,
                           const uint8_t *iv, size_t iv_size);
  • AES-CCM:

int CC_AES_CCM_decrypt(uint8_t *buffer, size_t buffer_size,
                       const uint8_t *key, size_t key_size,
                       const uint8_t *nonce, size_t nonce_size,
                       const uint8_t *aad, size_t aad_size,
                       const uint8_t *mac, size_t mac_size);
  • AES-256-GCM:

int CC_AES_GCM_256_decrypt(uint8_t *buffer, size_t buffer_size,
                           const uint8_t *key, size_t key_size,
                           const uint8_t *nonce, size_t nonce_size,
                           const uint8_t *aad, size_t aad_size,
                           const uint8_t *mac, size_t mac_size);