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);