Supported AEAD Modes

The table presents all available AEAD modes and backends that implement them.
You can change the backend implementation without the need to modify the AEAD API. See Configuring nrf_crypto frontend and backends.

AEAD modes backend support
Mode	CC310	mbed TLS	Cifra	Oberon	API
CCM	128-bit key	128-bit key	-	-	AEAD API
	-	192-bit key	-	-
	-	256-bit key	-	-
CCM*	128-bit key	-	-	-
	-	-	-	-
	-	-	-	-
EAX	-	-	128-bit key	-
	-	-	192-bit key	-
	-	-	256-bit key	-
GCM	-	128-bit key	-	-
	-	192-bit key	-	-
	-	256-bit key	-	-
ChaCha-Poly	-	-	-	-
	-	-	-	-
	256-bit key	-	-	256-bit key

The requirements and output type of each mode are outlined in the subsections below.

CCM

Counter (CTR) mode with CBC-MAC. See NIST SP 800-38C for more details.

CCM requirements:

Key must be 128 bits, 192 bits, or 256 bits (depending on the selected backend).
The nonce size must be in range from 7 to 13 bytes.
MAC size must be 4, 6, 8, 10, 12, 14, or 16 bytes.
MAC must be valid for the decrypted message.
Optional additional authenticated data (adata).
When using CC310 as a backend, the size of each buffer must not exceed 65535 bytes.

CCM output:

Encrypted or decrypted text.
MAC for the encrypted text.

CCM*

Minor variation of CCM.

CCM* requirements:

Key must be 128 bits.
The nonce size must be 13 bytes.
MAC size must be: 0, 4, 8, or 16 bytes.
MAC must be valid for the decrypted message.
Optional additional authenticated data (adata).
When using CC310 as a backend, the size of each buffer must not exceed 65535 bytes.

CCM* output:

Encrypted or decrypted text.
MAC for the encrypted text.

EAX

See the EAX mode of operation for more details. EAX requirements:

Key must be 128 bits, 192 bits, or 256 bits.
The nonce size can be of any length.
MAC size must be in range from 1 to 16 bytes.
MAC must be valid for the decrypted message.
Optional additional authenticated data (adata).

EAX output:

Encrypted or decrypted text.
MAC for the encrypted text.

GCM

Galois Counter Mode (GCM). See NIST SP 800-38D for more details.

GCM requirements:

Key must be 128 bits, 192 bits, or 256 bits.
The nonce size can be of any length.
MAC size must be in range from 4 to 16 bytes.
MAC must be valid for the decrypted message.
Optional additional authenticated data (adata).

GCM output:

Encrypted or decrypted text.
MAC for the encrypted text.

ChaCha-Poly

ChaCha20-Poly1305 AEAD.

ChaCha-Poly requirements:

Key must be 256 bits.
The nonce size must be 12 bytes.
MAC size must be 16 bytes.
MAC must be valid for the decrypted message.
Additional authenticated data (adata) size must not be 0.
When using CC310 as a backend, the size of each buffer must not exceed 65535 bytes.

ChaCha-Poly output:

Encrypted or decrypted text.
MAC for the encrypted text.

AEAD API

This section provides details on how AEAD is implemented by nrf_crypto API.

Creating a context for AEAD mode

The following example presents context creation for CCM and ChaCha-Poly modes.

nrf_crypto_aead_context_t ccm_ctx;

nrf_crypto_aead_context_t chacha_poly_ctx;

Note: The union nrf_crypto_aead_context_t handles all possible AEAD modes. To optimize memory usage, deactivate unused AEAD modes in the sdk_config file. See Configuring nrf_crypto frontend and backends.

Warning: When using CC310 as a backend, make sure that the input variable is stored in RAM due to Cryptocell® requirements.

Selecting an information object for AEAD mode

Depending on the backend, AEAD modes can be used with different key sizes: 128 bits, 192 bits, and 256 bits. Key size is set by selecting a proper information object.

/* selecting information object for CCM mode to use a 128-bit key */
nrf_crypto_aead_info_t const * p_ccm_k128_info = &g_nrf_crypto_aes_ccm_128_info; // for a 128-bit key
/* selecting information object for ChaCha-Poly mode to use a 256-bit key */
nrf_crypto_aead_info_t const * p_chacha_poly_k256_info = &g_nrf_crypto_chacha_poly_256_info; // for a 256-bit key

List of available information objects:

g_nrf_crypto_aes_ccm_128_info for CCM mode with a 128-bit key
g_nrf_crypto_aes_ccm_192_info for CCM mode with a 192-bit key
g_nrf_crypto_aes_ccm_256_info for CCM mode with a 256-bit key
g_nrf_crypto_aes_ccm_star_128_info for CCM* mode with a 128-bit key
g_nrf_crypto_aes_eax_128_info for EAX mode with a 128-bit key
g_nrf_crypto_aes_eax_192_info for EAX mode with a 192-bit key
g_nrf_crypto_aes_eax_256_info for EAX mode with a 256-bit key
g_nrf_crypto_aes_gcm_128_info for GCM mode with a 128-bit key
g_nrf_crypto_aes_gcm_192_info for GCM mode with a 192-bit key
g_nrf_crypto_aes_gcm_256_info for GCM mode with a 256-bit key
g_nrf_crypto_chacha_poly_256_info for ChaCha-Poly mode with a 256-bit key

Initializing a context

To be able to use API functions for the chosen AEAD mode, you must first initialize the created context with the selected information object and a key.

/* Initialize AES CCM context for 128-bit key operations and set a key */
ret_val = nrf_crypto_aead_init(&ccm_ctx,
 p_ccm_k128_info,
 key);
/* Initialize ChaCha-Poly context for 256-bit key operations and set a key */
ret_val = nrf_crypto_aead_init(&chacha_poly_ctx,
 p_chacha_poly_k256_info,
 key);

Encrypting and decrypting

Encryption and decryption operations are realized by one function nrf_crypto_aead_crypt.

/* Encrypt plain_text with ccm context and save results in encrypted_text buffer. 
 Calculate the MAC and save it to the MAC buffer. */
ret_val = nrf_crypto_aead_crypt(&ccm_ctx,
 NRF_CRYPTO_AES_ENCRYPT,
 nonce, 
 sizeof(nonce),
 adata,
 sizeof(adata),
 (uint8_t *)plain_text,
 strlen(plain_text),
 (uint8_t *)encrypted_text,
 mac,
 sizeof(mac));
/* Decrypt encrypted_text and save results to decrypted_text buffer 
 if the MAC is correct. */
ret_val = nrf_crypto_aead_crypt(&ccm_ctx,
 NRF_CRYPTO_AES_DECRYPT,
 nonce, 
 sizeof(nonce),
 adata,
 sizeof(adata),
 (uint8_t *)encrypted_text,
 len,
 (uint8_t *)decrypted_text,
 mac,
 sizeof(mac));
/* Encrypt plain_text with chacha-poly context and save results in encrypted_text 
 buffer. Calculate the MAC and save it to the MAC buffer. */
ret_val = nrf_crypto_aead_crypt(&chacha_poly_ctx,
 NRF_CRYPTO_AES_ENCRYPT,
 nonce, 
 sizeof(nonce),
 adata,
 sizeof(adata),
 (uint8_t *)plain_text,
 strlen(plain_text),
 (uint8_t *)encrypted_text,
 mac,
 sizeof(mac));
/* Decrypt encrypted_text and save results to decrypted_text buffer 
 if the MAC is correct. */
ret_val = nrf_crypto_aead_crypt(&chacha_poly_ctx,
 NRF_CRYPTO_AES_DECRYPT,
 nonce, 
 sizeof(nonce),
 adata,
 sizeof(adata),
 (uint8_t *)encrypted_text,
 len,
 (uint8_t *)decrypted_text,
 mac,
 sizeof(mac));

Warning: When using CC310 as a backend, make sure that all buffers are in RAM due to Cryptocell® requirements.

Uninitializing AEAD context

When AEAD context is no longer needed, it can be uninitialized.

/* Uninit CCM context */
ret_val = nrf_crypto_aead_uninit(&ccm_ctx);
ret_val = nrf_crypto_aead_uninit(&chacha_poly_ctx);

Examples

Refer to AES Example and ChaCha-Poly Example for usage examples of this library.

For an example showing the verification procedure of AEAD, see Test Example.