Detailed Description

Crypto driver implementation for a CC26XX Crypto controller.

============================================================================

Driver Include

The Crypto header file should be included in an application as follows:

#include <ti/drivers/crypto/CryptoCC26XX.h>

Overview

The CryptoCC26XX driver simplifies reading and writing to the CryptoCC26XX peripheral on the board with multiple modes of operation and performance. These include blocking and polling. A timeout can be configured in blocking mode. The driver supports encryption and decryption for both AES-ECB and AES-CCM.

Usage

Warning: The application should not attempt to encrypt a value stored in flash or use a key stored in flash if the application might switch to the XOSC_HF, the high frequency external oscillator, during the operation.

Opening the driver

The application initializes the CryptoCC26XX driver by calling CryptoCC26XX_init() and is then ready to open a CryptoCC26XX by calling CryptoCC26XX_open().
If one client (the first) calls the CryptoCC26XX_open() with the exclusiveAccess flag set, all subsequent calls to open will fail (i.e. return a NULL pointer). The first client can use the Crypto module exclusively.
Only one client can call CryptoCC26XX_open() at the same time, a second client will pend until the first client's call will release a semaphore.
The number of clients are counted with openCnt in CryptoCC26XX_Object.

// Declaration (typically done in a task)
CryptoCC26XX_Handle      handle;
CryptoCC26XX_Params      params;
bool                     exclusiveAccess = false;
// Initialize Crypto driver
CryptoCC26XX_init();
// Configure CryptoCC26XX parameters.
CryptoCC26XX_Params_init(&params);
// Attempt to open CryptoCC26XX.
handle = CryptoCC26XX_open(Board_CRYPTO0, exclusiveAccess, &params);
if (!handle) {
    System_printf("CryptoCC26XX did not open");
}

Before starting a crypto operation

Before any encryption/decryption operation starts, the key store must have at least one key loaded.
To get access to a location in the key store, the caller must allocated it by calling CryptoCC26XX_allocateKey().
If the requested key location is available, the client will get a key index (uint8_t) returned.
If the requested key location is already occupied, the CryptoCC26XX_allocateKey() will fail and return CRYPTOCC26XX_STATUS_ERROR.
The key locations available are defined in CryptoCC26XX_KeyLocation.
To select any available key location, call the allocate function with key location set to CRYPTOCC26XX_KEY_ANY.

Performing a crypto operation

The supported crypto operations are defined in CryptoCC26XX_Operation.
The operation is initiated by calling a transaction function.
The type of operation is decided by the transaction pointer passed to the transaction function.
The mode of the transaction (i.e. blocking/polling) is decided by selecting the corresponding transact function (see Supported transaction modes below).
The key index is passed to the encryption/decryption transaction functions as part of the transaction object.
When a transaction starts, a semaphore is used to ensure that only one transaction is performed at a given time. The polling transaction is using 0 wait time, and will return immediately with CRYPTOCC26XX_STATUS_ERROR if the semaphore is not granted.
In blocking mode a constraint is set to ensure that the device only enters idle mode if the CPU becomes inactive.
When the transaction ends, the device might enter standby.
A key location can be deallocated by calling CryptoCC26XX_releaseKey().

Supported transaction modes

CRYPTOCC26XX_MODE_BLOCKING, typically used from task context. Selected by calling the CryptoCC26XX_transact() function.
CRYPTOCC26XX_MODE_POLLING, typically used from hwi/swi context. Selected by calling the CryptoCC26XX_transactPolling() function. This mode should be replaced by a callback mode in a future release.

Closing the driver

The crypto driver is closed by calling CryptoCC26XX_close() function. When the openCnt is decremented to zero, the crypto related bios modules are destructed.

CryptoCC26XX_close(handle);

Error handling

If an error occur during encryption/decryption, the operation will return the error code and the device might enter standby.

Power Management

During a transaction in blocking mode, the Power_DISALLOW_STANDBY constraint is set to block the system from entering standby mode. During this period the system will enter idle mode if no tasks are running.

A system dependency on crypto will be active as long as there are clients with an open handle to the crypto.

Note: When coming out of standby the key store RAM has lost it's content, so the keyStore in CryptoCC26XX_Object will be cleared and the clients will have to reupload their keys again.

Unsupported functionality:

Functionality that currently not supported:

Callback mode
Queued transactions for use in callback mode

Supported Operations

Operation Type	Description
CRYPTOCC26XX_OP_AES_CCM_ENCRYPT	AES-CCM encryption of plaintext and authentication of AAD and plaintext
CRYPTOCC26XX_OP_AES_CCM_ENCRYPT_AAD_ONLY	AES-CCM authentication of AAD only. No payload.
CRYPTOCC26XX_OP_AES_CCM_DECRYPT	AES-CCM decryption of plaintext and verification of AAD and plaintext
CRYPTOCC26XX_OP_AES_CCM_DECRYPT_AAD_ONLY	AES-CCM verification of AAD only. No payload.
CRYPTOCC26XX_OP_AES_ECB_ENCRYPT	AES-ECB encryption
CRYPTOCC26XX_OP_AES_ECB_DECRYPT	AES-ECB decryption
CRYPTOCC26XX_OP_AES_CBC_ENCRYPT	AES-CBC encryption
CRYPTOCC26XX_OP_AES_CBC_DECRYPT	AES-CBC decryption

Synopsis

// Import Crypto Driver definitions
#include <ti/drivers/Crypto.h>
// Define name for Crypto channel index
#define Crypto_INSTANCE 0
// Initialize Crypto driver
CryptoCC26XX_init();
// Attempt to open CryptoCC26XX.
handle = CryptoCC26XX_open(Board_CRYPTO0, false, NULL);
keyIndex = CryptoCC26XX_allocateKey(handle, ecbExample.keyLocation,
                                   (const uint32_t *) ecbExample.key);
