The AES cryptography library provides functions that implement different variants of AES and AES AEAD cryptography, as well as a MAC calculations. The AES standard is described in Federal Information Processing Standard .

Supported AES Modes

The table presents all available AES modes, the backends that implement them, and the API that must be used for a particular AES mode.
You can change the backend implementation without the need to modify the API. See Configuring nrf_crypto frontend and backends .

AES backend support

API	Mode	CC310	mbed TLS	Cifra
AES API	CBC	128-bit key	128-bit key	-
		-	192-bit key	-
		-	256-bit key	-
	CTR	128-bit key	128-bit key	-
		-	192-bit key	-
		-	256-bit key	-
	CFB	-	128-bit key	-
		-	192-bit key	-
		-	256-bit key	-
	ECB	128-bit key	128-bit key	-
		-	192-bit key	-
		-	256-bit key	-
	CBC-MAC	128-bit key	128-bit key	-
		-	192-bit key	-
		-	256-bit key	-
	CMAC	128-bit key	128-bit key	-
		-	192-bit key	-
		-	256-bit key	-
AEAD API	CCM	128-bit key	128-bit key	-
		-	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	-

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

CBC

Cipher Block Chaining (CBC). See NIST SP 800-38A for more details.

CBC Requirements:

• During the encryption operation with nrf_crypto_aes_crypt or nrf_crypto_aes_finalize , if padding mode is selected, the size of p_data_out buffer must contain extra space for padding.
  
  When text_size is a multiple of 16 bytes, p_data_out must be allocated with a size equal to text_size + an additional block (that means 16 bytes for padding).
  When text_size is not a multiple of 16 bytes, p_data_out must be allocated with a size aligned to the next full 16-byte block (that means 1 - 15 bytes for padding).
• When no padding mode is selected, the text for encryption must be a multiple of 16 bytes.
• Size of the message for decryption must be always a multiple of 16 bytes.
• Key must be 128 bits, 192 bits, or 256 bits, depending on the selected backend.
• Initialization vector (IV) must be set before performing an encryption or decryption operation.

CBC output:

• Encrypted or decrypted text.
• When padding mode is selected, the last encrypted block is always padded, even if plain text is a multiple of 16 bytes.
• Upon a finished decryption operation, when padding mode is selected, p_data_out_size is decreased by the number of padded bytes.
• Updated IV value.

CTR

Counter (CTR). See NIST SP 800-38A for more details.

CTR Requirements:

• Key must be 128 bits, 192 bits, or 256 bits, depending on the selected backend.
• IV must be set before performing an encryption or decryption operation. For purpose of this API: "nonce" and "counter" are named Initialization Vector (IV).

CTR output:

• Encrypted or decrypted text.
• Updated IV value.

CFB

Cipher Feedback (CFB8). See NIST SP 800-38A for more details.

CFB Requirements:

• Key must be 128 bits, 192 bits, or 256 bits.
• IV shall be set before performing an encryption or decryption operation.

CFB output:

• Encrypted or decrypted text.
• Updated IV value.

ECB

Electronic Codebook (ECB). See NIST SP 800-38A for more details.

ECB Requirements:

• During the encryption operation with nrf_crypto_aes_crypt or nrf_crypto_aes_finalize , if padding mode is selected, the size of p_data_out buffer must contain extra space for padding.
  When text_size is a multiple of 16 bytes, p_data_out must be allocated with a size equal to text_size + an additional block (that means 16 bytes for padding).
  When text_size is not a multiple of 16 bytes, p_data_out must be allocated with a size aligned to the next full 16-byte block (that means 1 - 15 bytes for padding).
• When no padding mode is selected, the text for encryption must be a multiple of 16 bytes.
• Size of the message for decryption must be always a multiple of 16 bytes.
• Key must be 128 bits, 192 bits, or 256 bits, depending on the selected backend.

ECB output:

• Encrypted or decrypted text.
• When padding mode is selected, the last encrypted block is always padded, even if plain text is a multiple of 16 bytes.
• Upon a finished decryption operation, when padding mode is selected, p_data_out_size is decreased by the number of padded bytes.

CBC-MAC

Cipher Block Chaining Message Authentication Code (CBC-MAC). More details can be found in NIST SP 800-38C .

CBC-MAC Requirements:

• When no padding mode is selected, data_in_size for MAC calculation must be a multiple of 16 bytes.
• Size of the p_data_out buffer must be greater than or equal 16 bytes.
• Key must be 128 bits, 192 bits, or 256 bits, depending on the selected backend.
• IV must be set before performing a MAC calculation operation.

CBC-MAC output:

• Calculated 16-byte CBC-MAC value.
• Updated IV value.

CMAC

Cipher-based Message Authentication Code (CMAC). See NIST SP 800-38B for more details.

CMAC Requirements:

• Size of the p_data_out buffer must be greater than or equal 16 bytes.
• Key must be 128 bits, 192 bits, or 256 bits, depending on the selected backend.

CMAC output:

• Calculated 16-byte CMAC value.

Note

For descriptions of AES AEAD modes CCM , CCM* , EAX , and GCM , refer to AEAD - Authenticated Encryption with Associated Data .

AES API

There are two ways to use the AES related functions API, either by using nrf_crypto_aes_init , nrf_crypto_aes_key_set , nrf_crypto_aes_iv_set (for some ciphers), nrf_crypto_aes_update , and nrf_crypto_aes_finalize or through nrf_crypto_aes_crypt . The latter option does all the operations in a single integrated step.

Note

This API supports the following AES modes: CBC , CTR , CFB (CFB8 version), ECB , CBC-MAC , and CMAC .
To use CCM , CCM* , EAX , or GCM , refer to AEAD API .

Creating a context for AES mode

It is necessary to create at least one context, however when encryption and decryption operations are expected, it is more convenient to have a separate context for each operation.
The following code example demonstrates context creation for CTR and CBC-MAC modes.

        
         nrf_crypto_aes_context_t
        
        ctr_encr_ctx;
        
         // Encryption context for CTR mode
        
       

        
         nrf_crypto_aes_context_t
        
        ctr_decr_ctx;
        
         // Decryption context for CTR mode
        
       

       

        
         nrf_crypto_aes_context_t
        
        cbc_mac_ctx;
        
         // Context for CBC-MAC mode
        
       

Note

The union nrf_crypto_aes_context_t handles all possible AES modes. To optimize memory usage, you can deactivate unused AES modes in the sdk_config file. See Configuring nrf_crypto frontend and backends .

Selecting an AES algorithm

When initializing the context or when using the integrated function, one of the arguments is an info structure that contains information about the AES algorithm to use, key size, and padding mode. Such structure is available as a constant variable in the system.

List of available info structures:

• g_nrf_crypto_aes_cbc_128_info for CBC mode with a 128-bit key and no padding
• g_nrf_crypto_aes_cbc_192_info for CBC mode with a 192-bit key and no padding
• g_nrf_crypto_aes_cbc_256_info for CBC mode with a 256-bit key and no padding
• g_nrf_crypto_aes_cbc_128_pad_pkcs7_info for CBC mode with a 128-bit key and PKCS7 padding
• g_nrf_crypto_aes_cbc_192_pad_pkcs7_info for CBC mode with a 192-bit key and PKCS7 padding
• g_nrf_crypto_aes_cbc_256_pad_pkcs7_info for CBC mode with a 256-bit key and PKCS7 padding
• g_nrf_crypto_aes_cfb_128_info for CFB mode with a 128-bit key
• g_nrf_crypto_aes_cfb_192_info for CFB mode with a 192-bit key
• g_nrf_crypto_aes_cfb_256_info for CFB mode with a 256-bit key
• g_nrf_crypto_aes_ctr_128_info for CTR mode with a 128-bit key
• g_nrf_crypto_aes_ctr_192_info for CTR mode with a 192-bit key
• g_nrf_crypto_aes_ctr_256_info for CTR mode with a 256-bit key
• g_nrf_crypto_aes_ecb_128_info for ECB mode with a 128-bit key and no padding
• g_nrf_crypto_aes_ecb_192_info for ECB mode with a 192-bit key and no padding
• g_nrf_crypto_aes_ecb_256_info for ECB mode with a 256-bit key and no padding
• g_nrf_crypto_aes_cbc_128_pad_pkcs7_info for ECB mode with a 128-bit key and PKCS7 padding
• g_nrf_crypto_aes_cbc_192_pad_pkcs7_info for ECB mode with a 192-bit key and PKCS7 padding
• g_nrf_crypto_aes_cbc_256_pad_pkcs7_info for ECB mode with a 256-bit key and PKCS7 padding

• g_nrf_crypto_aes_cbc_mac_128_info for CBC-MAC mode with a 128-bit key
• g_nrf_crypto_aes_cbc_mac_192_info for CBC-MAC mode with a 192-bit key
• g_nrf_crypto_aes_cbc_mac_256_info for CBC-MAC mode with a 256-bit key
• g_nrf_crypto_aes_cbc_mac_128_pad_pkcs7_info for CBC-MAC mode with a 128-bit key and PKCS7 padding
• g_nrf_crypto_aes_cbc_mac_192_pad_pkcs7_info for CBC-MAC mode with a 192-bit key and PKCS7 padding
• g_nrf_crypto_aes_cbc_mac_256_pad_pkcs7_info for CBC-MAC mode with a 256-bit key and PKCS7 padding
• g_nrf_crypto_aes_cmac_128_info for CMAC mode with a 128-bit key
• g_nrf_crypto_aes_cmac_192_info for CMAC mode with a 192-bit key
• g_nrf_crypto_aes_cmac_256_info for CMAC mode with a 256-bit key

For more details regarding what key size is supported by which backend, refer to table in section Supported AES Modes .

Note

If there are no enabled nrf_crypto backends that support the given mode, then no globally accessible info structure is available.

AES API usage with init, update, and finalize

If the data to be used in an AES operation is available in smaller chunks, it is possible to initialize first using: nrf_crypto_aes_init , nrf_crypto_aes_key_set , nrf_crypto_aes_iv_set (for those ciphers that require it), and then call nrf_crypto_aes_update multiple times before running nrf_crypto_aes_finalize to get the result. Upon successful nrf_crypto_aes_finalize function execution, the AES context will be deinitialized.

        
         ret_code_t
        
        err_code;
       

       

        
         nrf_crypto_aes_context_t
        
        ctr_ctx;
       

       

        
         // Initialize AES CTR context for encryption to use a 128-bit key
        
       

        err_code =
        
         nrf_crypto_aes_init
        
        (&ctr_ctx,
       

        &
        
         g_nrf_crypto_aes_ctr_128_info
        
        ,
       

        NRF_CRYPTO_AES_ENCRYPT);
       

        
         APP_ERROR_CHECK
        
        (err_code);
       

       

        
         /* Setting the key for CTR mode */
        
       

        err_code =
        
         nrf_crypto_aes_key_set
        
        (&ctr_ctx,
       

        p_key);
       

        
         APP_ERROR_CHECK
        
        (err_code);
       

       

        
         /* Setting the IV for CTR mode */
        
       

        err_code =
        
         nrf_crypto_aes_iv_set
        
        (&ctr_ctx,
       

        p_iv);
       

        
         APP_ERROR_CHECK
        
        (err_code);
       

       

        
         // Run the update function (this can be run multiple times if the data is
        
       

        
         // accessible in smaller chunks, for example when received on-air).
        
       

        
         // data_in_size must be always multiple of 16 bytes when calling update function
        
       

        
         // (even when padding mode is selected).
        
       

        err_code =
        
         nrf_crypto_aes_update
        
        (&ctr_ctx, p_data_in, data_in_size, p_data_out);
       

        
         APP_ERROR_CHECK
        
        (err_code);
       

       

        
         // Run the finalize operation when all data has been fed to the update function.
        
       

        
         // This gives you the result in p_data_out.
        
       

        
         // Variable data_out_size will be updated with number of significant bytes
        
       

        
         // in p_data_out buffer.
        
       

        
         //   data_out_size = data_in_size + padding_length on encryption
        
       

        
         //   data_out_size = data_in_size - padding_length on decryption
        
       

        
         //   data_out_size = 16 on MAC calculation
        
       

        err_code =
        
         nrf_crypto_aes_finalize
        
        (&ctr_ctx,
       

        p_data_in,
       

        data_in_size,
       

        p_data_out,
       

        &data_out_size);
       

        
         APP_ERROR_CHECK
        
        (err_code);
       

Note

The AES context structures must be retained in RAM throughout all the calls to nrf_crypto_aes_update and the final call to nrf_crypto_aes_finalize .

Warning

CC310 requires storing the input data in RAM. This is caused by the fact that CC310 communicates with the shared memory by using DMA access.

AES API usage with the integrated function

If all data is available at the time of the call, it is possible to use the integrated version of the AES function. By calling nrf_crypto_aes_crypt , the init, key_set, iv_set, update, and finalize operations are done in a single integrated step.

        
         // Example of CMAC calculation using the integrated version
        
       

        
         ret_code_t
        
        err_code;
       

       

        
         nrf_crypto_aes_context_t
        
        cmac_ctx;
       

       

        err_code =
        
         nrf_crypto_aes_crypt
        
        (&cmac_ctx,
        
         // Context
        
       

        &
        
         g_nrf_crypto_aes_cmac_256_info
        
        ,
        
         // AES mode
        
       

        NRF_CRYPTO_MAC_CALCULATE,
        
         // Operation
        
       

        p_key,
        
         // AES key
        
       

        NULL,
        
         // CMAC: no IV
        
       

        p_data_in,
        
         // Text data
        
       

        data_in_size,
        
         // Data size
        
       

        p_data_out,
        
         // Out data
        
       

        &data_out_size);
        
         // Out size
        
       

        
         APP_ERROR_CHECK
        
        (err_code);
       

Note

Function nrf_crypto_aes_crypt supports dynamic memory allocation on stack or through a memory management for the context.

Warning

CC310 requires storing the input data in RAM. This is caused by the fact that CC310 communicates with the shared memory by using DMA access.

Examples

Refer to AES Example for a usage example of this library.

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