TI-RTOS Drivers
tidrivers_cc13xx_cc26xx_2_16_01_13
|
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/drivers/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, 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:
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:
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. |