TI-RTOS for SimpleLink Wireless MCUs
2.14.02.22
|
Crypto driver implementation for a CC26XX Crypto controller.
============================================================================
The Crypto header file should be included in an application as follows:
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.
For code examples, see Use Cases below.
The crypto driver is closed by calling CryptoCC26XX_close() function. When the openCnt is decremented to zero, the crypto related bios modules are destructed.
If an error occur during encryption/decryption, the operation will return the error code and the device might enter standby.
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.
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 |
Functionality that currently not supported:
Operation Type | Description |
---|---|
CRYPTOCC26XX_OP_AES_CCM | AES-CCM Operation with Cryptation |
CRYPTOCC26XX_OP_AES_CCM_NOCRYPT | AES-CCM Operation without Cryptation |
CRYPTOCC26XX_OP_AES_CCMINV | AES-CCM Inverse Operation with Cryptation |
CRYPTOCC26XX_OP_AES_CCMINV_NOCRYPT | AES-CCM Inverse Operation without Cryptation |
CRYPTOCC26XX_OP_AES_ECB | AES-ECB Operation with Cryptation |
CRYPTOCC26XX_OP_AES_ECB_NOCRYPT | AES-ECB Operation without Cryptation |
Do a crypto operation with AES-ECB in CRYPTOCC26XX_MODE_BLOCKING.
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/sysbios/family/arm/cc26xx/Power.h>
#include <driverlib/crypto.h>
#include <ti/sysbios/family/arm/m3/Hwi.h>
#include <ti/sysbios/knl/Semaphore.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_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 0 |
#define | CRYPTOCC26XX_OP_AES_CCM_NOCRYPT 1 |
#define | CRYPTOCC26XX_OP_AES_CCMINV 2 |
#define | CRYPTOCC26XX_OP_AES_CCMINV_NOCRYPT 3 |
#define | CRYPTOCC26XX_OP_AES_ECB 4 |
#define | CRYPTOCC26XX_OP_AES_ECB_NOCRYPT 5 |
#define | OP_TYPE(x) ((x)&0xFE) |
#define | DO_CRYPT(x) ((x)&0x01?false:true) |
#define | ti_sysbios_family_arm_m3_Hwi__nolocalnames |
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_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... | |
#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 0 |
AES-CCM Operation with Cryptation
#define CRYPTOCC26XX_OP_AES_CCM_NOCRYPT 1 |
AES-CCM Operation without Cryptation
#define CRYPTOCC26XX_OP_AES_CCMINV 2 |
AES-CCM Inverse Operation with Cryptation
#define CRYPTOCC26XX_OP_AES_CCMINV_NOCRYPT 3 |
AES-CCM Inverse Operation without Cryptation
#define CRYPTOCC26XX_OP_AES_ECB 4 |
AES-ECB Operation with Cryptation
#define CRYPTOCC26XX_OP_AES_ECB_NOCRYPT 5 |
AES-ECB Operation without Cryptation
#define OP_TYPE | ( | x | ) | ((x)&0xFE) |
Macro for selecting the operation type, i.e. omitting the crypt bit
#define DO_CRYPT | ( | x | ) | ((x)&0x01?false:true) |
Macro for getting cryptation flag from the operation type
#define ti_sysbios_family_arm_m3_Hwi__nolocalnames |
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 CRYPTOCC26XX_OP_AES_CCM, CRYPTOCC26XX_OP_AES_CCMINV, CRYPTOCC26XX_OP_AES_ECB, CRYPTOCC26XX_OP_AES_CCM_NOCRYPT, CRYPTOCC26XX_OP_AES_CCMINV_NOCRYPT and CRYPTOCC26XX_OP_AES_ECB_NOCRYPT.
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_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 are used by driverlib APIs and therefore must be populated by driverlib macro definitions. For CC26XXWare these definitions are found in:
A sample structure is shown below:
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.
enum CryptoCC26XX_Mode |
CryptoCC26XX Mode Settings.
This enum defines the read and write modes for the configured CryptoCC26XX.
CryptoCC26XX Key Store Location.
This enumeration defines the possible key locations in CryptoCC26XX.
int CryptoCC26XX_close | ( | CryptoCC26XX_Handle | handle | ) |
Function to closes a given CryptoCC26XX peripheral specified by the CryptoCC26XX handle.
handle | A CryptoCC26XX_Handle returned from CryptoCC26XX_open(). |
void CryptoCC26XX_init | ( | void | ) |
Function to initializes bios modules needed by CryptoCC26XX module.
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.
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. |
void CryptoCC26XX_Params_init | ( | CryptoCC26XX_Params * | params | ) |
Function to initialize the CryptoCC26XX_Params struct to its defaults.
Defaults values are: timeout = BIOS_WAIT_FOREVER;
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.
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 try 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.
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. |
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.
handle | A CryptoCC26XX_Handle returned by CryptoCC26XX_open(). |
keyIndex | A pointer to the keyIndex to be released. |
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.
handle | A CryptoCC26XX_Handle returned by CryptoCC26XX_open(). |
transaction | Pointer to a transaction descriptor. |
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.
handle | An CryptoCC26XX_Handle returned by CryptoCC26XX_open(). |
transaction | Pointer to a transaction descriptor. |
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.
handle | An CryptoCC26XX_Handle returned by CryptoCC26XX_open(). |
transaction | Pointer to a transaction descriptor. |