Functions
void	AESStartDMAOperation (const uint8_t channel0Addr, uint32_t channel0Length, uint8_t channel1Addr, uint32_t channel1Length)
	Start a crypto DMA operation. More...

void	AESSetInitializationVector (const uint32_t *initializationVector)
	Write the initialization vector (IV) to the crypto module. More...

void	AESWriteCCMInitializationVector (const uint8_t *nonce, uint32_t nonceLength)
	Generate and load the initialization vector for a CCM operation. More...

uint32_t	AESReadTag (uint8_t *tag, uint32_t tagLength)
	Read the tag out from the crypto module. More...

uint32_t	AESVerifyTag (const uint8_t *tag, uint32_t tagLength)
	Verifies the provided `tag` against calculated one. More...

uint32_t	AESWriteToKeyStore (const uint8_t *aesKey, uint32_t aesKeyLength, uint32_t keyStoreArea)
	Transfer a key from main memory to a key area within the key store. More...

uint32_t	AESReadFromKeyStore (uint32_t keyStoreArea)
	Transfer a key from key store area to the internal buffers within the hardware module. More...

uint32_t	AESWaitForIRQFlags (uint32_t irqFlags)
	Poll the interrupt status register and clear when done. More...

void	AESConfigureCCMCtrl (uint32_t nonceLength, uint32_t macLength, bool encrypt)
	Configure AES engine for CCM operation. More...

static void	AESInvalidateKey (uint32_t keyStoreArea)
	Invalidate a key in the key store. More...

static void	AESSelectAlgorithm (uint32_t algorithm)
	Select type of operation. More...

static void	AESSetCtrl (uint32_t ctrlMask)
	Set up the next crypto module operation. More...

static void	AESSetDataLength (uint32_t length)
	Specify length of the crypto operation. More...

static void	AESSetAuthLength (uint32_t length)
	Specify the length of the additional authentication data (AAD). More...

static void	AESIntEnable (uint32_t intFlags)
	Enable individual crypto interrupt sources. More...

static void	AESIntDisable (uint32_t intFlags)
	Disable individual crypto interrupt sources. More...

static uint32_t	AESIntStatusMasked (void)
	Get the current masked interrupt status. More...

static uint32_t	AESIntStatusRaw (void)
	Get the current raw interrupt status. More...

static void	AESIntClear (uint32_t intFlags)
	Clear crypto interrupt sources. More...

static void	AESIntRegister (void(*handlerFxn)(void))
	Register an interrupt handler for a crypto interrupt. More...

static void	AESIntUnregister (void)
	Unregister an interrupt handler for a crypto interrupt. More...

Detailed Description

Introduction

The AES (advanced encryption standard) API provides access to the AES and key store functionality of the crypto core. The SHA2 accelerator is also contained within the crypto core. Hence, only one of SHA2 and AES may be used at the same time. This module offers hardware acceleration for several protocols using the AES block cypher. The protocols below are supported by the hardware. The driverlib documentation only explicitly references the most commonly used ones.

ECB
CBC
CCM
CBC-MAC
GCM

The key store is a section of crypto memory that is only accessible to the crypto module and may be written to by the application via the crypto DMA. It is not possible to read from the key store to main memory. Thereby, it is not possible to compromise the key should the application be hacked if the original key in main memory was overwritten already.

The crypto core does not have retention and all configuration settings and keys in the keystore are lost when going into standby or shutdown. The typical security advantages a key store offers are not available in these low power modes as the key must be saved in regular memory to reload it after going into standby or shutdown. Consequently, the keystore primarily serves as an interface to the AES accelerator.

Function Documentation

void AESConfigureCCMCtrl	(	uint32_t	nonceLength,
		uint32_t	macLength,
		bool	encrypt
	)

Configure AES engine for CCM operation.

Parameters

[in]	nonceLength	Length of the nonce. Must be <= 14.
[in]	macLength	Length of the MAC. Must be <= 16.
[in]	encrypt	Whether to set up an encrypt or decrypt operation. true: encrypt false: decrypt

Returns: None

 {
     uint32_t ctrlVal = 0;
 
     ctrlVal = ((15 - nonceLength - 1) << CRYPTO_AESCTL_CCM_L_S);
     if ( macLength >= 2 ) {
         ctrlVal |= ((( macLength - 2 ) >> 1 ) << CRYPTO_AESCTL_CCM_M_S );
     }
     ctrlVal |= CRYPTO_AESCTL_CCM |
                CRYPTO_AESCTL_CTR |
                CRYPTO_AESCTL_SAVE_CONTEXT |
                CRYPTO_AESCTL_CTR_WIDTH_128_BIT;
     ctrlVal |= encrypt ? CRYPTO_AESCTL_DIR : 0;
 
     AESSetCtrl(ctrlVal);
 }

Here is the call graph for this function:

static void AESIntClear ( uint32_t intFlags )

inlinestatic

Clear crypto interrupt sources.

The specified crypto interrupt sources are cleared, so that they no longer assert. This function must be called in the interrupt handler to keep the interrupt from being recognized again immediately upon exit.

Note: Due to write buffers and synchronizers in the system it may take several clock cycles from a register write clearing an event in the module until the event is actually cleared in the NVIC of the system CPU. It is recommended to clear the event source early in the interrupt service routine (ISR) to allow the event clear to propagate to the NVIC before returning from the ISR.

Parameters

[in]

intFlags

is a bit mask of the interrupt sources to be cleared.

Returns: None

 {
     // Check the arguments.
     ASSERT((intFlags & AES_DMA_IN_DONE) ||
            (intFlags & AES_RESULT_RDY));
 
     // Clear the requested interrupt sources,
     HWREG(CRYPTO_BASE + CRYPTO_O_IRQCLR) = intFlags;
 }

static void AESIntDisable ( uint32_t intFlags )

inlinestatic

Disable individual crypto interrupt sources.

This function disables the indicated crypto interrupt sources. Only the sources that are enabled can be reflected to the processor interrupt. Disabled sources have no effect on the processor.

Parameters

[in]

intFlags

is the bitwise OR of the interrupt sources to be enabled.

Returns: None

 {
     // Check the arguments.
     ASSERT((intFlags & AES_DMA_IN_DONE) ||
            (intFlags & AES_RESULT_RDY));
 
     // Disable the specified interrupts.
     HWREG(CRYPTO_BASE + CRYPTO_O_IRQEN) &= ~intFlags;
 }

static void AESIntEnable ( uint32_t intFlags )

inlinestatic

Enable individual crypto interrupt sources.

This function enables the indicated crypto interrupt sources. Only the sources that are enabled can be reflected to the processor interrupt. Disabled sources have no effect on the processor.

Parameters

[in]

intFlags

is the bitwise OR of the interrupt sources to be enabled.

Returns: None

 {
     // Check the arguments.
     ASSERT((intFlags & AES_DMA_IN_DONE) ||
            (intFlags & AES_RESULT_RDY));
 
     // Using level interrupt.
     HWREG(CRYPTO_BASE + CRYPTO_O_IRQTYPE) = CRYPTO_IRQTYPE_LEVEL_M;
 
     // Enable the specified interrupts.
     HWREG(CRYPTO_BASE + CRYPTO_O_IRQEN) |= intFlags;
 }

static void AESIntRegister ( void(*)(void) handlerFxn )

inlinestatic

Register an interrupt handler for a crypto interrupt.

This function does the actual registering of the interrupt handler. This function enables the global interrupt in the interrupt controller; specific crypto interrupts must be enabled via AESIntEnable(). It is the interrupt handler's responsibility to clear the interrupt source.

Parameters

handlerFxn is a pointer to the function to be called when the crypto interrupt occurs.

Returns: None

See also: IntRegister() for important information about registering interrupt handlers.

 {
     // Register the interrupt handler.
     IntRegister(INT_CRYPTO_RESULT_AVAIL_IRQ, handlerFxn);
 
     // Enable the crypto interrupt.
     IntEnable(INT_CRYPTO_RESULT_AVAIL_IRQ);
 }

Here is the call graph for this function:

static uint32_t AESIntStatusMasked ( void )

inlinestatic

Get the current masked interrupt status.

This function returns the masked interrupt status of the crypto module.

Returns

