ADuCM302x Device Drivers API Reference Manual  Release 3.1.2.0
Crypto Driver

Crypto Driver More...

Modules

 Static Configuration
 

Data Structures

struct  ADI_CRYPTO_TRANSACTION
 

Macros

#define ADI_CRYPTO_MEMORY_SIZE   (88u + ADI_SEM_SIZE)
 
#define ADI_CRYPTO_SHA_HASH_BYTES   (256u/8u)
 

Typedefs

typedef struct __ADI_CRYPTO_DEV_DATA_TYPE * ADI_CRYPTO_HANDLE
 

Enumerations

enum  ADI_CRYPTO_RESULT {
  ADI_CRYPTO_SUCCESS = 0,
  ADI_CRYPTO_ERR_ALREADY_INITIALIZED,
  ADI_CRYPTO_ERR_BAD_BUFFER,
  ADI_CRYPTO_ERR_BAD_CONFIG,
  ADI_CRYPTO_ERR_BAD_DEVICE_NUM,
  ADI_CRYPTO_ERR_BAD_DEV_HANDLE,
  ADI_CRYPTO_ERR_COMPUTE_ACTIVE,
  ADI_CRYPTO_ERR_DMA_BUS_FAULT,
  ADI_CRYPTO_ERR_DMA_INVALID_DESCR,
  ADI_CRYPTO_ERR_DMA_REGISTER,
  ADI_CRYPTO_ERR_DMA_UNKNOWN_ERROR,
  ADI_CRYPTO_ERR_INSUFFICIENT_MEM,
  ADI_CRYPTO_ERR_INVALID_PARAM,
  ADI_CRYPTO_ERR_INVALID_STATE,
  ADI_CRYPTO_ERR_SEMAPHORE_FAILED,
  ADI_CRYPTO_ERR_INVALID_KEY_SIZE
}
 
enum  ADI_CRYPTO_EVENT {
  ADI_CRYPTO_EVENT_STATUS_CBC_DONE,
  ADI_CRYPTO_EVENT_STATUS_CCM_DONE,
  ADI_CRYPTO_EVENT_STATUS_CMAC_DONE,
  ADI_CRYPTO_EVENT_STATUS_CTR_DONE,
  ADI_CRYPTO_EVENT_STATUS_ECB_DONE,
  ADI_CRYPTO_RESERVED_EVENT,
  ADI_CRYPTO_EVENT_STATUS_SHA_DONE,
  ADI_CRYPTO_EVENT_DMA_BUS_ERROR,
  ADI_CRYPTO_EVENT_DMA_DESCRIPTOR_ERROR,
  ADI_CRYPTO_EVENT_DMA_UNKNOWN_ERROR,
  ADI_CRYPTO_EVENT_STATUS_INPUT_OVERFLOW,
  ADI_CRYPTO_EVENT_STATUS_UNKNOWN
}
 
enum  ADI_CRYPTO_CODING_MODE {
  ADI_CRYPTO_DECODE = (0u << BITP_CRYPT_CFG_ENCR),
  ADI_CRYPTO_ENCODE = (1u << BITP_CRYPT_CFG_ENCR)
}
 
enum  ADI_CRYPTO_AES_KEY_LEN {
  ADI_CRYPTO_AES_KEY_LEN_128_BIT = (0u << BITP_CRYPT_CFG_AESKEYLEN),
  ADI_CRYPTO_AES_KEY_LEN_256_BIT = (2u << BITP_CRYPT_CFG_AESKEYLEN)
}
 
enum  ADI_CRYPTO_AES_BYTE_SWAP {
  ADI_CRYPTO_AES_LITTLE_ENDIAN = (0u << BITP_CRYPT_CFG_AES_BYTESWAP),
  ADI_CRYPTO_AES_BIG_ENDIAN = (1u << BITP_CRYPT_CFG_AES_BYTESWAP)
}
 
enum  ADI_CRYPTO_CIPHER_MODE {
  ADI_CRYPTO_MODE_CBC = BITM_CRYPT_CFG_CBCEN,
  ADI_CRYPTO_MODE_CCM = BITM_CRYPT_CFG_CCMEN,
  ADI_CRYPTO_MODE_CMAC = BITM_CRYPT_CFG_CMACEN,
  ADI_CRYPTO_MODE_CTR = BITM_CRYPT_CFG_CTREN,
  ADI_CRYPTO_MODE_ECB = BITM_CRYPT_CFG_ECBEN,
  ADI_CRYPTO_MODE_SHA = BITM_CRYPT_CFG_SHA256EN
}
 

Functions

