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).

Comments about DCACHE

Usually the output data are not cached, because CAAM driver cleans them before scheduling job and invalidate after that, but in some cases the computing can take longer time and data could be written to memory by CAAM after invalidate happen, so it's recommended to invalidate CAAM output data again, right before their usage.

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

Modules
	CAAM Blocking APIs

	CAAM Non-blocking APIs

Data Structures
struct	caam_job_callback_t
	CAAM callback function. More...

struct	caam_handle_t
	CAAM handle Specifies jobRing and optionally the user callback function. More...

struct	caam_config_t
	CAAM configuration structure. More...

Typedefs
typedef uint32_t	caam_desc_aes_ecb_t [64]
	Memory buffer to hold CAAM descriptor for AESA ECB job.

typedef uint32_t	caam_desc_aes_cbc_t [64]
	Memory buffer to hold CAAM descriptor for AESA CBC job.

typedef uint32_t	caam_desc_aes_ctr_t [64]
	Memory buffer to hold CAAM descriptor for AESA CTR job.

typedef uint32_t	caam_desc_aes_ccm_t [64]
	Memory buffer to hold CAAM descriptor for AESA CCM job.

typedef uint32_t	caam_desc_aes_gcm_t [64]
	Memory buffer to hold CAAM descriptor for AESA GCM job.

typedef uint32_t	caam_desc_hash_t [64]
	Memory buffer to hold CAAM descriptor for MDHA job or AESA CMAC job.

typedef uint32_t	caam_desc_rng_t [64]
	Memory buffer to hold CAAM descriptor for RNG jobs.

typedef uint32_t	caam_desc_cipher_des_t [64]
	Memory buffer to hold CAAM descriptor for DESA jobs.

typedef uint32_t	caam_desc_pkha_t [64]
	Memory buffer to hold CAAM descriptor for PKHA jobs.

typedef uint32_t	caam_desc_pkha_ecc_t [64]
	Memory buffer to hold CAAM descriptor for PKHA ECC jobs.

Enumerations
enum	{ kStatus_CAAM_Again = MAKE_STATUS(kStatusGroup_CAAM, 0), kStatus_CAAM_DataOverflow = MAKE_STATUS(kStatusGroup_CAAM, 1) }
	CAAM status return codes. More...

enum	caam_job_ring_t { kCAAM_JobRing0 = 0u, kCAAM_JobRing1 = 1u, kCAAM_JobRing2 = 2u, kCAAM_JobRing3 = 3u }
	CAAM job ring selection. More...

enum	caam_wait_mode_t { kCAAM_Blocking = 0u, kCAAM_Nonblocking = 1u }
	CAAM driver wait mechanism. More...

enum	caam_rng_sample_mode_t { kCAAM_RNG_SampleModeVonNeumann = 0U, kCAAM_RNG_SampleModeRaw = 1U, kCAAM_RNG_SampleModeVonNeumannRaw }
	CAAM RNG sample mode. More...

enum	caam_rng_ring_osc_div_t { kCAAM_RNG_RingOscDiv0 = 0U, kCAAM_RNG_RingOscDiv2 = 1U, kCAAM_RNG_RingOscDiv4 = 2U, kCAAM_RNG_RingOscDiv8 = 3U }
	CAAM RNG ring oscillator divide. More...

enum	caam_priblob_t { kCAAM_PrivSecureBootBlobs = 0U, kCAAM_PrivProvisioningBlobsType1 = 1U, kCAAM_PrivProvisioningBlobsType2 = 2U, kCAAM_NormalOperationBlobs = 3U }
	CAAM Private Blob. More...

enum	caam_ext_key_xfr_source_t { kCAAM_ExtKeyXfr_KeyRegisterClass1 = 1U, kCAAM_ExtKeyXfr_KeyRegisterClass2 = 2U, kCAAM_ExtKeyXfr_PkhaRamE = 3U }
	CAAM External Key Transfer command SRC (The source from which the key will be obtained) More...

Functions
status_t	CAAM_Init (CAAM_Type base, const caam_config_t config)
	Initializes the CAAM driver. More...

status_t	CAAM_Deinit (CAAM_Type *base)
	Deinitializes the CAAM driver. More...

void	CAAM_GetDefaultConfig (caam_config_t *config)
	Gets the default configuration structure. More...

status_t	CAAM_Wait (CAAM_Type base, caam_handle_t handle, uint32_t *descriptor, caam_wait_mode_t mode)
	Wait for a CAAM job to complete. More...

status_t	CAAM_ExternalKeyTransfer (CAAM_Type base, caam_handle_t handle, caam_ext_key_xfr_source_t keySource, size_t keySize)
	External Key Transfer. More...

Driver version
#define	FSL_CAAM_DRIVER_VERSION (MAKE_VERSION(2, 1, 5))
	CAAM driver version. More...

Data Structure Documentation

struct caam_job_callback_t

Data Fields
void(*	JobCompleted )(void *userData)
	CAAM Job complete callback.

struct caam_handle_t

The user callback functions is invoked only if jobRing interrupt has been enabled by the user. By default the jobRing interrupt is disabled (default job complete test is polling CAAM output ring).

Data Fields
caam_job_callback_t	callback
	Callback function.

void *	userData
	Parameter for CAAM job complete callback.

struct caam_config_t

Data Fields
caam_rng_sample_mode_t	rngSampleMode
	RTMCTL Sample Mode. More...

caam_rng_ring_osc_div_t	rngRingOscDiv
	RTMCTL Oscillator Divide. More...

bool	scfgrLockTrngProgramMode
	SCFGR Lock TRNG Program Mode. More...

bool	scfgrEnableRandomDataBuffer
	SCFGR Enable random data buffer. More...

bool	scfgrRandomRngStateHandle0
	SCFGR Random Number Generator State Handle 0. More...

bool	scfgrRandomDpaResistance
	SCFGR Random Differential Power Analysis Resistance. More...

caam_priblob_t	scfgrPriblob
	SCFGR Private Blob. More...

Field Documentation

caam_rng_sample_mode_t caam_config_t::rngSampleMode

caam_rng_ring_osc_div_t caam_config_t::rngRingOscDiv

bool caam_config_t::scfgrLockTrngProgramMode

bool caam_config_t::scfgrEnableRandomDataBuffer

bool caam_config_t::scfgrRandomRngStateHandle0

bool caam_config_t::scfgrRandomDpaResistance

caam_priblob_t caam_config_t::scfgrPriblob

Macro Definition Documentation

#define FSL_CAAM_DRIVER_VERSION (MAKE_VERSION(2, 1, 5))

Version 2.1.5.

Current version: 2.1.4

Change log:

Version 2.0.0
- Initial version
Version 2.0.1
- Add Job Ring 2 and 3.
Version 2.0.2
- Add Data and Instruction Synchronization Barrier in caam_input_ring_set_jobs_added() to make sure that the descriptor will be loaded into CAAM correctly.
Version 2.0.3
- Use MACRO instead of numbers in descriptor.
- Correct descriptor size mask.
Version 2.1.0
- Add return codes check and handling.
Version 2.1.1
- Add DCACHE support.
Version 2.1.2
- Add data offset feature to provide support for mirrored (high-speed) memory.
Version 2.1.3
- Fix MISRA-2012 issues.
Version 2.1.4
- Fix MISRA-2012 issues.
Version 2.1.5
- Support EXTENDED data size for all AES, HASH and RNG operations.
- Support multiple De-Initialization/Initialization of CAAM driver within one POR event.

Enumeration Type Documentation

anonymous enum

Enumerator
kStatus_CAAM_Again	Non-blocking function shall be called again.
kStatus_CAAM_DataOverflow	Input data too big.

enum caam_job_ring_t

Enumerator
kCAAM_JobRing0	CAAM Job ring 0.
kCAAM_JobRing1	CAAM Job ring 1.
kCAAM_JobRing2	CAAM Job ring 2.
kCAAM_JobRing3	CAAM Job ring 3.

enum caam_wait_mode_t

Enumerator
kCAAM_Blocking	CAAM_Wait blocking mode.
kCAAM_Nonblocking	CAAM Wait non-blocking mode.

enum caam_rng_sample_mode_t

Used by caam_config_t.

Enumerator

kCAAM_RNG_SampleModeVonNeumann

Use von Neumann data in both Entropy shifter and Statistical Checker.

kCAAM_RNG_SampleModeRaw

Use raw data into both Entropy shifter and Statistical Checker.

kCAAM_RNG_SampleModeVonNeumannRaw

Use von Neumann data in Entropy shifter.

Use raw data into Statistical Checker.

enum caam_rng_ring_osc_div_t

Used by caam_config_t.

