Detailed Description

Crypto driver implementation for a CC32XX Crypto controller.

============================================================================

The Crypto header file should be included in an application as follows:

#include <ti/drivers/crypto/CryptoCC32XX.h>

Operation

The CryptoCC32XX driver is used several security methods (AES, DES and HMAC Hash functions). This driver provides API for encrypt/decrypt (AES and DES) and sign/verify (HMAC hash)

The application initializes the CryptoCC32XX driver by calling CryptoCC32XX_init() and is then ready to open a Crypto by calling CryptoCC32XX_open().

The APIs in this driver serve as an interface to a typical TI-RTOS application. The specific peripheral implementations are responsible to create all the OSAL specific primitives to allow for thread-safe operation.

Opening the driver

CryptoCC32XX_Handle      handle;
handle = CryptoCC32XX_open(CryptoCC32XX_configIndexValue,   CryptoCC32XX_AES |
                                                            CryptoCC32XX_DES |
                                                            CryptoCC32XX_HMAC);
if (!handle) {
    System_printf("CryptoCC32XX did not open");
}

AES data encryption

CryptoCC32XX_EncryptMethod  method = desiredMethod;
CryptoCC32XX_Params         params;
unsigned char               plainData[16] = "whatsoever123456";
unsigned int                plainDataLen = sizeof(plainData);
unsigned char               cipherData[16];
unsigned int                cipherDataLen;
params.aes.keySize = desiredKeySize;
params.aes.pKey = (CryptoCC32XX_KeyPtr)desiredKey; // desiredKey length should be as the desiredKeySize
params.aes.pIV = (void *)pointerToInitVector;
ret = CryptoCC32XX_encrypt(handle, method , plainData, plainDataLen, cipherData , &cipherDataLen , &params);

Generate HMAC Hash signature

CryptoCC32XX_HmacMethod hmacMethod = desiredHmacMethod;
CryptoCC32XX_Params     params;
unsigned char           dataBuff[] = "whatsoever";
unsigned int            dataLength = sizeof(dataBuff);
unsigned char           signatureBuff[32];
params.pKey = pointerToHMACkey;
params.moreData = 0;
ret = CryptoCC32XX_sign(handle, hmacMethod , &dataBuff, dataLength, &signatureBuff, &params);

Implementation

The CryptoCC32XX driver interface module is joined (at link time) to a NULL-terminated array of CryptoCC32XX_Config data structures named CryptoCC32XX_config. CryptoCC32XX_config is implemented in the application with each entry being an instance of a CryptoCC32XX peripheral. Each entry in CryptoCC32XX_config contains a:

(void *) data object that is pointed to CryptoCC32XX_Object

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
#include <ti/drivers/dpl/HwiP.h>
#include <ti/drivers/dpl/SemaphoreP.h>

Include dependency graph for CryptoCC32XX.h:

Go to the source code of this file.

Data Structures
struct	CryptoCC32XX_AesAadInputParams
	AES Additional Authentication Data input parameters. More...

union	CryptoCC32XX_AesAadParams
	AES Additional Authentication Data Parameters. More...

struct	CryptoCC32XX_AesParams
	AES Parameters. More...

struct	CryptoCC32XX_DesParams
	DES Parameters. More...

union	CryptoCC32XX_EncryptParams
	Cryptography Parameters. More...

struct	CryptoCC32XX_HmacParams
	HMAC Parameters. More...

struct	CryptoCC32XX_Config
	Crypto Global configuration. More...

struct	CryptoCC32XX_Object
	CryptoCC32XX Object. More...

Macros
#define	CryptoCC32XX_CMD_RESERVED 32

#define	CryptoCC32XX_STATUS_RESERVED -32

#define	CryptoCC32XX_STATUS_SUCCESS 0
	Successful status code returned by Crypto Common functions. More...

#define	CryptoCC32XX_STATUS_ERROR -1
	Generic error status code returned by Crypto Common functions. More...

#define	CryptoCC32XX_STATUS_UNDEFINEDCMD -2
	An error status code returned by Crypto Common functions for undefined command codes. More...

#define	CryptoCC32XX_STATUS_ERROR_VERIFY -3
	An error status code returned by CryptoCC32XX_verify for define error in verifying a given Hash value. More...

#define	CryptoCC32XX_STATUS_ERROR_NOT_SUPPORTED -4
	An error status code returned by Crypto Common functions for define cryptographic type not supported. More...

#define	CryptoCC32XX_MAX_TYPES 3

#define	CryptoCC32XX_MD5_BLOCK_SIZE 64

#define	CryptoCC32XX_SHA1_BLOCK_SIZE 64

#define	CryptoCC32XX_SHA256_BLOCK_SIZE 64

#define	CryptoCC32XX_MD5_DIGEST_SIZE 16

#define	CryptoCC32XX_SHA1_DIGEST_SIZE 20

#define	CryptoCC32XX_SHA256_DIGEST_SIZE 32

#define	CryptoCC32XX_MAX_DIGEST_SIZE CryptoCC32XX_SHA256_DIGEST_SIZE

#define	CryptoCC32XX_MAX_BLOCK_SIZE CryptoCC32XX_SHA256_BLOCK_SIZE

Typedefs
typedef CryptoCC32XX_Config *	CryptoCC32XX_Handle
	A handle that is returned from a CryptoCC32XX_open() call. More...

Enumerations
enum	CryptoCC32XX_Type { CryptoCC32XX_AES = 0x01, CryptoCC32XX_DES = 0x02, CryptoCC32XX_HMAC = 0x04 }
	Cryptography types configuration. More...

enum	CryptoCC32XX_EncryptMethod { CryptoCC32XX_AES_ECB = (CryptoCC32XX_AES << 8) \| 1, CryptoCC32XX_AES_CBC, CryptoCC32XX_AES_CTR, CryptoCC32XX_AES_ICM, CryptoCC32XX_AES_CFB, CryptoCC32XX_AES_GCM, CryptoCC32XX_AES_CCM, CryptoCC32XX_DES_ECB = (CryptoCC32XX_DES << 8) \| 1, CryptoCC32XX_DES_CBC, CryptoCC32XX_DES_CFB }
	AES and DES Cryptography methods configuration Keep the Crypto method in the lower 8 bit and Crypto type in the upper 8 bits. More...

enum	CryptoCC32XX_HmacMethod { CryptoCC32XX_HMAC_MD5 = (CryptoCC32XX_HMAC << 8) \| 1, CryptoCC32XX_HMAC_SHA1, CryptoCC32XX_HMAC_SHA224, CryptoCC32XX_HMAC_SHA256 }
	HMAC Cryptography methods configuration Keep the Crypto method in the lower 8 bit and Crypto type in the upper 8 bits. More...

enum	CryptoCC32XX_AesKeySize { CryptoCC32XX_AES_KEY_SIZE_128BIT, CryptoCC32XX_AES_KEY_SIZE_192BIT, CryptoCC32XX_AES_KEY_SIZE_256BIT }
	AES Cryptography key size type configuration. More...

enum	CryptoCC32XX_DesKeySize { CryptoCC32XX_DES_KEY_SIZE_SINGLE, CryptoCC32XX_DES_KEY_SIZE_TRIPLE }
	DES Cryptography key size type configuration. More...

Functions
void	CryptoCC32XX_close (CryptoCC32XX_Handle handle)
	Function to close a given Crypto peripheral specified by the Crypto handle. More...

void	CryptoCC32XX_init (void)
	Function to initializes the Crypto module. More...

CryptoCC32XX_Handle	CryptoCC32XX_open (uint32_t index, uint32_t types)
	Opens a Crypto object with a given index and returns a CryptoCC32XX_Handle. More...

void	CryptoCC32XX_HmacParams_init (CryptoCC32XX_HmacParams *params)
	Initialize params structure to default values. More...

int32_t	CryptoCC32XX_encrypt (CryptoCC32XX_Handle handle, CryptoCC32XX_EncryptMethod method, void pInBuff, size_t inLen, void pOutBuff, size_t outLen, CryptoCC32XX_EncryptParams pParams)
	Function which encrypt given data by a given AES or DES method. relevant to CryptoCC32XX_AES and CryptoCC32XX_DES. More...

int32_t	CryptoCC32XX_decrypt (CryptoCC32XX_Handle handle, CryptoCC32XX_EncryptMethod method, void pInBuff, size_t inLen, void pOutBuff, size_t outLen, CryptoCC32XX_EncryptParams pParams)
	Function which decrypt given cipher data by a given AES or DES method. relevant to CryptoCC32XX_AES and CryptoCC32XX_DES. More...

int32_t	CryptoCC32XX_sign (CryptoCC32XX_Handle handle, CryptoCC32XX_HmacMethod method, void pBuff, size_t len, uint8_t pSignature, CryptoCC32XX_HmacParams *pParams)
	Function which generates the HMAC Hash value of given plain Text. relevant to CryptoCC32XX_HMAC. More...

int32_t	CryptoCC32XX_verify (CryptoCC32XX_Handle handle, CryptoCC32XX_HmacMethod method, void pBuff, size_t len, uint8_t pSignature, CryptoCC32XX_HmacParams *pParams)
	Function which verify a given Hash value on given plain Text. relevant to CryptoCC32XX_HMAC. More...

Macro Definition Documentation

§ CryptoCC32XX_CMD_RESERVED

#define CryptoCC32XX_CMD_RESERVED 32

§ CryptoCC32XX_STATUS_RESERVED

#define CryptoCC32XX_STATUS_RESERVED -32

§ CryptoCC32XX_STATUS_SUCCESS

#define CryptoCC32XX_STATUS_SUCCESS 0

Successful status code returned by Crypto Common functions.

§ CryptoCC32XX_STATUS_ERROR

#define CryptoCC32XX_STATUS_ERROR -1

Generic error status code returned by Crypto Common functions.

§ CryptoCC32XX_STATUS_UNDEFINEDCMD

#define CryptoCC32XX_STATUS_UNDEFINEDCMD -2

An error status code returned by Crypto Common functions for undefined command codes.

§ CryptoCC32XX_STATUS_ERROR_VERIFY

#define CryptoCC32XX_STATUS_ERROR_VERIFY -3

An error status code returned by CryptoCC32XX_verify for define error in verifying a given Hash value.

§ CryptoCC32XX_STATUS_ERROR_NOT_SUPPORTED

#define CryptoCC32XX_STATUS_ERROR_NOT_SUPPORTED -4

An error status code returned by Crypto Common functions for define cryptographic type not supported.

§ CryptoCC32XX_MAX_TYPES

#define CryptoCC32XX_MAX_TYPES 3

§ CryptoCC32XX_MD5_BLOCK_SIZE

#define CryptoCC32XX_MD5_BLOCK_SIZE 64

§ CryptoCC32XX_SHA1_BLOCK_SIZE

#define CryptoCC32XX_SHA1_BLOCK_SIZE 64

§ CryptoCC32XX_SHA256_BLOCK_SIZE

#define CryptoCC32XX_SHA256_BLOCK_SIZE 64

§ CryptoCC32XX_MD5_DIGEST_SIZE

#define CryptoCC32XX_MD5_DIGEST_SIZE 16

§ CryptoCC32XX_SHA1_DIGEST_SIZE

#define CryptoCC32XX_SHA1_DIGEST_SIZE 20

§ CryptoCC32XX_SHA256_DIGEST_SIZE

#define CryptoCC32XX_SHA256_DIGEST_SIZE 32

§ CryptoCC32XX_MAX_DIGEST_SIZE

#define CryptoCC32XX_MAX_DIGEST_SIZE CryptoCC32XX_SHA256_DIGEST_SIZE

§ CryptoCC32XX_MAX_BLOCK_SIZE

#define CryptoCC32XX_MAX_BLOCK_SIZE CryptoCC32XX_SHA256_BLOCK_SIZE

Typedef Documentation

§ CryptoCC32XX_Handle

typedef CryptoCC32XX_Config* CryptoCC32XX_Handle

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

Enumeration Type Documentation

§ CryptoCC32XX_Type

enum CryptoCC32XX_Type

Cryptography types configuration.

This enum defines bitwise Cryptography types.

Enumerator
CryptoCC32XX_AES	Advanced Encryption Standard
CryptoCC32XX_DES	Data Encryption Standard
CryptoCC32XX_HMAC	Cryptographic hash function

§ CryptoCC32XX_EncryptMethod

enum CryptoCC32XX_EncryptMethod

AES and DES Cryptography methods configuration Keep the Crypto method in the lower 8 bit and Crypto type in the upper 8 bits.

This enum defines the AES and DES Cryptography modes.

Enumerator
CryptoCC32XX_AES_ECB	AES Electronic CodeBook
CryptoCC32XX_AES_CBC	AES Cipher Block Chaining
CryptoCC32XX_AES_CTR	AES Counter
CryptoCC32XX_AES_ICM	AES Integer Counter Mode
CryptoCC32XX_AES_CFB	AES Cipher FeedBack
CryptoCC32XX_AES_GCM	AES Galois/Counter Mode
CryptoCC32XX_AES_CCM	AES Counter with CBC-MAC Mode
CryptoCC32XX_DES_ECB	DES Electronic CodeBook
CryptoCC32XX_DES_CBC	DES Cipher Block Chaining
CryptoCC32XX_DES_CFB	DES Cipher FeedBack

§ CryptoCC32XX_HmacMethod

