Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
AESCTR.h File Reference

Detailed Description

AESCTR driver header.


Warning
This is a beta API. It may change in future releases.

Overview

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.

Operation

CTR encryption and decryption perform the following steps:

  1. Set the counter value to the initial counter value
  2. Encrypt the counter value under the symmetric key
  3. XOR the encrypted counter value with the input block (plaintext or ciphertext)
  4. Increment the counter value. Interpret the byte array as a big-endian number.
  5. Repeat steps 2 to 4 until the input is completely processed. If the input is not evenly divisible by the block size, XOR the last (u = input length % block size) input bytes with the most significant u bytes of the last encrypted counter value.

CTR performs the same steps regardless of whether it is used to encrypt or decrypt a message. The input merely changes.

Choosing Initial Counter Values

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.

Usage

Before starting a CTR operation

Before starting a CTR operation, the application must do the following:

Starting a CTR operation

The AESCTR_oneStepEncrypt() and AESCTR_oneStepDecrypt() functions perform a CTR operation in a single call.

After the CTR operation completes

After the CTR operation completes, the application should either start another operation or close the driver by calling AESCTR_close().

Synopsis

// Import AESCTR Driver definitions
// Define name for AESCTR channel index
#define AESCTR_INSTANCE 0
handle = AESCTR_open(AESCTR_INSTANCE, NULL);
// Initialize symmetric key
CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
// Set up AESCTR_Operation
operation.key = &cryptoKey;
operation.input = plaintext;
operation.output = ciphertext;
operation.inputLength = sizeof(plaintext);
operation.iv = iv;
encryptionResult = AESCTR_oneStepEncrypt(handle, &operation);
AESCTR_close(handle);

Examples

Single call CTR encryption with plaintext CryptoKey in blocking return mode
...
AESCTR_Handle handle;
CryptoKey cryptoKey;
int_fast16_t encryptionResult;
// For example purposes only. Generate IVs in a non-static way in practice.
// Test vector from NIST SP 800-38A
uint8_t initialCounter[16] = {0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7,
0xf8, 0xf9, 0xfa, 0xfb, 0xfc, 0xfd, 0xfe, 0xff};
uint8_t plaintext[64] = {0x6b, 0xc1, 0xbe, 0xe2, 0x2e, 0x40, 0x9f, 0x96,
0xe9, 0x3d, 0x7e, 0x11, 0x73, 0x93, 0x17, 0x2a,
0xae, 0x2d, 0x8a, 0x57, 0x1e, 0x03, 0xac, 0x9c,
0x9e, 0xb7, 0x6f, 0xac, 0x45, 0xaf, 0x8e, 0x51,
0x30, 0xc8, 0x1c, 0x46, 0xa3, 0x5c, 0xe4, 0x11,
0xe5, 0xfb, 0xc1, 0x19, 0x1a, 0x0a, 0x52, 0xef,
0xf6, 0x9f, 0x24, 0x45, 0xdf, 0x4f, 0x9b, 0x17,
0xad, 0x2b, 0x41, 0x7b, 0xe6, 0x6c, 0x37, 0x10};
ruint8_t ciphertext[sizeof(plaintext)];
uint8_t keyingMaterial[16] = {0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6,
0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf, 0x4f, 0x3c};
handle = AESCTR_open(0, NULL);
if (handle == NULL) {
// handle error
while(1);
}
CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
AESCTR_Operation operation;
AESCTR_Operation_init(&operation);
operation.key = &cryptoKey;
operation.input = plaintext;
operation.output = ciphertext;
operation.inputLength = sizeof(plaintext);
operation.initialCounter = initialCounter;
encryptionResult = AESCTR_oneStepEncrypt(handle, &operation);
if (encryptionResult != AESCTR_STATUS_SUCCESS) {
// handle error
while(1);
}
// The ciphertext should be the following after the encryption operation:
// 0x87, 0x4d, 0x61, 0x91, 0xb6, 0x20, 0xe3, 0x26,
// 0x1b, 0xef, 0x68, 0x64, 0x99, 0x0d, 0xb6, 0xce,
// 0x98, 0x06, 0xf6, 0x6b, 0x79, 0x70, 0xfd, 0xff,
// 0x86, 0x17, 0x18, 0x7b, 0xb9, 0xff, 0xfd, 0xff,
// 0x5a, 0xe4, 0xdf, 0x3e, 0xdb, 0xd5, 0xd3, 0x5e,
// 0x5b, 0x4f, 0x09, 0x02, 0x0d, 0xb0, 0x3e, 0xab,
// 0x1e, 0x03, 0x1d, 0xda, 0x2f, 0xbe, 0x03, 0xd1,
// 0x79, 0x21, 0x70, 0xa0, 0xf3, 0x00, 0x9c, 0xee
AESCTR_close(handle);
Single call CTR decryption with plaintext CryptoKey in callback return mode
...
void ctrCallback(AESCTR_Handle handle,
int_fast16_t returnValue,
AESCTR_Operation *operation,
AESCTR_OperationType operationType) {
if (returnValue != AESCTR_STATUS_SUCCESS) {
// handle error
while(1);
}
}
AESCTR_Operation operation;
void ctrStartFunction(void) {
uint8_t initialCounter[16] = {0x00, 0xE0, 0x01, 0x7B, 0x27, 0x77, 0x7F, 0x3F,
0x4A, 0x17, 0x86, 0xF0, 0x00, 0x00, 0x00, 0x01};
uint8_t ciphertext[] = {0xC1, 0xCF, 0x48, 0xA8, 0x9F, 0x2F, 0xFD, 0xD9,
0xCF, 0x46, 0x52, 0xE9, 0xEF, 0xDB, 0x72, 0xD7,
0x45, 0x40, 0xA4, 0x2B, 0xDE, 0x6D, 0x78, 0x36,
0xD5, 0x9A, 0x5C, 0xEA, 0xAE, 0xF3, 0x10, 0x53,
0x25, 0xB2, 0x07, 0x2F};
uint8_t keyingMaterial[] = {0x76, 0x91, 0xBE, 0x03, 0x5E, 0x50, 0x20, 0xA8,
0xAC, 0x6E, 0x61, 0x85, 0x29, 0xF9, 0xA0, 0xDC};
uint8_t plaintext[sizeof(ciphertext)];
AESCTR_Handle handle;
AESCTR_Params params;
CryptoKey cryptoKey;
int_fast16_t decryptionResult;
AESCTR_Operation operation;
params.callbackFxn = ctrCallback;
handle = AESCTR_open(0, &params);
if (handle == NULL) {
// handle error
while(1);
}
CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
AESCTR_Operation_init(&operation);
operation.key = &cryptoKey;
operation.input = ciphertext;
operation.output = plaintext;
operation.inputLength = sizeof(ciphertext);
operation.initialCounter = initialCounter;
decryptionResult = AESCTR_oneStepDecrypt(handle, &operation);
if (decryptionResult != AESCTR_STATUS_SUCCESS) {
// handle error
while(1);
}
// do other things while CTR operation completes in the background
// After the operation completes and the callback is invoked, the resultant
// plaintext should be
// 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
// 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F,
// 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
// 0x18, 0x19, 0x1A, 0x1B, 0x1C, 0x1D, 0x1E, 0x1F,
// 0x20, 0x21, 0x22, 0x23
}
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h>
Include dependency graph for AESCTR.h:
This graph shows which files directly or indirectly include this file:

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 AESCTR_ConfigAESCTR_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...
 
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...
 

