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 .