Returns the status of the masked lines when enabled:

 {
     uint32_t mask;
 
     // Return the masked interrupt status
     mask = HWREG(CRYPTO_BASE + CRYPTO_O_IRQEN);
     return(mask & HWREG(CRYPTO_BASE + CRYPTO_O_IRQSTAT));
 }

static uint32_t AESIntStatusRaw ( void )

inlinestatic

Get the current raw interrupt status.

This function returns the raw interrupt status of the crypto module. It returns both the status of the lines routed to the NVIC as well as the error flags.

Returns

Returns the raw interrupt status:

 {
     // Return either the raw interrupt status
     return(HWREG(CRYPTO_BASE + CRYPTO_O_IRQSTAT));
 }

static void AESIntUnregister ( void )

inlinestatic

Unregister an interrupt handler for a crypto interrupt.

This function does the actual unregistering of the interrupt handler. It clears the handler called when a crypto interrupt occurs. This function also masks off the interrupt in the interrupt controller so that the interrupt handler no longer is called.

Returns: None

See also: IntRegister() for important information about registering interrupt handlers.

 {
     //
     // Disable the interrupt.
     //
     IntDisable(INT_CRYPTO_RESULT_AVAIL_IRQ);
 
     //
     // Unregister the interrupt handler.
     //
     IntUnregister(INT_CRYPTO_RESULT_AVAIL_IRQ);
 }

Here is the call graph for this function:

static void AESInvalidateKey ( uint32_t keyStoreArea )

inlinestatic

Invalidate a key in the key store.

Parameters

[in]

keyStoreArea

is the entry in the key store to invalidate. This permanently deletes the key from the key store.

Returns: None

Referenced by AESWriteToKeyStore().

 {
     ASSERT((keyStoreArea == AES_KEY_AREA_0) ||
            (keyStoreArea == AES_KEY_AREA_1) ||
            (keyStoreArea == AES_KEY_AREA_2) ||
            (keyStoreArea == AES_KEY_AREA_3) ||
            (keyStoreArea == AES_KEY_AREA_4) ||
            (keyStoreArea == AES_KEY_AREA_5) ||
            (keyStoreArea == AES_KEY_AREA_6) ||
            (keyStoreArea == AES_KEY_AREA_7));
 
     // Clear any previously written key at the key location
     HWREG(CRYPTO_BASE + CRYPTO_O_KEYWRITTENAREA) = (0x00000001 << keyStoreArea);
 }

uint32_t AESReadFromKeyStore ( uint32_t keyStoreArea )

Transfer a key from key store area to the internal buffers within the hardware module.

The function polls until the transfer is complete.

Parameters

[in]

keyStoreArea

The key store area to transfer the key from. When using 256-bit keys, either of the occupied key areas may be specified to load the key. There is no need to specify the length of the key here as the key store keeps track of how long a key associated with any valid key area is and where is starts.

Returns

Returns a status code depending on the result of the transfer. When specifying a keyStoreArea value without a valid key in it an error is returned. If there was an error in the read process itself, an error is returned. Otherwise, a success code is returned.

See also: AESWriteToKeyStore

 {
     // Check the arguments.
     ASSERT((keyStoreArea == AES_KEY_AREA_0) ||
            (keyStoreArea == AES_KEY_AREA_1) ||
            (keyStoreArea == AES_KEY_AREA_2) ||
            (keyStoreArea == AES_KEY_AREA_3) ||
            (keyStoreArea == AES_KEY_AREA_4) ||
            (keyStoreArea == AES_KEY_AREA_5) ||
            (keyStoreArea == AES_KEY_AREA_6) ||
            (keyStoreArea == AES_KEY_AREA_7));
 
     // Check if there is a valid key in the specified keyStoreArea
     if (!(HWREG(CRYPTO_BASE + CRYPTO_O_KEYWRITTENAREA) & (1 << keyStoreArea))) {
         return AES_KEYSTORE_AREA_INVALID;
     }
 
     // Enable keys to read (e.g. Key 0).
     HWREG(CRYPTO_BASE + CRYPTO_O_KEYREADAREA) = keyStoreArea;
 
     // Wait until key is loaded to the AES module.
     // We cannot simply poll the IRQ status as only an error is communicated through
     // the IRQ status and not the completion of the transfer.
     do {
         CPUdelay(1);
     }
     while((HWREG(CRYPTO_BASE + CRYPTO_O_KEYREADAREA) & CRYPTO_KEYREADAREA_BUSY_M));
 
     // Check for keyStore read error.
     if((HWREG(CRYPTO_BASE + CRYPTO_O_IRQSTAT) & CRYPTO_IRQSTAT_KEY_ST_RD_ERR_M)) {
         return AES_KEYSTORE_ERROR;
     }
     else {
         return AES_SUCCESS;
     }
 }