Macro Definition Documentation

§ AESCTR_STATUS_RESERVED

#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 AESCTRXYZ_STATUS_ERROR0 AESCTR_STATUS_RESERVED - 0
#define AESCTRXYZ_STATUS_ERROR1 AESCTR_STATUS_RESERVED - 1
#define AESCTRXYZ_STATUS_ERROR2 AESCTR_STATUS_RESERVED - 2

§ AESCTR_STATUS_SUCCESS

#define AESCTR_STATUS_SUCCESS   (0)

Successful status code.

Functions return AESCTR_STATUS_SUCCESS if the function was executed successfully.

§ AESCTR_STATUS_ERROR

#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.

§ AESCTR_STATUS_RESOURCE_UNAVAILABLE

#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.

§ AESCTR_STATUS_CANCELED

#define AESCTR_STATUS_CANCELED   (-3)

The ongoing operation was canceled.

Typedef Documentation

§ AESCTR_Handle

A handle that is returned from an AESCTR_open() call.

§ AESCTR_CallbackFxn

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.

Parameters
handleHandle of the client that started the CTR operation.
returnValueThe result of the CTR operation. May contain an error code. Informs the application of why the callback function was called.
operationA pointer to an operation struct.
operationTypeThis parameter determines which operation the callback refers to.

Enumeration Type Documentation

§ AESCTR_ReturnBehavior

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
Enumerator
AESCTR_RETURN_BEHAVIOR_CALLBACK 

The function call will return immediately while the CTR operation goes on in the background. The registered callback function is called after the operation completes. The context the callback function is called (task, HWI, SWI) is implementation-dependent.

AESCTR_RETURN_BEHAVIOR_BLOCKING 

The function call will block while the CTR operation goes on in the background. CTR operation results are available after the function returns.

AESCTR_RETURN_BEHAVIOR_POLLING 

The function call will continuously poll a flag while CTR operation goes on in the background. CTR operation results are available after the function returns.

§ AESCTR_Mode

Enum for the direction of the CTR operation.