ADI_CRYPTO_RESULT adi_crypto_Open (uint32_t const nDeviceNum, void *const pMemory, uint32_t const nMemorySize, ADI_CRYPTO_HANDLE *const phDevice)
 Opens a Crypto device instance. More...
 
ADI_CRYPTO_RESULT adi_crypto_Close (ADI_CRYPTO_HANDLE const hDevice)
 Close the given device instance. More...
 
ADI_CRYPTO_RESULT adi_crypto_RegisterCallback (ADI_CRYPTO_HANDLE const hDevice, ADI_CALLBACK const pfCallback, void *const pCBParam)
 Register a user callback function. More...
 
ADI_CRYPTO_RESULT adi_crypto_Enable (ADI_CRYPTO_HANDLE const hDevice, bool const bEnable)
 Enable/Disable the device. Enabling the device causes the submitted buffer to be processed. More...
 
ADI_CRYPTO_RESULT adi_crypto_SubmitBuffer (ADI_CRYPTO_HANDLE const hDevice, ADI_CRYPTO_TRANSACTION *const pBuffer)
 Submit a Crypto transaction buffer for processing. More...
 
ADI_CRYPTO_RESULT adi_crypto_GetBuffer (ADI_CRYPTO_HANDLE const hDevice, ADI_CRYPTO_TRANSACTION **const ppBuffer)
 Get the submitted transaction buffer back from the driver. More...
 
ADI_CRYPTO_RESULT adi_crypto_IsBufferAvailable (ADI_CRYPTO_HANDLE const hDevice, bool *const pbAvailable)
 Peek function to know whether a submitted transaction is complete. More...
 

Detailed Description

Crypto Driver

The Crypto controller provides hardware acceleration of various AES cryptographic cipher modes, including: ECB, CBC, CTR, CMAC, CCM, SHA-256 and Keyed HMAC; as well as Protected Key Storage (PKSTOR) operations for safely storing and using encrypted keys. The Crypto block works most efficiently in DMA mode due to the large about of data I/O which would otherwise incur a lot of PIO-mode interrupt traffic to manually pump data.

Crypto Driver Static Configuration

A number of Crypto cipher modes are able to be configured statically, such that if particular mode(s) are not required, the resulting driver footprint can be reduced internally by blocking out chunks of code that are not needed.

Note
- The application must include drivers/crypto/adi_crypto.h to use this driver.
- This driver optionally uses the DMA driver if DMA is selected and active. In this case, the application must include the DMA driver sources to resolve DMA symbols.
- This documentation presented here is API documentation only. The device drive user's guide, located in the Documents folder, explains how to use these APIs in an application.

Macro Definition Documentation

◆ ADI_CRYPTO_MEMORY_SIZE

#define ADI_CRYPTO_MEMORY_SIZE   (88u + ADI_SEM_SIZE)

The amount of application supplied memory used by the CRYPTO driver to store internal state. Required user memory size for ADuCM302x processor family.

Definition at line 134 of file adi_crypto.h.

Referenced by adi_crypto_Open().

◆ ADI_CRYPTO_SHA_HASH_BYTES

#define ADI_CRYPTO_SHA_HASH_BYTES   (256u/8u)

Number of bytes to allocate for SHA256 hash outputs

Definition at line 144 of file adi_crypto.h.

Typedef Documentation

◆ ADI_CRYPTO_HANDLE

typedef struct __ADI_CRYPTO_DEV_DATA_TYPE* ADI_CRYPTO_HANDLE

A device handle used in all API functions to identify the flash device.

Definition at line 140 of file adi_crypto.h.

Enumeration Type Documentation

◆ ADI_CRYPTO_RESULT

Crypto API return codes

Enumerator
ADI_CRYPTO_SUCCESS 

No Error, API suceeded.

ADI_CRYPTO_ERR_ALREADY_INITIALIZED 

Crypto is already initialized.

ADI_CRYPTO_ERR_BAD_BUFFER 

Invalid buffer parameters.

ADI_CRYPTO_ERR_BAD_CONFIG 

Invalid device config parameters passed.

ADI_CRYPTO_ERR_BAD_DEVICE_NUM 

Invalid device instance number.

ADI_CRYPTO_ERR_BAD_DEV_HANDLE 

Invalid device handle passed.

ADI_CRYPTO_ERR_COMPUTE_ACTIVE 

Computation underway.

ADI_CRYPTO_ERR_DMA_BUS_FAULT 

Runtime DMA bus fault detected.

ADI_CRYPTO_ERR_DMA_INVALID_DESCR 

Runtime DMA invalid descriptor detected.

ADI_CRYPTO_ERR_DMA_REGISTER 

Error registering DMA error callback function.

ADI_CRYPTO_ERR_DMA_UNKNOWN_ERROR 

Unknown runtime DMA error detected.

ADI_CRYPTO_ERR_INSUFFICIENT_MEM 

Insufficient memory passed to the driver.

ADI_CRYPTO_ERR_INVALID_PARAM 

Invalid function parameter.

ADI_CRYPTO_ERR_INVALID_STATE 

Operation failed since the device is in an invalid state.

ADI_CRYPTO_ERR_SEMAPHORE_FAILED 

Failure in semaphore functions.

ADI_CRYPTO_ERR_INVALID_KEY_SIZE 

bad key size fault detected.

Definition at line 69 of file adi_crypto.h.

◆ ADI_CRYPTO_EVENT

Crypto callback events

Enumerator
ADI_CRYPTO_EVENT_STATUS_CBC_DONE 

CBC operation is complete.

ADI_CRYPTO_EVENT_STATUS_CCM_DONE 

CCM operation is complete.

ADI_CRYPTO_EVENT_STATUS_CMAC_DONE 

CMAC operation is complete.

ADI_CRYPTO_EVENT_STATUS_CTR_DONE 

CTR operation is complete.

ADI_CRYPTO_EVENT_STATUS_ECB_DONE 

ECB operation is complete.

ADI_CRYPTO_RESERVED_EVENT 

reserved: preserves ordering

ADI_CRYPTO_EVENT_STATUS_SHA_DONE 

SHA operation is complete.

ADI_CRYPTO_EVENT_DMA_BUS_ERROR 

DMA bus error encountered.

ADI_CRYPTO_EVENT_DMA_DESCRIPTOR_ERROR 

DMA descriptor error encountered.

ADI_CRYPTO_EVENT_DMA_UNKNOWN_ERROR 

DMA unknown error encountered.

ADI_CRYPTO_EVENT_STATUS_INPUT_OVERFLOW 

Input overflow error encountered.

ADI_CRYPTO_EVENT_STATUS_UNKNOWN 

Unknown error encountered.

Definition at line 103 of file adi_crypto.h.

◆ ADI_CRYPTO_CODING_MODE

Computation mode(Encryption/Decryption) for given buffers

Enumerator
ADI_CRYPTO_DECODE 

Encoding mode is decryption.

ADI_CRYPTO_ENCODE 

Encoding mode is encryption.

Definition at line 152 of file adi_crypto.h.

◆ ADI_CRYPTO_AES_KEY_LEN

Enum for the AES KEY Length

Enumerator
ADI_CRYPTO_AES_KEY_LEN_128_BIT 

KEY length is 128 bits.

ADI_CRYPTO_AES_KEY_LEN_256_BIT 

KEY length is 256 bits.

Definition at line 159 of file adi_crypto.h.

◆ ADI_CRYPTO_AES_BYTE_SWAP

Byte-swap the AES Input Data

Enumerator
ADI_CRYPTO_AES_LITTLE_ENDIAN 

Do not apply AES data write byte swaps.

ADI_CRYPTO_AES_BIG_ENDIAN 

Apply AES data write byte swaps.

Definition at line 184 of file adi_crypto.h.

◆ ADI_CRYPTO_CIPHER_MODE

Enum for the cipher modes.

Enumerator
ADI_CRYPTO_MODE_CBC 

Select CBC cipher mode.

ADI_CRYPTO_MODE_CCM 

Select CCM cipher mode.

ADI_CRYPTO_MODE_CMAC 

Select CMAC cipher mode.

ADI_CRYPTO_MODE_CTR 

Select CTR cipher mode.

ADI_CRYPTO_MODE_ECB 

Select ECB cipher mode.

ADI_CRYPTO_MODE_SHA 

Select SHA cipher mode.

Definition at line 194 of file adi_crypto.h.

Function Documentation

◆ adi_crypto_Open()

ADI_CRYPTO_RESULT adi_crypto_Open ( uint32_t const  nDeviceNum,
void *const  pMemory,
uint32_t const  nMemorySize,
ADI_CRYPTO_HANDLE *const  phDevice 
)

Opens a Crypto device instance.

Parameters
[in]nDeviceNumDevice number to open.
[in]pMemoryPointer to a ADI_CRYPTO_MEMORY_SIZE sized buffer to manage the device instance.
[in]nMemorySizeSize of the buffer to which "pMemory" points.
[out]phDevicePointer to a location where the Crypto device handle is to be written.
Returns
Status
See also
adi_crypto_Close().

Definition at line 426 of file adi_crypto.c.

◆ adi_crypto_Close()

ADI_CRYPTO_RESULT adi_crypto_Close ( ADI_CRYPTO_HANDLE const  hDevice)

Close the given device instance.

Parameters
[in]hDeviceHandle to the device instance.
Returns
Status
See also
adi_crypto_Open().

Definition at line 511 of file adi_crypto.c.

Referenced by adi_crypto_Open().

◆ adi_crypto_RegisterCallback()

ADI_CRYPTO_RESULT adi_crypto_RegisterCallback ( ADI_CRYPTO_HANDLE const  hDevice,
ADI_CALLBACK const  pfCallback,
void *const  pCBParam 
)

Register a user callback function.

Parameters
[in]hDeviceHandle to the device instance.
[in]pfCallbackFunction pointer to user callback function. Passing a NULL pointer will unregister the callback function.
[in]pCBParamCallback function parameter.

This function registers a user callback function. The registered function will be called when the given computation is over. Registering an active user callback function implies use of the (non-blocking) CALLBACK mode during which any subsequent calls to the (blocking-mode) adi_crypto_GetBuffer() API will be rejected.

Returns
Status

Definition at line 563 of file adi_crypto.c.

◆ adi_crypto_Enable()

ADI_CRYPTO_RESULT adi_crypto_Enable ( ADI_CRYPTO_HANDLE const  hDevice,
bool const  bEnable 
)

Enable/Disable the device. Enabling the device causes the submitted buffer to be processed.

Parameters
[in]hDeviceHandle to the device instance.
[in]bEnable'true' to enable and 'false' to disable the device.
Returns
Status

Definition at line 767 of file adi_crypto.c.

Referenced by adi_crypto_Close().

◆ adi_crypto_SubmitBuffer()

ADI_CRYPTO_RESULT adi_crypto_SubmitBuffer ( ADI_CRYPTO_HANDLE const  hDevice,
ADI_CRYPTO_TRANSACTION *const  pBuffer 
)

Submit a Crypto transaction buffer for processing.

Parameters
[in]hDeviceHandle to the device instance.
[in]pBufferPointer to the ADI_CRYPTO_TRANSACTION structure which contains details of the cipher-dependent buffer elements required by the driver.
Returns
Status

The buffer submitted is queued for eventual CRYPTO processing. A single buffer may be submitted prior to initiating CRYPTO buffer processing. Buffer processing is initiated with the adi_crypto_Enable() call. As buffer processing is completed, the buffer (and result info) is retrieved with the adi_crypto_GetBuffer() API or through the user callback notification.

Note
The driver takes ownership of the ADI_CRYPTO_TRANSACTION structure passed to the driver. The application must insure the structure is not used and its scope is valid until the structure is returned back to the application.
Warning
The ADI_CRYPTO_TRANSACTION buffer is a common superset of all possible cipher mode parameters. As such, not all parameters pertain to each cipher mode. It is recommended users clear unused parameters prior to configuration for the particular cipher mode. The example provided illustrates this with a call to: "memset(&Buffer, 0, sizeof(ADI_CRYPTO_TRANSACTION));" before configuring and then submitting each transaction.
See also
adi_crypto_Enable().
adi_crypto_GetBuffer().
adi_crypto_IsBufferAvailable().

Definition at line 616 of file adi_crypto.c.

◆ adi_crypto_GetBuffer()

ADI_CRYPTO_RESULT adi_crypto_GetBuffer ( ADI_CRYPTO_HANDLE const  hDevice,
ADI_CRYPTO_TRANSACTION **const  ppBuffer 
)

Get the submitted transaction buffer back from the driver.

Parameters
[in]hDeviceHandle to the device instance.
[out]ppBufferPointer to a location to which the address of the buffer structure is written.
Returns
Status

This is a blocking call and will await transaction completion (if not already). This function should not be called if a callback function is registered.

See also
adi_crypto_SubmitBuffer().
adi_crypto_IsBufferAvailable().

Definition at line 674 of file adi_crypto.c.

◆ adi_crypto_IsBufferAvailable()

ADI_CRYPTO_RESULT adi_crypto_IsBufferAvailable ( ADI_CRYPTO_HANDLE const  hDevice,
bool *const  pbAvailable 
)

Peek function to know whether a submitted transaction is complete.

Parameters
[in]hDeviceHandle to the device instance.
[in]pbAvailablePointer to a Boolean variable. Set to "true" if there is a completed buffer and a call to adi_crypto_GetBuffer is ensured to be successful. Set to "false" if there is no completed buffer.
Returns
Status
See also
adi_crypto_SubmitBuffer().
adi_crypto_GetBuffer().

Definition at line 728 of file adi_crypto.c.