 |
MCUXpresso SDK API Reference Manual
Rev. 0
NXP Semiconductors
|
|
MCUXpresso SDK API Reference Manual
Rev. 0
NXP Semiconductors
|
The MCUXpresso SDK provides the Peripheral driver for the CAU3 module.
To initialize CAU3, call CAU3_Init function. It enables the CAU3 clock and it loads the binary image of CAU3 firmware into CAU3 local memories (IMEM and DMEM).
Since the CAU3 is a shared system module, its "ownership" must first be claimed by the host processor. This is accomplished via a hardware semaphore implemented in the HIRC submodule. The CAU3 driver provides CAU3_LockSemaphore for this purpose. Once ownership has been acquired, the host processor continues with requested operations.
After the host processor is done with the operations and after receiving the appropriate notification, the host processor releases the CAU3 semaphore, making the module available for other CPU or another bus master such as DMA. The CAU3 driver provides CAU3_ReleaseSemaphore function for this purpose.
Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/cau3
The CAU3 maintains four symmetric key "contexts" in its local, private data memory. The data structure for the context is defined as:
Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/cau3 Up to 4 contexts can be addressed:
CAU_SINGLE_KEY_CONTEXT_T cauKeyContext[4];
The keySize definition is:
if (keySize == 0) then {key is invalid} else if (keySize == 8) then {key is 64-bit DES} else if (keySize == 16) then {key is 128-bit AES} else if (keySize == 24) then {key is 192-bit TDES} else if (keySize == 32) then {key is 256-bit AES}
When the CAU3 CryptoCore performs an AES key expansion, the output schedule is stored in the local, private data memory and the appropriate pointer stored in the keySched context location. The key expansion/scheduling must be performed before any AES encryption or decryption operations are attempted.
For specific situations, for example, the Boot ROM, a key context can be loaded directly from the host processor. In the more typical situation, an RFC3394-wrapped key blob is provided to a CAU3 function which automatically unwraps the blob and loads the specified key context.
There is also a special function that loads the special "hardware key" provided as an input to the CAU3 over a dedicated interface into cauKeyContext[0].
None of the API functions is designed to be re-entrant. Concurrent CAU3 accesses from multiple threads or by multiple host processors are not allowed.
Assuming the host processor receiving interrupt has the ownership of the CAU3 module, it can request Encrypt/Decrypt/Hash/public_key operations in an interrupt routine. Still, it shall be assured by the user that CAU3 API functions are not called concurrently among multiple pre-empting interrupt handlers or between an interrupt handler and the main thread. Additionally, as the CAU3 accesses system memory for it's operation with data, such as message, plaintext, ciphertext or keys, all of those data shall remain valid until CAU3 operation completes.
Encrypt plaintext by AES engine Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/cau3 Compute keyed hash by AES engine (CMAC) Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/cau3 Compute hash (SHA-256) Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/cau3
Modules | |
| CAU3 AES driver | |
| CAU3 Blob driver | |
| CAU3 CHACHA20_POLY1305 driver | |
| CAU3 HASH driver | |
| CAU3 PKHA driver | |
| CAU3 TDES driver | |
Data Structures | |
| struct | cau3_handle_t |
| Specify CAU3's key resource and signalling to be used for an operation. More... | |
Enumerations | |
| enum | cau3_key_slot_t { kCAU3_KeySlot0 = 0x0U, kCAU3_KeySlotNone = 0x0U, kCAU3_KeySlot1 = 0x1U, kCAU3_KeySlot2 = 0x2U, kCAU3_KeySlot3 = 0x3U } |
| CAU3 key slot selection. More... | |
| enum | cau3_task_done_t { , kCAU3_TaskDonePoll = 0x00000000U, kCAU3_TaskDoneIrq = 0x00010000U, kCAU3_TaskDoneEvent = 0x00020000U, kCAU3_TaskDoneDmaRequest = 0x00040000 } |
| CAU3 task done selection. More... | |
Functions | |
| void | CAU3_Init (CAU3_Type *base) |
| Enables clock for CAU3 and loads image to memory. More... | |
| status_t | CAU3_LockSemaphore (CAU3_Type *base) |
| Lock the CAU3's hardware semaphore and establish ownership. More... | |
| status_t | CAU3_ReleaseSemaphore (CAU3_Type *base) |
| Release the CAU3's hardware semaphore. More... | |
| status_t | CAU3_ForceError (CAU3_Type *base, cau3_task_done_t taskDone) |
| Execute a CAU3 null task to signal error termination. More... | |
| status_t | CAU3_LoadSpecialKeyContext (CAU3_Type *base, size_t keySize, cau3_key_slot_t keySlot, cau3_task_done_t taskDone) |
| Load special hardware "key context" into the CAU3's data memory. More... | |
| status_t | CAU3_ClearKeyContext (CAU3_Type *base, cau3_key_slot_t keySlot, cau3_task_done_t taskDone) |
| Invalidate a 64-byte "key context" in the CAU3's private data memory. More... | |
| status_t | CAU3_LoadKeyInitVector (CAU3_Type *base, const uint8_t *iv, cau3_key_slot_t keySlot, cau3_task_done_t taskDone) |
| Load an initialization vector into a key context. More... | |
Driver version | |
| #define | FSL_CAU3_DRIVER_VERSION (MAKE_VERSION(2, 0, 0)) |
| CAU3 driver version. More... | |
| struct cau3_handle_t |
Data Fields | |
| cau3_task_done_t | taskDone |
| Specify CAU3 task done signalling to Host CPU. More... | |
| cau3_key_slot_t | keySlot |
| For operations with key (such as AES encryption/decryption), specify CAU3 key slot. More... | |
| cau3_task_done_t cau3_handle_t::taskDone |
| cau3_key_slot_t cau3_handle_t::keySlot |
| #define FSL_CAU3_DRIVER_VERSION (MAKE_VERSION(2, 0, 0)) |
Version 2.0.0.
Current version: 2.0.0
Change log:
| enum cau3_key_slot_t |
| enum cau3_task_done_t |
| void CAU3_Init | ( | CAU3_Type * | base | ) |
Enable CAU3 clock and loads image to CryptoCore.
| base | CAU3 base address |
| status_t CAU3_LockSemaphore | ( | CAU3_Type * | base | ) |
Lock the CAU3's hardware semaphore. The function blocks. This function also executes a CAU3 null task to "establish ownership" by host processor. This is required for correct IRQ, EVT and DMA_REQ signaling by subsequent PKHA operations. The CryptoCore task executes one instruction - a "stop".
| base | CAU3 base address |
| status_t CAU3_ReleaseSemaphore | ( | CAU3_Type * | base | ) |
Release the CAU3's hardware semaphore. The function blocks.
| base | CAU3 base address |
| status_t CAU3_ForceError | ( | CAU3_Type * | base, |
| cau3_task_done_t | taskDone | ||
| ) |
Execute a null task to signal error termination. The CryptoCore task executes one instruction - a "stop with error".
| base | CAU3 base address |
| taskDone | indicates completion signal |
| status_t CAU3_LoadSpecialKeyContext | ( | CAU3_Type * | base, |
| size_t | keySize, | ||
| cau3_key_slot_t | keySlot, | ||
| cau3_task_done_t | taskDone | ||
| ) |
Load the special hardware key context into the private DMEM. This only includes the complete 256-bit key which is then specified with a size of [8,16,24,32] bytes (for DES or AES-[128,256]). It also loads the default IV value specified in NIST/RFC2294 IV=0xa6a6a6a6a6a6a6a6. This operation typically loads keySlot 0, which, by convention, is used for the system key encryption key.
See the GENERAL COMMENTS for more information on the keyContext structure.
NOTE: This function also performs an AES key expansion if a keySize > 8 is specified.
| base | CAU3 base address |
| keySize | is the logical key size in bytes [8,16,24,32] |
| keySlot | is the destination key slot number [0-3] |
| taskDone | indicates completion signal. |
| status_t CAU3_ClearKeyContext | ( | CAU3_Type * | base, |
| cau3_key_slot_t | keySlot, | ||
| cau3_task_done_t | taskDone | ||
| ) |
Clears the key context in the private DMEM. There is support for four "key slots" with slot 0 typically used for the system key encryption key.
| base | CAU3 base address |
| keySlot | is the key slot number [0-3] to invalidate |
| taskDone | indicates completion signal * |
| status_t CAU3_LoadKeyInitVector | ( | CAU3_Type * | base, |
| const uint8_t * | iv, | ||
| cau3_key_slot_t | keySlot, | ||
| cau3_task_done_t | taskDone | ||
| ) |
Loads a 16-byte initialization vector (iv) into the specified key slot. There is support for a maximum of 4 key slots. The function is used internally for loading AEAD_CHACHA20_POY1305 nonce. It can be also used for Alternative Initial Values for A[0] in RFC 3394.
| base | CAU3 base address |
| iv | The initialization vector, ALIGNED ON A 0-MOD-4 ADDRESS. |
| keySlot | is the destination key context |
| taskDone | indicates completion signal |
