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 of ciphertext can be decrypted individually and out of order. Encrypting the same plaintext using the same key yields identical ciphertext. This raises several security issues. For this reason, ECB is not recommended unless interfacing with legacy systems which cannot be updated 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 of 128, 192, or 256 bits.
Before starting an ECB operation, the application must do the following:
The AESECB_oneStepEncrypt and AESECB_oneStepDecrypt functions do an 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 encrypting each block individually.
After the ECB operation completes, the application should either start another operation or close the driver by calling AESECB_close()
### Encryption of multiple plaintext blocks in blocking mode #
### One step ECB decryption in callback mode #
### Multi-step ECB encryption in blocking 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 | AESECB_Operation |
Struct containing the parameters required for encrypting/decrypting and a message. More... | |
struct | AESECB_Params |
ECB Parameters. More... | |
Macros | |
#define | AESECB_STATUS_RESERVED AES_STATUS_RESERVED |
#define | AESECB_STATUS_SUCCESS AES_STATUS_SUCCESS |
Successful status code. More... | |
#define | AESECB_STATUS_ERROR AES_STATUS_ERROR |
Generic error status code. More... | |
#define | AESECB_STATUS_RESOURCE_UNAVAILABLE AES_STATUS_RESOURCE_UNAVAILABLE |
An error status code returned if the hardware or software resource is currently unavailable. More... | |
#define | AESECB_STATUS_CANCELED AES_STATUS_CANCELED |
The ongoing operation was canceled. More... | |
#define | AESECB_STATUS_FEATURE_NOT_SUPPORTED AES_STATUS_FEATURE_NOT_SUPPORTED |
The operation requested is not supported on the target hardware or by the current state of the SW implementation. More... | |
#define | AESECB_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 | AESECB_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 | AESECB_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 | AESECB_Config |
AESECB Global configuration. More... | |
typedef AESECB_Config * | AESECB_Handle |
A handle that is returned from an AESECB_open() call. 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... | |
Enumerations | |
enum | AESECB_ReturnBehavior { AESECB_RETURN_BEHAVIOR_CALLBACK = AES_RETURN_BEHAVIOR_CALLBACK, AESECB_RETURN_BEHAVIOR_BLOCKING = AES_RETURN_BEHAVIOR_BLOCKING, AESECB_RETURN_BEHAVIOR_POLLING = AES_RETURN_BEHAVIOR_POLLING } |
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, AESECB_OPERATION_TYPE_ENCRYPT_SEGMENTED = 3, AESECB_OPERATION_TYPE_DECRYPT_SEGMENTED = 4, AESECB_OPERATION_TYPE_FINALIZE_ENCRYPT_SEGMENTED = 5, AESECB_OPERATION_TYPE_FINALIZE_DECRYPT_SEGMENTED = 6 } |
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, const AESECB_Params *params) |
This function opens a given ECB peripheral. More... | |
void | AESECB_close (AESECB_Handle handle) |
Function to close an ECB peripheral specified by the ECB handle. More... | |
void | AESECB_Operation_init (AESECB_Operation *operationStruct) |
Function to initialize an 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... | |
int_fast16_t | AESECB_setupEncrypt (AESECB_Handle handle, const CryptoKey *key) |
Function to prepare a segmented AESECB encryption operation. More... | |
int_fast16_t | AESECB_setupDecrypt (AESECB_Handle handle, const CryptoKey *key) |
Function to prepare a segmented AESECB decryption operation. More... | |
int_fast16_t | AESECB_addData (AESECB_Handle handle, AESECB_Operation *operation) |
Encrypts or decrypts segment of data with a length. More... | |
int_fast16_t | AESECB_finalize (AESECB_Handle handle, AESECB_Operation *operation) |
Finalize the AES transaction. If new data needs to be added, inputLength will be used to govern how many bytes will be written. More... | |
int_fast16_t | AESECB_cancelOperation (AESECB_Handle handle) |
Cancels an ongoing AESECB operation. More... | |
AESECB_Handle | AESECB_construct (AESECB_Config *config, const AESECB_Params *params) |
Constructs a new AESECB object. More... | |
Variables | |
const AESECB_Params | AESECB_defaultParams |
Default AESECB_Params structure. More... | |
#define AESECB_STATUS_RESERVED AES_STATUS_RESERVED |
Common AESECB status code reservation offset. AESECB driver implementations should offset status codes with AESECB_STATUS_RESERVED growing negatively.
Example implementation specific status codes:
#define AESECB_STATUS_SUCCESS AES_STATUS_SUCCESS |
Successful status code.
Functions return AESECB_STATUS_SUCCESS if the function was executed successfully.
#define AESECB_STATUS_ERROR AES_STATUS_ERROR |
Generic error status code.
Functions return AESECB_STATUS_ERROR if the function was not executed successfully and no more pertinent error code could be returned.
#define AESECB_STATUS_RESOURCE_UNAVAILABLE AES_STATUS_RESOURCE_UNAVAILABLE |
An error status code returned if the hardware or software resource is currently unavailable.
AESECB 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 AESECB_STATUS_CANCELED AES_STATUS_CANCELED |
The ongoing operation was canceled.
#define AESECB_STATUS_FEATURE_NOT_SUPPORTED AES_STATUS_FEATURE_NOT_SUPPORTED |
The operation requested is not supported on the target hardware or by the current state of the SW implementation.
#define AESECB_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 AESECB_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 AESECB_STATUS_UNALIGNED_IO_NOT_SUPPORTED AES_STATUS_UNALIGNED_IO_NOT_SUPPORTED |
The operation does not support non-word-aligned input and/or output.
AESECB driver implementations may have restrictions on the alignment of input/output data due to performance limitations of the hardware.
typedef AESCommon_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 AESECB_Config* AESECB_Handle |
A handle that is returned from an AESECB_open() call.
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. |
returnValue | The result of the ECB 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. |
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 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.
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 |
enum AESECB_OperationType |
Enum for the operation types supported by the driver.
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, |
const AESECB_Params * | params | ||
) |
This function opens a given ECB peripheral.
[in] | index | Logical peripheral number for the ECB indexed into the AESECB_config table |
[in] | params | Pointer to an parameter block, if NULL it will use default values. |
void AESECB_close | ( | AESECB_Handle | handle | ) |
Function to close an ECB peripheral specified by the ECB handle.
[in] | handle | An ECB handle returned from AESECB_open() or AESECB_construct() |
void AESECB_Operation_init | ( | AESECB_Operation * | operationStruct | ) |
Function to initialize an AESECB_Operation struct to its defaults.
[in] | 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 | An ECB handle returned from AESECB_open() or AESECB_construct() |
[in] | operation | A pointer to a struct containing the parameters required to perform the operation. |
AESECB_STATUS_SUCCESS | The operation succeeded. |
AESECB_STATUS_ERROR | The operation failed. |
AESECB_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
AESECB_STATUS_UNALIGNED_IO_NOT_SUPPORTED | The input and/or output buffer were not word-aligned. |
int_fast16_t AESECB_oneStepDecrypt | ( | AESECB_Handle | handle, |
AESECB_Operation * | operation | ||
) |
Function to perform an AESECB decryption in one call.
[in] | handle | An ECB handle returned from AESECB_open() or AESECB_construct() |
[in] | operation | A pointer to a struct containing the parameters required to perform the operation. |
AESECB_STATUS_SUCCESS | The operation succeeded. |
AESECB_STATUS_ERROR | The operation failed. |
AESECB_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
AESECB_STATUS_UNALIGNED_IO_NOT_SUPPORTED | The input and/or output buffer were not word-aligned. |
int_fast16_t AESECB_setupEncrypt | ( | AESECB_Handle | handle, |
const CryptoKey * | key | ||
) |
Function to prepare a segmented AESECB encryption operation.
This functions sets up a segmented AESECB encryption operation.
[in] | handle | An ECB handle returned from AESECB_open() or AESECB_construct() |
[in] | key | A previously initialized CryptoKey. |
AESECB_STATUS_SUCCESS | The operation succeeded. |
AESECB_STATUS_ERROR | The operation failed. |
int_fast16_t AESECB_setupDecrypt | ( | AESECB_Handle | handle, |
const CryptoKey * | key | ||
) |
Function to prepare a segmented AESECB decryption operation.
This functions sets up a segmented AESECB decryption operation.
[in] | handle | An ECB handle returned from AESECB_open() or AESECB_construct() |
[in] | key | A previously initialized CryptoKey. |
AESECB_STATUS_SUCCESS | The operation succeeded. |
AESECB_STATUS_ERROR | The operation failed. |
int_fast16_t AESECB_addData | ( | AESECB_Handle | handle, |
AESECB_Operation * | operation | ||
) |
Encrypts or decrypts segment of data with a length.
AESECB_addData() may be called an arbitrary number times before finishing the operation with AESECB_finalize(). Note that this function is called for use with segmented operations. For segmented operations, inputLength
will govern the input/output lengths and must be a AES block size multiple (16-bytes).
[in] | handle | An ECB handle returned from AESECB_open() or AESECB_construct() |
[in] | operation | Pointer to ECB operation structure() |
AESECB_STATUS_SUCCESS | The operation succeeded. |
AESECB_STATUS_ERROR | The operation failed. |
AESECB_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
AESECB_STATUS_CANCELED | The operation was canceled. |
AESECB_STATUS_UNALIGNED_IO_NOT_SUPPORTED | The input and/or output buffer were not word-aligned. |
int_fast16_t AESECB_finalize | ( | AESECB_Handle | handle, |
AESECB_Operation * | operation | ||
) |
Finalize the AES transaction. If new data needs to be added, inputLength
will be used to govern how many bytes will be written.
[in] | handle | An ECB handle returned from AESECB_open() or AESECB_construct() |
[in] | operation | Pointer to ECB operation structure() |
AESECB_STATUS_SUCCESS | In AESECB_RETURN_BEHAVIOR_BLOCKING and AESECB_RETURN_BEHAVIOR_POLLING, this means the ECB output was generated successfully. In AESECB_RETURN_BEHAVIOR_CALLBACK, this means the operation started successfully. |
AESECB_STATUS_ERROR | The operation failed. |
AESECB_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
AESECB_STATUS_CANCELED | The operation was canceled. |
AESECB_STATUS_UNALIGNED_IO_NOT_SUPPORTED | The input and/or output buffer were not word-aligned. |
int_fast16_t AESECB_cancelOperation | ( | AESECB_Handle | handle | ) |
Cancels an ongoing AESECB operation.
Asynchronously cancels an AESECB operation. Only available when using AESECB_RETURN_BEHAVIOR_CALLBACK. The operation will terminate as though an error occurred. The return status code of the operation will be AESECB_STATUS_CANCELED.
[in] | handle | Handle of the operation to cancel |
AESECB_STATUS_SUCCESS | The operation was canceled, or the requested operation had already completed. |
AESECB_Handle AESECB_construct | ( | AESECB_Config * | config, |
const AESECB_Params * | params | ||
) |
Constructs a new AESECB object.
Unlike AESECB_open(), AESECB_construct() does not require the hwAttrs and object to be allocated in a AESECB_Config array that is indexed into. Instead, the AESECB_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.
config | AESECB_Config describing the location of the object and hwAttrs. |
params | AESECB_Params to configure the driver instance. |
config
points to must be zeroed out prior to calling this function. Otherwise, unexpected behavior may ensue. const AESECB_Params AESECB_defaultParams |
Default AESECB_Params structure.