Overview

The MCUXpresso SDK provides a peripheral driver for the Data Co-Processor (DCP) module. For security purposes, the Data Co-Processor (DCP) provides hardware acceleration for the cryptographic algorithms. The features of DCP are: Encryption Algorithms: AES-128 (ECB and CBC modes), Hashing Algorithms: SHA-1 and SHA-256, modified CRC-32, Key selection from the SNVS, DCP internal key storage, or general memory, Internal Memory for storing up to four AES-128 keys-when a key is written to a key slot it can be read only by the DCP AES-128 engine, IP slave interface, and DMA.

The driver comprises two sets of API functions.

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

The DCP work packets (descriptors) are placed on the system stack during the blocking API calls. The driver uses critical section (implemented as global interrupt enable/disable) for a short time whenever it needs to pass DCP work packets to DCP channel for processing. 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 DCP work packet's status word) for an operation completion. The non-blocking functions allow upper layer to inject an application specific operation after the DCP operation start and DCP channel complete events. RTOS event wait and RTOS event set can be an example of such an operation.

DCP Driver Initialization and Configuration

Initialize DCP after Power On Reset or reset cycle Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/dcp

The DCP Driver is initialized by calling the DCP_Init() function. It enables the DCP module clock and configures DCP for operation.

Key Management

The DCP implements four different key storage mechanisms: OTP-key, OTP-Unique key, Payload key, and SRAM-based keys that can be used by the software to securely store keys on a semi-permanent basis (kDCP_KeySlot0 ~ kDCP_KeySlot3). Once the function DCP_AES_SetKey() is called, it sets the AES key for encryption/decryption with the dcp_handle_t structure. In case the SRAM-based key is selected, the function copies and holds the key in memory. In case the OTP key is used, please make sure to set DCP related IOMUXC_GPRs before DCP initialization, since the software reset of DCP must be issued to take these setting in effect. Refer to the DCP_OTPKeySelect() function in BEE driver example.

Comments about API usage in RTOS

DCP transactional (encryption or hash) APIs can be called from multiple threads.

Comments about API usage in interrupt handler

Assuming the host processor receiving interrupt has the ownership of the DCP module, it can request Encrypt/Decrypt/Hash/public_key operations in an interrupt routine. Additionally, as the DCP accesses system memory for it's operation with data (such as message, plaintext, ciphertext, or keys) all data should remain valid until the DCP operation completes.

DCP Driver Examples

Simple examples

Encrypt plaintext by AES engine Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/DCP

Compute hash (CRC-32) The CRC-32 algorithm implements a 32-bit CRC algorithm similar to the one used by Ethernet and many other protocols. The CRC differs from the Unix cksum() function in these four ways: The CRC initial value is 0xFFFFFFFF instead of 0x00000000, final XOR value is 0x00000000 instead of 0xFFFFFFFF, the logic pads the zeros to a 32-bit boundary for the trailing bytes, and it does not post-pend the file length. Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/DCP

Compute hash (SHA-256) Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/DCP

Modules
	DCP AES blocking driver

	DCP AES non-blocking driver

	DCP HASH driver

Data Structures
struct	dcp_work_packet_t
	DCP's work packet. More...

struct	dcp_handle_t
	Specify DCP's key resource and DCP channel. More...

struct	dcp_context_t
	DCP's context buffer, used by DCP for context switching between channels. More...

struct	dcp_config_t
	DCP's configuration structure. More...

Enumerations
enum	_dcp_ch_enable_t { kDCP_chDisable = 0U, kDCP_ch0Enable = 1U, kDCP_ch1Enable = 2U, kDCP_ch2Enable = 4U, kDCP_ch3Enable = 8U, kDCP_chEnableAll = 15U }
	DCP channel enable. More...

enum	_dcp_ch_int_enable_t { kDCP_chIntDisable = 0U, kDCP_ch0IntEnable = 1U, kDCP_ch1IntEnable = 2U, kDCP_ch2IntEnable = 4U, kDCP_ch3IntEnable = 8U }
	DCP interrupt enable. More...

enum	dcp_channel_t { kDCP_Channel0 = (1u << 16), kDCP_Channel1 = (1u << 17), kDCP_Channel2 = (1u << 18), kDCP_Channel3 = (1u << 19) }
	DCP channel selection. More...

enum	dcp_key_slot_t { kDCP_KeySlot0 = 0U, kDCP_KeySlot1 = 1U, kDCP_KeySlot2 = 2U, kDCP_KeySlot3 = 3U, kDCP_OtpKey = 4U, kDCP_OtpUniqueKey = 5U, kDCP_PayloadKey = 6U }
	DCP key slot selection. More...

enum	dcp_swap_t
	DCP key, input & output swap options. More...

Functions
void	DCP_Init (DCP_Type base, const dcp_config_t config)
	Enables clock to and enables DCP. More...

void	DCP_Deinit (DCP_Type *base)
	Disable DCP clock. More...

void	DCP_GetDefaultConfig (dcp_config_t *config)
	Gets the default configuration structure. More...

status_t	DCP_WaitForChannelComplete (DCP_Type base, dcp_handle_t handle)
	Poll and wait on DCP channel. More...

Driver version
#define	FSL_DCP_DRIVER_VERSION (MAKE_VERSION(2, 1, 3))
	DCP driver version. More...

Data Structure Documentation

struct dcp_work_packet_t

struct dcp_handle_t

Data Fields
dcp_channel_t	channel
	Specify DCP channel. More...

dcp_key_slot_t	keySlot
	For operations with key (such as AES encryption/decryption), specify DCP key slot. More...

uint32_t	swapConfig
	For configuration of key, input, output byte/word swap options.

Field Documentation

dcp_channel_t dcp_handle_t::channel

dcp_key_slot_t dcp_handle_t::keySlot

struct dcp_context_t

struct dcp_config_t

Data Fields
bool	gatherResidualWrites
	Enable the ragged writes to the unaligned buffers. More...

bool	enableContextCaching
	Enable the caching of contexts between the operations. More...

bool	enableContextSwitching
	Enable automatic context switching for the channels. More...

uint8_t	enableChannel
	DCP channel enable. More...

uint8_t	enableChannelInterrupt
	Per-channel interrupt enable. More...

Field Documentation

bool dcp_config_t::gatherResidualWrites

bool dcp_config_t::enableContextCaching

bool dcp_config_t::enableContextSwitching

uint8_t dcp_config_t::enableChannel

uint8_t dcp_config_t::enableChannelInterrupt

Macro Definition Documentation

#define FSL_DCP_DRIVER_VERSION (MAKE_VERSION(2, 1, 3))

Version 2.1.3.

Current version: 2.1.3

Change log:

Version 2.1.3
- Bug Fix
  - MISRA C-2012 issue fixed: rule 10.1, 10.3, 10.4, 11.9, 14.4, 16.4 and 17.7.
Version 2.1.2
- Fix sign-compare warning in dcp_reverse_and_copy.
Version 2.1.1
- Add DCP status clearing when channel operation is complete
2.1.0
- Add byte/word swap feature for key, input and output data
Version 2.0.0
- Initial version

Enumeration Type Documentation

enum _dcp_ch_enable_t

Enumerator
kDCP_chDisable	DCP channel disable.
kDCP_ch0Enable	DCP channel 0 enable.
kDCP_ch1Enable	DCP channel 1 enable.
kDCP_ch2Enable	DCP channel 2 enable.
kDCP_ch3Enable	DCP channel 3 enable.
kDCP_chEnableAll	DCP channel enable all.

enum _dcp_ch_int_enable_t

Enumerator
kDCP_chIntDisable	DCP interrupts disable.
kDCP_ch0IntEnable	DCP channel 0 interrupt enable.
kDCP_ch1IntEnable	DCP channel 1 interrupt enable.
kDCP_ch2IntEnable	DCP channel 2 interrupt enable.
kDCP_ch3IntEnable	DCP channel 3 interrupt enable.

enum dcp_channel_t

Enumerator
kDCP_Channel0	DCP channel 0.
kDCP_Channel1	DCP channel 1.
kDCP_Channel2	DCP channel 2.
kDCP_Channel3	DCP channel 3.

enum dcp_key_slot_t

Enumerator
kDCP_KeySlot0	DCP key slot 0.
kDCP_KeySlot1	DCP key slot 1.
kDCP_KeySlot2	DCP key slot 2.
kDCP_KeySlot3	DCP key slot 3.
kDCP_OtpKey	DCP OTP key.
kDCP_OtpUniqueKey	DCP unique OTP key.
kDCP_PayloadKey	DCP payload key.

enum dcp_swap_t

Function Documentation

void DCP_Init	(	DCP_Type *	base,
		const dcp_config_t *	config
	)

Enable DCP clock and configure DCP.

Parameters

base	DCP base address
config	Pointer to configuration structure.

void DCP_Deinit ( DCP_Type * base )

Reset DCP and Disable DCP clock.

Parameters

base	DCP base address

void DCP_GetDefaultConfig ( dcp_config_t * config )

This function initializes the DCP configuration structure to a default value. The default values are as follows. dcpConfig->gatherResidualWrites = true; dcpConfig->enableContextCaching = true; dcpConfig->enableContextSwitching = true; dcpConfig->enableChannnel = kDCP_chEnableAll; dcpConfig->enableChannelInterrupt = kDCP_chIntDisable;

Parameters

[out] config Pointer to configuration structure.

status_t DCP_WaitForChannelComplete	(	DCP_Type *	base,
		dcp_handle_t *	handle
	)

Polls the specified DCP channel until current it completes activity.

Parameters

base	DCP peripheral base address.
handle	Specifies DCP channel.

Returns: kStatus_Success When data processing completes without error.; kStatus_Fail When error occurs.

Overview

DCP Driver Initialization and Configuration

Key Management

Comments about API usage in RTOS

Comments about API usage in interrupt handler

DCP Driver Examples

Simple examples

Modules

Data Structures

Enumerations

Functions

Driver version

Data Structure Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation