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 which is used in this implementation.
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 <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 | AESCTR_OneStepOperation |
Struct containing the parameters required for encrypting/decrypting a message using a one-step operation. More... | |
struct | AESCTR_SegmentedOperation |
Struct containing the parameters required for encrypting/decrypting a message using a segmented operation. This struct must be updated for each "add data" and "finalize" step. Modifying the structure and any buffers that it points to while an operation is in progress is prohibited. More... | |
union | AESCTR_OperationUnion |
Union containing a reference to a one-step and segmented operation structure. More... | |
struct | AESCTR_Params |
CTR Parameters. More... | |
Macros | |
#define | AESCTR_STATUS_RESERVED AES_STATUS_RESERVED |
#define | AESCTR_STATUS_SUCCESS AES_STATUS_SUCCESS |
Successful status code. More... | |
#define | AESCTR_STATUS_ERROR AES_STATUS_ERROR |
Generic error status code. More... | |
#define | AESCTR_STATUS_RESOURCE_UNAVAILABLE AES_STATUS_RESOURCE_UNAVAILABLE |
An error status code returned if the hardware or software resource is currently unavailable. More... | |
#define | AESCTR_STATUS_CANCELED AES_STATUS_CANCELED |
The ongoing operation was canceled. More... | |
#define | AESCTR_STATUS_FEATURE_NOT_SUPPORTED AES_STATUS_FEATURE_NOT_SUPPORTED |
The operation requested is not supported. More... | |
#define | AESCTR_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 | AESCTR_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 | AESCTR_STATUS_UNALIGNED_IO_NOT_SUPPORTED AES_STATUS_UNALIGNED_IO_NOT_SUPPORTED |
The operation does not support non-word-aligned input and/or output. More... | |
#define | AESCTR_OP_MODE_MASK 0x0F |
Mask for the operation mode. More... | |
#define | AESCTR_OP_FLAG_SEGMENTED 0x10 /* bit 4 */ |
Flag indicating a segmented operation. More... | |
#define | AESCTR_OP_FLAG_FINALIZE 0x20 /* bit 5 */ |
Flag indicating a finalize operation. More... | |
#define | AESCTR_OP_FLAGS_MASK (AESCTR_OP_FLAG_SEGMENTED | AESCTR_OP_FLAG_FINALIZE) |
Mask for all valid operation flags. More... | |
Typedefs | |
typedef AESCTR_OneStepOperation | AESCTR_Operation |
typedef AESCommon_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_OperationUnion *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 = AES_RETURN_BEHAVIOR_CALLBACK, AESCTR_RETURN_BEHAVIOR_BLOCKING = AES_RETURN_BEHAVIOR_BLOCKING, AESCTR_RETURN_BEHAVIOR_POLLING = AES_RETURN_BEHAVIOR_POLLING } |
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 = AESCTR_MODE_ENCRYPT, AESCTR_OPERATION_TYPE_DECRYPT = AESCTR_MODE_DECRYPT, AESCTR_OPERATION_TYPE_ENCRYPT_SEGMENTED = (AESCTR_MODE_ENCRYPT | 0x10 ), AESCTR_OPERATION_TYPE_DECRYPT_SEGMENTED = (AESCTR_MODE_DECRYPT | 0x10 ), AESCTR_OPERATION_TYPE_ENCRYPT_FINALIZE = (AESCTR_MODE_ENCRYPT | 0x20 ), AESCTR_OPERATION_TYPE_DECRYPT_FINALIZE = (AESCTR_MODE_DECRYPT | 0x20 ) } |
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 AESCTR handle. More... | |
int_fast16_t | AESCTR_setupEncrypt (AESCTR_Handle handle, const CryptoKey *key, const uint8_t *initialCounter) |
Function to prepare a segmented AESCTR encryption operation. More... | |
int_fast16_t | AESCTR_setupDecrypt (AESCTR_Handle handle, const CryptoKey *key, const uint8_t *initialCounter) |
Function to prepare a segmented AESCTR decryption operation. More... | |
int_fast16_t | AESCTR_addData (AESCTR_Handle handle, AESCTR_SegmentedOperation *operation) |
Encrypts or decrypts a segment of data with a length. More... | |
int_fast16_t | AESCTR_finalize (AESCTR_Handle handle, AESCTR_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. More... | |
void | AESCTR_Operation_init (AESCTR_Operation *operation) |
Function to initialize an AESCTR_Operation struct to its defaults (all zeroes) More... | |
void | AESCTR_OneStepOperation_init (AESCTR_OneStepOperation *operation) |
Function to initialize an AESCTR_OneStepOperation struct to its defaults (all zeroes) More... | |
void | AESCTR_SegmentedOperation_init (AESCTR_SegmentedOperation *operation) |
Function to initialize an AESCTR_SegmentedOperation struct to its defaults (all zeroes) More... | |
int_fast16_t | AESCTR_oneStepEncrypt (AESCTR_Handle handle, AESCTR_OneStepOperation *operation) |
Function to perform an AESCTR encryption operation in one call. More... | |
int_fast16_t | AESCTR_oneStepDecrypt (AESCTR_Handle handle, AESCTR_OneStepOperation *operation) |
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... | |
AESCTR_Handle | AESCTR_construct (AESCTR_Config *config, const AESCTR_Params *params) |
Constructs a new AESCTR object. More... | |
Variables | |
const AESCTR_Params | AESCTR_defaultParams |
Default AESCTR_Params structure. More... | |
#define AESCTR_STATUS_RESERVED AES_STATUS_RESERVED |
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 AES_STATUS_SUCCESS |
Successful status code.
Functions return AESCTR_STATUS_SUCCESS if the function was executed successfully.
#define AESCTR_STATUS_ERROR AES_STATUS_ERROR |
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 AES_STATUS_RESOURCE_UNAVAILABLE |
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 AES_STATUS_CANCELED |
The ongoing operation was canceled.
#define AESCTR_STATUS_FEATURE_NOT_SUPPORTED AES_STATUS_FEATURE_NOT_SUPPORTED |
The operation requested is not supported.
#define AESCTR_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 AESCTR_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 AESCTR_STATUS_UNALIGNED_IO_NOT_SUPPORTED AES_STATUS_UNALIGNED_IO_NOT_SUPPORTED |
The operation does not support non-word-aligned input and/or output.
AESCTR driver implementations may have restrictions on the alignment of input/output data due to performance limitations of the hardware.
#define AESCTR_OP_MODE_MASK 0x0F |
Mask for the operation mode.
#define AESCTR_OP_FLAG_SEGMENTED 0x10 /* bit 4 */ |
Flag indicating a segmented operation.
#define AESCTR_OP_FLAG_FINALIZE 0x20 /* bit 5 */ |
Flag indicating a finalize operation.
#define AESCTR_OP_FLAGS_MASK (AESCTR_OP_FLAG_SEGMENTED | AESCTR_OP_FLAG_FINALIZE) |
Mask for all valid operation flags.
typedef AESCommon_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_OperationUnion *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 | Pointer to the operation union 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 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.
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.
[in] | params | 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.
[in] | index | Logical peripheral number for the CTR indexed into the AESCTR_config table |
[in] | 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 AESCTR handle.
[in] | handle | AESCTR handle |
int_fast16_t AESCTR_setupEncrypt | ( | AESCTR_Handle | handle, |
const CryptoKey * | key, | ||
const uint8_t * | initialCounter | ||
) |
Function to prepare a segmented AESCTR encryption operation.
This function sets up a segmented AESCTR encryption operation.
[in] | handle | AESCTR handle |
[in] | key | Pointer to a previously initialized CryptoKey |
[in] | initialCounter | Pointer to initial counter value. The buffer size must be at least 16-bytes. If NULL, zero will be used for the initial counter value. |
AESCTR_STATUS_SUCCESS | The operation succeeded. |
AESCTR_STATUS_ERROR | The operation failed. |
int_fast16_t AESCTR_setupDecrypt | ( | AESCTR_Handle | handle, |
const CryptoKey * | key, | ||
const uint8_t * | initialCounter | ||
) |
Function to prepare a segmented AESCTR decryption operation.
This function sets up a segmented AESCTR decryption operation.
[in] | handle | AESCTR handle |
[in] | key | Pointer to a previously initialized CryptoKey. |
[in] | initialCounter | Pointer to initial counter value. The buffer size must be at least 16-bytes. If NULL, zero will be used for the initial counter value. |
AESCTR_STATUS_SUCCESS | The operation succeeded. |
AESCTR_STATUS_ERROR | The operation failed. |
int_fast16_t AESCTR_addData | ( | AESCTR_Handle | handle, |
AESCTR_SegmentedOperation * | operation | ||
) |
Encrypts or decrypts a segment of data with a length.
The inputLength must be a non-zero multiple of the block size (16-bytes). AESCTR_addData() may be called an arbitrary number of times before finishing the operation with AESCTR_finalize().
This function blocks until the final stream bytes have been computed. It returns immediately when AESCTR_RETURN_BEHAVIOR_CALLBACK is set.
[in] | handle | AESCTR handle |
[in] | operation | Pointer to AESCTR_SegmentedOperation structure 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_UNALIGNED_IO_NOT_SUPPORTED | The input and/or output buffer were not word-aligned. |
int_fast16_t AESCTR_finalize | ( | AESCTR_Handle | handle, |
AESCTR_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.
inputLength
to zero. The input and output buffers will not be used in this scenario.[in] | handle | AESCTR handle |
[in] | operation | Pointer to AESCTR_SegmentedOperation structure containing the parameters required to perform the operation. |
AESCTR_STATUS_SUCCESS | In AESCTR_RETURN_BEHAVIOR_BLOCKING and AESCTR_RETURN_BEHAVIOR_POLLING, this means the CTR was generated successfully. In AESCTR_RETURN_BEHAVIOR_CALLBACK, this means the operation started successfully. |
AESCTR_STATUS_ERROR | The operation failed. |
AESCTR_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
AESCTR_STATUS_UNALIGNED_IO_NOT_SUPPORTED | The input and/or output buffer were not word-aligned. |
void AESCTR_Operation_init | ( | AESCTR_Operation * | operation | ) |
Function to initialize an AESCTR_Operation struct to its defaults (all zeroes)
operation | Pointer to an AESCTR_Operation structure for initialization |
void AESCTR_OneStepOperation_init | ( | AESCTR_OneStepOperation * | operation | ) |
Function to initialize an AESCTR_OneStepOperation struct to its defaults (all zeroes)
[in] | operation | Pointer to an AESCTR_OneStepOperation structure for initialization |
void AESCTR_SegmentedOperation_init | ( | AESCTR_SegmentedOperation * | operation | ) |
Function to initialize an AESCTR_SegmentedOperation struct to its defaults (all zeroes)
[in] | operation | Pointer to an AESCTR_SegmentedOperation structure for initialization |
int_fast16_t AESCTR_oneStepEncrypt | ( | AESCTR_Handle | handle, |
AESCTR_OneStepOperation * | operation | ||
) |
Function to perform an AESCTR encryption operation in one call.
[in] | handle | AESCTR handle |
[in] | operation | 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_UNALIGNED_IO_NOT_SUPPORTED | The input and/or output buffer were not word-aligned. |
int_fast16_t AESCTR_oneStepDecrypt | ( | AESCTR_Handle | handle, |
AESCTR_OneStepOperation * | operation | ||
) |
Function to perform an AESCTR decryption operation in one call.
[in] | handle | AESCTR handle |
[in] | operation | 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_UNALIGNED_IO_NOT_SUPPORTED | The input and/or output buffer were not word-aligned. |
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. The operation will terminate as though an error occurred. The return status code of the operation will be AESCTR_STATUS_CANCELED.
[in] | handle | AESCTR handle |
AESCTR_STATUS_SUCCESS | The operation was canceled or the operation had already completed. |
AESCTR_Handle AESCTR_construct | ( | AESCTR_Config * | config, |
const AESCTR_Params * | params | ||
) |
Constructs a new AESCTR object.
Unlike AESCTR_open(), AESCTR_construct() does not require the hwAttrs and object to be allocated in a AESCTR_Config array that is indexed into. Instead, the AESCTR_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
points to must be zeroed out prior to calling this function. Otherwise, unexpected behavior may occur.[in] | config | AESCTR_Config describing the location of the object and hwAttrs. |
[in] | params | AESCTR_Params to configure the driver instance. |
const AESCTR_Params AESCTR_defaultParams |
Default AESCTR_Params structure.