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

Detailed Description

AESCBC driver header.


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

Overview

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 divisibly by the block size. Unlike ECB, it guarantees confidentiality of the entire message when the message is larger than one block.

Operation

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

Padding

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.

Initialization Vectors

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 decryting party. In CBC mode, the IVs must not be predictable. Two recommended ways to generate IVs is to either:

Drawbacks

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.

Usage

Before starting a CBC operation

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

Starting a CBC operation

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

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

Synopsis

// Import AESCBC Driver definitions
// Define name for AESCBC channel index
#define AESCBC_INSTANCE 0
handle = AESCBC_open(AESCBC_INSTANCE, NULL);
// Initialize symmetric key
CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
// Set up AESCBC_Operation
operation.key = &cryptoKey;
operation.input = plaintext;
operation.output = ciphertext;
operation.inputLength = sizeof(plaintext);
operation.iv = iv;
encryptionResult = AESCBC_oneStepEncrypt(handle, &operation);
AESCBC_close(handle);

Examples

### Single call CBC encryption with plaintext CryptoKey in blocking return mode #

#include <ti/drivers/types/cryptoKey/CryptoKey_Plaintext.h>
...
AESCBC_Handle handle;
CryptoKey cryptoKey;
int_fast16_t encryptionResult;
// For example purposes only. Generate IVs in a non-static way in practice.
// Test vector 0 from NIST CAPV set CBCMMT128
uint8_t iv[16] = {0x2f, 0xe2, 0xb3, 0x33, 0xce, 0xda, 0x8f, 0x98,
0xf4, 0xa9, 0x9b, 0x40, 0xd2, 0xcd, 0x34, 0xa8};
uint8_t plaintext[16] = {0x45, 0xcf, 0x12, 0x96, 0x4f, 0xc8, 0x24, 0xab,
0x76, 0x61, 0x6a, 0xe2, 0xf4, 0xbf, 0x08, 0x22};
uint8_t ciphertext[sizeof(plaintext)];
uint8_t keyingMaterial[16] = {0x1f, 0x8e, 0x49, 0x73, 0x95, 0x3f, 0x3f, 0xb0,
0xbd, 0x6b, 0x16, 0x66, 0x2e, 0x9a, 0x3c, 0x17};
// The ciphertext should be the following after the encryption operation:
// 0x0f, 0x61, 0xc4, 0xd4, 0x4c, 0x51, 0x47, 0xc0
// 0x3c, 0x19, 0x5a, 0xd7, 0xe2, 0xcc, 0x12, 0xb2
handle = AESCBC_open(0, NULL);
if (handle == NULL) {
// handle error
}
CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
AESCBC_Operation operation;
operation.key = &cryptoKey;
operation.input = plaintext;
operation.output = ciphertext;
operation.inputLength = sizeof(plaintext);
operation.iv = iv;
encryptionResult = AESCBC_oneStepEncrypt(handle, &operation);
if (encryptionResult != AESCBC_STATUS_SUCCESS) {
// handle error
}
AESCBC_close(handle);

Single call CBC decryption with plaintext CryptoKey in callback return mode

...
// Test vector 0 from NIST CAPV set CBCMMT256
uint8_t iv[16] = {0xdd, 0xbb, 0xb0, 0x17, 0x3f, 0x1e, 0x2d, 0xeb,
0x23, 0x94, 0xa6, 0x2a, 0xa2, 0xa0, 0x24, 0x0e};
uint8_t ciphertext[16] = {0xd5, 0x1d, 0x19, 0xde, 0xd5, 0xca, 0x4a, 0xe1,
0x4b, 0x2b, 0x20, 0xb0, 0x27, 0xff, 0xb0, 0x20};
uint8_t keyingMaterial[] = {0x43, 0xe9, 0x53, 0xb2, 0xae, 0xa0, 0x8a, 0x3a,
0xd5, 0x2d, 0x18, 0x2f, 0x58, 0xc7, 0x2b, 0x9c,
0x60, 0xfb, 0xe4, 0xa9, 0xca, 0x46, 0xa3, 0xcb,
0x89, 0xe3, 0x86, 0x38, 0x45, 0xe2, 0x2c, 0x9e};
uint8_t plaintext[sizeof(ciphertext)];
// The plaintext should be the following after the decryption operation:
// 0x07, 0x27, 0x0d, 0x0e, 0x63, 0xaa, 0x36, 0xda
// 0xed, 0x8c, 0x6a, 0xde, 0x13, 0xac, 0x1a, 0xf1
void cbcCallback(AESCBC_Handle handle,
int_fast16_t returnValue,
AESCBC_Operation *operation,
AESCBC_OperationType operationType) {
if (returnValue != AESCBC_STATUS_SUCCESS) {
// handle error
}
}
AESCBC_Operation operation;
void cbcStartFunction(void) {
AESCBC_Handle handle;
AESCBC_Params params;
CryptoKey cryptoKey;
int_fast16_t decryptionResult;
params.callbackFxn = cbcCallback;
handle = AESCBC_open(0, &params);
if (handle == NULL) {
// handle error
}
CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
AESCBC_Operation_init(&operation);
operation.key = &cryptoKey;
operation.input = plaintext;
operation.output = ciphertext;
operation.inputLength = sizeof(plaintext);
operation.iv = iv;
decryptionResult = AESCBC_oneStepDecrypt(handle, &operation);
if (decryptionResult != AESCBC_STATUS_SUCCESS) {
// handle error
}
// do other things while CBC operation completes in the background
}
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h>
Include dependency graph for AESCBC.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  AESCBC_Config_
 AESCBC Global configuration. More...
 
struct  AESCBC_Operation
 Struct containing the parameters required for encrypting/decrypting a message. More...
 
struct  AESCBC_Params
 CBC Parameters. More...
 

Macros

#define AESCBC_STATUS_RESERVED   (-32)
 
#define AESCBC_STATUS_SUCCESS   (0)
 Successful status code. More...
 
#define AESCBC_STATUS_ERROR   (-1)
 Generic error status code. More...
 
#define AESCBC_STATUS_RESOURCE_UNAVAILABLE   (-2)
 An error status code returned if the hardware or software resource is currently unavailable. More...
 
#define AESCBC_STATUS_CANCELED   (-3)
 The ongoing operation was canceled. More...
 

Typedefs

typedef struct AESCBC_Config_ AESCBC_Config
 AESCBC Global configuration. More...
 
typedef AESCBC_ConfigAESCBC_Handle
 A handle that is returned from an AESCBC_open() call. More...
 
typedef void(* AESCBC_CallbackFxn) (AESCBC_Handle handle, int_fast16_t returnValue, AESCBC_Operation *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 = 1, AESCBC_RETURN_BEHAVIOR_BLOCKING = 2, AESCBC_RETURN_BEHAVIOR_POLLING = 4 }
 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 }
 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...
 
int_fast16_t AESCBC_oneStepEncrypt (AESCBC_Handle handle, AESCBC_Operation *operationStruct)
 Function to perform an AESCBC encryption operation in one call. More...
 
int_fast16_t AESCBC_oneStepDecrypt (AESCBC_Handle handle, AESCBC_Operation *operationStruct)
 Function to perform an AESCBC decryption operation in one call. 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...
 
int_fast16_t AESCBC_getNextIv (AESCBC_Handle handle, uint8_t *iv)
 Returns the IV for the next block to encrypt or decrypt. More...
 

Variables

const AESCBC_Params AESCBC_defaultParams
 Default AESCBC_Params structure. More...
 

Macro Definition Documentation

§ AESCBC_STATUS_RESERVED

#define AESCBC_STATUS_RESERVED   (-32)

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 AESCBCXYZ_STATUS_ERROR0 AESCBC_STATUS_RESERVED - 0
#define AESCBCXYZ_STATUS_ERROR1 AESCBC_STATUS_RESERVED - 1
#define AESCBCXYZ_STATUS_ERROR2 AESCBC_STATUS_RESERVED - 2

§ AESCBC_STATUS_SUCCESS

#define AESCBC_STATUS_SUCCESS   (0)

Successful status code.

Functions return AESCBC_STATUS_SUCCESS if the function was executed successfully.

§ AESCBC_STATUS_ERROR

#define AESCBC_STATUS_ERROR   (-1)

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.

§ AESCBC_STATUS_RESOURCE_UNAVAILABLE

#define AESCBC_STATUS_RESOURCE_UNAVAILABLE   (-2)

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.

§ AESCBC_STATUS_CANCELED

#define AESCBC_STATUS_CANCELED   (-3)

The ongoing operation was canceled.

Typedef Documentation

§ AESCBC_Config

typedef struct AESCBC_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.

See also
AESCBC_init()

§ AESCBC_Handle

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

§ AESCBC_CallbackFxn

typedef void(* AESCBC_CallbackFxn) (AESCBC_Handle handle, int_fast16_t returnValue, AESCBC_Operation *operation, AESCBC_OperationType operationType)

The definition of a callback function used by the AESCBC driver when used in AESCBC_RETURN_BEHAVIOR_CALLBACK.

Parameters
handleHandle of the client that started the CBC operation.
returnValueThe result of the CBC 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

§ AESCBC_ReturnBehavior

The way in which CBC function calls return after performing an encryption or decryption operation.

Not all CBC 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.

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

The function call will return immediately while the CBC 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.

AESCBC_RETURN_BEHAVIOR_BLOCKING 

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

AESCBC_RETURN_BEHAVIOR_POLLING 

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

§ AESCBC_Mode

Enum for the direction of the CBC operation.

Enumerator
AESCBC_MODE_ENCRYPT 
AESCBC_MODE_DECRYPT 

§ AESCBC_OperationType

Enum for the operation types supported by the driver.

Enumerator
AESCBC_OPERATION_TYPE_ENCRYPT 
AESCBC_OPERATION_TYPE_DECRYPT 

Function Documentation

§ AESCBC_init()

void AESCBC_init ( void  )

This function initializes the CBC module.

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

§ AESCBC_Params_init()

void AESCBC_Params_init ( AESCBC_Params params)

Function to initialize the AESCBC_Params struct to its defaults.

Parameters
paramsAn pointer to AESCBC_Params structure for initialization

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

§ AESCBC_open()

AESCBC_Handle AESCBC_open ( uint_least8_t  index,
const AESCBC_Params params 
)

This function opens a given CBC peripheral.

Precondition
CBC controller has been initialized using AESCBC_init()
Parameters
indexLogical peripheral number for the CBC indexed into the AESCBC_config table
paramsPointer to an parameter block, if NULL it will use default values.
Returns
An AESCBC_Handle on success or a NULL on an error or if it has been opened already.
See also
AESCBC_init()
AESCBC_close()

§ AESCBC_close()

void AESCBC_close ( AESCBC_Handle  handle)

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

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

§ AESCBC_Operation_init()

void AESCBC_Operation_init ( AESCBC_Operation operationStruct)

Function to initialize an AESCBC_Operation struct to its defaults.

Parameters
operationStructA pointer to an AESCBC_Operation structure for initialization

Defaults values are all zeros.

§ AESCBC_oneStepEncrypt()

int_fast16_t AESCBC_oneStepEncrypt ( AESCBC_Handle  handle,
AESCBC_Operation operationStruct 
)

Function to perform an AESCBC 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
AESCBC_open() and AESCBC_Operation_init() must be called first.
Parameters
[in]handleA CBC handle returned from AESCBC_open()
[in]operationStructA pointer to a struct containing the parameters required to perform the operation.
Return values
AESCBC_STATUS_SUCCESSThe operation succeeded.
AESCBC_STATUS_ERRORThe operation failed.
AESCBC_STATUS_RESOURCE_UNAVAILABLEThe required hardware resource was not available. Try again later.
AESCBC_STATUS_CANCELEDThe operation was canceled.
See also
AESCBC_oneStepDecrypt()

§ AESCBC_oneStepDecrypt()

int_fast16_t AESCBC_oneStepDecrypt ( AESCBC_Handle  handle,
AESCBC_Operation operationStruct 
)

Function to perform an AESCBC 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
AESCBC_open() and AESCBC_Operation_init() must be called first.
Parameters
[in]handleA CBC handle returned from AESCBC_open()
[in]operationStructA pointer to a struct containing the parameters required to perform the operation.
Return values
AESCBC_STATUS_SUCCESSThe operation succeeded.
AESCBC_STATUS_ERRORThe operation failed.
AESCBC_STATUS_RESOURCE_UNAVAILABLEThe required hardware resource was not available. Try again later.
AESCBC_STATUS_CANCELEDThe operation was canceled.
See also
AESCBC_oneStepEncrypt()

§ AESCBC_cancelOperation()

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 or AESCBC_RETURN_BEHAVIOR_BLOCKING. The operation will terminate as though an error occured. The return status code of the operation will be AESCBC_STATUS_CANCELED.

Parameters
[in]handleHandle of the operation to cancel
Return values
AESCBC_STATUS_SUCCESSThe operation was canceled.
AESCBC_STATUS_ERRORThe operation was not canceled. There may be no operation to cancel.

§ AESCBC_construct()

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.

Parameters
[in]configAESCBC_Config describing the location of the object and hwAttrs.
[in]paramsAESCBC_Params to configure the driver instance.
Returns
Returns a AESCBC_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.

§ AESCBC_getNextIv()

int_fast16_t AESCBC_getNextIv ( AESCBC_Handle  handle,
uint8_t *  iv 
)

Returns the IV for the next block to encrypt or decrypt.

When encrypting or decrypting messages in multiple segments, it is necessary to save the intermediate iv to use with the next message segment.

Only call this function after a successful call to AESCBC_oneStepEncrypt() or AESCBC_oneStepDecrypt() and before starting another operation with the same handle.

Parameters
[in]handleA CBC handle returned from AESCBC_open()
[out]ivIV of the next block to encrypt or decrypt
Return values
AESCBC_STATUS_SUCCESSThe operation succeeded.
AESCBC_STATUS_ERRORThe operation failed.

Variable Documentation

§ AESCBC_defaultParams

const AESCBC_Params AESCBC_defaultParams

Default AESCBC_Params structure.

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