 |
MCUXpresso SDK API Reference Manual
Rev 2.15.000
NXP Semiconductors
|
|
MCUXpresso SDK API Reference Manual
Rev 2.15.000
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 |
| Specify CAU3's key resource and signalling to be used for an operation. More... | |
Typedefs | |
| typedef enum _cau3_key_slot | cau3_key_slot_t |
| Hardware semaphore usage by driver functions. More... | |
| typedef enum _cau3_task_done | cau3_task_done_t |
| CAU3 task done selection. More... | |
| typedef struct _cau3_handle | cau3_handle_t |
| Specify CAU3's key resource and signalling to be used for an operation. More... | |
Enumerations | |
| enum | _cau3_key_slot { kCAU3_KeySlot0 = 0x0U, kCAU3_KeySlotNone = 0x0U, kCAU3_KeySlot1 = 0x1U, kCAU3_KeySlot2 = 0x2U, kCAU3_KeySlot3 = 0x3U } |
| Hardware semaphore usage by driver functions. More... | |
| enum | _cau3_task_done { , 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_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... | |
| status_t | CAU3_MakeMemsPrivate (CAU3_Type *base, cau3_task_done_t taskDone) |
| Make the CAU3's local memories private. More... | |
Driver version | |
| #define | FSL_CAU3_DRIVER_VERSION (MAKE_VERSION(2, 0, 5)) |
| CAU3 driver version. More... | |
| struct _cau3_handle |
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::taskDone |
| cau3_key_slot_t _cau3_handle::keySlot |
| #define FSL_CAU3_DRIVER_VERSION (MAKE_VERSION(2, 0, 5)) |
Version 2.0.5.
Current version: 2.0.5
Change log:
| typedef enum _cau3_key_slot cau3_key_slot_t |
This macro can be enabled for mutual exclusive calls to CAU3 APIs from multiple CPUs. Note this does not lock against calls from multiple threads on one CPU.
CAU3 key slot selection. Current CryptoCore firmware supports 4 key slots inside CryptoCore's Private DMEM.
| typedef enum _cau3_task_done cau3_task_done_t |
| typedef struct _cau3_handle cau3_handle_t |
| enum _cau3_key_slot |
This macro can be enabled for mutual exclusive calls to CAU3 APIs from multiple CPUs. Note this does not lock against calls from multiple threads on one CPU.
CAU3 key slot selection. Current CryptoCore firmware supports 4 key slots inside CryptoCore's Private DMEM.
| Enumerator | |
|---|---|
| kCAU3_KeySlot0 |
CAU3 key slot 0. |
| kCAU3_KeySlotNone |
No key. |
| kCAU3_KeySlot1 |
CAU3 key slot 1. |
| kCAU3_KeySlot2 |
CAU3 key slot 2. |
| kCAU3_KeySlot3 |
CAU3 key slot 3. |
| enum _cau3_task_done |
| void CAU3_Init | ( | CAU3_Type * | base | ) |
Enable CAU3 clock and loads image to CryptoCore.
| 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 |
| status_t CAU3_MakeMemsPrivate | ( | CAU3_Type * | base, |
| cau3_task_done_t | taskDone | ||
| ) |
Modify the CAU3's internal configuration so the local memories are private and only accessible to the CAU3. This operation is typically performed after the CAU_InitializeInstMemory(), CAU_InitializeDataMemory(), and CAU_InitializeReadOnlyDataMemory() functions have been performed.
This configuration remains in effect until the next hardware reset.
| base | CAU3 base address |
| taskDone | indicates completion signal: CAU_[POLL, IRQ, EVENT, DMAREQ] |
| status | check from task completion: CAU_[OK, ERROR] |
