AESECB driver header.
============================================================================
The Electronic Code Book (ECB) mode of operation is a generic encryption block cipher mode. It can be used with any block cipher. AESECB encrypts or decrypts one or multiple blocks of plaintext or ciphertext using the Advanced Encryption Standard (AES) block cipher. Each input block is individually encrypted or decrypted. This means that blocks if ciphertext can be decrypted individually and out of order. This raises several security issues. For this reason, it is not recommended that ECB be used unless interfacing with unupdatable legacy systems or where a standard specifies its use. Better alternatives would be an authenticated encryption with associated data (AEAD) mode such as CCM or GCM.
The AES key is a shared secret between the two parties and has a length between 128 and 256 bits.
Before starting a ECB operation, the application must do the following:
The AESECB_oneStepEncrypt and AESECB_oneStepDecrypt functions do a ECB operation in a single call. They will always be the most highly optimized routines with the least overhead and the fastest runtime. Since ECB plaintext blocks are simply encrypted with the block cipher block by block, there is no difference in the ciphertext between encrypting two blocks in one go or encypting each block individually.
After the ECB operation completes, the application should either start another operation or close the driver by calling AESECB_close()
In order to use the AESECB APIs, the application is required to provide device-specific AESECB configuration in the Board.c file. The AESECB driver interface defines a configuration data structure:
The application must declare an array of AESECB_Config elements, named AESECB_config[]. Each element of AESECB_config[] must be populated with pointers to a device specific AESECB driver implementation's driver object and hardware attributes. The hardware attributes define properties such as the AESECB peripheral's base address. Each element in AESECB_config[] corresponds to an AESECB instance and none of the elements should have NULL pointers. There is no correlation between the index and the peripheral designation (such as AESECB0 or AESECB1). For example, it is possible to use AESECB_config[0] for AESECB1. 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 AESECB configuration is very device dependent, you will need to check the doxygen for the device specific AESECB implementation. There you will find a description of the AESECB hardware attributes. Please also refer to the Board.c file of any of your examples to see the AESECB configuration.
The AESECB_Params structure is passed to the AESECB_open() call. If NULL is passed for the parameters, AESECB_open() uses default parameters. A AESECB_Params structure is initialized with default values by passing it to AESECB_Params_init(). Some of the AESECB parameters are described below. To see brief descriptions of all the parameters, see AESECB_Params.
### Encyption of multiple plaintext blocks in blocking 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 | AESECB_Operation_ |
Struct containing the parameters required for encrypting/decrypting and a message. More... | |
struct | AESECB_Config_ |
AESECB Global configuration. More... | |
struct | AESECB_Params_ |
ECB Parameters. More... | |
Macros | |
#define | AESECB_CMD_RESERVED (32) |
#define | AESECB_STATUS_RESERVED (-32) |
#define | AESECB_STATUS_SUCCESS (0) |
Successful status code. More... | |
#define | AESECB_STATUS_ERROR (-1) |
Generic error status code. More... | |
#define | AESECB_STATUS_UNDEFINEDCMD (-2) |
An error status code returned by AESECB_control() for undefined command codes. More... | |
#define | AESECB_STATUS_RESOURCE_UNAVAILABLE (-3) |
An error status code returned if the hardware or software resource is currently unavailable. More... | |
Typedefs | |
typedef struct AESECB_Config_ * | AESECB_Handle |
A handle that is returned from an AESECB_open() call. More... | |
typedef enum AESECB_ReturnBehavior_ | AESECB_ReturnBehavior |
The way in which ECB function calls return after performing an encryption + authentication or decryption + verification operation. More... | |
typedef enum AESECB_Mode_ | AESECB_Mode |
Enum for the direction of the ECB operation. More... | |
typedef struct AESECB_Operation_ | AESECB_Operation |
Struct containing the parameters required for encrypting/decrypting and a message. More... | |
typedef enum AESECB_OperationType_ | AESECB_OperationType |
Enum for the operation types supported by the driver. More... | |
typedef struct AESECB_Config_ | AESECB_Config |
AESECB Global configuration. More... | |
typedef void(* | AESECB_CallbackFxn) (AESECB_Handle handle, int_fast16_t returnValue, AESECB_Operation *operation, AESECB_OperationType operationType) |
The definition of a callback function used by the AESECB driver when used in AESECB_RETURN_BEHAVIOR_CALLBACK. More... | |
typedef struct AESECB_Params_ | AESECB_Params |
ECB Parameters. More... | |
Enumerations | |
enum | AESECB_ReturnBehavior_ { AESECB_RETURN_BEHAVIOR_CALLBACK = 1, AESECB_RETURN_BEHAVIOR_BLOCKING = 2, AESECB_RETURN_BEHAVIOR_POLLING = 4 } |
The way in which ECB function calls return after performing an encryption + authentication or decryption + verification operation. More... | |
enum | AESECB_Mode_ { AESECB_MODE_ENCRYPT = 1, AESECB_MODE_DECRYPT = 2 } |
Enum for the direction of the ECB operation. More... | |
enum | AESECB_OperationType_ { AESECB_OPERATION_TYPE_ENCRYPT = 1, AESECB_OPERATION_TYPE_DECRYPT = 2 } |
Enum for the operation types supported by the driver. More... | |
Functions | |
void | AESECB_init (void) |
This function initializes the ECB module. More... | |
void | AESECB_Params_init (AESECB_Params *params) |
Function to initialize the AESECB_Params struct to its defaults. More... | |
AESECB_Handle | AESECB_open (uint_least8_t index, AESECB_Params *params) |
This function opens a given ECB peripheral. More... | |
void | AESECB_close (AESECB_Handle handle) |
Function to close a ECB peripheral specified by the ECB handle. More... | |
int_fast16_t | AESECB_control (AESECB_Handle handle, uint32_t cmd, void *args) |
Function performs implementation specific features on a given AESECB_Handle. More... | |
void | AESECB_Operation_init (AESECB_Operation *operationStruct) |
Function to initialize a AESECB_Operation struct to its defaults. More... | |
int_fast16_t | AESECB_oneStepEncrypt (AESECB_Handle handle, AESECB_Operation *operation) |
Function to perform an AESECB encryption operation in one call. More... | |
int_fast16_t | AESECB_oneStepDecrypt (AESECB_Handle handle, AESECB_Operation *operation) |
Function to perform an AESECB decryption in one call. More... | |
Variables | |
const AESECB_Params | AESECB_defaultParams |
Default AESECB_Params structure. More... | |
typedef struct AESECB_Config_* AESECB_Handle |
A handle that is returned from an AESECB_open() call.
typedef enum AESECB_ReturnBehavior_ AESECB_ReturnBehavior |
The way in which ECB function calls return after performing an encryption + authentication or decryption + verification operation.
Not all ECB 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.
AESECB functions exhibiting the specified return behavior have restrictions on the context from which they may be called.
Task | Hwi | Swi | |
---|---|---|---|
AESECB_RETURN_BEHAVIOR_CALLBACK | X | X | X |
AESECB_RETURN_BEHAVIOR_BLOCKING | X | ||
AESECB_RETURN_BEHAVIOR_POLLING | X | X | X |
typedef enum AESECB_Mode_ AESECB_Mode |
Enum for the direction of the ECB operation.
typedef struct AESECB_Operation_ AESECB_Operation |
Struct containing the parameters required for encrypting/decrypting and a message.
typedef enum AESECB_OperationType_ AESECB_OperationType |
Enum for the operation types supported by the driver.
typedef struct AESECB_Config_ AESECB_Config |
AESECB Global configuration.
The AESECB_Config structure contains a set of pointers used to characterize the AESECB driver implementation.
This structure needs to be defined before calling AESECB_init() and it must not be changed thereafter.
typedef void(* AESECB_CallbackFxn) (AESECB_Handle handle, int_fast16_t returnValue, AESECB_Operation *operation, AESECB_OperationType operationType) |
The definition of a callback function used by the AESECB driver when used in AESECB_RETURN_BEHAVIOR_CALLBACK.
handle | Handle of the client that started the ECB operation. |
processedKey | The CryptoKey that the ECB operation was performed with. |
typedef struct AESECB_Params_ AESECB_Params |
ECB Parameters.
ECB Parameters are used to with the AESECB_open() call. Default values for these parameters are set using AESECB_Params_init().
The way in which ECB function calls return after performing an encryption + authentication or decryption + verification operation.
Not all ECB 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.
AESECB functions exhibiting the specified return behavior have restrictions on the context from which they may be called.
Task | Hwi | Swi | |
---|---|---|---|
AESECB_RETURN_BEHAVIOR_CALLBACK | X | X | X |
AESECB_RETURN_BEHAVIOR_BLOCKING | X | ||
AESECB_RETURN_BEHAVIOR_POLLING | X | X | X |
enum AESECB_Mode_ |
void AESECB_init | ( | void | ) |
This function initializes the ECB module.
void AESECB_Params_init | ( | AESECB_Params * | params | ) |
Function to initialize the AESECB_Params struct to its defaults.
params | An pointer to AESECB_Params structure for initialization |
Defaults values are: returnBehavior = AESECB_RETURN_BEHAVIOR_BLOCKING callbackFxn = NULL timeout = SemaphoreP_WAIT_FOREVER custom = NULL
AESECB_Handle AESECB_open | ( | uint_least8_t | index, |
AESECB_Params * | params | ||
) |
This function opens a given ECB peripheral.
index | Logical peripheral number for the ECB indexed into the AESECB_config table |
params | Pointer to an parameter block, if NULL it will use default values. |
void AESECB_close | ( | AESECB_Handle | handle | ) |
Function to close a ECB peripheral specified by the ECB handle.
handle | A ECB handle returned from AESECB_open() |
int_fast16_t AESECB_control | ( | AESECB_Handle | handle, |
uint32_t | cmd, | ||
void * | args | ||
) |
Function performs implementation specific features on a given AESECB_Handle.
Commands for AESECB_control can originate from AESECB.h or from implementation specific AESECB*.h (AESECBCC26XX.h, AESECBMSP432.h, etc.. ) files. While commands from AESECB.h are API portable across driver implementations, not all implementations may support all these commands. Conversely, commands from driver implementation specific AESECB*.h files add unique driver capabilities but are not API portable across all AESECB driver implementations.
Commands supported by AESECB.h follow an AESECB_CMD_<cmd> naming convention.
Commands supported by AESECB*.h follow an AESECB*_CMD_<cmd> naming convention.
Each control command defines arg differently. The types of arg are documented with each command.
See AESECB_control command codes for command codes.
See AESECB_control return status codes for status codes.
handle | A AESECB handle returned from AESECB_open() |
cmd | AESECB.h or AESECB*.h commands. |
args | An optional R/W (read/write) command argument accompanied with cmd |
void AESECB_Operation_init | ( | AESECB_Operation * | operationStruct | ) |
Function to initialize a AESECB_Operation struct to its defaults.
operationStruct | An pointer to AESECB_Operation structure for initialization |
Defaults values are all zeros.
int_fast16_t AESECB_oneStepEncrypt | ( | AESECB_Handle | handle, |
AESECB_Operation * | operation | ||
) |
Function to perform an AESECB encryption operation in one call.
[in] | handle | A ECB handle returned from AESECB_open() |
[in] | operation | A pointer to a struct containing the parameters required to perform the operation. |
int_fast16_t AESECB_oneStepDecrypt | ( | AESECB_Handle | handle, |
AESECB_Operation * | operation | ||
) |
Function to perform an AESECB decryption in one call.
[in] | handle | A ECB handle returned from AESECB_open() |
[in] | operation | A pointer to a struct containing the parameters required to perform the operation. |
const AESECB_Params AESECB_defaultParams |
Default AESECB_Params structure.