// Initialize transaction
CryptoCC26XX_Transac_init((CryptoCC26XX_Transaction *) &trans, CRYPTOCC26XX_OP_AES_ECB_ENCRYPT);
// Setup transaction
trans.keyIndex         = keyIndex;
trans.msgIn            = (uint32_t *) ecbExample.clearText;
trans.msgOut           = (uint32_t *) ecbExample.msgOut;
// Encrypt the plaintext with AES ECB
status = CryptoCC26XX_transact(handle, (CryptoCC26XX_Transaction *) &trans);
// Initialize transaction
CryptoCC26XX_Transac_init((CryptoCC26XX_Transaction *) &trans, CRYPTOCC26XX_OP_AES_ECB_DECRYPT);
// Setup transaction
trans.keyIndex         = keyIndex;
trans.msgIn            = (uint32_t *) ecbExample.msgOut;
trans.msgOut           = (uint32_t *) ecbExample.clearText;
// Decrypt the plaintext with AES ECB
status = CryptoCC26XX_transact(handle, (CryptoCC26XX_Transaction *) &trans);
CryptoCC26XX_releaseKey(handle, &keyIndex);
Crypto_close(handle);

Examples

AES ECB operation

Perform a crypto operation with AES-ECB in CRYPTOCC26XX_MODE_BLOCKING.

// AES-ECB example struct
typedef struct
{
  uint8_t key[16];                      // Stores the Aes Key
  CryptoCC26XX_KeyLocation keyLocation; // Location in Key RAM
  uint8_t clearText[AES_ECB_LENGTH];    // Input message - cleartext
  uint8_t msgOut[AES_ECB_LENGTH];       // Output message
} AESECBExample;
// AES ECB example data
AESECBExample ecbExample =
{
  { 0x2B, 0x7E, 0x15, 0x16, 0x28, 0xAE, 0xD2, 0xA6,
  0xAB, 0xF7, 0x15, 0x88, 0x09, 0xCF, 0x4F, 0x3C },
  CRYPTOCC26XX_KEY_0,
  {'t','h','i','s','i','s','a','p','l','a','i','n','t','e','x','t'},
  { 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0 }
};
// Declaration (typically done in a task)
CryptoCC26XX_Handle             handle;
int32_t                         keyIndex;
int32_t                         status;
CryptoCC26XX_AESECB_Transaction trans;
// Initialize Crypto driver
CryptoCC26XX_init();
// Attempt to open CryptoCC26XX.
handle = CryptoCC26XX_open(Board_CRYPTO0, false, NULL);
if (!handle) {
  System_abort("Crypto module could not be opened.");
}
keyIndex = CryptoCC26XX_allocateKey(handle, ecbExample.keyLocation,
                                   (const uint32_t *) ecbExample.key);
if (keyIndex == CRYPTOCC26XX_STATUS_ERROR) {
    System_abort("Key Location was not allocated.");
}
// Initialize transaction
CryptoCC26XX_Transac_init((CryptoCC26XX_Transaction *) &trans, CRYPTOCC26XX_OP_AES_ECB_ENCRYPT);
// Setup transaction
trans.keyIndex         = keyIndex;
trans.msgIn            = (uint32_t *) ecbExample.clearText;
trans.msgOut           = (uint32_t *) ecbExample.msgOut;
// Encrypt the plaintext with AES ECB
status = CryptoCC26XX_transact(handle, (CryptoCC26XX_Transaction *) &trans);
if(status != CRYPTOCC26XX_STATUS_SUCCESS){
    System_abort("Encryption failed.");
}
// Initialize transaction
CryptoCC26XX_Transac_init((CryptoCC26XX_Transaction *) &trans, CRYPTOCC26XX_OP_AES_ECB_DECRYPT);
// Setup transaction
trans.keyIndex         = keyIndex;
trans.msgIn            = (uint32_t *) ecbExample.msgOut;
trans.msgOut           = (uint32_t *) ecbExample.clearText;
// Zero original clear text before decrypting the cypher text into the ecbExample.clearText array
memset(ecbExample.clearText, 0x0, AES_ECB_LENGTH);
// Decrypt the plaintext with AES ECB
status = CryptoCC26XX_transact(handle, (CryptoCC26XX_Transaction *) &trans);
if(status != CRYPTOCC26XX_STATUS_SUCCESS){
    System_abort("Encryption failed.");
}
CryptoCC26XX_releaseKey(handle, &keyIndex);

AES CCM operation

Perform a crypto and authentication operation with AES-CCM in CRYPTOCC26XX_MODE_BLOCKING.

#define macLength           (4)
#define clearTextLength     (16)
#define cipherTextLength    (macLength + clearTextLength)
#define nonceLength         (12)
#define aadLength           (14)
// Holds the AES-CCM setup for this example
typedef struct
{
    uint8_t key[16];                                // A 128 Bit AES key
    CryptoCC26XX_KeyLocation keyLocation;           // One of 8 key locations in the hardware
    uint8_t clearAndCipherText[cipherTextLength];   // Holds the cleartext before, and the ciphertext
                                                    // after the encryption operation.
                                                    // Ciphertext = encrypted text + message authentication code (MAC).
    uint8_t nonce[nonceLength];                     // A value that is used only once (cryptographic term 'nonce')
    uint8_t header[aadLength];                      // A header that is not encrypted but is authenticated in the operation (AAD).
    uint8_t verificationMAC[macLength];             // Location that the recalculated and encrypted MAC is stored during decryption.
} AesCcmExample;
AesCcmExample ccmSetup =
{
    .key = { 0x2B, 0x7E, 0x15, 0x16, 0x28, 0xAE, 0xD2, 0xA6,
             0xAB, 0xF7, 0x15, 0x88, 0x09, 0xCF, 0x4F, 0x3C },
    .keyLocation = CRYPTOCC26XX_KEY_0,
    .clearAndCipherText = { 't','h','i','s','i','s','a','p','l','a','i','n','t','e','x','t','0','0','0','0' },
    .nonce  = { 't','h','i','s','i','s','a','n','o','n','c','e' },
    .header = { 't','h','i','s','i','s','a','h','e','a','d','e','r','1' }
};
CryptoCC26XX_Handle             handle;
int32_t                         keyIndex;
CryptoCC26XX_AESCCM_Transaction trans;
int32_t                         status;
// Initialize Crypto driver structures
CryptoCC26XX_init();
// Open the crypto hardware with non-exclusive access and default parameters.
handle = CryptoCC26XX_open(Board_CRYPTO0, false, NULL);
if (handle == NULL) {
    System_abort("CryptoCC26XX did not open");
}
// Allocate a key storage location in the hardware
keyIndex = CryptoCC26XX_allocateKey(handle, ccmSetup.keyLocation, (const uint32_t *) ccmSetup.key);
if (keyIndex == CRYPTOCC26XX_STATUS_ERROR) {
    System_abort("Key Location was not allocated.");
}
// Encrypt and authenticate the message
CryptoCC26XX_Transac_init((CryptoCC26XX_Transaction *) &trans, CRYPTOCC26XX_OP_AES_CCM);
trans.keyIndex   = keyIndex;
trans.authLength = macLength;
trans.nonce  = (char *) ccmSetup.nonce;
trans.header = (char *) ccmSetup.header;
trans.fieldLength  = 3;
trans.msgInLength  = clearTextLength;
trans.headerLength = aadLength;
trans.msgIn  = (char *) &(ccmSetup.clearAndCipherText[0]);                // Message is encrypted in place
trans.msgOut = (char *) &(ccmSetup.clearAndCipherText[clearTextLength]);  // MAC will be written to this position
status = CryptoCC26XX_transact(handle, (CryptoCC26XX_Transaction *) &trans);
if (status != CRYPTOCC26XX_STATUS_SUCCESS) {
    System_abort("Encryption and signing failed.");
}
// Decrypt and authenticate message
CryptoCC26XX_Transac_init((CryptoCC26XX_Transaction *) &trans, CRYPTOCC26XX_OP_AES_CCMINV);
trans.keyIndex   = keyIndex;
trans.authLength = macLength;
trans.nonce  = (char *) ccmSetup.nonce;
trans.header = (char *) ccmSetup.header;
trans.fieldLength  = 3;
trans.msgInLength  = cipherTextLength;
trans.headerLength = aadLength;
trans.msgIn  = (char *) &(ccmSetup.clearAndCipherText[0]);                // Message is decrypted in place
trans.msgOut = (char *) ccmSetup.verificationMAC;
// Do AES-CCM decryption and authentication
status = CryptoCC26XX_transact(handle, (CryptoCC26XX_Transaction *) &trans);
if(status != CRYPTOCC26XX_STATUS_SUCCESS){
    System_abort("Decryption and authentication failed.");
}
// Release the key location
status = CryptoCC26XX_releaseKey(handle, &keyIndex);
if (status != CRYPTOCC26XX_STATUS_SUCCESS) {
    System_abort("Key release was not successful.");
}

Instrumentation

The CryptoCC26XX driver interface produces log statements if instrumentation is enabled.

Diagnostics Mask	Log details
Diags_USER1	Basic CryptoCC26XX operations performed
Diags_USER2	Detailed CryptoCC26XX operations performed

#include <stdint.h>
#include <stdbool.h>
#include <ti/drivers/Power.h>
#include <ti/devices/DeviceFamily.h>
#include <DeviceFamily_constructPath(driverlib/crypto.h)>
#include <ti/drivers/dpl/HwiP.h>
#include <ti/drivers/dpl/SemaphoreP.h>

Include dependency graph for CryptoCC26XX.h:

Go to the source code of this file.

Data Structures
struct	CryptoCC26XX_Params
	CryptoCC26XX Parameters. More...

struct	CryptoCC26XX_Transaction
	CryptoCC26XX Transaction. More...

struct	CryptoCC26XX_AESCCM_Transaction
	CryptoCC26XX AES-CCM Transaction. More...

struct	CryptoCC26XX_AESCBC_Transaction
	CryptoCC26XX AES-CBC Transaction. More...

struct	CryptoCC26XX_AESECB_Transaction
	CryptoCC26XX AES-ECB Transaction. More...

struct	CryptoCC26XX_HWAttrs
	CryptoCC26XX Hardware Attributes. More...

struct	CryptoCC26XX_Object
	CryptoCC26XX Object. More...

struct	CryptoCC26XX_Config
	CryptoCC26XX Global Configuration. More...

Macros
#define	CRYPTOCC26XX_TIMEOUT 20

#define	CRYPTOCC26XX_STATUS_SUCCESS 0

#define	CRYPTOCC26XX_STATUS_ERROR -1

#define	CRYPTOCC26XX_STATUS_UNDEFINEDCMD -2

#define	CRYPTOCC26XX_OP_AES_CCM_ENCRYPT 0

#define	CRYPTOCC26XX_OP_AES_CCM_ENCRYPT_AAD_ONLY 1

#define	CRYPTOCC26XX_OP_AES_CCM_DECRYPT 2

#define	CRYPTOCC26XX_OP_AES_CCM_DECRYPT_AAD_ONLY 3

#define	CRYPTOCC26XX_OP_AES_ECB_ENCRYPT 4

