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

CAAM driver requires any cached memory to be used with CAAM module to be set in write-trough mode, so any data in CACHE are up to date with ones in memory. This guarantee that CAAM can fetch descriptor, execute desired operation and when computation is done, it is safe to perform invalidate even over unaligned data, since all data in physical memory are up to date with ones in CACHE (so no memory corruption occurs) and finally, CPU can retrieve correct output.

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 Blob driver

	CAAM Blocking APIs

	CAAM CRC driver

	CAAM Key Blankening driver

	CAAM Non-blocking APIs

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

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

struct	_caam_config
	CAAM configuration structure. More...

Typedefs
typedef struct _caam_job_callback	caam_job_callback_t
	CAAM callback function. More...

typedef enum _caam_job_ring_t	caam_job_ring_t
	CAAM job ring selection. More...

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

typedef enum _caam_wait_mode	caam_wait_mode_t
	CAAM driver wait mechanism.

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.

typedef uint32_t	caam_desc_key_black_t [64]
	Memory buffer to hold CAAM descriptor for performing key blackening jobs.

typedef uint32_t	caam_desc_gen_enc_blob_t [64]
	Memory buffer to hold CAAM descriptor for performing generating dek blob jobs.

typedef enum _caam_rng_sample_mode	caam_rng_sample_mode_t
	CAAM RNG sample mode. More...

typedef enum _caam_rng_ring_osc_div	caam_rng_ring_osc_div_t
	CAAM RNG ring oscillator divide. More...

typedef enum _caam_priblob	caam_priblob_t
	CAAM Private Blob. More...

typedef struct _caam_config	caam_config_t
	CAAM configuration structure. More...

typedef enum _caam_ext_key_xfr_source	caam_ext_key_xfr_source_t
	CAAM External Key Transfer command SRC (The source from which the key will be obtained)

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 { kCAAM_Blocking = 0u, kCAAM_Nonblocking = 1u }
	CAAM driver wait mechanism. More...

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

enum	_caam_rng_ring_osc_div { 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 { kCAAM_PrivSecureBootBlobs = 0U, kCAAM_PrivProvisioningBlobsType1 = 1U, kCAAM_PrivProvisioningBlobsType2 = 2U, kCAAM_NormalOperationBlobs = 3U }
	CAAM Private Blob. More...

enum	_caam_ext_key_xfr_source { 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, 3, 2))
	CAAM driver version. More...

Data Structure Documentation

struct _caam_job_callback

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

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::rngSampleMode

caam_rng_ring_osc_div_t _caam_config::rngRingOscDiv

bool _caam_config::scfgrLockTrngProgramMode

bool _caam_config::scfgrEnableRandomDataBuffer

bool _caam_config::scfgrRandomRngStateHandle0

bool _caam_config::scfgrRandomDpaResistance

caam_priblob_t _caam_config::scfgrPriblob

Macro Definition Documentation

#define FSL_CAAM_DRIVER_VERSION (MAKE_VERSION(2, 3, 2))

Version 2.3.2.

Current version: 2.3.2

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.
Version 2.1.6
- Improve DCACHE handling. Requires CAAM used and cached memory set in write-trough mode.
Version 2.2.0
- Added API for Blob functions and CRC
Version 2.2.1
- Fixed AES-CCM decrypt failing with TAG length bigger than 8 byte.
Version 2.2.2
- Modify RNG to not reseed with each request.
Version 2.2.3
- Fix DCACHE invalidation in CAAM_HASH_Finish().
Version 2.2.4
- Fix issue where the outputSize parameter of CAAM_HASH_Finish() has impact on hash calculation.
Version 2.3.0
- Add support for SHA HMAC.
Version 2.3.1
- Modified function caam_aes_ccm_check_input_args() to allow payload be empty as is specified in NIST800-38C Section 5.3.
Version 2.3.2
- Fix MISRA-2012 issues.

Typedef Documentation

typedef struct _caam_job_callback caam_job_callback_t

typedef enum _caam_job_ring_t caam_job_ring_t

typedef struct _caam_handle_t 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).

typedef enum _caam_rng_sample_mode caam_rng_sample_mode_t

Used by caam_config_t.

typedef enum _caam_rng_ring_osc_div caam_rng_ring_osc_div_t

Used by caam_config_t.

typedef enum _caam_priblob caam_priblob_t

Used by caam_config_t.

typedef struct _caam_config caam_config_t

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

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

enum _caam_rng_sample_mode

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

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

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

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

Typedef Documentation

Enumeration Type Documentation

Function Documentation