AESCTR driver header.
The Counter (CTR) mode of operation is a generic block cipher mode of operation that can be used with any block cipher including AES.
CTR mode encrypts and decrypts messages. It is not required for the message length to be evenly divisible by the cipher block size. This also means that padding the message is not required.
CTR encryption and decryption perform the following steps:
CTR performs the same steps regardless of whether it is used to encrypt or decrypt a message. The input merely changes.
CTR requires that each counter value used to encrypt a block of a message is unique for each key used. If this requirement is not kept, the confidentiality of that message block may be compromised.
There are two general strategies when choosing the initial counter value of a CTR operation to ensure this requirement holds.
The first is to choose an initial counter value for the first message and increment the initial counter value for a subsequent message by by message length % block length (16-bytes for AES). This effectively turns a sequence of messages into one long message. If 0 is chosen as the initial counter value, up to 2^128 - 1 blocks may be encrypted before key rotation is mandatory.
The second is to split the initial counter value into a nonce and counter section. The nonce of length n bits must be unique per message. This allows for up to 2^n - 1 messages to be encrypted before key rotation is required. The counter section of length c is incremented as usual. This limits messages to a length of at most 2^c - 1 blocks. n and c must be chosen such that n + c = block length in bits (128 bits for AES) holds.
Before starting a CTR operation, the application must do the following:
The AESCTR_oneStepEncrypt() and AESCTR_oneStepDecrypt() functions perform a CTR operation in a single call.
After the CTR operation completes, the application should either start another operation or close the driver by calling AESCTR_close().
#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 | AESCTR_Operation |
Struct containing the parameters required for encrypting/decrypting a message. More... | |
struct | AESCTR_Config |
AESCTR Global configuration. More... | |
struct | AESCTR_Params |
CTR Parameters. More... | |
Macros | |
#define | AESCTR_STATUS_RESERVED (-32) |
#define | AESCTR_STATUS_SUCCESS (0) |
Successful status code. More... | |
#define | AESCTR_STATUS_ERROR (-1) |
Generic error status code. More... | |
#define | AESCTR_STATUS_RESOURCE_UNAVAILABLE (-2) |
An error status code returned if the hardware or software resource is currently unavailable. More... | |
#define | AESCTR_STATUS_CANCELED (-3) |
The ongoing operation was canceled. More... | |
Typedefs | |
typedef struct AESCTR_Config | AESCTR_Config |
AESCTR Global configuration. More... | |
typedef AESCTR_Config * | AESCTR_Handle |
A handle that is returned from an AESCTR_open() call. More... | |
typedef void(* | AESCTR_CallbackFxn) (AESCTR_Handle handle, int_fast16_t returnValue, AESCTR_Operation *operation, AESCTR_OperationType operationType) |
The definition of a callback function used by the AESCTR driver when used in AESCTR_RETURN_BEHAVIOR_CALLBACK. More... | |
Enumerations | |
enum | AESCTR_ReturnBehavior { AESCTR_RETURN_BEHAVIOR_CALLBACK = 1, AESCTR_RETURN_BEHAVIOR_BLOCKING = 2, AESCTR_RETURN_BEHAVIOR_POLLING = 4 } |
The way in which CTR function calls return after performing an encryption or decryption operation. More... | |
enum | AESCTR_Mode { AESCTR_MODE_ENCRYPT = 1, AESCTR_MODE_DECRYPT = 2 } |
Enum for the direction of the CTR operation. More... | |
enum | AESCTR_OperationType { AESCTR_OPERATION_TYPE_ENCRYPT = 1, AESCTR_OPERATION_TYPE_DECRYPT = 2 } |
Enum for the operation types supported by the driver. More... | |
Functions | |
void | AESCTR_init (void) |
This function initializes the CTR module. More... | |
void | AESCTR_Params_init (AESCTR_Params *params) |
Function to initialize the AESCTR_Params struct to its defaults. More... | |
AESCTR_Handle | AESCTR_open (uint_least8_t index, const AESCTR_Params *params) |
This function opens a given AESCTR peripheral. More... | |
void | AESCTR_close (AESCTR_Handle handle) |
Function to close a CTR peripheral specified by the CTR handle. More... | |
void | AESCTR_Operation_init (AESCTR_Operation *operationStruct) |
Function to initialize an AESCTR_Operation struct to its defaults. More... | |
int_fast16_t | AESCTR_oneStepEncrypt (AESCTR_Handle handle, AESCTR_Operation *operationStruct) |
Function to perform an AESCTR encryption operation in one call. More... | |
int_fast16_t | AESCTR_oneStepDecrypt (AESCTR_Handle handle, AESCTR_Operation *operationStruct) |
Function to perform an AESCTR decryption operation in one call. More... | |
int_fast16_t | AESCTR_cancelOperation (AESCTR_Handle handle) |
Cancels an ongoing AESCTR operation. More... | |
Variables | |
const AESCTR_Params | AESCTR_defaultParams |
Default AESCTR_Params structure. More... | |
#define AESCTR_STATUS_RESERVED (-32) |
Common AESCTR status code reservation offset. AESCTR driver implementations should offset status codes with AESCTR_STATUS_RESERVED growing negatively.
Example implementation specific status codes:
#define AESCTR_STATUS_SUCCESS (0) |
Successful status code.
Functions return AESCTR_STATUS_SUCCESS if the function was executed successfully.
#define AESCTR_STATUS_ERROR (-1) |
Generic error status code.
Functions return AESCTR_STATUS_ERROR if the function was not executed successfully and no more pertinent error code could be returned.
#define AESCTR_STATUS_RESOURCE_UNAVAILABLE (-2) |
An error status code returned if the hardware or software resource is currently unavailable.
AESCTR 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 AESCTR_STATUS_CANCELED (-3) |
The ongoing operation was canceled.
typedef struct AESCTR_Config AESCTR_Config |
AESCTR Global configuration.
The AESCTR_Config structure contains a set of pointers used to characterize the AESCTR driver implementation.
This structure needs to be defined before calling AESCTR_init() and it must not be changed thereafter.
typedef AESCTR_Config* AESCTR_Handle |
A handle that is returned from an AESCTR_open() call.
typedef void(* AESCTR_CallbackFxn) (AESCTR_Handle handle, int_fast16_t returnValue, AESCTR_Operation *operation, AESCTR_OperationType operationType) |
The definition of a callback function used by the AESCTR driver when used in AESCTR_RETURN_BEHAVIOR_CALLBACK.
handle | Handle of the client that started the CTR operation. |
returnValue | The result of the CTR 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 CTR function calls return after performing an encryption or decryption operation.
Not all CTR 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.
AESCTR functions exhibiting the specified return behavior have restrictions on the context from which they may be called.
Task | Hwi | Swi | |
---|---|---|---|
AESCTR_RETURN_BEHAVIOR_CALLBACK | X | X | X |
AESCTR_RETURN_BEHAVIOR_BLOCKING | X | ||
AESCTR_RETURN_BEHAVIOR_POLLING | X | X | X |
enum AESCTR_Mode |
enum AESCTR_OperationType |
void AESCTR_init | ( | void | ) |
This function initializes the CTR module.
void AESCTR_Params_init | ( | AESCTR_Params * | params | ) |
Function to initialize the AESCTR_Params struct to its defaults.
params | An pointer to AESCTR_Params structure for initialization |
Defaults values are: returnBehavior = AESCTR_RETURN_BEHAVIOR_BLOCKING callbackFxn = NULL timeout = SemaphoreP_WAIT_FOREVER custom = NULL
AESCTR_Handle AESCTR_open | ( | uint_least8_t | index, |
const AESCTR_Params * | params | ||
) |
This function opens a given AESCTR peripheral.
index | Logical peripheral number for the CTR indexed into the AESCTR_config table |
params | Pointer to a parameter block, if NULL it will use default values. |
void AESCTR_close | ( | AESCTR_Handle | handle | ) |
Function to close a CTR peripheral specified by the CTR handle.
handle | A CTR handle returned from AESCTR_open() |
void AESCTR_Operation_init | ( | AESCTR_Operation * | operationStruct | ) |
Function to initialize an AESCTR_Operation struct to its defaults.
operationStruct | A pointer to an AESCTR_Operation structure for initialization |
Defaults values are all zeros.
int_fast16_t AESCTR_oneStepEncrypt | ( | AESCTR_Handle | handle, |
AESCTR_Operation * | operationStruct | ||
) |
Function to perform an AESCTR encryption operation in one call.
[in] | handle | A CTR handle returned from AESCTR_open() |
[in] | operationStruct | A pointer to a struct containing the parameters required to perform the operation. |
AESCTR_STATUS_SUCCESS | The operation succeeded. |
AESCTR_STATUS_ERROR | The operation failed. |
AESCTR_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
AESCTR_STATUS_CANCELED | The operation was canceled. |
int_fast16_t AESCTR_oneStepDecrypt | ( | AESCTR_Handle | handle, |
AESCTR_Operation * | operationStruct | ||
) |
Function to perform an AESCTR decryption operation in one call.
[in] | handle | A CTR handle returned from AESCTR_open() |
[in] | operationStruct | A pointer to a struct containing the parameters required to perform the operation. |
AESCTR_STATUS_SUCCESS | The operation succeeded. |
AESCTR_STATUS_ERROR | The operation failed. |
AESCTR_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
AESCTR_STATUS_CANCELED |
int_fast16_t AESCTR_cancelOperation | ( | AESCTR_Handle | handle | ) |
Cancels an ongoing AESCTR operation.
Asynchronously cancels an AESCTR operation. Only available when using AESCTR_RETURN_BEHAVIOR_CALLBACK or AESCTR_RETURN_BEHAVIOR_BLOCKING. The operation will terminate as though an error occured. The return status code of the operation will be AESCTR_STATUS_CANCELED.
handle | Handle of the operation to cancel |
AESCTR_STATUS_SUCCESS | The operation was canceled. |
AESCTR_STATUS_ERROR | The operation was not canceled. There may be no operation to cancel. |
const AESCTR_Params AESCTR_defaultParams |
Default AESCTR_Params structure.