#define	CRYPTOCC26XX_OP_AES_ECB_DECRYPT 5

#define	CRYPTOCC26XX_OP_AES_CBC_ENCRYPT 6

#define	CRYPTOCC26XX_OP_AES_CBC_DECRYPT 7

#define	CRYPTOCC26XX_OP_AES_CCM CRYPTOCC26XX_OP_AES_CCM_ENCRYPT

#define	CRYPTOCC26XX_OP_AES_CCM_NOCRYPT CRYPTOCC26XX_OP_AES_CCM_ENCRYPT_AAD_ONLY

#define	CRYPTOCC26XX_OP_AES_CCMINV CRYPTOCC26XX_OP_AES_CCM_DECRYPT

#define	CRYPTOCC26XX_OP_AES_CCMINV_NOCRYPT CRYPTOCC26XX_OP_AES_CCM_DECRYPT_AAD_ONLY

#define	CRYPTOCC26XX_OP_AES_ECB CRYPTOCC26XX_OP_AES_ECB_ENCRYPT

#define	CRYPTOCC26XX_OP_AES_ECB_NOCRYPT CRYPTOCC26XX_OP_AES_ECB_DECRYPT

Typedefs
typedef struct CryptoCC26XX_Config *	CryptoCC26XX_Handle
	A handle that is returned from a CryptoCC26XX_open() call. More...

typedef enum CryptoCC26XX_Mode	CryptoCC26XX_Mode
	CryptoCC26XX Mode Settings. More...

typedef uint8_t	CryptoCC26XX_Operation
	CryptoCC26XX Operation Type. More...

typedef enum CryptoCC26XX_KeyLocation	CryptoCC26XX_KeyLocation
	CryptoCC26XX Key Store Location. More...

typedef struct CryptoCC26XX_Params	CryptoCC26XX_Params
	CryptoCC26XX Parameters. More...

typedef uint8_t	CryptoCC26XX_KeyStore
	CryptoCC26XX Key. More...

typedef struct CryptoCC26XX_Transaction	CryptoCC26XX_Transaction
	CryptoCC26XX Transaction. More...

typedef struct CryptoCC26XX_AESCCM_Transaction	CryptoCC26XX_AESCCM_Transaction
	CryptoCC26XX AES-CCM Transaction. More...

typedef struct CryptoCC26XX_AESCBC_Transaction	CryptoCC26XX_AESCBC_Transaction
	CryptoCC26XX AES-CBC Transaction. More...

typedef struct CryptoCC26XX_AESECB_Transaction	CryptoCC26XX_AESECB_Transaction
	CryptoCC26XX AES-ECB Transaction. More...

typedef struct CryptoCC26XX_HWAttrs	CryptoCC26XX_HWAttrs
	CryptoCC26XX Hardware Attributes. More...

typedef struct CryptoCC26XX_Object	CryptoCC26XX_Object
	CryptoCC26XX Object. More...

typedef struct CryptoCC26XX_Config	CryptoCC26XX_Config
	CryptoCC26XX Global Configuration. More...

Enumerations
enum	CryptoCC26XX_Mode { CRYPTOCC26XX_MODE_BLOCKING, CRYPTOCC26XX_MODE_POLLING }
	CryptoCC26XX Mode Settings. More...

enum	CryptoCC26XX_KeyLocation { CRYPTOCC26XX_KEY_0 = 0, CRYPTOCC26XX_KEY_1, CRYPTOCC26XX_KEY_2, CRYPTOCC26XX_KEY_3, CRYPTOCC26XX_KEY_4, CRYPTOCC26XX_KEY_5, CRYPTOCC26XX_KEY_COUNT, CRYPTOCC26XX_KEY_ANY = 9 }
	CryptoCC26XX Key Store Location. More...

Functions
int	CryptoCC26XX_close (CryptoCC26XX_Handle handle)
	Function to closes a given CryptoCC26XX peripheral specified by the CryptoCC26XX handle. More...

void	CryptoCC26XX_init (void)
	Function to initialize CryptoCC26XX driver. Users of this module must call init(). Multiple users/libraries may call init(), though subsequent calls may be benign. More...

CryptoCC26XX_Handle	CryptoCC26XX_open (unsigned int index, bool exclusiveAccess, CryptoCC26XX_Params *params)
	Function to initialize a given CryptoCC26XX peripheral specified by the particular index value. The parameter specifies which mode the CryptoCC26XX will operate. More...

void	CryptoCC26XX_Params_init (CryptoCC26XX_Params *params)
	Function to initialize the CryptoCC26XX_Params struct to its defaults. More...

void	CryptoCC26XX_Transac_init (CryptoCC26XX_Transaction *trans, CryptoCC26XX_Operation opType)
	Function to initialize the CryptoCC26XX_Transaction struct to its defaults. More...

int	CryptoCC26XX_allocateKey (CryptoCC26XX_Handle handle, CryptoCC26XX_KeyLocation keyLocation, const uint32_t *keySrc)
	Function that allocates key, writes key into key store RAM and returns a handle to CryptoCC26XX Key. More...

int	CryptoCC26XX_loadKey (CryptoCC26XX_Handle handle, int keyIndex, const uint32_t *keySrc)
	Function that writes a given key into a key store. More...

int	CryptoCC26XX_releaseKey (CryptoCC26XX_Handle handle, int *keyIndex)
	Function that releases the specified CryptoCC26XX Key. More...

int	CryptoCC26XX_transact (CryptoCC26XX_Handle handle, CryptoCC26XX_Transaction *transaction)
	Function to do a Crypto operation (encryption or decryption) in blocking mode. More...

int	CryptoCC26XX_transactPolling (CryptoCC26XX_Handle handle, CryptoCC26XX_Transaction *transaction)
	Function to do a Crypto transaction operation (encryption or decryption) in polling mode. More...

int	CryptoCC26XX_transactCallback (CryptoCC26XX_Handle handle, CryptoCC26XX_Transaction *transaction)
	Function to do a Crypto transaction operation (encryption or decryption) in callback mode. Currently not supported. More...

Macro Definition Documentation

§ CRYPTOCC26XX_TIMEOUT

#define CRYPTOCC26XX_TIMEOUT 20

Timeout Return Code

§ CRYPTOCC26XX_STATUS_SUCCESS

#define CRYPTOCC26XX_STATUS_SUCCESS 0

Success Return Code

§ CRYPTOCC26XX_STATUS_ERROR

#define CRYPTOCC26XX_STATUS_ERROR -1

Error Return Code

§ CRYPTOCC26XX_STATUS_UNDEFINEDCMD

#define CRYPTOCC26XX_STATUS_UNDEFINEDCMD -2

Command Undefined Return Code

§ CRYPTOCC26XX_OP_AES_CCM_ENCRYPT

#define CRYPTOCC26XX_OP_AES_CCM_ENCRYPT 0

AES-CCM encryption of both AAD and plain text

§ CRYPTOCC26XX_OP_AES_CCM_ENCRYPT_AAD_ONLY

#define CRYPTOCC26XX_OP_AES_CCM_ENCRYPT_AAD_ONLY 1

AES-CCM authentication of ADD only

§ CRYPTOCC26XX_OP_AES_CCM_DECRYPT

#define CRYPTOCC26XX_OP_AES_CCM_DECRYPT 2

AES-CCM decryption of both AAD and plain text and verification of both

§ CRYPTOCC26XX_OP_AES_CCM_DECRYPT_AAD_ONLY

#define CRYPTOCC26XX_OP_AES_CCM_DECRYPT_AAD_ONLY 3

AES-CCM verification of ADD only

§ CRYPTOCC26XX_OP_AES_ECB_ENCRYPT

#define CRYPTOCC26XX_OP_AES_ECB_ENCRYPT 4

AES-ECB encryption

§ CRYPTOCC26XX_OP_AES_ECB_DECRYPT

#define CRYPTOCC26XX_OP_AES_ECB_DECRYPT 5

AES-ECB decryption

§ CRYPTOCC26XX_OP_AES_CBC_ENCRYPT

#define CRYPTOCC26XX_OP_AES_CBC_ENCRYPT 6

AES-CBC encryption

§ CRYPTOCC26XX_OP_AES_CBC_DECRYPT

#define CRYPTOCC26XX_OP_AES_CBC_DECRYPT 7

AES-CBC decryption

§ CRYPTOCC26XX_OP_AES_CCM

#define CRYPTOCC26XX_OP_AES_CCM CRYPTOCC26XX_OP_AES_CCM_ENCRYPT

§ CRYPTOCC26XX_OP_AES_CCM_NOCRYPT

#define CRYPTOCC26XX_OP_AES_CCM_NOCRYPT CRYPTOCC26XX_OP_AES_CCM_ENCRYPT_AAD_ONLY

§ CRYPTOCC26XX_OP_AES_CCMINV

#define CRYPTOCC26XX_OP_AES_CCMINV CRYPTOCC26XX_OP_AES_CCM_DECRYPT

§ CRYPTOCC26XX_OP_AES_CCMINV_NOCRYPT

#define CRYPTOCC26XX_OP_AES_CCMINV_NOCRYPT CRYPTOCC26XX_OP_AES_CCM_DECRYPT_AAD_ONLY

§ CRYPTOCC26XX_OP_AES_ECB

#define CRYPTOCC26XX_OP_AES_ECB CRYPTOCC26XX_OP_AES_ECB_ENCRYPT

§ CRYPTOCC26XX_OP_AES_ECB_NOCRYPT

#define CRYPTOCC26XX_OP_AES_ECB_NOCRYPT CRYPTOCC26XX_OP_AES_ECB_DECRYPT

Typedef Documentation

§ CryptoCC26XX_Handle

typedef struct CryptoCC26XX_Config* CryptoCC26XX_Handle

A handle that is returned from a CryptoCC26XX_open() call.

§ CryptoCC26XX_Mode

typedef enum CryptoCC26XX_Mode CryptoCC26XX_Mode

CryptoCC26XX Mode Settings.

This enum defines the read and write modes for the configured CryptoCC26XX.

§ CryptoCC26XX_Operation

typedef uint8_t CryptoCC26XX_Operation

CryptoCC26XX Operation Type.

This type holds the CryptoCC26XX operation.

Currently supported types are

Encryption	Decryption
CRYPTOCC26XX_OP_AES_CCM_ENCRYPT	CRYPTOCC26XX_OP_AES_CCM_DECRYPT
CRYPTOCC26XX_OP_AES_CCM_ENCRYPT_AAD_ONLY	CRYPTOCC26XX_OP_AES_CCM_DECRYPT_AAD_ONLY
CRYPTOCC26XX_OP_AES_ECB_ENCRYPT	CRYPTOCC26XX_OP_AES_ECB_DECRYPT
CRYPTOCC26XX_OP_AES_CBC_ENCRYPT	CRYPTOCC26XX_OP_AES_CBC_DECRYPT

§ CryptoCC26XX_KeyLocation

typedef enum CryptoCC26XX_KeyLocation CryptoCC26XX_KeyLocation

CryptoCC26XX Key Store Location.

This enumeration defines the possible key locations in CryptoCC26XX.

§ CryptoCC26XX_Params

typedef struct CryptoCC26XX_Params CryptoCC26XX_Params

CryptoCC26XX Parameters.

§ CryptoCC26XX_KeyStore

typedef uint8_t CryptoCC26XX_KeyStore

CryptoCC26XX Key.

This holds allocation information for the keys in the key store.

§ CryptoCC26XX_Transaction

typedef struct CryptoCC26XX_Transaction CryptoCC26XX_Transaction

CryptoCC26XX Transaction.

This structure defines the nature of a general crypto transaction. An operation specific object, e.g. CryptoCC26XX_AESCCM_Transaction, must be used by the clients. All transaction must be typecasted to this common type when calling the transact functions. The first data of all transactions must hold a type field indicating which type of transaction to be performed.

§ CryptoCC26XX_AESCCM_Transaction

typedef struct CryptoCC26XX_AESCCM_Transaction CryptoCC26XX_AESCCM_Transaction

CryptoCC26XX AES-CCM Transaction.

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. AES-CCM combines CBC-MAC with an AES block cipher.

AES-CCM 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 cleartext + MAC)
AAD (optional)	AAD (optional)
Output
Ciphertext (encrypted cleartext + MAC)	Cleartext

The AES key is a shared secret between the two parties and has a length of 128 Bit. The key is stored in the dedicated RAM of the AES hardware unit before the crypto operation.

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 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 for transport layer security.

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.

AES-CCM works in both ways: encryption and decryption. When a message is decrypted, then ciphertext, AAD and nonce are used as inputs while the output comprises the cleartext only. The decryption operation is successful, when the received ciphertext, the nonce and the AAD can reproduce the containing MAC.

The CryptoCC26XX_AESCCM_Transaction structure defines all necessary parameters for a AES-CCM transaction.

§ CryptoCC26XX_AESCBC_Transaction

typedef struct CryptoCC26XX_AESCBC_Transaction CryptoCC26XX_AESCBC_Transaction

CryptoCC26XX AES-CBC Transaction.

This structure defines the nature of the AES-CBC transaction. An object of this structure must be initialized by calling CryptoCC26XX_Transac_init().

§ CryptoCC26XX_AESECB_Transaction

typedef struct CryptoCC26XX_AESECB_Transaction CryptoCC26XX_AESECB_Transaction

CryptoCC26XX AES-ECB Transaction.

This structure defines the nature of the AES-ECB transaction. An object of this structure must be initialized by calling CryptoCC26XX_Transac_init().

§ CryptoCC26XX_HWAttrs

typedef struct CryptoCC26XX_HWAttrs CryptoCC26XX_HWAttrs

CryptoCC26XX Hardware Attributes.

These fields, with the exception of intPriority, are used by driverlib APIs and therefore must be populated by driverlib macro definitions. For CC26XXWare these definitions are found in:

inc/hw_memmap.h
inc/hw_ints.h

intPriority is the Crypto peripheral's interrupt priority, as defined by the underlying OS. It is passed unmodified to the underlying OS's interrupt handler creation code, so you need to refer to the OS documentation for usage. If the driver uses the ti.dpl interface instead of making OS calls directly, then the HwiP port handles the interrupt priority in an OS specific way. In the case of the SYS/BIOS port, intPriority is passed unmodified to Hwi_create().

A sample structure is shown below:

const CryptoCC26XX_HWAttrs cryptoCC26XXHWAttrs[] = {
    {
        .baseAddr = CRYPTO_BASE,
        .powerMngrId = PERIPH_CRYPTO,
        .intNum = INT_CRYPTO,
        .intPriority = (~0)
    }
};

§ CryptoCC26XX_Object

typedef struct CryptoCC26XX_Object CryptoCC26XX_Object

CryptoCC26XX Object.

The application must not access any member variables of this structure!

§ CryptoCC26XX_Config

typedef struct CryptoCC26XX_Config CryptoCC26XX_Config

CryptoCC26XX Global Configuration.

Enumeration Type Documentation

§ CryptoCC26XX_Mode

enum CryptoCC26XX_Mode

CryptoCC26XX Mode Settings.

This enum defines the read and write modes for the configured CryptoCC26XX.

Enumerator
CRYPTOCC26XX_MODE_BLOCKING	Uses a semaphore to block while data is being sent. Context of the call must be a Task.
CRYPTOCC26XX_MODE_POLLING	Will return when the operation has finished. Call can be made from hwi and swi context.

§ CryptoCC26XX_KeyLocation

enum CryptoCC26XX_KeyLocation

CryptoCC26XX Key Store Location.

This enumeration defines the possible key locations in CryptoCC26XX.

Enumerator
CRYPTOCC26XX_KEY_0
CRYPTOCC26XX_KEY_1
CRYPTOCC26XX_KEY_2
CRYPTOCC26XX_KEY_3
CRYPTOCC26XX_KEY_4
CRYPTOCC26XX_KEY_5
CRYPTOCC26XX_KEY_COUNT
CRYPTOCC26XX_KEY_ANY

Function Documentation

§ CryptoCC26XX_close()

int CryptoCC26XX_close ( CryptoCC26XX_Handle handle )

Function to closes a given CryptoCC26XX peripheral specified by the CryptoCC26XX handle.

Precondition: CryptoCC26XX_open() had to be called first. Calling context: Task

Parameters

handle A CryptoCC26XX_Handle returned from CryptoCC26XX_open().

Returns: Returns CRYPTOCC26XX_STATUS_SUCCESS if successful, otherwise will return CRYPTOCC26XX_STATUS_ERROR.

See also: CryptoCC26XX_open

§ CryptoCC26XX_init()

void CryptoCC26XX_init ( void )

Function to initialize CryptoCC26XX driver. Users of this module must call init(). Multiple users/libraries may call init(), though subsequent calls may be benign.

Precondition: This function must be called before any other CryptoCC26XX driver APIs. Calling context: Task and Main.

§ CryptoCC26XX_open()

CryptoCC26XX_Handle CryptoCC26XX_open	(	unsigned int	index,
		bool	exclusiveAccess,
		CryptoCC26XX_Params *	params
	)

Function to initialize a given CryptoCC26XX peripheral specified by the particular index value. The parameter specifies which mode the CryptoCC26XX will operate.

Precondition: The CryptoCC26XX_Config structure must exist and be persistent before this function can be called. CryptoCC26XX has been initialized with CryptoCC26XX_init(). Calling context: Task.

Parameters

index	Logical peripheral number indexed into the HWAttrs table. This is usually provided in the Board support file.
exclusiveAccess	Boolean flag to get exclusive access, if true all subsequent calls to CryptoCC26XX_open() will fail.
params	Pointer to an parameter block, if NULL it will use default values.

Returns: A CryptoCC26XX_Handle on success or a NULL on an error or if it has been already opened with exclusiveAccess set.

See also: CryptoCC26XX_close(), CryptoCC26XX_init()

§ CryptoCC26XX_Params_init()

void CryptoCC26XX_Params_init ( CryptoCC26XX_Params * params )

Function to initialize the CryptoCC26XX_Params struct to its defaults.

Precondition: Calling context: Hwi, Swi and Task.

Defaults values are: timeout = BIOS_WAIT_FOREVER;

Parameters

params Parameter structure to initialize.

§ CryptoCC26XX_Transac_init()

void CryptoCC26XX_Transac_init	(	CryptoCC26XX_Transaction *	trans,
		CryptoCC26XX_Operation	opType
	)

Function to initialize the CryptoCC26XX_Transaction struct to its defaults.

Precondition: Calling context: Hwi, Swi and Task.

Parameters

trans	Transaction structure to initialize.
opType	Cryto Operation type to perform in the transaction. See CryptoCC26XX_Operation for currently supported types.

§ CryptoCC26XX_allocateKey()

int CryptoCC26XX_allocateKey	(	CryptoCC26XX_Handle	handle,
		CryptoCC26XX_KeyLocation	keyLocation,
		const uint32_t *	keySrc
	)

Function that allocates key, writes key into key store RAM and returns a handle to CryptoCC26XX Key.

This function tries to allocate the wanted key location, initiates an operation to write a key into one of the keystore RAM entries and returns a key index integer to the calling client. The allocated key index shall be used when building a transaction data object, e.g. CryptoCC26XX_AESCCM_Transaction.keyIndex. The function blocks the task calling it until the crypto hardware is available.

Once allocated, the key location will remain allocated until CryptoCC26XX_releaseKey() is called. When when entering standby, the keying material in the key location will be lost but the allocation will remain. The application will need to load new keying material to their already allocated key location using CryptoCC26XX_loadKey().

If CryptoCC26XX_allocateKey() is called repeatedly with keyLocation CRYPTOCC26XX_KEY_ANY, the keystore will run out of available locations and will not be able to allocate new key locations until CryptoCC26XX_releaseKey() is called.

Precondition: CryptoCC26XX_open() has to be called first. Calling context: Hwi, Swi and Task.

Parameters

handle	A CryptoCC26XX_Handle returned by CryptoCC26XX_open().
keyLocation	The key location in key store to allocate. If set to CRYPTOCC26XX_KEY_ANY, the first available key, starting from highest index, will be allocated.
keySrc	A pointer to buffer containing key to be written. If this pointer is NULL, the key store will be reserved for the handle, but no key will be written to the key store.

Returns: An integer representing the index allocated in key store or a CRYPTOCC26XX_STATUS_ERROR on an error.

See also: CryptoCC26XX_releaseKey(); CryptoCC26XX_loadKey()

§ CryptoCC26XX_loadKey()

int CryptoCC26XX_loadKey	(	CryptoCC26XX_Handle	handle,
		int	keyIndex,
		const uint32_t *	keySrc
	)

Function that writes a given key into a key store.

This function loads a key into a keystore without needing to release the key store and re-allocate it using CryptoCC26XX_releaseKey() and CryptoCC26XX_allocateKey(). If called in task context, the function blocks for as long as specified in the timeout. If called in Swi or Hwi context, the function returns an error immediately if it cannot acquire the semaphore.

Precondition: CryptoCC26XX_open() and CryptoCC26XX_allocateKey() have to be called first. Calling context: Hwi, Swi and Task.

Parameters

handle	A CryptoCC26XX_Handle returned by CryptoCC26XX_open().
keyIndex	A key index returned by a previous call to CryptoCC26XX_allocateKey().
keySrc	A pointer to buffer containing a key.

Returns: An integer representing success (CRYPTOCC26XX_STATUS_SUCCESS) or an error (CRYPTOCC26XX_STATUS_ERROR).

See also: CryptoCC26XX_releaseKey(); CryptoCC26XX_loadKey()

§ CryptoCC26XX_releaseKey()

int CryptoCC26XX_releaseKey	(	CryptoCC26XX_Handle	handle,
		int *	keyIndex
	)

Function that releases the specified CryptoCC26XX Key.

This function releases the crypto key, so it can be used by other clients.

Precondition: Driver must have been opened and the key must have been allocated first. Calling context: Hwi, Swi and Task.

Parameters

handle	A CryptoCC26XX_Handle returned by CryptoCC26XX_open().
keyIndex	A pointer to the keyIndex to be released.

Returns: Returns CRYPTOCC26XX_STATUS_SUCCESS if successful, otherwise will return CRYPTOCC26XX_STATUS_ERROR.

See also: CryptoCC26XX_allocateKey()

§ CryptoCC26XX_transact()

int CryptoCC26XX_transact	(	CryptoCC26XX_Handle	handle,
		CryptoCC26XX_Transaction *	transaction
	)

Function to do a Crypto operation (encryption or decryption) in blocking mode.

This function initiates a blocking crypto operation.

CryptoCC26XX_transact() will block task execution until all the data has been encrypted or decrypted, a task switch could be done when pending on a semaphore.

Precondition: Driver must have been opened and a key must have been allocated first. Calling context: Task.

Parameters

handle	A CryptoCC26XX_Handle returned by CryptoCC26XX_open().
transaction	Pointer to a transaction descriptor.

Returns: Returns CRYPTOCC26XX_STATUS_SUCCESS if successful, error code if not.

See also: CryptoCC26XX_open(), CryptoCC26XX_allocateKey(), CryptoCC26XX_transactPolling()

§ CryptoCC26XX_transactPolling()

int CryptoCC26XX_transactPolling	(	CryptoCC26XX_Handle	handle,
		CryptoCC26XX_Transaction *	transaction
	)

Function to do a Crypto transaction operation (encryption or decryption) in polling mode.

This function initiates a polling crypto operation.

CryptoCC26XX_transactPolling() blocks task execution and does not pend on a semaphore, consequently no task switch will be done as a result of pending.

Precondition: Driver must have been opened and a key must have been allocated first. Calling context: Hwi, Swi and Task.

Parameters

handle	An CryptoCC26XX_Handle returned by CryptoCC26XX_open().
transaction	Pointer to a transaction descriptor.

Returns: Returns CRYPTOCC26XX_STATUS_SUCCESS if successful, error code if not.

See also: CryptoCC26XX_open(), CryptoCC26XX_allocateKey(), CryptoCC26XX_transact()

§ CryptoCC26XX_transactCallback()

int CryptoCC26XX_transactCallback	(	CryptoCC26XX_Handle	handle,
		CryptoCC26XX_Transaction *	transaction
	)

Function to do a Crypto transaction operation (encryption or decryption) in callback mode. Currently not supported.

This function initiates a callback crypto operation.

CryptoCC26XX_transactCallback() will continue task execution (i.e. does not pend on a semaphore). A callback function must be defined, and will be called when the crypto operation has finished.

Precondition: Driver must have been opened and a key must have been allocated first. Calling context: Hwi, Swi and Task.

Parameters

handle	An CryptoCC26XX_Handle returned by CryptoCC26XX_open().
transaction	Pointer to a transaction descriptor.

Returns: Returns CRYPTOCC26XX_STATUS_SUCCESS if successful, error code if not.

Note: Currently not supported. Will replace CryptoCC26XX_transactPolling in the future.

See also: CryptoCC26XX_open(), CryptoCC26XX_allocateKey(), CryptoCC26XX_transact()

Detailed Description

Driver Include

Overview

Usage

Opening the driver

Before starting a crypto operation

Performing a crypto operation

Supported transaction modes

Closing the driver

Error handling

Power Management

Unsupported functionality:

Supported Operations

Synopsis

Examples

AES ECB operation

AES CCM operation

Instrumentation

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

§ CRYPTOCC26XX_TIMEOUT

§ CRYPTOCC26XX_STATUS_SUCCESS

§ CRYPTOCC26XX_STATUS_ERROR

§ CRYPTOCC26XX_STATUS_UNDEFINEDCMD

§ CRYPTOCC26XX_OP_AES_CCM_ENCRYPT

§ CRYPTOCC26XX_OP_AES_CCM_ENCRYPT_AAD_ONLY

§ CRYPTOCC26XX_OP_AES_CCM_DECRYPT

§ CRYPTOCC26XX_OP_AES_CCM_DECRYPT_AAD_ONLY

§ CRYPTOCC26XX_OP_AES_ECB_ENCRYPT

§ CRYPTOCC26XX_OP_AES_ECB_DECRYPT

§ CRYPTOCC26XX_OP_AES_CBC_ENCRYPT

§ CRYPTOCC26XX_OP_AES_CBC_DECRYPT

§ CRYPTOCC26XX_OP_AES_CCM

§ CRYPTOCC26XX_OP_AES_CCM_NOCRYPT

§ CRYPTOCC26XX_OP_AES_CCMINV

§ CRYPTOCC26XX_OP_AES_CCMINV_NOCRYPT

§ CRYPTOCC26XX_OP_AES_ECB

§ CRYPTOCC26XX_OP_AES_ECB_NOCRYPT

Typedef Documentation

§ CryptoCC26XX_Handle

§ CryptoCC26XX_Mode

§ CryptoCC26XX_Operation

§ CryptoCC26XX_KeyLocation

§ CryptoCC26XX_Params

§ CryptoCC26XX_KeyStore

§ CryptoCC26XX_Transaction

§ CryptoCC26XX_AESCCM_Transaction

§ CryptoCC26XX_AESCBC_Transaction

§ CryptoCC26XX_AESECB_Transaction

§ CryptoCC26XX_HWAttrs

§ CryptoCC26XX_Object

§ CryptoCC26XX_Config

Enumeration Type Documentation

§ CryptoCC26XX_Mode

§ CryptoCC26XX_KeyLocation

Function Documentation

§ CryptoCC26XX_close()

§ CryptoCC26XX_init()

§ CryptoCC26XX_open()

§ CryptoCC26XX_Params_init()

§ CryptoCC26XX_Transac_init()

§ CryptoCC26XX_allocateKey()

§ CryptoCC26XX_loadKey()

§ CryptoCC26XX_releaseKey()

§ CryptoCC26XX_transact()

§ CryptoCC26XX_transactPolling()

§ CryptoCC26XX_transactCallback()