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 divisible 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 encrypted. 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 decrypting 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().
### Single call CBC encryption with plaintext CryptoKey in blocking return mode #
### Multi-step CBC encryption with plaintext CryptoKey in blocking return mode #
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/drivers/AESCommon.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h>
Go to the source code of this file.
Data Structures | |
struct | AESCBC_OneStepOperation |
Struct containing the parameters required for encrypting/decrypting a message in a single-step operation. More... | |
struct | AESCBC_SegmentedOperation |
Struct containing the parameters required for encrypting/decrypting a message in a segmented operation. Must be updated for steps of a segmented operation where data is processed (addData() and finalize()). More... | |
union | AESCBC_OperationUnion |
Union containing a reference to a one step or segmented operation. More... | |
struct | AESCBC_Params |
CBC Parameters. More... | |
Macros | |
#define | AESCBC_STATUS_RESERVED AES_STATUS_RESERVED |
#define | AESCBC_STATUS_SUCCESS AES_STATUS_SUCCESS |
Successful status code. More... | |
#define | AESCBC_STATUS_ERROR AES_STATUS_ERROR |
Generic error status code. More... | |
#define | AESCBC_STATUS_RESOURCE_UNAVAILABLE AES_STATUS_RESOURCE_UNAVAILABLE |
An error status code returned if the hardware or software resource is currently unavailable. More... | |
#define | AESCBC_STATUS_CANCELED AES_STATUS_CANCELED |
The ongoing operation was canceled. More... | |
#define | AESCBC_STATUS_FEATURE_NOT_SUPPORTED AES_STATUS_FEATURE_NOT_SUPPORTED |
The operation requested is not supported for now. More... | |
#define | AESCBC_STATUS_KEYSTORE_INVALID_ID AES_STATUS_KEYSTORE_INVALID_ID |
The operation tried to load a key from the keystore using an invalid key ID. More... | |
#define | AESCBC_STATUS_KEYSTORE_GENERIC_ERROR AES_STATUS_KEYSTORE_GENERIC_ERROR |
The key store module returned a generic error. See key store documentation for additional details. More... | |
#define | AESCBC_STATUS_UNALIGNED_IO_NOT_SUPPORTED AES_STATUS_UNALIGNED_IO_NOT_SUPPORTED |
The operation does not support non-word-aligned input and/or output. More... | |
Typedefs | |
typedef AESCommon_Config | AESCBC_Config |
AESCBC Global configuration. More... | |
typedef AESCBC_Config * | AESCBC_Handle |
A handle that is returned from an AESCBC_open() call. More... | |
typedef AESCBC_OneStepOperation | AESCBC_Operation |
typedef union AESCBC_OperationUnion | AESCBC_OperationUnion |
Union containing a reference to a one step or segmented operation. More... | |
typedef void(* | AESCBC_CallbackFxn) (AESCBC_Handle handle, int_fast16_t returnValue, AESCBC_OperationUnion *operation, AESCBC_OperationType operationType) |
The definition of a callback function used by the AESCBC driver when used in AESCBC_RETURN_BEHAVIOR_CALLBACK. More... | |
Enumerations | |
enum | AESCBC_ReturnBehavior { AESCBC_RETURN_BEHAVIOR_CALLBACK = AES_RETURN_BEHAVIOR_CALLBACK, AESCBC_RETURN_BEHAVIOR_BLOCKING = AES_RETURN_BEHAVIOR_BLOCKING, AESCBC_RETURN_BEHAVIOR_POLLING = AES_RETURN_BEHAVIOR_POLLING } |
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, AESCBC_OP_TYPE_ONESTEP_ENCRYPT = 1, AESCBC_OP_TYPE_ONESTEP_DECRYPT = 2, AESCBC_OP_TYPE_ENCRYPT_SEGMENTED = 3, AESCBC_OP_TYPE_DECRYPT_SEGMENTED = 4, AESCBC_OP_TYPE_FINALIZE_ENCRYPT_SEGMENTED = 5, AESCBC_OP_TYPE_FINALIZE_DECRYPT_SEGMENTED = 6 } |
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, const 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... | |
void | AESCBC_Operation_init (AESCBC_Operation *operationStruct) |
Function to initialize an AESCBC_Operation struct to its defaults. More... | |
void | AESCBC_OneStepOperation_init (AESCBC_OneStepOperation *operationStruct) |
Function to initialize an AESCBC_OneStepOperation struct to its defaults. More... | |
void | AESCBC_SegmentedOperation_init (AESCBC_SegmentedOperation *operationStruct) |
Function to initialize an AESCBC_SegmentedOperation struct to its defaults. More... | |
int_fast16_t | AESCBC_oneStepEncrypt (AESCBC_Handle handle, AESCBC_OneStepOperation *operationStruct) |
Function to perform an AESCBC encryption operation in one call. More... | |
int_fast16_t | AESCBC_oneStepDecrypt (AESCBC_Handle handle, AESCBC_OneStepOperation *operationStruct) |
Function to perform an AESCBC decryption operation in one call. More... | |
int_fast16_t | AESCBC_setupEncrypt (AESCBC_Handle handle, const CryptoKey *key) |
Function to prepare a segmented AESCBC encryption operation. More... | |
int_fast16_t | AESCBC_setupDecrypt (AESCBC_Handle handle, const CryptoKey *key) |
Function to prepare a segmented AESCBC decryption operation. More... | |
int_fast16_t | AESCBC_setIV (AESCBC_Handle handle, const uint8_t *iv, size_t ivLength) |
Function to set an initialization vector for an AES CBC segmented operation. More... | |
int_fast16_t | AESCBC_generateIV (AESCBC_Handle handle, uint8_t *iv, size_t ivSize, size_t *ivLength) |
Function to generate an initialization vector for an AES CBC segmented encryption operation. More... | |
int_fast16_t | AESCBC_addData (AESCBC_Handle handle, AESCBC_SegmentedOperation *operation) |
Encrypts or decrypts a segment of data defined by the AESCBC_SegmentedOperation struct. More... | |
int_fast16_t | AESCBC_finalize (AESCBC_Handle handle, AESCBC_SegmentedOperation *operation) |
Finalize the AES operation. If new data needs to be added, inputLength will be used to govern how many bytes will be written. New data must be a multiple of a block length, 16 bytes, or 0 if no new data needs to be added. More... | |
int_fast16_t | AESCBC_cancelOperation (AESCBC_Handle handle) |
Cancels an ongoing AESCBC operation. More... | |
AESCBC_Handle | AESCBC_construct (AESCBC_Config *config, const AESCBC_Params *params) |
Constructs a new AESCBC object. More... | |
Variables | |
const AESCBC_Params | AESCBC_defaultParams |
Default AESCBC_Params structure. More... | |
#define AESCBC_STATUS_RESERVED AES_STATUS_RESERVED |
Common AESCBC status code reservation offset. AESCBC driver implementations should offset status codes with AESCBC_STATUS_RESERVED growing negatively.
Example implementation specific status codes:
#define AESCBC_STATUS_SUCCESS AES_STATUS_SUCCESS |
Successful status code.
Functions return AESCBC_STATUS_SUCCESS if the function was executed successfully.
#define AESCBC_STATUS_ERROR AES_STATUS_ERROR |
Generic error status code.
Functions return AESCBC_STATUS_ERROR if the function was not executed successfully and no more pertinent error code could be returned.
#define AESCBC_STATUS_RESOURCE_UNAVAILABLE AES_STATUS_RESOURCE_UNAVAILABLE |
An error status code returned if the hardware or software resource is currently unavailable.
AESCBC driver implementations may have hardware or software limitations on how many clients can simultaneously perform operations. This status code is returned if the mutual exclusion mechanism signals that an operation cannot currently be performed.
#define AESCBC_STATUS_CANCELED AES_STATUS_CANCELED |
The ongoing operation was canceled.
#define AESCBC_STATUS_FEATURE_NOT_SUPPORTED AES_STATUS_FEATURE_NOT_SUPPORTED |
The operation requested is not supported for now.
This code is returned by AESCBC_generateIV(), and internal generation of IVs isn't supported for now. Eventually, this function will make the TRNG generate the IV.
#define AESCBC_STATUS_KEYSTORE_INVALID_ID AES_STATUS_KEYSTORE_INVALID_ID |
The operation tried to load a key from the keystore using an invalid key ID.
#define AESCBC_STATUS_KEYSTORE_GENERIC_ERROR AES_STATUS_KEYSTORE_GENERIC_ERROR |
The key store module returned a generic error. See key store documentation for additional details.
#define AESCBC_STATUS_UNALIGNED_IO_NOT_SUPPORTED AES_STATUS_UNALIGNED_IO_NOT_SUPPORTED |
The operation does not support non-word-aligned input and/or output.
AESCBC driver implementations may have restrictions on the alignment of input/output data due to performance limitations of the hardware.
typedef AESCommon_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 AESCBC_Config* AESCBC_Handle |
A handle that is returned from an AESCBC_open() call.
typedef union AESCBC_OperationUnion AESCBC_OperationUnion |
Union containing a reference to a one step or segmented operation.
typedef void(* AESCBC_CallbackFxn) (AESCBC_Handle handle, int_fast16_t returnValue, AESCBC_OperationUnion *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 union. |
operationType | This parameter determines which operation the callback refers to. |
The way in which CBC function calls return after performing an encryption or decryption operation.
Not all CBC operations exhibit the specified return behavior. Functions that do not require significant computation and cannot offload that computation to a background thread behave like regular functions. Which functions exhibit the specified 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 |
enum AESCBC_OperationType |
Enum for the operation types supported by the driver.
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, |
const AESCBC_Params * | params | ||
) |
This function opens a given CBC peripheral.
[in] | index | Logical peripheral number for the CBC indexed into the AESCBC_config table |
[in] | 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.
[in] | handle | A CBC handle |
void AESCBC_Operation_init | ( | AESCBC_Operation * | operationStruct | ) |
Function to initialize an AESCBC_Operation struct to its defaults.
[in] | operationStruct | A pointer to an AESCBC_Operation structure for initialization |
Defaults values are all zeros.
void AESCBC_OneStepOperation_init | ( | AESCBC_OneStepOperation * | operationStruct | ) |
Function to initialize an AESCBC_OneStepOperation struct to its defaults.
[in] | operationStruct | A pointer to an AESCBC_OneStepOperation structure for initialization |
Defaults values are all zeros.
void AESCBC_SegmentedOperation_init | ( | AESCBC_SegmentedOperation * | operationStruct | ) |
Function to initialize an AESCBC_SegmentedOperation struct to its defaults.
[in] | operationStruct | A pointer to an AESCBC_SegmentedOperation structure for initialization |
Defaults values are all zeros.
int_fast16_t AESCBC_oneStepEncrypt | ( | AESCBC_Handle | handle, |
AESCBC_OneStepOperation * | operationStruct | ||
) |
Function to perform an AESCBC encryption operation in one call.
[in] | handle | A CBC handle returned from AESCBC_open() or AESCBC_construct() |
[in] | operationStruct | A pointer to a struct containing the parameters required to perform the operation. |
AESCBC_STATUS_SUCCESS | The operation succeeded. |
AESCBC_STATUS_ERROR | The operation failed. |
AESCBC_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
AESCBC_STATUS_UNALIGNED_IO_NOT_SUPPORTED | The input and/or output buffer were not word-aligned. |
int_fast16_t AESCBC_oneStepDecrypt | ( | AESCBC_Handle | handle, |
AESCBC_OneStepOperation * | operationStruct | ||
) |
Function to perform an AESCBC decryption operation in one call.
[in] | handle | A CBC handle returned from AESCBC_open() or AESCBC_construct() |
[in] | operationStruct | A pointer to a struct containing the parameters required to perform the operation. |
AESCBC_STATUS_SUCCESS | The operation succeeded. |
AESCBC_STATUS_ERROR | The operation failed. |
AESCBC_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
AESCBC_STATUS_UNALIGNED_IO_NOT_SUPPORTED | The input and/or output buffer were not word-aligned. |
int_fast16_t AESCBC_setupEncrypt | ( | AESCBC_Handle | handle, |
const CryptoKey * | key | ||
) |
Function to prepare a segmented AESCBC encryption operation.
This function sets up a segmented AESCBC encryption operation.
[in] | handle | A CBC handle returned from AESCBC_open() or AESCBC_construct() |
[in] | key | Pointer to a previously initialized CryptoKey. |
AESCBC_STATUS_SUCCESS | The operation succeeded. |
AESCBC_STATUS_ERROR | The operation failed. |
int_fast16_t AESCBC_setupDecrypt | ( | AESCBC_Handle | handle, |
const CryptoKey * | key | ||
) |
Function to prepare a segmented AESCBC decryption operation.
This function sets up a segmented AESCBC decryption operation.
[in] | handle | A CBC handle returned from AESCBC_open() or AESCBC_construct() |
[in] | key | Pointer to a previously initialized CryptoKey. |
AESCBC_STATUS_SUCCESS | The operation succeeded. |
AESCBC_STATUS_ERROR | The operation failed. |
int_fast16_t AESCBC_setIV | ( | AESCBC_Handle | handle, |
const uint8_t * | iv, | ||
size_t | ivLength | ||
) |
Function to set an initialization vector for an AES CBC segmented operation.
This function sets up a segmented AESCBC encryption or decryption operation.
[in] | handle | A CBC handle returned from AESCBC_open() or AESCBC_construct() |
[in] | iv | Pointer to the buffer containing the initialization vector |
[in] | ivLength | The length of the initialization vector. The length of the IV buffer must be 16 bytes. |
AESCBC_STATUS_SUCCESS | The operation succeeded. |
AESCBC_STATUS_ERROR | The operation failed. |
int_fast16_t AESCBC_generateIV | ( | AESCBC_Handle | handle, |
uint8_t * | iv, | ||
size_t | ivSize, | ||
size_t * | ivLength | ||
) |
Function to generate an initialization vector for an AES CBC segmented encryption operation.
This function sets up a segmented AESCBC encryption operation.
[in] | handle | A CBC handle returned from AESCBC_open() or AESCBC_construct() |
[in] | iv | Pointer to a buffer to write the generated initialization vector to |
[in] | ivSize | Size of the buffer pointed to by iv. This buffer must be 16 bytes long for AES CBC mode. |
[out] | ivLength | The length of the initialization vector actually written if the operation was successful. |
AESCBC_STATUS_SUCCESS | The operation succeeded. |
AESCBC_STATUS_ERROR | The operation failed. |
AESCBC_STATUS_FEATURE_NOT_SUPPORTED | The operation is not supported in this device. |
int_fast16_t AESCBC_addData | ( | AESCBC_Handle | handle, |
AESCBC_SegmentedOperation * | operation | ||
) |
Encrypts or decrypts a segment of data defined by the AESCBC_SegmentedOperation struct.
AESCBC_addData() may be called an arbitrary number times before finishing the operation with AESCBC_finalize().
This function returns according to the return behavior set when opening the driver.
[in] | handle | A CBC handle returned from AESCBC_open() or AESCBC_construct() |
[in] | operation | Pointer to a segmented CBC operation structure |
AESCBC_STATUS_SUCCESS | The operation succeeded. |
AESCBC_STATUS_ERROR | The operation failed. |
AESCBC_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
AESCBC_STATUS_UNALIGNED_IO_NOT_SUPPORTED | The input and/or output buffer were not word-aligned. |
int_fast16_t AESCBC_finalize | ( | AESCBC_Handle | handle, |
AESCBC_SegmentedOperation * | operation | ||
) |
Finalize the AES operation. If new data needs to be added, inputLength
will be used to govern how many bytes will be written. New data must be a multiple of a block length, 16 bytes, or 0 if no new data needs to be added.
[in] | handle | A CBC handle returned from AESCBC_open() or AESCBC_construct() |
[in] | operation | Pointer to a segmented CBC operation structure |
AESCBC_STATUS_SUCCESS | In AESCBC_RETURN_BEHAVIOR_BLOCKING and AESCBC_RETURN_BEHAVIOR_POLLING, this means the CBC was generated successfully. In AESCBC_RETURN_BEHAVIOR_CALLBACK, this means the operation started successfully. |
AESCBC_STATUS_ERROR | The operation failed. |
AESCBC_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
AESCBC_STATUS_UNALIGNED_IO_NOT_SUPPORTED | The input and/or output buffer were not word-aligned. |
int_fast16_t AESCBC_cancelOperation | ( | AESCBC_Handle | handle | ) |
Cancels an ongoing AESCBC operation.
Asynchronously cancels an AESCBC operation. Only available when using AESCBC_RETURN_BEHAVIOR_CALLBACK. The operation will terminate as though an error occurred. The return status code of the operation will be AESCBC_STATUS_CANCELED.
[in] | handle | Handle of the operation to cancel |
AESCBC_STATUS_SUCCESS | The operation was canceled or the operation had already completed. |
AESCBC_STATUS_ERROR | The IV buffer was not properly cleared. |
AESCBC_Handle AESCBC_construct | ( | AESCBC_Config * | config, |
const AESCBC_Params * | params | ||
) |
Constructs a new AESCBC object.
Unlike AESCBC_open(), AESCBC_construct() does not require the hwAttrs and object to be allocated in a AESCBC_Config array that is indexed into. Instead, the AESCBC_Config, hwAttrs, and object can be allocated at any location. This allows for relatively simple run-time allocation of temporary driver instances on the stack or the heap. The drawback is that this makes it more difficult to write device-agnostic code. If you use an ifdef with DeviceFamily, you can choose the correct object and hwAttrs to allocate. That compilation unit will be tied to the device it was compiled for at this point. To change devices, recompilation of the application with a different DeviceFamily setting is necessary.
[in] | config | AESCBC_Config describing the location of the object and hwAttrs. |
[in] | params | AESCBC_Params to configure the driver instance. |
config
points to must be zeroed out prior to calling this function. Otherwise, unexpected behavior may ensue. const AESCBC_Params AESCBC_defaultParams |
Default AESCBC_Params structure.