Enumerator
kCAAM_RNG_RingOscDiv0	Ring oscillator with no divide.
kCAAM_RNG_RingOscDiv2	Ring oscillator divided-by-2.
kCAAM_RNG_RingOscDiv4	Ring oscillator divided-by-4.
kCAAM_RNG_RingOscDiv8	Ring oscillator divided-by-8.

enum caam_priblob_t

Used by caam_config_t.

Enumerator
kCAAM_PrivSecureBootBlobs	Private secure boot software blobs.
kCAAM_PrivProvisioningBlobsType1	Private Provisioning Type 1 blobs.
kCAAM_PrivProvisioningBlobsType2	Private Provisioning Type 2 blobs.
kCAAM_NormalOperationBlobs	Normal operation blobs.

enum caam_ext_key_xfr_source_t

Enumerator
kCAAM_ExtKeyXfr_KeyRegisterClass1	The Class 1 Key Register is the source.
kCAAM_ExtKeyXfr_KeyRegisterClass2	The Class 2 Key Register is the source.
kCAAM_ExtKeyXfr_PkhaRamE	The PKHA E RAM is the source.

Function Documentation

status_t CAAM_Init	(	CAAM_Type *	base,
		const caam_config_t *	config
	)

This function initializes the CAAM driver, including CAAM's internal RNG.

Parameters

base	CAAM peripheral base address
config	Pointer to configuration structure.

Returns: kStatus_Success the CAAM Init has completed with zero termination status word; kStatus_Fail the CAAM Init has completed with non-zero termination status word

status_t CAAM_Deinit ( CAAM_Type * base )

This function deinitializes the CAAM driver.

Parameters

base	CAAM peripheral base address

Returns: kStatus_Success the CAAM Deinit has completed with zero termination status word; kStatus_Fail the CAAM Deinit has completed with non-zero termination status word

void CAAM_GetDefaultConfig ( caam_config_t * config )

This function initializes the CAAM configuration structure to a default value. The default values are as follows. caamConfig->rngSampleMode = kCAAM_RNG_SampleModeVonNeumann; caamConfig->rngRingOscDiv = kCAAM_RNG_RingOscDiv4;

Parameters

[out] config Pointer to configuration structure.

status_t CAAM_Wait	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		uint32_t *	descriptor,
		caam_wait_mode_t	mode
	)

This function polls CAAM output ring for a specific job.

The CAAM job ring is specified by the jobRing field in the caam_handle_t structure. The job to be waited is specified by it's descriptor address.

This function has two modes, determined by the mode argument. In blocking mode, the function polls the specified jobRing until the descriptor is available in the CAAM output job ring. In non-blocking mode, it polls the output ring once and returns status immediately.

The function can be called from multiple threads or interrupt service routines, as internally it uses global critical section (global interrupt disable enable) to protect it's operation against concurrent accesses. The global interrupt is disabled only when the descriptor is found in the output ring, for a very short time, to remove the descriptor from the output ring safely.

Parameters

base	CAAM peripheral base address
handle	Data structure with CAAM jobRing used for this request
descriptor
mode	Blocking and non-blocking mode. Zero is blocking. Non-zero is non-blocking.

Returns: kStatus_Success the CAAM job has completed with zero job termination status word; kStatus_Fail the CAAM job has completed with non-zero job termination status word; kStatus_Again In non-blocking mode, the job is not ready in the CAAM Output Ring

status_t CAAM_ExternalKeyTransfer	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		caam_ext_key_xfr_source_t	keySource,
		size_t	keySize
	)

This function loads the given key source to an CAAM external destination via a private interface, such as Inline Encryption Engine IEE Private Key bus.

The CAAM job ring is specified by the jobRing field in the caam_handle_t structure.

This function is blocking.

Parameters

base	CAAM peripheral base address
handle	Data structure with CAAM jobRing used for this request.
keySource	The source from which the key will be obtained.
keySize	Size of the key in bytes.

Returns: kStatus_Success the CAAM job has completed with zero job termination status word; kStatus_Fail the CAAM job has completed with non-zero job termination status word

Overview

CAAM Driver Initialization and Configuration

Comments about API usage in RTOS

Comments about API usage in interrupt handler

Comments about DCACHE

CAAM Driver Examples

Simple examples

Modules

Data Structures

Typedefs

Enumerations

Functions

Driver version

Data Structure Documentation

Data Fields

Data Fields

Data Fields

Field Documentation

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation