AESCCM driver header.
============================================================================
The Counter with CBC-MAC (CCM) mode of operation is a generic authenticated encryption block cipher mode. It can be used with any 128-bit block cipher. AESCCM combines CBC-MAC with an AES block cipher in CTR mode of operation.
This combination of block cipher modes enables CCM to encrypt messages of any length and not only multiples of the block cipher block size.
AESCCM encryption has the following inputs and outputs:
Encryption | Decryption |
---|---|
Input | |
Shared AES key | Shared AES key |
Nonce | Nonce |
Cleartext | Ciphertext (encrypted plaintext + MAC) |
AAD (optional) | AAD (optional) |
Output | |
Ciphertext (encrypted plaintext + MAC) | Cleartext |
The AES key is a shared secret between the two parties and has a length between 128 and 256 bits.
The nonce is generated by the party performing the authenticated encryption operation. Within the scope of any authenticated encryption key, the nonce value must be unique. That is, the set of nonce values used with any given key must not contain any duplicate values. Using the same nonce for two different messages encrypted with the same key destroys the security properties.
The optional additional authentication data (AAD) is authenticated, but not encrypted. Thus, the AAD is not included in the AES-CCM output. It can be used to authenticate packet headers.
After the encryption operation, the ciphertext contains the encrypted data and the message authentication code (MAC). The MAC can be seen as an encrypted fingerprint of the message header and content.
Before starting a CCM operation, the application must do the following:
There are two general ways to execute a CCM operation. In one call or multiple.
The AESCCM_oneStepEncrypt and AESCCM_oneStepDecrypt functions do a CCM operation in a single call. They will always be the most highly optimized routines with the least overhead and the fastest runtime. However, they require all AAD and plaintext or ciphertext data to be available to the function at the start of the call. When trying to operate on data that is too large to fit into available memory, partial processing would be more advisable. All devices support single call operations. When performing a decryption operation with AESCCM_oneStepDecrypt(), the MAC is automatically verified when using AESCCM_RETURN_BEHAVIOR_BLOCKING or AESCCM_RETURN_BEHAVIOR_POLLING. When using AESCCM_RETURN_BEHAVIOR_CALLBACK however, the application's registered callback function must call AESCCM_verifyMac() itself to ensure that the computed and transmitted MACs match.
After the CCM operation completes, the application should either start another operation or close the driver by calling AESCCM_close()
In order to use the AESCCM APIs, the application is required to provide device-specific AESCCM configuration in the Board.c file. The AESCCM driver interface defines a configuration data structure:
The application must declare an array of AESCCM_Config elements, named AESCCM_config[]. Each element of AESCCM_config[] must be populated with pointers to a device specific AESCCM driver implementation's driver object and hardware attributes. The hardware attributes define properties such as the AESCCM peripheral's base address. Each element in AESCCM_config[] corresponds to an AESCCM instance and none of the elements should have NULL pointers. There is no correlation between the index and the peripheral designation (such as AESCCM0 or AESCCM1). For example, it is possible to use AESCCM_config[0] for AESCCM1. Multiple drivers and driver instances may all access the same underlying hardware. This is transparent to the application. Mutual exclusion is performed automatically by the drivers as necessary.
Because the AESCCM configuration is very device dependent, you will need to check the doxygen for the device specific AESCCM implementation. There you will find a description of the AESCCM hardware attributes. Please also refer to the Board.c file of any of your examples to see the AESCCM configuration.
The AESCCM_Params structure is passed to the AESCCM_open() call. If NULL is passed for the parameters, AESCCM_open() uses default parameters. A AESCCM_Params structure is initialized with default values by passing it to AESCCM_Params_init(). Some of the AESCCM parameters are described below. To see brief descriptions of all the parameters, see AESCCM_Params.
The AESCCM driver supports three return behaviors when processing data: blocking, polling, and callback. The return behavior is determined by the returnBehavior parameter in the AESCCM_Params data structure. The AESCCM driver defaults to blocking mode, if the application does not set it. Once an AESCCM driver is opened, the only way to change the return behavior is to close and re-open the AESCCM instance with the new return behavior.
In blocking mode, a task's code execution is blocked until an AESCCM operation has completed. This ensures that only one AESCCM operation operates at a given time. Other tasks requesting AESCCM operations while a operation is currently taking place are also placed into a blocked state. AESCCM operations are executed in the order in which they were received. In blocking mode, you cannot perform AESCCM operations in the context of a software or hardware ISR.
In callback mode, an AESCCM operation functions asynchronously, which means that it does not block code execution. After an AESCCM operation has been completed, the AESCCM driver calls a user-provided hook function. Callback mode is supported in the task, SWI, and HWI execution context, However, if an AESCCM operation is requested while a operation is taking place, the call returns an error code.
In polling mode, an AESCCM operation behaves the almost the same way as in blocking mode. Instead of pending on a semaphore and letting other scheduled tasks run, the application task, SWI, or HWI continuously polls a flag until the operation completes. If an AESCCM operation is requested while a operation is taking place, the call returns an error code. When starting an AESCCM operation in polling mode from HWI or SWI context, the AESCCM HWI and SWI must be configured to have a higher priority to pre-empt the polling context.
### Single call CCM encryption + authentication with plaintext CryptoKey in blocking return mode #
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h>
Go to the source code of this file.
Data Structures | |
struct | AESCCM_Operation_ |
Struct containing the parameters required for encrypting/decrypting and authenticating/verifying a message. More... | |
struct | AESCCM_Config_ |
AESCCM Global configuration. More... | |
struct | AESCCM_Params_ |
CCM Parameters. More... | |
Macros | |
#define | AESCCM_CMD_RESERVED (32) |
#define | AESCCM_STATUS_RESERVED (-32) |
#define | AESCCM_STATUS_SUCCESS (0) |
Successful status code. More... | |
#define | AESCCM_STATUS_ERROR (-1) |
Generic error status code. More... | |
#define | AESCCM_STATUS_UNDEFINEDCMD (-2) |
An error status code returned by AESCCM_control() for undefined command codes. More... | |
#define | AESCCM_STATUS_RESOURCE_UNAVAILABLE (-3) |
An error status code returned if the hardware or software resource is currently unavailable. More... | |
#define | AESCCM_STATUS_MAC_INVALID (-4) |
An error status code returned if the MAC provided by the application for a decryption operation does not match the one calculated during the operation. More... | |
Typedefs | |
typedef struct AESCCM_Config_ * | AESCCM_Handle |
A handle that is returned from an AESCCM_open() call. More... | |
typedef enum AESCCM_ReturnBehavior_ | AESCCM_ReturnBehavior |
The way in which CCM function calls return after performing an encryption + authentication or decryption + verification operation. More... | |
typedef enum AESCCM_Mode_ | AESCCM_Mode |
Enum for the direction of the CCM operation. More... | |
typedef struct AESCCM_Operation_ | AESCCM_Operation |
Struct containing the parameters required for encrypting/decrypting and authenticating/verifying a message. More... | |
typedef enum AESCCM_OperationType_ | AESCCM_OperationType |
Enum for the operation types supported by the driver. More... | |
typedef struct AESCCM_Config_ | AESCCM_Config |
AESCCM Global configuration. More... | |
typedef void(* | AESCCM_CallbackFxn) (AESCCM_Handle handle, int_fast16_t returnValue, AESCCM_Operation *operation, AESCCM_OperationType operationType) |
The definition of a callback function used by the AESCCM driver when used in AESCCM_RETURN_BEHAVIOR_CALLBACK. More... | |
typedef struct AESCCM_Params_ | AESCCM_Params |
CCM Parameters. More... | |
Enumerations | |
enum | AESCCM_ReturnBehavior_ { AESCCM_RETURN_BEHAVIOR_CALLBACK = 1, AESCCM_RETURN_BEHAVIOR_BLOCKING = 2, AESCCM_RETURN_BEHAVIOR_POLLING = 4 } |
The way in which CCM function calls return after performing an encryption + authentication or decryption + verification operation. More... | |
enum | AESCCM_Mode_ { AESCCM_MODE_ENCRYPT = 1, AESCCM_MODE_DECRYPT = 2 } |
Enum for the direction of the CCM operation. More... | |
enum | AESCCM_OperationType_ { AESCCM_OPERATION_TYPE_ENCRYPT = 1, AESCCM_OPERATION_TYPE_DECRYPT = 2 } |
Enum for the operation types supported by the driver. More... | |
Functions | |
void | AESCCM_init (void) |
This function initializes the CCM module. More... | |
void | AESCCM_Params_init (AESCCM_Params *params) |
Function to initialize the AESCCM_Params struct to its defaults. More... | |
AESCCM_Handle | AESCCM_open (uint_least8_t index, AESCCM_Params *params) |
This function opens a given CCM peripheral. More... | |
void | AESCCM_close (AESCCM_Handle handle) |
Function to close a CCM peripheral specified by the CCM handle. More... | |
int_fast16_t | AESCCM_control (AESCCM_Handle handle, uint32_t cmd, void *args) |
Function performs implementation specific features on a given AESCCM_Handle. More... | |
void | AESCCM_Operation_init (AESCCM_Operation *operationStruct) |
Function to initialize a AESCCM_Operation struct to its defaults. More... | |
int_fast16_t | AESCCM_oneStepEncrypt (AESCCM_Handle handle, AESCCM_Operation *operationStruct) |
Function to perform an AESCCM encryption + authentication operation in one call. More... | |
int_fast16_t | AESCCM_oneStepDecrypt (AESCCM_Handle handle, AESCCM_Operation *operationStruct) |
Function to perform an AESCCM decryption + verification operation in one call. More... | |
Variables | |
const AESCCM_Params | AESCCM_defaultParams |
Default AESCCM_Params structure. More... | |
typedef struct AESCCM_Config_* AESCCM_Handle |
A handle that is returned from an AESCCM_open() call.
typedef enum AESCCM_ReturnBehavior_ AESCCM_ReturnBehavior |
The way in which CCM function calls return after performing an encryption + authentication or decryption + verification operation.
Not all CCM operations exhibit the specified return behavor. Functions that do not require significant computation and cannot offload that computation to a background thread behave like regular functions. Which functions exhibit the specfied return behavior is not implementation dependent. Specifically, a software-backed implementation run on the same CPU as the application will emulate the return behavior while not actually offloading the computation to the background thread.
AESCCM functions exhibiting the specified return behavior have restrictions on the context from which they may be called.
Task | Hwi | Swi | |
---|---|---|---|
AESCCM_RETURN_BEHAVIOR_CALLBACK | X | X | X |
AESCCM_RETURN_BEHAVIOR_BLOCKING | X | ||
AESCCM_RETURN_BEHAVIOR_POLLING | X | X | X |
typedef enum AESCCM_Mode_ AESCCM_Mode |
Enum for the direction of the CCM operation.
typedef struct AESCCM_Operation_ AESCCM_Operation |
Struct containing the parameters required for encrypting/decrypting and authenticating/verifying a message.
typedef enum AESCCM_OperationType_ AESCCM_OperationType |
Enum for the operation types supported by the driver.
typedef struct AESCCM_Config_ AESCCM_Config |
AESCCM Global configuration.
The AESCCM_Config structure contains a set of pointers used to characterize the AESCCM driver implementation.
This structure needs to be defined before calling AESCCM_init() and it must not be changed thereafter.
typedef void(* AESCCM_CallbackFxn) (AESCCM_Handle handle, int_fast16_t returnValue, AESCCM_Operation *operation, AESCCM_OperationType operationType) |
The definition of a callback function used by the AESCCM driver when used in AESCCM_RETURN_BEHAVIOR_CALLBACK.
handle | Handle of the client that started the CCM operation. |
processedKey | The CryptoKey that the CCM operation was performed with. |
typedef struct AESCCM_Params_ AESCCM_Params |
CCM Parameters.
CCM Parameters are used to with the AESCCM_open() call. Default values for these parameters are set using AESCCM_Params_init().
The way in which CCM function calls return after performing an encryption + authentication or decryption + verification operation.
Not all CCM operations exhibit the specified return behavor. Functions that do not require significant computation and cannot offload that computation to a background thread behave like regular functions. Which functions exhibit the specfied return behavior is not implementation dependent. Specifically, a software-backed implementation run on the same CPU as the application will emulate the return behavior while not actually offloading the computation to the background thread.
AESCCM functions exhibiting the specified return behavior have restrictions on the context from which they may be called.
Task | Hwi | Swi | |
---|---|---|---|
AESCCM_RETURN_BEHAVIOR_CALLBACK | X | X | X |
AESCCM_RETURN_BEHAVIOR_BLOCKING | X | ||
AESCCM_RETURN_BEHAVIOR_POLLING | X | X | X |
enum AESCCM_Mode_ |
void AESCCM_init | ( | void | ) |
This function initializes the CCM module.
void AESCCM_Params_init | ( | AESCCM_Params * | params | ) |
Function to initialize the AESCCM_Params struct to its defaults.
params | An pointer to AESCCM_Params structure for initialization |
Defaults values are: returnBehavior = AESCCM_RETURN_BEHAVIOR_BLOCKING callbackFxn = NULL timeout = SemaphoreP_WAIT_FOREVER custom = NULL
AESCCM_Handle AESCCM_open | ( | uint_least8_t | index, |
AESCCM_Params * | params | ||
) |
This function opens a given CCM peripheral.
index | Logical peripheral number for the CCM indexed into the AESCCM_config table |
params | Pointer to an parameter block, if NULL it will use default values. |
void AESCCM_close | ( | AESCCM_Handle | handle | ) |
Function to close a CCM peripheral specified by the CCM handle.
handle | A CCM handle returned from AESCCM_open() |
int_fast16_t AESCCM_control | ( | AESCCM_Handle | handle, |
uint32_t | cmd, | ||
void * | args | ||
) |
Function performs implementation specific features on a given AESCCM_Handle.
Commands for AESCCM_control can originate from AESCCM.h or from implementation specific AESCCM*.h (AESCCMCC26XX.h, AESCCMMSP432.h, etc.. ) files. While commands from AESCCM.h are API portable across driver implementations, not all implementations may support all these commands. Conversely, commands from driver implementation specific AESCCM*.h files add unique driver capabilities but are not API portable across all AESCCM driver implementations.
Commands supported by AESCCM.h follow an AESCCM_CMD_<cmd> naming convention.
Commands supported by AESCCM*.h follow an AESCCM*_CMD_<cmd> naming convention.
Each control command defines arg differently. The types of arg are documented with each command.
See AESCCM_control command codes for command codes.
See AESCCM_control return status codes for status codes.
handle | A AESCCM handle returned from AESCCM_open() |
cmd | AESCCM.h or AESCCM*.h commands. |
args | An optional R/W (read/write) command argument accompanied with cmd |
void AESCCM_Operation_init | ( | AESCCM_Operation * | operationStruct | ) |
Function to initialize a AESCCM_Operation struct to its defaults.
operationStruct | An pointer to AESCCM_Operation structure for initialization |
Defaults values are all zeros.
int_fast16_t AESCCM_oneStepEncrypt | ( | AESCCM_Handle | handle, |
AESCCM_Operation * | operationStruct | ||
) |
Function to perform an AESCCM encryption + authentication operation in one call.
[in] | handle | A CCM handle returned from AESCCM_open() |
[in] | operationStruct | A pointer to a struct containing the parameters required to perform the operation. |
int_fast16_t AESCCM_oneStepDecrypt | ( | AESCCM_Handle | handle, |
AESCCM_Operation * | operationStruct | ||
) |
Function to perform an AESCCM decryption + verification operation in one call.
[in] | handle | A CCM handle returned from AESCCM_open() |
[in] | operationStruct | A pointer to a struct containing the parameters required to perform the operation. |
const AESCCM_Params AESCCM_defaultParams |
Default AESCCM_Params structure.