nRF5 SDK v17.0.2
AES - Advanced Encryption Standard

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:

CBC output:

CTR

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

CTR Requirements:

CTR output:

CFB

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

CFB Requirements:

CFB output:

ECB

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

ECB Requirements:

ECB output:

CBC-MAC

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

CBC-MAC Requirements:

CBC-MAC output:

CMAC

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

CMAC Requirements:

CMAC output:

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:


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;
// Initialize AES CTR context for encryption to use a 128-bit key
err_code = nrf_crypto_aes_init(&ctr_ctx,
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;
err_code = nrf_crypto_aes_crypt(&cmac_ctx, // Context
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.


Documentation feedback | Developer Zone | Subscribe | Updated