Here is the call graph for this function:

uint32_t AESReadTag	(	uint8_t *	tag,
		uint32_t	tagLength
	)

Read the tag out from the crypto module.

This function copies the tagLength bytes from the tag calculated by the crypto module in CCM, GCM, or CBC-MAC mode to tag.

Parameters

[out]	tag	Pointer to an array of `tagLength` bytes.
[in]	tagLength	Number of bytes to copy to `tag`.

Returns

Returns a status code depending on the result of the transfer.

AES_TAG_NOT_READY if the tag is not ready yet
AES_SUCCESS otherwise

Referenced by AESVerifyTag().

 {
     // The intermediate array is used instead of a caller-provided one
     // to enable a simple API with no unintuitive alignment or size requirements.
     // This is a trade-off of stack-depth vs ease-of-use that came out on the
     // ease-of-use side.
     uint32_t computedTag[AES_BLOCK_SIZE / sizeof(uint32_t)];
 
     // Wait until the computed tag is ready.
     while (!(HWREG(CRYPTO_BASE + CRYPTO_O_AESCTL) & CRYPTO_AESCTL_SAVED_CONTEXT_RDY_M));
 
     // Read computed tag out from the HW registers
     // Need to read out all 128 bits in four reads to correctly clear CRYPTO_AESCTL_SAVED_CONTEXT_RDY flag
     computedTag[0] = HWREG(CRYPTO_BASE + CRYPTO_O_AESTAGOUT0);
     computedTag[1] = HWREG(CRYPTO_BASE + CRYPTO_O_AESTAGOUT1);
     computedTag[2] = HWREG(CRYPTO_BASE + CRYPTO_O_AESTAGOUT2);
     computedTag[3] = HWREG(CRYPTO_BASE + CRYPTO_O_AESTAGOUT3);
 
     memcpy(tag, computedTag, tagLength);
 
     return AES_SUCCESS;
 }

static void AESSelectAlgorithm ( uint32_t algorithm )

inlinestatic

Select type of operation.

Parameters

[in]

algorithm

Flags that specify which type of operation the crypto module shall perform. The flags are mutually exclusive.

Returns: None

 {
     ASSERT((algorithm == AES_ALGSEL_AES) ||
            (algorithm == AES_ALGSEL_AES | AES_ALGSEL_TAG) ||
            (algorithm == AES_ALGSEL_KEY_STORE));
 
     HWREG(CRYPTO_BASE + CRYPTO_O_ALGSEL) = algorithm;
 }

static void AESSetAuthLength ( uint32_t length )

inlinestatic

Specify the length of the additional authentication data (AAD).

Despite specifying it here, the crypto DMA must still be set up with the correct AAD length.

Parameters

[in]

length

Specifies how long the AAD is in a CCM operation. In CCM mode, set this to 0 if no AAD is required. If set to 0, AESWriteDataLength() must be set to >0. Range depends on the mode:

ECB: Do not call.
CBC: [0]
CBC-MAC: [0]
CCM: [0, sizeof(RAM)]

Returns: None

See also: AESWriteDataLength

 {
     HWREG(CRYPTO_BASE + CRYPTO_O_AESAUTHLEN) = length;
 }

static void AESSetCtrl ( uint32_t ctrlMask )

inlinestatic

Set up the next crypto module operation.

The function uses a bitwise OR of the fields within the CRYPTO_O_AESCTL register. The relevant field names have the format:

CRYPTO_AESCTL_[field name]

Parameters

[in] ctrlMask Specifies which register fields shall be set.

Returns: None

