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.
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.
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.
Cipher Block Chaining (CBC). See NIST SP 800-38A for more details.
CBC Requirements:
p_data_out
buffer must contain extra space for padding.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). 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).CBC output:
p_data_out_size
is decreased by the number of padded bytes.Counter (CTR). See NIST SP 800-38A for more details.
CTR Requirements:
CTR output:
Cipher Feedback (CFB8). See NIST SP 800-38A for more details.
CFB Requirements:
CFB output:
Electronic Codebook (ECB). See NIST SP 800-38A for more details.
ECB Requirements:
p_data_out
buffer must contain extra space for padding. 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). 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).ECB output:
p_data_out_size
is decreased by the number of padded bytes.Cipher Block Chaining Message Authentication Code (CBC-MAC). More details can be found in NIST SP 800-38C.
CBC-MAC Requirements:
data_in_size
for MAC calculation must be a multiple of 16 bytes.p_data_out
buffer must be greater than or equal 16 bytes.CBC-MAC output:
Cipher-based Message Authentication Code (CMAC). See NIST SP 800-38B for more details.
CMAC Requirements:
p_data_out
buffer must be greater than or equal 16 bytes.CMAC output:
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.
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.
sdk_config
file. See Configuring nrf_crypto frontend and backends.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.
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.
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.
Refer to AES Example for a usage example of this library.
For an example showing the verification procedure of AES, see Test Example.