AESCBC driver header.
============================================================================
The Cipher Block Chaining (CBC) mode of operation is a generic block cipher mode of operation. It can be used with any block cipher including AES.
CBC mode encrypts messages of any practical length that have a length evenly divisibly by the block size. Unlike ECB, it guarantees confidentiality of the entire message when the message is larger than one block.
In CBC encryption, the initialization vector (IV) is XOR'd with a block of plaintext and then encrypted. The output ciphertext block is then XOR'd with the next plaintext block and the result is encryped. This process is repeated until the final block of plaintext has been encrypted.
To decrypt the message, decrypt the first block of ciphertext and XOR the result with the IV. The result is the first plaintext block. For subsequent ciphertext blocks, decrypt each block and XOR the previous block of the encrypted message into the result.
CBC operates on entire blocks of ciphertext and plaintext at a time. This means that message lengths must be a multiple of the block cipher block size. AES has a block size of 16 bytes no matter the key size. Since messages do not necessarily always have a length that is a multiple of 16 bytes, it may be necessary to pad the message to a 16-byte boundary. Padding requires the sender and receiver to implicitly agree on the padding convention. Improperly designed or implemented padding schemes may leak information to an attacker through a padding oracle attack for example.
The IV is generated by the party performing the encryption operation. Within the scope of any encryption key, the IV value must be unique. The IV does not need to be kept secret and is usually transmitted together with the ciphertext to the decryting party. In CBC mode, the IVs must not be predictable. Two recommended ways to generate IVs is to either:
CBC mode has several drawbacks. Unless interfacing with legacy devices, it is recommended to use an AEAD (Authenticated Encryption with Associated Data) mode such as CCM or GCM. Below is a non-exhaustive list of reasons to use a different block cipher mode of operation.
Before starting a CBC operation, the application must do the following:
The AESCBC_oneStepEncrypt and AESCBC_oneStepDecrypt functions perform a CBC 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 plaintext or ciphertext to be available to the function at the start of the call. All devices support single call operations.
After the CBC operation completes, the application should either start another operation or close the driver by calling AESCBC_close().
In order to use the AESCBC APIs, the application is required to provide device-specific AESCBC configuration in the Board.c file. The AESCBC driver interface defines a configuration data structure:
The application must declare an array of AESCBC_Config elements, named AESCBC_config[]. Each element of AESCBC_config[] must be populated with pointers to a device specific AESCBC driver implementation's driver object and hardware attributes. The hardware attributes define properties such as the AESCBC peripheral's base address. Each element in AESCBC_config[] corresponds to an AESCBC instance and none of the elements should have NULL pointers. There is no correlation between the index and the peripheral designation (such as AESCBC0 or AESCBC1). For example, it is possible to use AESCBC_config[0] for AESCBC1. 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 AESCBC configuration is very device dependent, you will need to check the doxygen for the device specific AESCBC implementation. There you will find a description of the AESCBC hardware attributes. Please also refer to the Board.c file of any of your examples to see the AESCBC configuration.
The AESCBC_Params structure is passed to the AESCBC_open() call. If NULL is passed for the parameters, AESCBC_open() uses default parameters. A AESCBC_Params structure is initialized with default values by passing it to AESCBC_Params_init(). Some of the AESCBC parameters are described below. To see brief descriptions of all the parameters, see AESCBC_Params.
### Single call CBC encryption 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 | AESCBC_Operation_ |
Struct containing the parameters required for encrypting/decrypting a message. More... | |
struct | AESCBC_Config_ |
AESCBC Global configuration. More... | |
struct | AESCBC_Params_ |
CBC Parameters. More... | |
Macros | |
#define | AESCBC_CMD_RESERVED (32) |
#define | AESCBC_STATUS_RESERVED (-32) |
#define | AESCBC_STATUS_SUCCESS (0) |
Successful status code. More... | |
#define | AESCBC_STATUS_ERROR (-1) |
Generic error status code. More... | |
#define | AESCBC_STATUS_UNDEFINEDCMD (-2) |
An error status code returned by AESCBC_control() for undefined command codes. More... | |
#define | AESCBC_STATUS_RESOURCE_UNAVAILABLE (-3) |
An error status code returned if the hardware or software resource is currently unavailable. More... | |
Typedefs | |
typedef struct AESCBC_Config_ * | AESCBC_Handle |
A handle that is returned from an AESCBC_open() call. More... | |
typedef enum AESCBC_ReturnBehavior_ | AESCBC_ReturnBehavior |
The way in which CBC function calls return after performing an encryption or decryption operation. More... | |
typedef enum AESCBC_Mode_ | AESCBC_Mode |
Enum for the direction of the CBC operation. More... | |
typedef struct AESCBC_Operation_ | AESCBC_Operation |
Struct containing the parameters required for encrypting/decrypting a message. More... | |
typedef enum AESCBC_OperationType_ | AESCBC_OperationType |
Enum for the operation types supported by the driver. More... | |
typedef struct AESCBC_Config_ | AESCBC_Config |
AESCBC Global configuration. More... | |
typedef void(* | AESCBC_CallbackFxn) (AESCBC_Handle handle, int_fast16_t returnValue, AESCBC_Operation *operation, AESCBC_OperationType operationType) |
The definition of a callback function used by the AESCBC driver when used in AESCBC_RETURN_BEHAVIOR_CALLBACK. More... | |
typedef struct AESCBC_Params_ | AESCBC_Params |
CBC Parameters. More... | |
Enumerations | |
enum | AESCBC_ReturnBehavior_ { AESCBC_RETURN_BEHAVIOR_CALLBACK = 1, AESCBC_RETURN_BEHAVIOR_BLOCKING = 2, AESCBC_RETURN_BEHAVIOR_POLLING = 4 } |
The way in which CBC function calls return after performing an encryption or decryption operation. More... | |
enum | AESCBC_Mode_ { AESCBC_MODE_ENCRYPT = 1, AESCBC_MODE_DECRYPT = 2 } |
Enum for the direction of the CBC operation. More... | |
enum | AESCBC_OperationType_ { AESCBC_OPERATION_TYPE_ENCRYPT = 1, AESCBC_OPERATION_TYPE_DECRYPT = 2 } |
Enum for the operation types supported by the driver. More... | |
Functions | |
void | AESCBC_init (void) |
This function initializes the CBC module. More... | |
void | AESCBC_Params_init (AESCBC_Params *params) |
Function to initialize the AESCBC_Params struct to its defaults. More... | |
AESCBC_Handle | AESCBC_open (uint_least8_t index, AESCBC_Params *params) |
This function opens a given CBC peripheral. More... | |
void | AESCBC_close (AESCBC_Handle handle) |
Function to close a CBC peripheral specified by the CBC handle. More... | |
int_fast16_t | AESCBC_control (AESCBC_Handle handle, uint32_t cmd, void *args) |
Function performs implementation specific features on a given AESCBC_Handle. More... | |
void | AESCBC_Operation_init (AESCBC_Operation *operationStruct) |
Function to initialize an AESCBC_Operation struct to its defaults. More... | |
int_fast16_t | AESCBC_oneStepEncrypt (AESCBC_Handle handle, AESCBC_Operation *operationStruct) |
Function to perform an AESCBC encryption operation in one call. More... | |
int_fast16_t | AESCBC_oneStepDecrypt (AESCBC_Handle handle, AESCBC_Operation *operationStruct) |
Function to perform an AESCBC decryption operation in one call. More... | |
Variables | |
const AESCBC_Params | AESCBC_defaultParams |
Default AESCBC_Params structure. More... | |
typedef struct AESCBC_Config_* AESCBC_Handle |
A handle that is returned from an AESCBC_open() call.
typedef enum AESCBC_ReturnBehavior_ AESCBC_ReturnBehavior |
The way in which CBC function calls return after performing an encryption or decryption operation.
Not all CBC 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.
AESCBC functions exhibiting the specified return behavior have restrictions on the context from which they may be called.
Task | Hwi | Swi | |
---|---|---|---|
AESCBC_RETURN_BEHAVIOR_CALLBACK | X | X | X |
AESCBC_RETURN_BEHAVIOR_BLOCKING | X | ||
AESCBC_RETURN_BEHAVIOR_POLLING | X | X | X |
typedef enum AESCBC_Mode_ AESCBC_Mode |
Enum for the direction of the CBC operation.
typedef struct AESCBC_Operation_ AESCBC_Operation |
Struct containing the parameters required for encrypting/decrypting a message.
typedef enum AESCBC_OperationType_ AESCBC_OperationType |
Enum for the operation types supported by the driver.
typedef struct AESCBC_Config_ AESCBC_Config |
AESCBC Global configuration.
The AESCBC_Config structure contains a set of pointers used to characterize the AESCBC driver implementation.
This structure needs to be defined before calling AESCBC_init() and it must not be changed thereafter.
typedef void(* AESCBC_CallbackFxn) (AESCBC_Handle handle, int_fast16_t returnValue, AESCBC_Operation *operation, AESCBC_OperationType operationType) |
The definition of a callback function used by the AESCBC driver when used in AESCBC_RETURN_BEHAVIOR_CALLBACK.
handle | Handle of the client that started the CBC operation. |
returnValue | The result of the CBC operation. May contain an error code. Informs the application of why the callback function was called. |
operation | A pointer to an operation struct. |
operationType | This parameter determines which operation the callback refers to. |
typedef struct AESCBC_Params_ AESCBC_Params |
CBC Parameters.
CBC Parameters are used to with the AESCBC_open() call. Default values for these parameters are set using AESCBC_Params_init().
The way in which CBC function calls return after performing an encryption or decryption operation.
Not all CBC 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.
AESCBC functions exhibiting the specified return behavior have restrictions on the context from which they may be called.
Task | Hwi | Swi | |
---|---|---|---|
AESCBC_RETURN_BEHAVIOR_CALLBACK | X | X | X |
AESCBC_RETURN_BEHAVIOR_BLOCKING | X | ||
AESCBC_RETURN_BEHAVIOR_POLLING | X | X | X |
enum AESCBC_Mode_ |
void AESCBC_init | ( | void | ) |
This function initializes the CBC module.
void AESCBC_Params_init | ( | AESCBC_Params * | params | ) |
Function to initialize the AESCBC_Params struct to its defaults.
params | An pointer to AESCBC_Params structure for initialization |
Defaults values are: returnBehavior = AESCBC_RETURN_BEHAVIOR_BLOCKING callbackFxn = NULL timeout = SemaphoreP_WAIT_FOREVER custom = NULL
AESCBC_Handle AESCBC_open | ( | uint_least8_t | index, |
AESCBC_Params * | params | ||
) |
This function opens a given CBC peripheral.
index | Logical peripheral number for the CBC indexed into the AESCBC_config table |
params | Pointer to an parameter block, if NULL it will use default values. |
void AESCBC_close | ( | AESCBC_Handle | handle | ) |
Function to close a CBC peripheral specified by the CBC handle.
handle | A CBC handle returned from AESCBC_open() |
int_fast16_t AESCBC_control | ( | AESCBC_Handle | handle, |
uint32_t | cmd, | ||
void * | args | ||
) |
Function performs implementation specific features on a given AESCBC_Handle.
Commands for AESCBC_control can originate from AESCBC.h or from implementation specific AESCBC*.h (AESCBCCC26XX.h, AESCBCMSP432.h, etc.. ) files. While commands from AESCBC.h are API portable across driver implementations, not all implementations may support all these commands. Conversely, commands from driver implementation specific AESCBC*.h files add unique driver capabilities but are not API portable across all AESCBC driver implementations.
Commands supported by AESCBC.h follow an AESCBC_CMD_<cmd> naming convention.
Commands supported by AESCBC*.h follow an AESCBC*_CMD_<cmd> naming convention.
Each control command defines arg differently. The types of arg are documented with each command.
See AESCBC_CMD "AESCBC_control command codes" for command codes.
See AESCBC_STATUS "AESCBC_control return status codes" for status codes.
handle | An AESCBC handle returned from AESCBC_open() |
cmd | AESCBC.h or AESCBC*.h commands. |
args | An optional R/W (read/write) command argument accompanied with cmd |
void AESCBC_Operation_init | ( | AESCBC_Operation * | operationStruct | ) |
Function to initialize an AESCBC_Operation struct to its defaults.
operationStruct | A pointer to an AESCBC_Operation structure for initialization |
Defaults values are all zeros.
int_fast16_t AESCBC_oneStepEncrypt | ( | AESCBC_Handle | handle, |
AESCBC_Operation * | operationStruct | ||
) |
Function to perform an AESCBC encryption operation in one call.
[in] | handle | A CBC handle returned from AESCBC_open() |
[in] | operationStruct | A pointer to a struct containing the parameters required to perform the operation. |
int_fast16_t AESCBC_oneStepDecrypt | ( | AESCBC_Handle | handle, |
AESCBC_Operation * | operationStruct | ||
) |
Function to perform an AESCBC decryption operation in one call.
[in] | handle | A CBC handle returned from AESCBC_open() |
[in] | operationStruct | A pointer to a struct containing the parameters required to perform the operation. |
const AESCBC_Params AESCBC_defaultParams |
Default AESCBC_Params structure.