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.
- 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.
List of available information objects:
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.
p_ccm_k128_info,
key);
p_chacha_poly_k256_info,
key);
Encrypting and decrypting
Encryption and decryption operations are realized by one function nrf_crypto_aead_crypt.
NRF_CRYPTO_AES_ENCRYPT,
nonce,
sizeof(nonce),
adata,
sizeof(adata),
(uint8_t *)plain_text,
strlen(plain_text),
(uint8_t *)encrypted_text,
mac,
sizeof(mac));
NRF_CRYPTO_AES_DECRYPT,
nonce,
sizeof(nonce),
adata,
sizeof(adata),
(uint8_t *)encrypted_text,
len,
(uint8_t *)decrypted_text,
mac,
sizeof(mac));
NRF_CRYPTO_AES_ENCRYPT,
nonce,
sizeof(nonce),
adata,
sizeof(adata),
(uint8_t *)plain_text,
strlen(plain_text),
(uint8_t *)encrypted_text,
mac,
sizeof(mac));
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.
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.