Enumerator
AESCTR_MODE_ENCRYPT 
AESCTR_MODE_DECRYPT 

§ AESCTR_OperationType

Enum for the operation types supported by the driver.

Enumerator
AESCTR_OPERATION_TYPE_ENCRYPT 
AESCTR_OPERATION_TYPE_DECRYPT 

Function Documentation

§ AESCTR_init()

void AESCTR_init ( void  )

This function initializes the CTR module.

Precondition
The AESCTR_config structure must exist and be persistent before this function can be called. This function must also be called before any other CTR driver APIs. This function call does not modify any peripheral registers.

§ AESCTR_Params_init()

void AESCTR_Params_init ( AESCTR_Params params)

Function to initialize the AESCTR_Params struct to its defaults.

Parameters
paramsAn pointer to AESCTR_Params structure for initialization

Defaults values are: returnBehavior = AESCTR_RETURN_BEHAVIOR_BLOCKING callbackFxn = NULL timeout = SemaphoreP_WAIT_FOREVER custom = NULL

§ AESCTR_open()

AESCTR_Handle AESCTR_open ( uint_least8_t  index,
const AESCTR_Params params 
)

This function opens a given AESCTR peripheral.

Precondition
AESCTR driver has been initialized using AESCTR_init()
Parameters
indexLogical peripheral number for the CTR indexed into the AESCTR_config table
paramsPointer to a parameter block, if NULL it will use default values.
Returns
A AESCTR_Handle on success or a NULL on an error or if it has been opened already.
See also
AESCTR_init()
AESCTR_close()

§ AESCTR_close()

void AESCTR_close ( AESCTR_Handle  handle)

Function to close a CTR peripheral specified by the CTR handle.

Precondition
AESCTR_open() has to be called first.
Parameters
handleA CTR handle returned from AESCTR_open()
See also
AESCTR_open()

§ AESCTR_Operation_init()

void AESCTR_Operation_init ( AESCTR_Operation operationStruct)

Function to initialize an AESCTR_Operation struct to its defaults.

Parameters
operationStructA pointer to an AESCTR_Operation structure for initialization

Defaults values are all zeros.

§ AESCTR_oneStepEncrypt()

int_fast16_t AESCTR_oneStepEncrypt ( AESCTR_Handle  handle,
AESCTR_Operation operationStruct 
)

Function to perform an AESCTR encryption operation in one call.

Note
None of the buffers provided as arguments may be altered by the application during an ongoing operation. Doing so can yield corrupted ciphertext.
Precondition
AESCTR_open() and AESCTR_Operation_init() must be called first.
Parameters
[in]handleA CTR handle returned from AESCTR_open()
[in]operationStructA pointer to a struct containing the parameters required to perform the operation.
Return values
AESCTR_STATUS_SUCCESSThe operation succeeded.
AESCTR_STATUS_ERRORThe operation failed.
AESCTR_STATUS_RESOURCE_UNAVAILABLEThe required hardware resource was not available. Try again later.
AESCTR_STATUS_CANCELEDThe operation was canceled.
See also
AESCTR_oneStepDecrypt()

§ AESCTR_oneStepDecrypt()

int_fast16_t AESCTR_oneStepDecrypt ( AESCTR_Handle  handle,
AESCTR_Operation operationStruct 
)

Function to perform an AESCTR decryption operation in one call.

Note
None of the buffers provided as arguments may be altered by the application during an ongoing operation. Doing so can yield corrupted plaintext.
Precondition
AESCTR_open() and AESCTR_Operation_init() must be called first.
Parameters
[in]handleA CTR handle returned from AESCTR_open()
[in]operationStructA pointer to a struct containing the parameters required to perform the operation.
Return values
AESCTR_STATUS_SUCCESSThe operation succeeded.
AESCTR_STATUS_ERRORThe operation failed.
AESCTR_STATUS_RESOURCE_UNAVAILABLEThe required hardware resource was not available. Try again later.
AESCTR_STATUS_CANCELED
See also
AESCTR_oneStepEncrypt()

§ AESCTR_cancelOperation()

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.

Parameters
handleHandle of the operation to cancel
Return values
AESCTR_STATUS_SUCCESSThe operation was canceled.
AESCTR_STATUS_ERRORThe operation was not canceled. There may be no operation to cancel.

§ AESCTR_construct()

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.

Parameters
configAESCTR_Config describing the location of the object and hwAttrs.
paramsAESCTR_Params to configure the driver instance.
Returns
Returns a AESCTR_Handle on success or NULL on failure.
Precondition
The object struct config points to must be zeroed out prior to calling this function. Otherwise, unexpected behavior may ensue.

Variable Documentation

§ AESCTR_defaultParams

const AESCTR_Params AESCTR_defaultParams

Default AESCTR_Params structure.

See also
AESCTR_Params_init()
© Copyright 1995-2019, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale