Overview

The MCUXpresso SDK provides the peripheral driver for the Cryptographic Acceleration and Assurance Module (CAAM) module. CAAM is a multi-functional accelerator that supports the cryptographic functions common in many security protocols. This includes AES128, AES256, DES, 3DES, SHA1, SHA224, SHA256, RSA-4096, and a random number generator with a true entropic seed. CAAM includes a DMA engine that is descriptor-based to reduce processor-accelerator interaction.

The driver comprises two sets of API functions.

In the first set, blocking APIs are provided for the selected subset of operations supported by CAAM hardware. The CAAM operations are complete, and results are made availabe for further usage, when a function returns. When called, these functions do not return until a CAAM operation is complete. These functions use main CPU for simple polling loops to determine operation complete or error status.

The CAAM job descriptor is placed on the system stack during the blocking API calls. The driver uses global variable to manage the input and output job rings. The driver uses critical section (implemented as global interrupt enable/disable) for a short time, whenever it needs to access these global variables. Therefore, the driver functions are designed to be re-entrant and as a consequence, one CPU thread can call one blocking API, such as AES Encrypt, while other CPU thread can call another blocking API, such as SHA-256 Update. The blocking functions provide typical interface to upper layer or application software.

In the second set, non-blocking variants of the first set APIs are provided. Internally, the blocking APIs are implemented as a non-blocking operation start, followed by a blocking wait (CPU polling CAAM output job ring). for an operation completion. The non-blocking functions allow upper layer to inject an application specific operation after the CAAM job start and CAAM job complete events. The RTOS event wait and RTOS event set can be an example of such an operation.

CAAM Driver Initialization and Configuration

The CAAM Job Ring interface is a software job programming interface. CAAM implements 2 Job Ring interfaces. The CAAM driver uses caam_job_ring_interface_t data type as the Job Ring interface. Job Ring interface 0 is mandatory to be configured for the CAAM driver, Job Ring interface 1 is optional.

Initialize CAAM after Power On Reset or reset cycle See the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/caam.

The CAAM Driver is initialized by calling the CAAM_Init() function. It enables the CAAM module clock, it configures the Job Ring interface(s) and instantiates the CAAM RNG module in normal (non-deterministic) mode. Then, it calls CAAM_RNG_GenerateSecureKey() to load the JDKEK, TDKEK, and TDSK registers and finally configures the CAAM SCFGR register.

Comments about API usage in RTOS

CAAM operations provided by this driver are re-entrant by protecting global variables (Job Ring interface) in critical section (global interrupt enable/disable by EnableGlobalIRQ() and DisableGlobalIRQ() MCUXpresso SDK APIs). If required, different RTOS threads can call CAAM driver APIs simultaneously, given that EnableGlobalIRQ() and DisableGlobalIRQ() can a create critical section.

Comments about API usage in interrupt handler

All APIs can be used from interrupt handler although execution time should be considered (interrupt latency of equal and lower priority interrupts increases).

CAAM Driver Examples

Simple examples

Encrypt plaintext by DES engine Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/caam Encrypt plaintext by AES engine Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/caam Compute keyed hash by AES engine (CMAC) Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/caam Compute hash by MDHA engine (SHA-256) Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/caam Compute modular integer exponentiation Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/caam Compute elliptic curve point addition Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/caam