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.

General Behavior

For code examples, see Use Cases below.

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_CRYPTO, 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_SB_DISALLOW 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 allocate the key over again.

Supported Functions

API function	Description
CryptoCC26XX_init()	Function to initializes bios modules needed by CryptoCC26XX module
CryptoCC26XX_open()	Initialize Crypto and get crypto handle
CryptoCC26XX_close()	Disable Crypto HW and destruct bios modules used by transactions
CryptoCC26XX_Params_init()	Initialize Crypto parameters
CryptoCC26XX_Transac_init()	Initialize Crypto transaction
CryptoCC26XX_allocateKey()	Allocate a key for current client and write key into one of the Crypto RAM locations
CryptoCC26XX_releaseKey()	Release/deallocate a key for current client
CryptoCC26XX_transact()	Start a crypto operation in blocking mode
CryptoCC26XX_transactPolling()	Start a crypto operation in polling mode

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 AAD and plain text
CRYPTOCC26XX_OP_AES_CCM_ENCRYPT_AAD_ONLY	AES-CCM encryption of AAD only
CRYPTOCC26XX_OP_AES_CCM_DECRYPT	AES-CCM decryption of AAD and plain text
CRYPTOCC26XX_OP_AES_CCM_DECRYPT_AAD_ONLY	AES-CCM decryption of AAD only
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

Use Cases

AES ECB operation

Do a crypto operation with AES-ECB in CRYPTOCC26XX_MODE_BLOCKING.

// AES-ECB example struct
typedef struct
{
    uint8_t ui8AESKey[16];                      // Stores the Aes Key
    CryptoCC26XX_KeyLocation ui8AESKeyLocation; // Location in Key RAM
    uint8_t ui8AESClearText[16];                // Input message - clear text
    uint8_t ui8AESMsgOut[16];                   // Output message
    uint8_t ui8IntEnable;                       // Set to true/false to enable/
                                                // disable interrupts
} tAESECBExample;
// AES ECB example data
tAESECBExample sAESexample =
{
    { 0x2B, 0x7E, 0x15, 0x16, 0x28, 0xAE, 0xD2, 0xA6,
    0xAB, 0xF7, 0x15, 0x88, 0x09, 0xCF, 0x4F, 0x3C },
    CRYPTOCC26XX_KEY_0,
    { 0x6B, 0xC1, 0xBE, 0xE2, 0x2E, 0x40, 0x9F, 0x96,
    0xE9, 0x3D, 0x7E, 0x11, 0x73, 0x93, 0x17, 0x2A },
    { 0x3A, 0xD7, 0x7B, 0xB4, 0x0D, 0x7A, 0x36, 0x60,
    0xA8, 0x9E, 0xCA, 0xF3, 0x24, 0x66, 0xEF, 0x97 },
    true,
};
// Declaration (typically done in a task)
CryptoCC26XX_Handle             handle;
CryptoCC26XX_Params             params;
uint8_t                         keyIndex;
CryptoCC26XX_AESECB_Transaction trans;
// Initialize Crypto driver
CryptoCC26XX_init();
// Configure CryptoCC26XX parameters.
CryptoCC26XX_Params_init(&params);
// Initialize transaction
CryptoCC26XX_Transac_init((CryptoCC26XX_Transaction *) &trans, CRYPTOCC26XX_OP_AES_ECB);
// Attempt to open CryptoCC26XX.
handle = CryptoCC26XX_open(Board_CRYPTO, false, &params);
if (!handle) {
    System_printf("CryptoCC26XX did not open");
} else {
    keyIndex = CryptoCC26XX_allocateKey(handle, sAESexample.ui8AESKeyLocation,
                                         (const uint32_t *) sAESexample.ui8AESKey);
    if (keyIndex != CRYPTOCC26XX_STATUS_ERROR) {
        // Setup transaction
        trans.keyIndex         = keyIndex;
        trans.msgIn            = (uint32_t *) sAESexample.ui8AESClearText;
        trans.msgOut           = (uint32_t *) sAESexample.ui8AESMsgOut;
        // Do AES-ECB operation
        res = CryptoCC26XX_transact(handle, (CryptoCC26XX_Transaction *) &trans);
        CryptoCC26XX_releaseKey(handle);
    } else {
        System_printf("Key Location was not allocated.");
    }
}

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 <driverlib/crypto.h>
#include <ti/sysbios/family/arm/m3/Hwi.h>
#include <ti/sysbios/knl/Semaphore.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

#define	ti_sysbios_family_arm_m3_Hwi__nolocalnames

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_6, CRYPTOCC26XX_KEY_7, CRYPTOCC26XX_KEY_COUNT, CRYPTOCC26XX_KEY_ANY }
	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 initializes bios modules needed by CryptoCC26XX module. 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

#define CRYPTOCC26XX_TIMEOUT 20

Timeout Return Code

#define CRYPTOCC26XX_STATUS_SUCCESS 0

Success Return Code

#define CRYPTOCC26XX_STATUS_ERROR -1

Error Return Code

#define CRYPTOCC26XX_STATUS_UNDEFINEDCMD -2

Command Undefined Return Code

#define CRYPTOCC26XX_OP_AES_CCM_ENCRYPT 0

AES-CCM encryption of both AAD and plain text

#define CRYPTOCC26XX_OP_AES_CCM_ENCRYPT_AAD_ONLY 1

AES-CCM encryption of ADD only

#define CRYPTOCC26XX_OP_AES_CCM_DECRYPT 2

AES-CCM decryption of both AAD and plain text

#define CRYPTOCC26XX_OP_AES_CCM_DECRYPT_AAD_ONLY 3

AES-CCM decryption of ADD only

#define CRYPTOCC26XX_OP_AES_ECB_ENCRYPT 4

AES-ECB encryption

#define CRYPTOCC26XX_OP_AES_ECB_DECRYPT 5

AES-ECB decryption

#define CRYPTOCC26XX_OP_AES_CBC_ENCRYPT 6

AES-CBC encryption

#define CRYPTOCC26XX_OP_AES_CBC_DECRYPT 7

AES-CBC decryption

#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

#define ti_sysbios_family_arm_m3_Hwi__nolocalnames

Typedef Documentation

typedef struct CryptoCC26XX_Config* CryptoCC26XX_Handle

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

typedef enum CryptoCC26XX_Mode CryptoCC26XX_Mode

CryptoCC26XX Mode Settings.

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

typedef uint8_t CryptoCC26XX_Operation

CryptoCC26XX Operation Type.

This type holds the CryptoCC26XX operation.

Currently supported types are

typedef enum CryptoCC26XX_KeyLocation CryptoCC26XX_KeyLocation

CryptoCC26XX Key Store Location.

This enumeration defines the possible key locations in CryptoCC26XX.

typedef struct CryptoCC26XX_Params CryptoCC26XX_Params

CryptoCC26XX Parameters.

typedef uint8_t CryptoCC26XX_KeyStore

CryptoCC26XX Key.

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

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.

typedef struct CryptoCC26XX_AESCCM_Transaction CryptoCC26XX_AESCCM_Transaction

CryptoCC26XX AES-CCM Transaction.

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

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

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

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. For example, for SYS/BIOS applications, refer to the ti.sysbios.family.arm.m3.Hwi documentation for SYS/BIOS usage of interrupt priorities. If the driver uses the ti.drivers.ports 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)
     }
 };

typedef struct CryptoCC26XX_Object CryptoCC26XX_Object

CryptoCC26XX Object.

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

typedef struct CryptoCC26XX_Config CryptoCC26XX_Config

CryptoCC26XX Global Configuration.

Enumeration Type Documentation

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.

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_6
CRYPTOCC26XX_KEY_7
CRYPTOCC26XX_KEY_COUNT
CRYPTOCC26XX_KEY_ANY

Function Documentation

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

void CryptoCC26XX_init ( void )

Function to initializes bios modules needed by CryptoCC26XX module.

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

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

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.

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.

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.

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

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

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

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

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

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

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

General Behavior

Opening the driver

Before starting a crypto operation

Performing a crypto operation

Supported transaction modes

Closing the driver

Error handling

Power Management

Supported Functions

Unsupported functionality:

Supported Operations

Use Cases

AES ECB operation

Instrumentation

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation