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

Detailed Description

AESCCM driver header.


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

Overview

The Counter with CBC-MAC (CCM) mode of operation is a generic authenticated encryption block cipher mode. It can be used with any block cipher. AESCCM combines CBC-MAC with an AES block cipher in CTR mode of operation.

This combination of block cipher modes enables CCM to encrypt messages of any length and not only multiples of the block cipher block size.

CTR provides confidentiality. The defined application of CBC-MAC provides message integrity and authentication.

AESCCM has the following inputs and outputs:

AES-CCM input and output parameters
EncryptionDecryption
Input
Shared AES keyShared AES key
NonceNonce
CleartextCiphertext
MAC
AAD (optional)AAD (optional)
Output
CiphertextCleartext
MAC

The AES key is a shared secret between the two parties and has a length between 128, 192, or 256 bits.

The nonce is generated by the party performing the authenticated encryption operation. Within the scope of any authenticated encryption key, the nonce value must be unique. That is, the set of nonce values used with any given key must not contain any duplicate values. Using the same nonce for two different messages encrypted with the same key destroys the security properties.

The length of the nonce determines the maximum number of messages that may be encrypted and authenticated before you must regenerate the key. Reasonable session key rotation schemes will regenerate the key before reaching this limit. There is a trade-off between the nonce-length and the maximum length of the plaintext to encrypt and authenticate per nonce. This is because CTR concatenates the nonce and an internal counter into one 16-byte IV. The counter is incremented after generating an AES-block-sized pseudo-random bitstream. This bitstream is XOR'd with the plaintext. The counter would eventually roll over for a sufficiently long message. This is must not happen. Hence, the longer the nonce and the more messages you can send before needing to rotate the key, the shorter the lengths of invidual messages sent may be. The minimum and maximum nonce length defined by the CCM standard provide for both a reasonable number of messages before key rotation and a reasonable maximum message length. Check NIST SP 800-38C for details.

The optional additional authentication data (AAD) is authenticated but not encrypted. Thus, the AAD is not included in the AES-CCM output. It can be used to authenticate packet headers.

After the encryption operation, the ciphertext contains the encrypted data. The message authentication code (MAC) is also provided.

CCM Variations

The AESCCM driver supports both classic CCM as defined by NIST SP 800-38C and the CCM* variant used in IEEE 802.15.4. CCM* allows for unauthenticated encryption using CCM by permitting a MAC length of 0. It also imposes the requirement that the MAC length be embedded in the nonce used for each message if the MAC length varies within the protocol using CCM*.

Usage

Before starting a CCM operation

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

Starting a CCM operation

The AESCCM_oneStepEncrypt and AESCCM_oneStepDecrypt functions do a CCM 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 AAD and plaintext or ciphertext data to be available to the function at the start of the call. All devices support single call operations.

When performing a decryption operation with AESCCM_oneStepDecrypt(), the MAC is automatically verified.

After the CCM operation completes

After the CCM operation completes, the application should either start another operation or close the driver by calling AESCCM_close()

Synopsis

// Import AESCCM Driver definitions
// Define name for AESCCM channel index
#define AESCCM_INSTANCE 0
handle = AESCCM_open(AESCCM_INSTANCE, NULL);
// Initialize symmetric key
CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
// Set up AESCCM_Operation
operation.key = &cryptoKey;
operation.aad = aad;
operation.aadLength = sizeof(aad);
operation.input = plaintext;
operation.output = ciphertext;
operation.inputLength = sizeof(plaintext);
operation.nonce = nonce;
operation.nonceLength = sizeof(nonce);
operation.mac = mac;
operation.macLength = sizeof(mac);
encryptionResult = AESCCM_oneStepEncrypt(handle, &operation);
AESCCM_close(handle);

Examples

### Single call CCM encryption + authentication with plaintext CryptoKey in blocking return mode #

#include <ti/drivers/types/cryptoKey/CryptoKey_Plaintext.h>
...
AESCCM_Handle handle;
CryptoKey cryptoKey;
int_fast16_t encryptionResult;
uint8_t nonce[] = "Thisisanonce";
uint8_t aad[] = "This string will be authenticated but not encrypted.";
uint8_t plaintext[] = "This string will be encrypted and authenticated.";
uint8_t mac[16];
uint8_t ciphertext[sizeof(plaintext)];
uint8_t keyingMaterial[32] = {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}
handle = AESCCM_open(0, NULL);
if (handle == NULL) {
// handle error
}
CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
AESCCM_Operation operation;
AESCCM_Operation_init(&operation);
operation.key = &cryptoKey;
operation.aad = aad;
operation.aadLength = sizeof(aad);
operation.input = plaintext;
operation.output = ciphertext;
operation.inputLength = sizeof(plaintext);
operation.nonce = nonce;
operation.nonceLength = sizeof(nonce);
operation.mac = mac;
operation.macLength = sizeof(mac);
encryptionResult = AESCCM_oneStepEncrypt(handle, &operation);
if (encryptionResult != AESCCM_STATUS_SUCCESS) {
// handle error
}
AESCCM_close(handle);

Single call CCM decryption + verification with plaintext CryptoKey in callback return mode

...
// The following test vector is Packet Vector 1 from RFC 3610 of the IETF.
uint8_t nonce[] = {0x00, 0x00, 0x00, 0x03, 0x02, 0x01, 0x00, 0xA0,
0xA1, 0xA2, 0xA3, 0xA4, 0xA5};
uint8_t aad[] = {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07};
uint8_t mac[] = {0x17, 0xE8, 0xD1, 0x2C, 0xFD, 0xF9, 0x26, 0xE0};
uint8_t ciphertext[] = {0x58, 0x8C, 0x97, 0x9A, 0x61, 0xC6, 0x63, 0xD2,
0xF0, 0x66, 0xD0, 0xC2, 0xC0, 0xF9, 0x89, 0x80,
0x6D, 0x5F, 0x6B, 0x61, 0xDA, 0xC3, 0x84};
uint8_t keyingMaterial[] = {0xC0, 0xC1, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7,
0xC8, 0xC9, 0xCA, 0xCB, 0xCC, 0xCD, 0xCE, 0xCF};
uint8_t plaintext[sizeof(ciphertext)];
// The plaintext should be the following after the decryption operation:
// {0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F,
// 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
// 0x18, 0x19, 0x1A, 0x1B, 0x1C, 0x1D, 0x1E}
void ccmCallback(AESCCM_Handle handle,
int_fast16_t returnValue,
AESCCM_Operation *operation,
AESCCM_OperationType operationType) {
if (returnValue != AESCCM_STATUS_SUCCESS) {
// handle error
}
}
AESCCM_Operation operation;
void ccmStartFunction(void) {
AESCCM_Handle handle;
AESCCM_Params params;
CryptoKey cryptoKey;
int_fast16_t decryptionResult;
params.callbackFxn = ccmCallback;
handle = AESCCM_open(0, &params);
if (handle == NULL) {
// handle error
}
CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
AESCCM_Operation_init(&operation);
operation.key = &cryptoKey;
operation.aad = aad;
operation.aadLength = sizeof(aad);
operation.input = plaintext;
operation.output = ciphertext;
operation.inputLength = sizeof(plaintext);
operation.nonce = nonce;
operation.nonceLength = sizeof(nonce);
operation.mac = mac;
operation.macLength = sizeof(mac);
decryptionResult = AESCCM_oneStepDecrypt(handle, &operation);
if (decryptionResult != AESCCM_STATUS_SUCCESS) {
// handle error
}
// do other things while CCM 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 AESCCM.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  AESCCM_Config
 AESCCM Global configuration. More...
 
struct  AESCCM_Operation
 Struct containing the parameters required for encrypting/decrypting and authenticating/verifying a message. More...
 
struct  AESCCM_Params
 CCM Parameters. More...
 

Macros

#define AESCCM_STATUS_RESERVED   (-32)
 
#define AESCCM_STATUS_SUCCESS   (0)
 Successful status code. More...
 
#define AESCCM_STATUS_ERROR   (-1)
 Generic error status code. More...
 
#define AESCCM_STATUS_RESOURCE_UNAVAILABLE   (-2)
 An error status code returned if the hardware or software resource is currently unavailable. More...
 
#define AESCCM_STATUS_MAC_INVALID   (-3)
 An error status code returned if the MAC provided by the application for a decryption operation does not match the one calculated during the operation. More...
 
#define AESCCM_STATUS_CANCELED   (-4)
 The ongoing operation was canceled. More...
 

Typedefs

typedef AESCCM_ConfigAESCCM_Handle
 A handle that is returned from an AESCCM_open() call. More...
 
typedef void(* AESCCM_CallbackFxn) (AESCCM_Handle handle, int_fast16_t returnValue, AESCCM_Operation *operation, AESCCM_OperationType operationType)
 The definition of a callback function used by the AESCCM driver when used in AESCCM_RETURN_BEHAVIOR_CALLBACK. More...
 

Enumerations

enum  AESCCM_ReturnBehavior { AESCCM_RETURN_BEHAVIOR_CALLBACK = 1, AESCCM_RETURN_BEHAVIOR_BLOCKING = 2, AESCCM_RETURN_BEHAVIOR_POLLING = 4 }
 The way in which CCM function calls return after performing an encryption + authentication or decryption + verification operation. More...
 
enum  AESCCM_Mode { AESCCM_MODE_ENCRYPT = 1, AESCCM_MODE_DECRYPT = 2 }
 Enum for the direction of the CCM operation. More...
 
enum  AESCCM_OperationType { AESCCM_OPERATION_TYPE_ENCRYPT = 1, AESCCM_OPERATION_TYPE_DECRYPT = 2 }
 Enum for the operation types supported by the driver. More...
 

Functions

void AESCCM_init (void)
 This function initializes the CCM module. More...
 
void AESCCM_Params_init (AESCCM_Params *params)
 Function to initialize the AESCCM_Params struct to its defaults. More...
 
AESCCM_Handle AESCCM_open (uint_least8_t index, const AESCCM_Params *params)
 This function opens a given CCM peripheral. More...
 
void AESCCM_close (AESCCM_Handle handle)
 Function to close a CCM peripheral specified by the CCM handle. More...
 
void AESCCM_Operation_init (AESCCM_Operation *operationStruct)
 Function to initialize an AESCCM_Operation struct to its defaults. More...
 
int_fast16_t AESCCM_oneStepEncrypt (AESCCM_Handle handle, AESCCM_Operation *operationStruct)
 Function to perform an AESCCM encryption + authentication operation in one call. More...
 
int_fast16_t AESCCM_oneStepDecrypt (AESCCM_Handle handle, AESCCM_Operation *operationStruct)
 Function to perform an AESCCM decryption + verification operation in one call. More...
 
int_fast16_t AESCCM_cancelOperation (AESCCM_Handle handle)
 Cancels an ongoing AESCCM operation. More...
 
AESCCM_Handle AESCCM_construct (AESCCM_Config *config, const AESCCM_Params *params)
 Constructs a new AESCCM object. More...
 

Variables

const AESCCM_Params AESCCM_defaultParams
 Default AESCCM_Params structure. More...
 

Macro Definition Documentation

§ AESCCM_STATUS_RESERVED

#define AESCCM_STATUS_RESERVED   (-32)

Common AESCCM status code reservation offset. AESCCM driver implementations should offset status codes with AESCCM_STATUS_RESERVED growing negatively.

Example implementation specific status codes:

#define AESCCMXYZ_STATUS_ERROR0 AESCCM_STATUS_RESERVED - 0
#define AESCCMXYZ_STATUS_ERROR1 AESCCM_STATUS_RESERVED - 1
#define AESCCMXYZ_STATUS_ERROR2 AESCCM_STATUS_RESERVED - 2

§ AESCCM_STATUS_SUCCESS

#define AESCCM_STATUS_SUCCESS   (0)

Successful status code.

Functions return AESCCM_STATUS_SUCCESS if the function was executed successfully.

§ AESCCM_STATUS_ERROR

#define AESCCM_STATUS_ERROR   (-1)

Generic error status code.

Functions return AESCCM_STATUS_ERROR if the function was not executed successfully and no more pertinent error code could be returned.

§ AESCCM_STATUS_RESOURCE_UNAVAILABLE

#define AESCCM_STATUS_RESOURCE_UNAVAILABLE   (-2)

An error status code returned if the hardware or software resource is currently unavailable.

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

§ AESCCM_STATUS_MAC_INVALID

#define AESCCM_STATUS_MAC_INVALID   (-3)

An error status code returned if the MAC provided by the application for a decryption operation does not match the one calculated during the operation.

This code is returned by AESCCM_oneStepDecrypt() if the verification of the MAC fails.

§ AESCCM_STATUS_CANCELED

#define AESCCM_STATUS_CANCELED   (-4)

The ongoing operation was canceled.

Typedef Documentation

§ AESCCM_Handle

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

§ AESCCM_CallbackFxn

typedef void(* AESCCM_CallbackFxn) (AESCCM_Handle handle, int_fast16_t returnValue, AESCCM_Operation *operation, AESCCM_OperationType operationType)

The definition of a callback function used by the AESCCM driver when used in AESCCM_RETURN_BEHAVIOR_CALLBACK.

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

§ AESCCM_ReturnBehavior

The way in which CCM function calls return after performing an encryption + authentication or decryption + verification operation.

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

AESCCM functions exhibiting the specified return behavior have restrictions on the context from which they may be called.

Task Hwi Swi
AESCCM_RETURN_BEHAVIOR_CALLBACK X X X
AESCCM_RETURN_BEHAVIOR_BLOCKING X
AESCCM_RETURN_BEHAVIOR_POLLING X X X
Enumerator
AESCCM_RETURN_BEHAVIOR_CALLBACK 

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

AESCCM_RETURN_BEHAVIOR_BLOCKING 

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

AESCCM_RETURN_BEHAVIOR_POLLING 

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

§ AESCCM_Mode

Enum for the direction of the CCM operation.

Enumerator
AESCCM_MODE_ENCRYPT 
AESCCM_MODE_DECRYPT 

§ AESCCM_OperationType

Enum for the operation types supported by the driver.

Enumerator
AESCCM_OPERATION_TYPE_ENCRYPT 
AESCCM_OPERATION_TYPE_DECRYPT 

Function Documentation

§ AESCCM_init()

void AESCCM_init ( void  )

This function initializes the CCM module.

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

§ AESCCM_Params_init()

void AESCCM_Params_init ( AESCCM_Params params)

Function to initialize the AESCCM_Params struct to its defaults.

Parameters
paramsAn pointer to AESCCM_Params structure for initialization

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

§ AESCCM_open()

AESCCM_Handle AESCCM_open ( uint_least8_t  index,
const AESCCM_Params params 
)

This function opens a given CCM peripheral.

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

§ AESCCM_close()

void AESCCM_close ( AESCCM_Handle  handle)

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

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

§ AESCCM_Operation_init()

void AESCCM_Operation_init ( AESCCM_Operation operationStruct)

Function to initialize an AESCCM_Operation struct to its defaults.

Parameters
operationStructA pointer to an AESCCM_Operation structure for initialization

Defaults values are all zeros.

§ AESCCM_oneStepEncrypt()

int_fast16_t AESCCM_oneStepEncrypt ( AESCCM_Handle  handle,
AESCCM_Operation operationStruct 
)

Function to perform an AESCCM encryption + authentication 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 or incorrect authentication.
Precondition
AESCCM_open() and AESCCM_Operation_init() have to be called first.
Parameters
[in]handleA CCM handle returned from AESCCM_open()
[in]operationStructA pointer to a struct containing the parameters required to perform the operation.
Return values
AESCCM_STATUS_SUCCESSThe operation succeeded.
AESCCM_STATUS_ERRORThe operation failed.
AESCCM_STATUS_RESOURCE_UNAVAILABLEThe required hardware resource was not available. Try again later.
AESCCM_STATUS_CANCELEDThe operation was canceled.
See also
AESCCM_oneStepDecrypt()

§ AESCCM_oneStepDecrypt()

int_fast16_t AESCCM_oneStepDecrypt ( AESCCM_Handle  handle,
AESCCM_Operation operationStruct 
)

Function to perform an AESCCM decryption + verification 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 or incorrectly failed verification.
Precondition
AESCCM_open() and AESCCM_Operation_init() have to be called first.
Parameters
[in]handleA CCM handle returned from AESCCM_open()
[in]operationStructA pointer to a struct containing the parameters required to perform the operation.
Return values
AESCCM_STATUS_SUCCESSThe operation succeeded.
AESCCM_STATUS_ERRORThe operation failed.
AESCCM_STATUS_RESOURCE_UNAVAILABLEThe required hardware resource was not available. Try again later.
AESCCM_STATUS_CANCELEDThe operation was canceled.
AESCCM_STATUS_MAC_INVALIDThe provided MAC did no match the recomputed one.
See also
AESCCM_oneStepEncrypt()

§ AESCCM_cancelOperation()

int_fast16_t AESCCM_cancelOperation ( AESCCM_Handle  handle)

Cancels an ongoing AESCCM operation.

Asynchronously cancels an AESCCM operation. Only available when using AESCCM_RETURN_BEHAVIOR_CALLBACK or AESCCM_RETURN_BEHAVIOR_BLOCKING. The operation will terminate as though an error occured. The return status code of the operation will be AESCCM_STATUS_CANCELED.

Parameters
[in]handleHandle of the operation to cancel
Return values
AESCCM_STATUS_SUCCESSThe operation was canceled.
AESCCM_STATUS_ERRORThe operation was not canceled.

§ AESCCM_construct()

AESCCM_Handle AESCCM_construct ( AESCCM_Config config,
const AESCCM_Params params 
)

Constructs a new AESCCM object.

Unlike AESCCM_open(), AESCCM_construct() does not require the hwAttrs and object to be allocated in a AESCCM_Config array that is indexed into. Instead, the AESCCM_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
configAESCCM_Config describing the location of the object and hwAttrs.
paramsAESCCM_Params to configure the driver instance.
Returns
Returns a AESCCM_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

§ AESCCM_defaultParams

const AESCCM_Params AESCCM_defaultParams

Default AESCCM_Params structure.

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