![]() |
![]() |
TI-RTOS Drivers
tidrivers_full_2_20_01_10
|
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_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. Encryption of MAC |
CRYPTOCC26XX_OP_AES_CCM_DECRYPT | AES-CCM decryption of plaintext and authentication of AAD and plaintext |
CRYPTOCC26XX_OP_AES_CCM_DECRYPT_AAD_ONLY | AES-CCM authentication of AAD only. No payload. Encryption of MAC |
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 |
Perform a crypto operation with AES-ECB in CRYPTOCC26XX_MODE_BLOCKING.
Perform a crypto and authentication operation with AES-CCM 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_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 |
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... | |
#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 authentication 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 authentication 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 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.
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:
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.
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:
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 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.
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. |
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(). The function blocks the task calling it until the crypto hardware is available.
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. |
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. |