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 128-bit 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.

AESCCM encryption has the following inputs and outputs:

AES-CCM input and output parameters
Encryption	Decryption
Input
Shared AES key	Shared AES key
Nonce	Nonce
Cleartext	Ciphertext (encrypted plaintext + MAC)
AAD (optional)	AAD (optional)
Output
Ciphertext (encrypted plaintext + MAC)	Cleartext

The AES key is a shared secret between the two parties and has a length between 128 and 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 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 and the message authentication code (MAC). The MAC can be seen as an encrypted fingerprint of the message header and content.

Usage

Before starting a CCM operation

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

Call AESCCM_init() to initialize the driver
Call AESCCM_Params_init() to initialize the AESCCM_Params to default values.
Modify the AESCCM_Params as desired
Call AESCCM_open() to open an instance of the driver
Initialize a CryptoKey. These opaque datastructures are representations of keying material and its storage. Depending on how the keying material is stored (RAM or flash, key store, key blob), the CryptoKey must be initialized differently. The AESCCM API can handle all types of CryptoKey. However, not all device-specific implementions support all types of CryptoKey. Devices without a key store will not support CryptoKeys with keying material stored in a key store for example. All devices support plaintext CryptoKeys.

Starting a CCM operation

There are two general ways to execute a CCM operation. In one call or multiple.

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. When trying to operate on data that is too large to fit into available memory, partial processing would be more advisable. All devices support single call operations. When performing a decryption operation with AESCCM_oneStepDecrypt(), the MAC is automatically verified when using AESCCM_RETURN_BEHAVIOR_BLOCKING or AESCCM_RETURN_BEHAVIOR_POLLING. When using AESCCM_RETURN_BEHAVIOR_CALLBACK however, the application's registered callback function must call AESCCM_verifyMac() itself to ensure that the computed and transmitted MACs match.

The partial processing functions split the setup, processing of the AAD, processing of the plaintext or ciphertext, and computation or verification of the MAC into multiple calls. The AAD and payload processing functions may be called on buffers smaller than the total AAD and payload sizes. Not all devices support partial processing. The hardware or software implementations of the CCM mode of operation available on a specific device may not be designed to support partial processing.

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()

AESCCM Driver Configuration

In order to use the AESCCM APIs, the application is required to provide device-specific AESCCM configuration in the Board.c file. The AESCCM driver interface defines a configuration data structure:

typedef struct AESCCM_Config_ {
    void                   *object;
    void          const    *hwAttrs;
} AESCCM_Config;

The application must declare an array of AESCCM_Config elements, named AESCCM_config[]. Each element of AESCCM_config[] must be populated with pointers to a device specific AESCCM driver implementation's driver object and hardware attributes. The hardware attributes define properties such as the AESCCM peripheral's base address. Each element in AESCCM_config[] corresponds to an AESCCM instance and none of the elements should have NULL pointers. There is no correlation between the index and the peripheral designation (such as AESCCM0 or AESCCM1). For example, it is possible to use AESCCM_config[0] for AESCCM1. Multiple drivers and driver instances may all access the same underlying hardware. This is transparent to the application. Mutual exclusion is performed automatically by the drivers as necessary.

Because the AESCCM configuration is very device dependent, you will need to check the doxygen for the device specific AESCCM implementation. There you will find a description of the AESCCM hardware attributes. Please also refer to the Board.c file of any of your examples to see the AESCCM configuration.

AESCCM Parameters

The AESCCM_Params structure is passed to the AESCCM_open() call. If NULL is passed for the parameters, AESCCM_open() uses default parameters. A AESCCM_Params structure is initialized with default values by passing it to AESCCM_Params_init(). Some of the AESCCM parameters are described below. To see brief descriptions of all the parameters, see AESCCM_Params.

AESCCM Return Behavior

The AESCCM driver supports three return behaviors when processing data: blocking, polling, and callback. The return behavior is determined by the returnBehavior parameter in the AESCCM_Params data structure. The AESCCM driver defaults to blocking mode, if the application does not set it. Once an AESCCM driver is opened, the only way to change the return behavior is to close and re-open the AESCCM instance with the new return behavior.

In blocking mode, a task's code execution is blocked until an AESCCM operation has completed. This ensures that only one AESCCM operation operates at a given time. Other tasks requesting AESCCM operations while a operation is currently taking place are also placed into a blocked state. AESCCM operations are executed in the order in which they were received. In blocking mode, you cannot perform AESCCM operations in the context of a software or hardware ISR.

In callback mode, an AESCCM operation functions asynchronously, which means that it does not block code execution. After an AESCCM operation has been completed, the AESCCM driver calls a user-provided hook function. Callback mode is supported in the task, SWI, and HWI execution context, However, if an AESCCM operation is requested while a operation is taking place, the call returns an error code.

In polling mode, an AESCCM operation behaves the almost the same way as in blocking mode. Instead of pending on a semaphore and letting other scheduled tasks run, the application task, SWI, or HWI continuously polls a flag until the operation completes. If an AESCCM operation is requested while a operation is taking place, the call returns an error code. When starting an AESCCM operation in polling mode from HWI or SWI context, the AESCCM HWI and SWI must be configured to have a higher priority to pre-empt the polling context.

Examples

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

#include <ti/drivers/AESCCM.h>
#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));
encryptionResult = AESCCM_oneStepEncrypt(handle,
                                         &cryptoKey,
                                         aad, sizeof(aad),
                                         plaintext, sizeof(plaintext),
                                         nonce, sizeof(nonce),
                                         mac, sizeof(mac),
                                         ciphertext);
if (encryptionResult != AESCCM_STATUS_SUCCESS) {
    // handle error
}
AESCCM_close(handle);

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

#include <ti/drivers/AESCCM.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
...
// 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, CryptoKey *processedKey) {
    int_fast16_t verificationResult;
    verificationResult = AESCCM_verifyMac(handle, &mac);
    if (verificationResult != AESCCM_STATUS_SUCCESS) {
        // handle error
    }
}
void ccmStartFunction(void) {
    AESCCM_Handle handle;
    AESCCM_Params params;
    CryptoKey cryptoKey;
    int_fast16_t decryptionResult;
    AESCCM_Params_init(&params);
    params.returnBehavior = AESCCM_RETURN_BEHAVIOR_CALLBACK;
    params.callbackFxn = ccmCallback;
    handle = AESCCM_open(0, &params);
    if (handle == NULL) {
        // handle error
    }
    CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
    decryptionResult = AESCCM_oneStepEncrypt(handle,
                                             &cryptoKey,
                                             aad, sizeof(aad),
                                             ciphertext, sizeof(ciphertext),
                                             nonce, sizeof(nonce),
                                             mac, sizeof(mac),
                                             plaintext);
    if (encryptionResult != 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>

Go to the source code of this file.

Data Structures
struct	AESCCM_Params_
	CCM Parameters. More...

struct	AESCCM_Config_
	AESCCM Global configuration. More...

Macros
#define	AESCCM_CMD_RESERVED (32)

#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_UNDEFINEDCMD (-2)
	An error status code returned by AESCCM_control() for undefined command codes. More...

#define	AESCCM_STATUS_RESOURCE_UNAVAILABLE (-3)
	An error status code returned if the hardware or software resource is currently unavailable. More...

#define	AESCCM_STATUS_MAC_INVALID (-4)
	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...

Typedefs
typedef struct AESCCM_Config_ *	AESCCM_Handle
	A handle that is returned from an AESCCM_open() call. More...

typedef void(*	AESCCM_CallbackFxn) (AESCCM_Handle handle, CryptoKey *processedKey)
	The definition of a callback function used by the AESCCM driver when used in AESCCM_RETURN_BEHAVIOR_CALLBACK. More...

typedef enum AESCCM_ReturnBehavior_	AESCCM_ReturnBehavior
	The way in which CCM function calls return after performing an encryption + authentication or decryption + verification operation. More...

typedef enum AESCCM_Mode_	AESCCM_Mode
	Enum for the direction of the CCM operation. More...

typedef struct AESCCM_Params_	AESCCM_Params
	CCM Parameters. More...

typedef struct AESCCM_Config_	AESCCM_Config
	AESCCM Global configuration. 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...

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

int_fast16_t	AESCCM_control (AESCCM_Handle handle, uint32_t cmd, void *args)
	Function performs implementation specific features on a given AESCCM_Handle. More...

int_fast16_t	AESCCM_setupEncrypt (AESCCM_Handle handle, CryptoKey key, uint8_t nonce, uint8_t nonceLength, size_t aadTotalLength, size_t plaintextTotalLength, uint8_t macLength)
	Function to set up an AESCCM encryption + authentication operation in multiple calls. More...

int_fast16_t	AESCCM_setupDecrypt (AESCCM_Handle handle, CryptoKey key, uint8_t nonce, uint8_t nonceLength, size_t aadTotalLength, size_t ciphertextTotalLength, uint8_t macLength)
	Function to set up an AESCCM decryption + verification operation in multiple calls. More...

int_fast16_t	AESCCM_processAAD (AESCCM_Handle handle, uint8_t *aad, size_t length)
	Function to process the additional authentication data in one or more calls. More...

int_fast16_t	AESCCM_processPayload (AESCCM_Handle handle, uint8_t input, size_t length, uint8_t output)
	Function to process the input data in one or more calls. More...

int_fast16_t	AESCCM_computeMAC (AESCCM_Handle handle, uint8_t *mac)
	Function to compute the message authentication code. More...

int_fast16_t	AESCCM_verifyMAC (AESCCM_Handle handle, uint8_t *mac)
	Function to verify the provided message authentication code. More...

int_fast16_t	AESCCM_oneStepEncrypt (AESCCM_Handle handle, CryptoKey key, uint8_t aad, size_t aadLength, uint8_t plaintext, size_t plaintextLength, uint8_t nonce, uint8_t nonceLength, uint8_t mac, uint8_t macLength, uint8_t ciphertext)
	Function to perform an AESCCM encryption + authentication operation in one call. More...

int_fast16_t	AESCCM_oneStepDecrypt (AESCCM_Handle handle, CryptoKey key, uint8_t aad, size_t aadLength, uint8_t ciphertext, size_t ciphertextLength, uint8_t nonce, uint8_t nonceLength, uint8_t mac, uint8_t macLength, uint8_t plaintext)
	Function to perform an AESCCM decryption + verification operation in one call. More...

int_fast16_t	AESCCM_getMode (AESCCM_Handle handle, AESCCM_Mode *mode)
	Returns the AESCCM_Mode of an AESCCM operation in progress. More...

int_fast16_t	AESCCM_getCryptoKey (AESCCM_Handle handle, CryptoKey **key)
	Returns a pointer to the CryptoKey used for an AESCCM operation in progress. More...

int_fast16_t	AESCCM_getNonce (AESCCM_Handle handle, uint8_t *nonce, uint8_t nonceLength)
	Returns a pointer to the nonce and the nonce length of an AESCCM operation in progress. More...

int_fast16_t	AESCCM_getAAD (AESCCM_Handle handle, uint8_t *aad, size_t aadLength)
	Returns a pointer to the AAD and the AAD length of an AESCCM operation in progress. More...

int_fast16_t	AESCCM_getInput (AESCCM_Handle handle, uint8_t *input, size_t inputLength, size_t *totalInputLength)
	Returns a pointer to the input (plaintext or ciphertext) and the input length of an AESCCM operation in progress. More...

int_fast16_t	AESCCM_getOutput (AESCCM_Handle handle, uint8_t *output, size_t outputLength, size_t *totalOutputLength)
	Returns a pointer to the output (plaintext or ciphertext) and the output length of an AESCCM operation in progress. More...

int_fast16_t	AESCCM_getMAC (AESCCM_Handle handle, uint8_t mac, uint8_t macLength)
	Returns a pointer to the MAC and the MAC length of the last completed AESCCM operation. More...

int_fast16_t	AESCCM_setMACReturnPointer (AESCCM_Handle handle, uint8_t *mac)

Variables
const AESCCM_Params	AESCCM_defaultParams
	Default AESCCM_Params structure. More...

Typedef Documentation

§ AESCCM_Handle

typedef struct AESCCM_Config_* AESCCM_Handle

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

§ AESCCM_CallbackFxn

typedef void(* AESCCM_CallbackFxn) (AESCCM_Handle handle, CryptoKey *processedKey)

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

Parameters

handle	Handle of the client that started the CCM operation.
processedKey	The CryptoKey that the CCM operation was performed with.

§ AESCCM_ReturnBehavior

typedef enum AESCCM_ReturnBehavior_ 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

§ AESCCM_Mode

typedef enum AESCCM_Mode_ AESCCM_Mode

Enum for the direction of the CCM operation.

§ AESCCM_Params

typedef struct AESCCM_Params_ AESCCM_Params

CCM Parameters.

CCM Parameters are used to with the AESCCM_open() call. Default values for these parameters are set using AESCCM_Params_init().

See also: AESCCM_Params_init()

§ AESCCM_Config

typedef struct AESCCM_Config_ AESCCM_Config

AESCCM Global configuration.

The AESCCM_Config structure contains a set of pointers used to characterize the AESCCM driver implementation.

This structure needs to be defined before calling AESCCM_init() and it must not be changed thereafter.

See also: AESCCM_init()

Enumeration Type Documentation

§ AESCCM_ReturnBehavior_

enum 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 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 AESCCM_Mode_

Enum for the direction of the CCM operation.

Enumerator
AESCCM_MODE_ENCRYPT
AESCCM_MODE_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

params An pointer to AESCCM_Params structure for initialization

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

§ AESCCM_open()

AESCCM_Handle AESCCM_open	(	uint_least8_t	index,
		AESCCM_Params *	params
	)

This function opens a given CCM peripheral.

Precondition: CCM controller has been initialized using AESCCM_init()

Parameters

index	Logical peripheral number for the CCM indexed into the AESCCM_config table
params	Pointer to an parameter block, if NULL it will use default values.

Returns: A 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

handle A CCM handle returned from AESCCM_open()

See also: AESCCM_open()

§ AESCCM_control()

int_fast16_t AESCCM_control	(	AESCCM_Handle	handle,
		uint32_t	cmd,
		void *	args
	)

Function performs implementation specific features on a given AESCCM_Handle.

Commands for AESCCM_control can originate from AESCCM.h or from implementation specific AESCCM*.h (AESCCMCC26XX.h, AESCCMMSP432.h, etc.. ) files. While commands from AESCCM.h are API portable across driver implementations, not all implementations may support all these commands. Conversely, commands from driver implementation specific AESCCM*.h files add unique driver capabilities but are not API portable across all AESCCM driver implementations.

Commands supported by AESCCM.h follow an AESCCM_CMD_<cmd> naming convention.
Commands supported by AESCCM*.h follow an AESCCM*_CMD_<cmd> naming convention.
Each control command defines arg differently. The types of arg are documented with each command.

See AESCCM_control command codes for command codes.

See AESCCM_control return status codes for status codes.

Precondition: AESCCM_open() has to be called first.

Parameters

handle	A AESCCM handle returned from AESCCM_open()
cmd	AESCCM.h or AESCCM*.h commands.
args	An optional R/W (read/write) command argument accompanied with cmd

Returns: Implementation specific return codes. Negative values indicate unsuccessful operations.

See also: AESCCM_open()

§ AESCCM_setupEncrypt()

int_fast16_t AESCCM_setupEncrypt	(	AESCCM_Handle	handle,
		CryptoKey *	key,
		uint8_t *	nonce,
		uint8_t	nonceLength,
		size_t	aadTotalLength,
		size_t	plaintextTotalLength,
		uint8_t	macLength
	)

Function to set up an AESCCM encryption + authentication operation in multiple calls.

Precondition: AESCCM_open() has to be called first.

Parameters

[in]	handle	A CCM handle returned from AESCCM_open()
[in]	key	A previously initialized CryptoKey
[in]	aadTotalLength	Total length of the additional authentication data in bytes. Either `aadTotalLength` or `plaintextTotalLength` must be non-zero.
[in]	plaintextTotalLength	Total length of the plaintext in bytes. Either `aadTotalLength` or `plaintextTotalLength` must be non-zero.
[in,out]	nonce	A buffer containing a nonce. Nonces must be unique to each CCM operation and may not be reused. If nonceInternallyGenerated was set in the AESCCM_Params, the nonce will be generated by this function call and copied to this buffer.
[in]	nonceLength	Length of `nonce` in bytes. Valid nonce lengths are {7, 8, 9, 10, 11, 12, 13}.
[in]	macLength	Length of the message authentication code in bytes. Valid MAC lengths are [0, 1, ... 16].

Returns: A status code

Postcondition: AESCCM_processAAD() must be called next.

See also: AESCCM_setupDecrypt()

§ AESCCM_setupDecrypt()

int_fast16_t AESCCM_setupDecrypt	(	AESCCM_Handle	handle,
		CryptoKey *	key,
		uint8_t *	nonce,
		uint8_t	nonceLength,
		size_t	aadTotalLength,
		size_t	ciphertextTotalLength,
		uint8_t	macLength
	)

Function to set up an AESCCM decryption + verification operation in multiple calls.

Precondition: AESCCM_open() has to be called first.

Parameters

[in]	handle	A CCM handle returned from AESCCM_open()
[in]	key	A previously initialized CryptoKey
[in]	aadTotalLength	Total length of the additional authentication data in bytes. Either `aadTotalLength` or `plaintextTotalLength` must be non-zero.
[in]	ciphertextTotalLength	Total length of the ciphertext in bytes. Either `aadTotalLength` or `ciphertextTotalLength` must be non-zero.
[in]	nonce	A buffer containing the nonce transmitted with the ciphertext and AAD.
[in]	nonceLength	Length of `nonce` in bytes. Valid nonce lengths are {7, 8, 9, 10, 11, 12, 13}.
[in]	macLength	Length of the message authentication code in bytes. Valid MAC lengths are [0, 1, ... 16].

Returns: A status code

Postcondition: AESCCM_processAAD() must be called next.

See also: AESCCM_setupEncrypt()

§ AESCCM_processAAD()

int_fast16_t AESCCM_processAAD	(	AESCCM_Handle	handle,
		uint8_t *	aad,
		size_t	length
	)

Function to process the additional authentication data in one or more calls.

Precondition: AESCCM_setupDecrypt(), AESCCM_setupEncrypt(), or AESCCM_processAAD() has to be called first.

Parameters

[in]	handle	A CCM handle returned from AESCCM_open()
[in]	aad	A buffer of length `length` containing additional authentication data to be authenticated but not encrypted.
[in]	length	Length of `aad` in bytes. Must be non-zero. May be smaller than the total AAD length provided in the setup call. This enables partial processing of longer AAD.

Returns: A status code

Postcondition: AESCCM_processPayload() or AESCCM_processAAD() must be called next.

§ AESCCM_processPayload()

int_fast16_t AESCCM_processPayload	(	AESCCM_Handle	handle,
		uint8_t *	input,
		size_t	length,
		uint8_t *	output
	)

Function to process the input data in one or more calls.

Precondition: AESCCM_processAAD() or AESCCM_processPayload() has to be called first.

Parameters

[in]	handle	A CCM handle returned from AESCCM_open()
[in]	input	A buffer of length `length` containing either plaintext or ciphertext depending on the AESCCM_Mode.
[in]	length	Length of `input` and output in bytes. Must be non-zero. May be smaller than the total input length provided in the setup call. This enables partial processing of longer inputs.
[out]	output	A buffer of length `length` that is filled with either ciphertext or plaintext depending on the AESCCM_Mode after processing.

Returns: A status code

Postcondition: AESCCM_processPayload(), AESCCM_computeMAC(), or AESCCM_verifyMAC() must be called next.

§ AESCCM_computeMAC()

int_fast16_t AESCCM_computeMAC	(	AESCCM_Handle	handle,
		uint8_t *	mac
	)

Function to compute the message authentication code.

Precondition: AESCCM_processPayload() has to be called first.

Parameters

[in]	handle	A CCM handle returned from AESCCM_open()
[out]	mac	A buffer that the computed MAC is copied to.

Returns: A status code

§ AESCCM_verifyMAC()

int_fast16_t AESCCM_verifyMAC	(	AESCCM_Handle	handle,
		uint8_t *	mac
	)

Function to verify the provided message authentication code.

Precondition: AESCCM_processPayload() has to be called first.

Parameters

[in]	handle	A CCM handle returned from AESCCM_open()
[in]	mac	A buffer containing the MAC that the computed one will be verified against.

Returns: A status code

§ AESCCM_oneStepEncrypt()

int_fast16_t AESCCM_oneStepEncrypt	(	AESCCM_Handle	handle,
		CryptoKey *	key,
		uint8_t *	aad,
		size_t	aadLength,
		uint8_t *	plaintext,
		size_t	plaintextLength,
		uint8_t *	nonce,
		uint8_t	nonceLength,
		uint8_t *	mac,
		uint8_t	macLength,
		uint8_t *	ciphertext
	)

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() has to be called first.

Parameters

[in]	handle	A CCM handle returned from AESCCM_open()
[in]	key	A previously initialized CryptoKey
[in]	aad	A buffer of length `aadLength` containing additional authentication data to be authenticated but not encrypted.
[in]	aadLength	Length of `aad` in bytes. Either `aadLength` or `plaintextLength` must be non-zero.
[in]	plaintext	The plaintext buffer to be encrypted and authenticated in the CCM operation.
[in]	plaintextLength	Length of `plaintext` in bytes. Either `aadLength` or `plaintextLength` must be non-zero.
[in,out]	nonce	A buffer containing a nonce. Nonces must be unique to each CCM operation and may not be reused. If nonceInternallyGenerated was set in the AESCCM_Params, the nonce will be generated by this function call and copied to this buffer.
[in]	nonceLength	Length of `nonce` in bytes. Valid nonce lengths are {7, 8, 9, 10, 11, 12, 13}.
[out]	mac	The message authentication code buffer to store the encrypted authentication tag.
[in]	macLength	Length of `mac` in bytes. Valid MAC lengths are [0, 1, ... 16].
[out]	ciphertext	The output ciphertext buffer that the encrypted plaintext is copied to. It is of length `plaintextLength`.

Returns: A status code

See also: AESCCM_oneStepDecrypt()

§ AESCCM_oneStepDecrypt()

int_fast16_t AESCCM_oneStepDecrypt	(	AESCCM_Handle	handle,
		CryptoKey *	key,
		uint8_t *	aad,
		size_t	aadLength,
		uint8_t *	ciphertext,
		size_t	ciphertextLength,
		uint8_t *	nonce,
		uint8_t	nonceLength,
		uint8_t *	mac,
		uint8_t	macLength,
		uint8_t *	plaintext
	)

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() has to be called first.

Parameters

[in]	handle	A CCM handle returned from AESCCM_open()
[in]	key	A previously initialized CryptoKey
[in]	aad	A buffer of length `aadLength` containing additional authentication data to be verified but not decrypted.
[in]	aadLength	Length of `aad` in bytes. Either `aadLength` or `plaintextLength` must be non-zero.
[in]	ciphertext	The ciphertext buffer to be decrypted and verified in the CCM operation.
[in]	ciphertextLength	Length of `plaintext` in bytes. Either `aadLength` or `plaintextLength` must be non-zero.
[in]	nonce	A buffer containing the nonce transmitted with the ciphertext and AAD.
[in]	nonceLength	Length of `nonce` in bytes. Valid nonce lengths are {7, 8, 9, 10, 11, 12, 13}.
[in]	mac	The message authentication code buffer containing the encrypted authentication tag.
[in]	macLength	Length of `mac` in bytes. Valid MAC lengths are [0, 1, ... 16].
[out]	plaintext	The output plaintext buffer that the decrypted ciphertext is copied to. It is of length `ciphertexttextLength`.

Returns: A status code

See also: AESCCM_oneStepEncrypt()

§ AESCCM_getMode()

int_fast16_t AESCCM_getMode	(	AESCCM_Handle	handle,
		AESCCM_Mode *	mode
	)

Returns the AESCCM_Mode of an AESCCM operation in progress.

Precondition: AESCCM_setupEncrypt() or AESCCM_setupDecrypt() has to be called first.

Parameters

[in]	handle	A CCM handle returned from AESCCM_open()
[out]	mode	Whether the operation in progress is a decryption or encryption operation

Returns: A status code

§ AESCCM_getCryptoKey()

int_fast16_t AESCCM_getCryptoKey	(	AESCCM_Handle	handle,
		CryptoKey **	key
	)

Returns a pointer to the CryptoKey used for an AESCCM operation in progress.

Precondition: AESCCM_setupEncrypt() or AESCCM_setupDecrypt() has to be called first.

Parameters

[in]	handle	A CCM handle returned from AESCCM_open()
[out]	key	The CryptoKey used in the operation

Returns: A status code

§ AESCCM_getNonce()

int_fast16_t AESCCM_getNonce	(	AESCCM_Handle	handle,
		uint8_t **	nonce,
		uint8_t *	nonceLength
	)

Returns a pointer to the nonce and the nonce length of an AESCCM operation in progress.

Precondition: AESCCM_setupEncrypt() or AESCCM_setupDecrypt() has to be called first.

Parameters

[in]	handle	A CCM handle returned from AESCCM_open()
[out]	nonce	The nonce used in the operation
[out]	nonceLength	The length of the nonce used in the operation

Returns: A status code

§ AESCCM_getAAD()

int_fast16_t AESCCM_getAAD	(	AESCCM_Handle	handle,
		uint8_t **	aad,
		size_t *	aadLength
	)

Returns a pointer to the AAD and the AAD length of an AESCCM operation in progress.

Precondition: AESCCM_processAAD() has to be called first.

Parameters

[in]	handle	A CCM handle returned from AESCCM_open()
[out]	aad	The AAD used in the operation
[out]	aadLength	The length of the AAD used in the operation

Returns: A status code

§ AESCCM_getInput()

int_fast16_t AESCCM_getInput	(	AESCCM_Handle	handle,
		uint8_t **	input,
		size_t *	inputLength,
		size_t *	totalInputLength
	)

Returns a pointer to the input (plaintext or ciphertext) and the input length of an AESCCM operation in progress.

Precondition: AESCCM_processPayload() has to be called first.

Parameters

[in]	handle	A CCM handle returned from AESCCM_open()
[out]	input	The last input buffer used in the operation
[out]	inputLength	The length of the last input buffer used in the operation
[out]	totalInputLength	The total length of the input specified in the setup call. It is the same as the total length of the input.

Returns: A status code

§ AESCCM_getOutput()

int_fast16_t AESCCM_getOutput	(	AESCCM_Handle	handle,
		uint8_t **	output,
		size_t *	outputLength,
		size_t *	totalOutputLength
	)

Returns a pointer to the output (plaintext or ciphertext) and the output length of an AESCCM operation in progress.

Precondition: AESCCM_processPayload() has to be called first.

Parameters

[in]	handle	A CCM handle returned from AESCCM_open()
[out]	output	The output buffer used in the operation
[out]	outputLength	The output of the input used in the operation
[out]	totalOutputLength	The total length of the output specified in the setup call. It is the same as the total length of the input.

Returns: A status code

§ AESCCM_getMAC()

int_fast16_t AESCCM_getMAC	(	AESCCM_Handle	handle,
		uint8_t *	mac,
		uint8_t *	macLength
	)

Returns a pointer to the MAC and the MAC length of the last completed AESCCM operation.

Precondition: AESCCM_verifyMAC() or AESCCM_calculateMAC() has to be called first.

Parameters

[in]	handle	A CCM handle returned from AESCCM_open()
[out]	mac	The MAC verified or calculated in the operation
[out]	macLength	The length of the MAC

Returns: A status code

§ AESCCM_setMACReturnPointer()

int_fast16_t AESCCM_setMACReturnPointer	(	AESCCM_Handle	handle,
		uint8_t *	mac
	)

Variable Documentation

§ AESCCM_defaultParams

const AESCCM_Params AESCCM_defaultParams

Default AESCCM_Params structure.

See also: AESCCM_Params_init()

Detailed Description

Overview

Usage

Before starting a CCM operation

Starting a CCM operation

After the CCM operation completes

AESCCM Driver Configuration

AESCCM Parameters

AESCCM Return Behavior

Examples

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

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Typedef Documentation

§ AESCCM_Handle

§ AESCCM_CallbackFxn

§ AESCCM_ReturnBehavior

§ AESCCM_Mode

§ AESCCM_Params

§ AESCCM_Config

Enumeration Type Documentation

§ AESCCM_ReturnBehavior_

§ AESCCM_Mode_

Function Documentation

§ AESCCM_init()

§ AESCCM_Params_init()

§ AESCCM_open()

§ AESCCM_close()

§ AESCCM_control()

§ AESCCM_setupEncrypt()

§ AESCCM_setupDecrypt()

§ AESCCM_processAAD()

§ AESCCM_processPayload()

§ AESCCM_computeMAC()

§ AESCCM_verifyMAC()

§ AESCCM_oneStepEncrypt()

§ AESCCM_oneStepDecrypt()

§ AESCCM_getMode()

§ AESCCM_getCryptoKey()

§ AESCCM_getNonce()

§ AESCCM_getAAD()

§ AESCCM_getInput()

§ AESCCM_getOutput()

§ AESCCM_getMAC()

§ AESCCM_setMACReturnPointer()

Variable Documentation

§ AESCCM_defaultParams