Referenced by AESConfigureCCMCtrl().

 {
     HWREG(CRYPTO_BASE + CRYPTO_O_AESCTL) = ctrlMask;
 }

static void AESSetDataLength ( uint32_t length )

inlinestatic

Specify length of the crypto operation.

Despite specifying it here, the crypto DMA must still be set up with the correct data length.

Parameters

[in]

length

Data length in bytes. If this value is set to 0, only authentication of the AAD is performed in CCM-mode and AESWriteAuthLength() must be set to >0. Range depends on the mode:

ECB: [16]
CBC: [1, sizeof(RAM)]
CBC-MAC: [1, sizeof(RAM)]
CCM: [0, sizeof(RAM)]

Returns: None

See also: AESWriteAuthLength

 {
     HWREG(CRYPTO_BASE + CRYPTO_O_AESDATALEN0) = length;
     HWREG(CRYPTO_BASE + CRYPTO_O_AESDATALEN1) = 0;
 }

void AESSetInitializationVector ( const uint32_t * initializationVector )

Write the initialization vector (IV) to the crypto module.

Depending on the mode of operation, the tag must be constructed differently:

CBC: No special care must be taken. Any 128-bit IV (initialization vector) will suffice.
CBC-MAC: IV's must be all 0's.
CCM: Only 12 and 13 byte IV's are permitted. See code below for formatting.
1 uint8_t initVectorLength = 12; // Could also be 13

2

3 union {

4 uint32_t word[4];

5 uint8_t byte[16];

6 } initVector;

7

8 uint8_t initVectorUnformatted[initVectorLength];

9

10 // This is the same field length value that is written to the ctrl register

11 initVector.byte[0] = L - 1;

12

13 memcpy(&initVector.byte[1], initVectorUnformatted, initVectorLength);

14

15 // Fill the remaining bytes with zeros

16 for (initVectorLength++; initVectorLength < sizeof(initVector.byte); initVectorLength++) {

17 initVector.byte[initVectorLength] = 0;

18 }

Parameters

[in] initializationVector Pointer to an array with four 32-bit elements to be used as initialization vector. Elements of array must be word aligned in memory.

Returns: None

Referenced by AESWriteCCMInitializationVector().

 {
     // Write initialization vector to the aes registers
     HWREG(CRYPTO_BASE + CRYPTO_O_AESIV0) = initializationVector[0];
     HWREG(CRYPTO_BASE + CRYPTO_O_AESIV1) = initializationVector[1];
     HWREG(CRYPTO_BASE + CRYPTO_O_AESIV2) = initializationVector[2];
     HWREG(CRYPTO_BASE + CRYPTO_O_AESIV3) = initializationVector[3];
 }

void AESStartDMAOperation	(	const uint8_t *	channel0Addr,
		uint32_t	channel0Length,
		uint8_t *	channel1Addr,
		uint32_t	channel1Length
	)

Start a crypto DMA operation.

Enable the crypto DMA channels, configure the channel addresses, and set the length of the data transfer. Setting the length of the data transfer automatically starts the transfer. It is also used by the hardware module as a signal to begin the encryption, decryption, or MAC operation.

Parameters

[in]	channel0Addr	A pointer to the address channel 0 shall use.
[in]	channel0Length	Length of the data in bytes to be read from or written to at channel0Addr. Set to 0 to not set up this channel. Permitted ranges are mode dependent and displayed below. ECB: [16] CBC: [1, sizeof(RAM)] CBC-MAC: [1, sizeof(RAM)] CCM: [1, sizeof(RAM)]
[out]	channel1Addr	A pointer to the address channel 1 shall use.
[in]	channel1Length	Length of the data in bytes to be read from or written to at channel1Addr. Set to 0 to not set up this channel.Permitted ranges are mode dependent and displayed below. ECB: [16] CBC: [1, sizeof(RAM)] CBC-MAC: [1, sizeof(RAM)] CCM: [1, sizeof(RAM)]

Returns: None

Referenced by AESWriteToKeyStore().

 {
     if (channel0Length && channel0Addr) {
         // We actually want to perform an operation. Clear any outstanding events.
         HWREG(CRYPTO_BASE + CRYPTO_O_IRQCLR) = CRYPTO_IRQCLR_RESULT_AVAIL_M | CRYPTO_IRQEN_DMA_IN_DONE_M; // This might need AES_IRQEN_DMA_IN_DONE as well
 
         while(HWREG(CRYPTO_BASE + CRYPTO_O_IRQSTAT) & (CRYPTO_IRQSTAT_DMA_IN_DONE_M | CRYPTO_IRQSTAT_RESULT_AVAIL_M));
 
         // Configure the DMA controller - enable both DMA channels.
         HWREGBITW(CRYPTO_BASE + CRYPTO_O_DMACH0CTL, CRYPTO_DMACH0CTL_EN_BITN) = 1;
 
         // Base address of the payload data in ext. memory.
         HWREG(CRYPTO_BASE + CRYPTO_O_DMACH0EXTADDR) = (uint32_t)channel0Addr;
 
         // Payload data length in bytes, equal to the cipher text length.
         HWREG(CRYPTO_BASE + CRYPTO_O_DMACH0LEN) = channel0Length;
     }
 
     if (channel1Length && channel1Addr) {
         // Enable DMA channel 1.
         HWREGBITW(CRYPTO_BASE + CRYPTO_O_DMACH1CTL, CRYPTO_DMACH1CTL_EN_BITN) = 1;
 
         // Base address of the output data buffer.
         HWREG(CRYPTO_BASE + CRYPTO_O_DMACH1EXTADDR) = (uint32_t)channel1Addr;
 
         // Output data length in bytes, equal to the cipher text length.
         HWREG(CRYPTO_BASE + CRYPTO_O_DMACH1LEN) = channel1Length;
     }
 }

uint32_t AESVerifyTag	(	const uint8_t *	tag,
		uint32_t	tagLength
	)

Verifies the provided tag against calculated one.

This function compares the provided tag against the tag calculated by the crypto module during the last CCM, GCM, or CBC-MAC

This function copies the tagLength bytes from the tag calculated by the crypto module in CCM, GCM, or CBC-MAC mode to tag.

Parameters

[in]	tag	Pointer to an array of `tagLength` bytes.
[in]	tagLength	Number of bytes to compare.

Returns

Returns a status code depending on the result of the transfer.

AES_TAG_VERIFICATION_FAILED if the verification failed
AES_SUCCESS otherwise

 {
     uint32_t resultStatus;
     // The intermediate array is allocated on the stack to ensure users do not
     // point the tag they provide and the one computed at the same location.
     // That would cause memcmp to compare an array against itself. We could add
     // a check that verifies that the arrays are not the same. If we did that and
     // modified AESReadTag to just copy all 128 bits into a provided array,
     // we could save 16 bytes of stack space while making the API much more
     // complicated.
     uint8_t computedTag[AES_BLOCK_SIZE];
 
     resultStatus = AESReadTag(computedTag, tagLength);
 
     if (resultStatus != AES_SUCCESS) {
         return resultStatus;
     }
 
     resultStatus = memcmp(computedTag, tag, tagLength);
 
     if (resultStatus != 0) {
         return AES_TAG_VERIFICATION_FAILED;
     }
 
     return AES_SUCCESS;
 }

Here is the call graph for this function:

uint32_t AESWaitForIRQFlags ( uint32_t irqFlags )

Poll the interrupt status register and clear when done.

This function polls until one of the bits in the irqFlags is asserted. Only AES_DMA_IN_DONE and AES_RESULT_RDY can actually trigger the interrupt line. That means that one of those should always be included in irqFlags and will always be returned together with any error codes.

Parameters

[in]

irqFlags

IRQ flags to poll and mask that the status register will be masked with. May consist of any bitwise OR of the flags below that includes at least one of AES_DMA_IN_DONE or AES_RESULT_RDY :

Returns

Returns the IRQ status register masked with irqFlags. May be any bitwise OR of the following masks:

Referenced by AESWriteToKeyStore().

 {
     uint32_t irqTrigger = 0;
     // Wait for the DMA operation to complete. Add a delay to make sure we are
     // not flooding the bus with requests too much.
     do {
         CPUdelay(1);
     }
     while(!(HWREG(CRYPTO_BASE + CRYPTO_O_IRQSTAT) & irqFlags & (CRYPTO_IRQSTAT_DMA_IN_DONE_M |
                                                                 CRYPTO_IRQSTAT_RESULT_AVAIL_M |
                                                                 CRYPTO_IRQSTAT_DMA_BUS_ERR_M |
                                                                 CRYPTO_IRQSTAT_KEY_ST_WR_ERR_M)));
 
     // Save the IRQ trigger source
     irqTrigger = HWREG(CRYPTO_BASE + CRYPTO_O_IRQSTAT) & irqFlags;
 
     // Clear IRQ flags
     HWREG(CRYPTO_BASE + CRYPTO_O_IRQCLR) = irqTrigger;
 
     return irqTrigger;
 }

Here is the call graph for this function:

void AESWriteCCMInitializationVector	(	const uint8_t *	nonce,
		uint32_t	nonceLength
	)

Generate and load the initialization vector for a CCM operation.

Parameters

[in]	nonce	Pointer to a nonce of length `nonceLength`.
[in]	nonceLength	Number of bytes to copy from `nonce` when creating the CCM IV. The L-value is also derived from it.

Returns: None

 {
     union {
         uint32_t word[4];
         uint8_t  byte[16];
     } initializationVector = {{0}};
 
     initializationVector.byte[0] = 15 - nonceLength - 1;
 
     memcpy(&(initializationVector.byte[1]), nonce, nonceLength);
 
     AESSetInitializationVector(initializationVector.word);
 }

Here is the call graph for this function:

uint32_t AESWriteToKeyStore	(	const uint8_t *	aesKey,
		uint32_t	aesKeyLength,
		uint32_t	keyStoreArea
	)

Transfer a key from main memory to a key area within the key store.

The crypto DMA transfers the key and function does not return until the operation completes. The keyStore can only contain valid keys of one aesKeyLength at any one point in time. The keyStore cannot contain both 128-bit and 256-bit keys simultaneously. When a key of a different aesKeyLength from the previous aesKeyLength is loaded, all previous keys are invalidated.

Parameters

[in]	aesKey	Pointer to key. Does not need to be word-aligned.
[in]	aesKeyLength	The key size in bytes. Currently, 128-bit, 192-bit, and 256-bit keys are supported. AES_128_KEY_LENGTH_BYTES AES_192_KEY_LENGTH_BYTES AES_256_KEY_LENGTH_BYTES
[in]	keyStoreArea	The key store area to transfer the key to. When using 128-bit keys, only the specified key store area will be occupied. When using 256-bit or 192-bit keys, two consecutive key areas are used to store the key. AES_KEY_AREA_0 AES_KEY_AREA_1 AES_KEY_AREA_2 AES_KEY_AREA_3 AES_KEY_AREA_4 AES_KEY_AREA_5 AES_KEY_AREA_6 AES_KEY_AREA_7 When using 256-bit or 192-bit keys, the 8 `keyStoreArea's` are split into four sets of two. Selecting any `keyStoreArea` automatically occupies the second `keyStoreArea` of the tuples below: (AES_KEY_AREA_0, AES_KEY_AREA_1) (AES_KEY_AREA_2, AES_KEY_AREA_3) (AES_KEY_AREA_4, AES_KEY_AREA_5) (AES_KEY_AREA_6, AES_KEY_AREA_7) For example: if `keyStoreArea` == AES_KEY_AREA_2, both AES_KEY_AREA_2 and AES_KEY_AREA_3 are occupied. If `keyStoreArea` == AES_KEY_AREA_5, both AES_KEY_AREA_4 and AES_KEY_AREA_5 are occupied.

Returns

Returns a status code depending on the result of the transfer. If there was an error in the read process itself, an error is returned. Otherwise, a success code is returned.

See also: AESReadFromKeyStore

 {
     // Check the arguments.
     ASSERT((keyStoreArea == AES_KEY_AREA_0) ||
            (keyStoreArea == AES_KEY_AREA_1) ||
            (keyStoreArea == AES_KEY_AREA_2) ||
            (keyStoreArea == AES_KEY_AREA_3) ||
            (keyStoreArea == AES_KEY_AREA_4) ||
            (keyStoreArea == AES_KEY_AREA_5) ||
            (keyStoreArea == AES_KEY_AREA_6) ||
            (keyStoreArea == AES_KEY_AREA_7));
 
     ASSERT((aesKeyLength == AES_128_KEY_LENGTH_BYTES) ||
            (aesKeyLength == AES_192_KEY_LENGTH_BYTES) ||
            (aesKeyLength == AES_256_KEY_LENGTH_BYTES));
 
     uint32_t keySize = 0;
 
     switch (aesKeyLength) {
         case AES_128_KEY_LENGTH_BYTES:
             keySize = CRYPTO_KEYSIZE_SIZE_128_BIT;
             break;
         case AES_192_KEY_LENGTH_BYTES:
             keySize = CRYPTO_KEYSIZE_SIZE_192_BIT;
             break;
         case AES_256_KEY_LENGTH_BYTES:
             keySize = CRYPTO_KEYSIZE_SIZE_256_BIT;
             break;
     }
 
     // Clear any previously written key at the keyLocation
     AESInvalidateKey(keyStoreArea);
 
     // Disable the external interrupt to stop the interrupt form propagating
     // from the module to the System CPU.
     IntDisable(INT_CRYPTO_RESULT_AVAIL_IRQ);
 
     // Enable internal interrupts.
     HWREG(CRYPTO_BASE + CRYPTO_O_IRQTYPE) = CRYPTO_IRQTYPE_LEVEL_M;
     HWREG(CRYPTO_BASE + CRYPTO_O_IRQEN) = CRYPTO_IRQEN_DMA_IN_DONE_M | CRYPTO_IRQEN_RESULT_AVAIL_M;
 
     // Configure master control module.
     HWREG(CRYPTO_BASE + CRYPTO_O_ALGSEL) = CRYPTO_ALGSEL_KEY_STORE;
 
     // Clear any outstanding events.
     HWREG(CRYPTO_BASE + CRYPTO_O_IRQCLR) = (CRYPTO_IRQCLR_DMA_IN_DONE | CRYPTO_IRQCLR_RESULT_AVAIL);
 
     // Configure the size of keys contained within the key store
     // Do not write to the register if the correct key size is already set.
     // Writing to this register causes all current keys to be invalidated.
     uint32_t keyStoreKeySize = HWREG(CRYPTO_BASE + CRYPTO_O_KEYSIZE);
     if (keySize != keyStoreKeySize) {
         HWREG(CRYPTO_BASE + CRYPTO_O_KEYSIZE) = keySize;
     }
 
     // Enable key to write (e.g. Key 0).
     HWREG(CRYPTO_BASE + CRYPTO_O_KEYWRITEAREA) = 1 << keyStoreArea;
 
     // Total key length in bytes (16 for 1 x 128-bit key and 32 for 1 x 256-bit key).
     AESStartDMAOperation(aesKey, aesKeyLength, 0, 0);
 
     // Wait for the DMA operation to complete.
     uint32_t irqTrigger = AESWaitForIRQFlags(CRYPTO_IRQCLR_RESULT_AVAIL | CRYPTO_IRQCLR_DMA_IN_DONE | CRYPTO_IRQSTAT_DMA_BUS_ERR | CRYPTO_IRQSTAT_KEY_ST_WR_ERR);
 
     // Re-enable interrupts globally.
     IntPendClear(INT_CRYPTO_RESULT_AVAIL_IRQ);
     IntEnable(INT_CRYPTO_RESULT_AVAIL_IRQ);
 
     // If we had a bus error or the key is not in the CRYPTO_O_KEYWRITTENAREA, return an error.
     if ((irqTrigger & (CRYPTO_IRQSTAT_DMA_BUS_ERR_M | CRYPTO_IRQSTAT_KEY_ST_WR_ERR_M)) || !(HWREG(CRYPTO_BASE + CRYPTO_O_KEYWRITTENAREA) & (1 << keyStoreArea))) {
         // There was an error in writing to the keyStore.
         return AES_KEYSTORE_ERROR;
     }
     else {
         return AES_SUCCESS;
     }
 }