enum CryptoCC32XX_HmacMethod

HMAC Cryptography methods configuration Keep the Crypto method in the lower 8 bit and Crypto type in the upper 8 bits.

This enum defines the HMAC HASH algorithms modes.

Enumerator
CryptoCC32XX_HMAC_MD5	MD5 used keyed-hash message authentication code
CryptoCC32XX_HMAC_SHA1	SHA1 used keyed-hash message authentication code
CryptoCC32XX_HMAC_SHA224	SHA224 used keyed-hash message authentication code
CryptoCC32XX_HMAC_SHA256	SHA256 used keyed-hash message authentication code

§ CryptoCC32XX_AesKeySize

enum CryptoCC32XX_AesKeySize

AES Cryptography key size type configuration.

This enum defines the AES key size types

Enumerator
CryptoCC32XX_AES_KEY_SIZE_128BIT
CryptoCC32XX_AES_KEY_SIZE_192BIT
CryptoCC32XX_AES_KEY_SIZE_256BIT

§ CryptoCC32XX_DesKeySize

enum CryptoCC32XX_DesKeySize

DES Cryptography key size type configuration.

This enum defines the DES key size types

Enumerator
CryptoCC32XX_DES_KEY_SIZE_SINGLE
CryptoCC32XX_DES_KEY_SIZE_TRIPLE

Function Documentation

§ CryptoCC32XX_close()

void CryptoCC32XX_close ( CryptoCC32XX_Handle handle )

Function to close a given Crypto peripheral specified by the Crypto handle.

Precondition: CryptoCC32XX_open() had to be called first.

Parameters

handle A CryptoCC32XX_Handle returned from CryptoCC32XX_open

See also: CryptoCC32XX_open()

§ CryptoCC32XX_init()

void CryptoCC32XX_init ( void )

Function to initializes the Crypto module.

Precondition: The CryptoCC32XX_Config structure must exist and be persistent before this function can be called. This function must also be called before any other Crypto driver APIs. This function call does not modify any peripheral registers.

§ CryptoCC32XX_open()

CryptoCC32XX_Handle CryptoCC32XX_open	(	uint32_t	index,
		uint32_t	types
	)

Opens a Crypto object with a given index and returns a CryptoCC32XX_Handle.

Precondition: Crypto module has been initialized

Parameters

index	Logical peripheral number for the Crypto indexed into the CryptoCC32XX_config table
types	Define bitwise Crypto Types to support

Returns: A CryptoCC32XX_Handle on success or a NULL on an error or if it has been opened already.

See also: CryptoCC32XX_init(); CryptoCC32XX_HmacParams_init(); CryptoCC32XX_close()

§ CryptoCC32XX_HmacParams_init()

void CryptoCC32XX_HmacParams_init ( CryptoCC32XX_HmacParams * params )

Initialize params structure to default values.

The default parameters are:

pKey: 0
moreData: 0
*pContext: 0
first: 1
digestCount: 0
innerDigest: 0
buff: 0
buffLen: 0
blockSize: CryptoCC32XX_SHA256_BLOCK_SIZE

Parameters

params Pointer to the instance configuration parameters.

§ CryptoCC32XX_encrypt()

int32_t CryptoCC32XX_encrypt	(	CryptoCC32XX_Handle	handle,
		CryptoCC32XX_EncryptMethod	method,
		void *	pInBuff,
		size_t	inLen,
		void *	pOutBuff,
		size_t *	outLen,
		CryptoCC32XX_EncryptParams *	pParams
	)

Function which encrypt given data by a given AES or DES method. relevant to CryptoCC32XX_AES and CryptoCC32XX_DES.

Parameters

handle	A CryptoCC32XX_Handle
method	An AES or DES encryption method to use on a given plain data.
pInBuff	Pointer to plain data to encrypt.
inLen	Size of plain data to encrypt.
pOutBuff	Pointer to encrypted data (cipher text).
outLen	Size of encrypted data.
pParams	Specific parameters according to Crypto Type (AES or DES).

Returns: Returns CryptoCC32XX_STATUS_SUCCESS if successful else would return CryptoCC32XX_STATUS_ERROR on an error.

See also: CryptoCC32XX_open()

§ CryptoCC32XX_decrypt()

int32_t CryptoCC32XX_decrypt	(	CryptoCC32XX_Handle	handle,
		CryptoCC32XX_EncryptMethod	method,
		void *	pInBuff,
		size_t	inLen,
		void *	pOutBuff,
		size_t *	outLen,
		CryptoCC32XX_EncryptParams *	pParams
	)

Function which decrypt given cipher data by a given AES or DES method. relevant to CryptoCC32XX_AES and CryptoCC32XX_DES.

Parameters

handle	A CryptoCC32XX_Handle
method	An AES or DES decryption method to use on a given cipher data.
pInBuff	Pointer to cipher data to decrypt.
inLen	Size of cipher data to decrypt.
pOutBuff	Pointer to decrypted data (plain text).
outLen	Size of decrypted data.
pParams	Specific parameters according to Crypto Type (AES or DES).

Returns: Returns CryptoCC32XX_STATUS_SUCCESS if successful else would return CryptoCC32XX_STATUS_ERROR on an error.

See also: CryptoCC32XX_open()

§ CryptoCC32XX_sign()

int32_t CryptoCC32XX_sign	(	CryptoCC32XX_Handle	handle,
		CryptoCC32XX_HmacMethod	method,
		void *	pBuff,
		size_t	len,
		uint8_t *	pSignature,
		CryptoCC32XX_HmacParams *	pParams
	)

Function which generates the HMAC Hash value of given plain Text. relevant to CryptoCC32XX_HMAC.

Parameters

handle	A CryptoCC32XX_Handle
method	HMAC Hash algorithm to use in order to generates the hash value
pBuff	Pointer to plain data.
len	Size of plain data.
pSignature	As input pointer to the given HMAC Hash value in case the HMAC flag was set and as output pointer for the generated Hash value.
pParams	Specific parameters according to HMAC algorithm

Returns: Returns CryptoCC32XX_STATUS_SUCCESS if successful else would return CryptoCC32XX_STATUS_ERROR on an error.

See also: CryptoCC32XX_open()

§ CryptoCC32XX_verify()

int32_t CryptoCC32XX_verify	(	CryptoCC32XX_Handle	handle,
		CryptoCC32XX_HmacMethod	method,
		void *	pBuff,
		size_t	len,
		uint8_t *	pSignature,
		CryptoCC32XX_HmacParams *	pParams
	)

Function which verify a given Hash value on given plain Text. relevant to CryptoCC32XX_HMAC.

Parameters

handle	A CryptoCC32XX_Handle
method	HMAC Hash algorithm to use in order to verify the hash value
pBuff	Pointer to plain data.
len	Size of plain data.
pSignature	As input pointer to the given HMAC Hash value in case the HMAC flag was set and as output pointer for the generated Hash value.
pParams	Specific parameters according to HMAC algorithm.

Returns: Returns CryptoCC32XX_STATUS_SUCCESS if value was successfully verified else would return CryptoCC32XX_STATUS_ERROR.

See also: CryptoCC32XX_open()

Detailed Description

Operation

Opening the driver

AES data encryption

Generate HMAC Hash signature

Implementation

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

§ CryptoCC32XX_CMD_RESERVED

§ CryptoCC32XX_STATUS_RESERVED

§ CryptoCC32XX_STATUS_SUCCESS

§ CryptoCC32XX_STATUS_ERROR

§ CryptoCC32XX_STATUS_UNDEFINEDCMD

§ CryptoCC32XX_STATUS_ERROR_VERIFY

§ CryptoCC32XX_STATUS_ERROR_NOT_SUPPORTED

§ CryptoCC32XX_MAX_TYPES

§ CryptoCC32XX_MD5_BLOCK_SIZE

§ CryptoCC32XX_SHA1_BLOCK_SIZE

§ CryptoCC32XX_SHA256_BLOCK_SIZE

§ CryptoCC32XX_MD5_DIGEST_SIZE

§ CryptoCC32XX_SHA1_DIGEST_SIZE

§ CryptoCC32XX_SHA256_DIGEST_SIZE

§ CryptoCC32XX_MAX_DIGEST_SIZE

§ CryptoCC32XX_MAX_BLOCK_SIZE

Typedef Documentation

§ CryptoCC32XX_Handle

Enumeration Type Documentation

§ CryptoCC32XX_Type

§ CryptoCC32XX_EncryptMethod

§ CryptoCC32XX_HmacMethod

§ CryptoCC32XX_AesKeySize

§ CryptoCC32XX_DesKeySize

Function Documentation

§ CryptoCC32XX_close()

§ CryptoCC32XX_init()

§ CryptoCC32XX_open()

§ CryptoCC32XX_HmacParams_init()

§ CryptoCC32XX_encrypt()

§ CryptoCC32XX_decrypt()

§ CryptoCC32XX_sign()

§ CryptoCC32XX_verify()