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.
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_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.
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. |
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 |
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 <ti/devices/DeviceFamily.h>
#include <DeviceFamily_constructPath(driverlib/crypto.h)>
#include <ti/drivers/dpl/HwiP.h>
#include <ti/drivers/dpl/SemaphoreP.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 |
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... | |
#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 and verification of both
#define CRYPTOCC26XX_OP_AES_CCM_DECRYPT_AAD_ONLY 3 |
AES-CCM verification 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 |
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. 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:
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.
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 initialize CryptoCC26XX driver. Users of this module must call init(). Multiple users/libraries may call init(), though subsequent calls may be benign.
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. 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. |
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.
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.
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(). 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.
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. |