[aes.h] Advanced Encryption Standard

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	AESReadNonAuthenticationModeIV (uint32_t *iv)
	Read the initialization vector (IV) out from the crypto module for Non-Authenticated Modes (CBC or CTR). More...
void	AESReadAuthenticationModeIV (uint32_t *iv)
	Read the initialization vector (IV) out from the crypto module for Authenticated Modes (CCM or GCM). 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...
void	AESReset (void)
	Reset the accelerator and cancel ongoing operations. More...
void	AESDMAReset (void)
	Reset the accelerator DMA. 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...
static uint32_t	AESGetCtrl (void)
	Read the Crypto module control and mode register value. More...
void	AESWriteKey2 (const uint32_t *key2)
	Write the crypto module KEY2 registers. More...
void	AESWriteKey3 (const uint32_t *key3)
	Write the crypto module KEY3 registers. More...
void	AESClearDataIn (void)
	Clear the crypto module DATA_IN registers. More...
void	AESWriteDataIn (const uint32_t *dataInBuffer)
	Write the crypto module DATA_IN registers. More...
void	AESReadDataOut (uint32_t *dataOutBuffer)
	Read the crypto module DATA_OUT registers. More...
void	AESClearKey2 (void)
	Clear the crypto module KEY2 registers. More...
void	AESClearKey3 (void)
	Clear the crypto module KEY3 registers. More...
static void	AESCBCMACClearKeys (void)
	Clear key registers as required for AES CBC-MAC. 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

AESCBCMACClearKeys()

static void AESCBCMACClearKeys ( void  )

inlinestatic

Clear key registers as required for AES CBC-MAC.

Returns

None

{
    AESClearKey2();
    AESClearKey3();
}

Here is the call graph for this function:

AESClearDataIn()

void AESClearDataIn

(

void

)

Clear the crypto module DATA_IN registers.

Returns

None

Referenced by AESGetCtrl().

                          {
    HWREG(CRYPTO_BASE + CRYPTO_O_AESDATAIN0) = 0;
    HWREG(CRYPTO_BASE + CRYPTO_O_AESDATAIN1) = 0;
    HWREG(CRYPTO_BASE + CRYPTO_O_AESDATAIN2) = 0;
    HWREG(CRYPTO_BASE + CRYPTO_O_AESDATAIN3) = 0;
}

AESClearKey2()

void AESClearKey2

(

void

)

Clear the crypto module KEY2 registers.

Returns

None

Referenced by AESCBCMACClearKeys(), and AESGetCtrl().

                        {
    HWREG(CRYPTO_BASE + CRYPTO_O_AESKEY20) = 0;
    HWREG(CRYPTO_BASE + CRYPTO_O_AESKEY21) = 0;
    HWREG(CRYPTO_BASE + CRYPTO_O_AESKEY22) = 0;
    HWREG(CRYPTO_BASE + CRYPTO_O_AESKEY23) = 0;
}

AESClearKey3()

void AESClearKey3

(

void

)

Clear the crypto module KEY3 registers.

Returns

None

Referenced by AESCBCMACClearKeys(), and AESGetCtrl().

                        {
    HWREG(CRYPTO_BASE + CRYPTO_O_AESKEY30) = 0;
    HWREG(CRYPTO_BASE + CRYPTO_O_AESKEY31) = 0;
    HWREG(CRYPTO_BASE + CRYPTO_O_AESKEY32) = 0;
    HWREG(CRYPTO_BASE + CRYPTO_O_AESKEY33) = 0;
}

AESConfigureCCMCtrl()

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:

AESDMAReset()

void AESDMAReset

(

void

)

Reset the accelerator DMA.

Returns

None

See also

AESReset

Referenced by AESSetAuthLength().

{
    /* Reset DMA */
    HWREG(CRYPTO_BASE + CRYPTO_O_DMASWRESET) = CRYPTO_DMASWRESET_SWRES;

    /* Wait for DMA channels to be inactive */
    while (HWREG(CRYPTO_BASE + CRYPTO_O_DMASTAT) &
           (CRYPTO_DMASTAT_CH0_ACT | CRYPTO_DMASTAT_CH1_ACT));
}

AESGetCtrl()

static uint32_t AESGetCtrl ( void  )

inlinestatic

Read the Crypto module control and mode register value.

Returns

Returns the AES_CTL register value

{
    return(HWREG(CRYPTO_BASE + CRYPTO_O_AESCTL));
}

Here is the call graph for this function:

AESIntClear()

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. AES_DMA_IN_DONE AES_RESULT_RDY

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;
}

AESIntDisable()

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. AES_DMA_IN_DONE AES_RESULT_RDY

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;
}

AESIntEnable()

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. AES_DMA_IN_DONE AES_RESULT_RDY

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;
}

AESIntRegister()

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:

AESIntStatusMasked()

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:

• AES_DMA_IN_DONE
• AES_RESULT_RDY

{
    uint32_t mask;

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

AESIntStatusRaw()

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:

• AES_DMA_IN_DONE
• AES_RESULT_RDY
• AES_DMA_BUS_ERR
• AES_KEY_ST_WR_ERR
• AES_KEY_ST_RD_ERR

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

AESIntUnregister()

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:

AESInvalidateKey()

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. 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

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);
}

AESReadAuthenticationModeIV()

void AESReadAuthenticationModeIV

(

uint32_t *

iv

)

Read the initialization vector (IV) out from the crypto module for Authenticated Modes (CCM or GCM).

This function copies the IV calculated by the crypto module in CCM or GCM mode to iv.

Precondition

AESReadTag() must be called first.

Parameters

[out]

iv

Pointer to an array with four 32-bit elements (16-bytes).

Returns

None

See also

AESReadTag()

Referenced by AESReadNonAuthenticationModeIV().

{
    /* Read the computed IV out from the hw registers */
    iv[0] = HWREG(CRYPTO_BASE + CRYPTO_O_AESIV0);
    iv[1] = HWREG(CRYPTO_BASE + CRYPTO_O_AESIV1);
    iv[2] = HWREG(CRYPTO_BASE + CRYPTO_O_AESIV2);
    /* This read will clear the saved_context_ready bit
     * and allow the AES core to start the next operation.
     */
    iv[3] = HWREG(CRYPTO_BASE + CRYPTO_O_AESIV3);
}

AESReadDataOut()

void AESReadDataOut

(

uint32_t *

dataOutBuffer

)

Read the crypto module DATA_OUT registers.

Parameters

[out]

dataOutBuffer

Pointer to the 4 x 32-bit buffer to output data from AES_DATA_OUT_0 .. AES_DATA_OUT_3 registers.

Returns

None

Referenced by AESGetCtrl().

                                             {
    dataOutBuffer[0] = HWREG(CRYPTO_BASE + CRYPTO_O_AESDATAOUT0);
    dataOutBuffer[1] = HWREG(CRYPTO_BASE + CRYPTO_O_AESDATAOUT1);
    dataOutBuffer[2] = HWREG(CRYPTO_BASE + CRYPTO_O_AESDATAOUT2);
    dataOutBuffer[3] = HWREG(CRYPTO_BASE + CRYPTO_O_AESDATAOUT3);
}

AESReadFromKeyStore()

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. 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

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.

• AES_KEYSTORE_AREA_INVALID
• AES_KEYSTORE_ERROR
• AES_SUCCESS

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:

AESReadNonAuthenticationModeIV()

void AESReadNonAuthenticationModeIV

(

uint32_t *

iv

)

Read the initialization vector (IV) out from the crypto module for Non-Authenticated Modes (CBC or CTR).

This function copies the IV calculated by the crypto module in CBC or CTR mode to iv.

Parameters

[out]

iv

Pointer to an array with four 32-bit elements (16-bytes).

Returns

None

{
    /* Wait until the saved context is ready */
    while(!(HWREG(CRYPTO_BASE + CRYPTO_O_AESCTL) & CRYPTO_AESCTL_SAVED_CONTEXT_RDY_M));

    AESReadAuthenticationModeIV(iv);
}

Here is the call graph for this function:

AESReadTag()

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;
}

AESReset()

void AESReset

(

void

)

Reset the accelerator and cancel ongoing operations.

Precondition

AESDMAReset

Returns

None

Referenced by AESSetAuthLength().

{
    /* Soft reset routine per SafeXcel */
    HWREG(CRYPTO_BASE + CRYPTO_O_SWRESET) = CRYPTO_SWRESET_SW_RESET;
    AESSetCtrl(0);
    AESSetDataLength(0);
    AESSetAuthLength(0);

}

Here is the call graph for this function:

AESSelectAlgorithm()

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. 0 : Reset the module AES_ALGSEL_AES AES_ALGSEL_TAG AES_ALGSEL_KEY_STORE

Returns

None

{
    ASSERT((algorithm == AES_ALGSEL_AES) ||
           (algorithm == AES_ALGSEL_TAG) ||
           (algorithm == AES_ALGSEL_KEY_STORE));

    HWREG(CRYPTO_BASE + CRYPTO_O_ALGSEL) = algorithm;
}

AESSetAuthLength()

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

Referenced by AESReset().

{
    HWREG(CRYPTO_BASE + CRYPTO_O_AESAUTHLEN) = length;
}

Here is the call graph for this function:

AESSetCtrl()

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(), and AESReset().

{
    HWREG(CRYPTO_BASE + CRYPTO_O_AESCTL) = ctrlMask;
}

AESSetDataLength()

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

Referenced by AESReset().

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

AESSetInitializationVector()

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.

  uint8_t initVectorLength = 12;  // Could also be 13
  
  union {
      uint32_t word[4];
      uint8_t byte[16];
  } initVector;
  
  uint8_t initVectorUnformatted[initVectorLength];
  
  // This is the same field length value that is written to the ctrl register
  initVector.byte[0] = L - 1;
  
  memcpy(&initVector.byte[1], initVectorUnformatted, initVectorLength);
  
  // Fill the remaining bytes with zeros
  for (initVectorLength++; initVectorLength < sizeof(initVector.byte); initVectorLength++) {
      initVector.byte[initVectorLength] = 0;
  }

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];
}

AESStartDMAOperation()

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;
    }
}

AESVerifyTag()

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:

AESWaitForIRQFlags()

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 : AES_DMA_IN_DONE AES_RESULT_RDY AES_DMA_BUS_ERR AES_KEY_ST_WR_ERR AES_KEY_ST_RD_ERR

Returns

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

• AES_DMA_IN_DONE
• AES_RESULT_RDY
• AES_DMA_BUS_ERR
• AES_KEY_ST_WR_ERR
• AES_KEY_ST_RD_ERR

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:

AESWriteCCMInitializationVector()

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:

AESWriteDataIn()

void AESWriteDataIn

(

const uint32_t *

dataInBuffer

)

Write the crypto module DATA_IN registers.

Parameters

[in]

dataInBuffer

Pointer to the 4 x 32-bit buffer containing data to be written to AES_DATA_IN_0 .. AES_DATA_IN_3 registers.

Returns

None

Referenced by AESGetCtrl().

                                                  {
    HWREG(CRYPTO_BASE + CRYPTO_O_AESDATAIN0) = dataInBuffer[0];
    HWREG(CRYPTO_BASE + CRYPTO_O_AESDATAIN1) = dataInBuffer[1];
    HWREG(CRYPTO_BASE + CRYPTO_O_AESDATAIN2) = dataInBuffer[2];
    HWREG(CRYPTO_BASE + CRYPTO_O_AESDATAIN3) = dataInBuffer[3];
}

AESWriteKey2()

void AESWriteKey2

(

const uint32_t *

key2

)

Write the crypto module KEY2 registers.

Parameters

[in]

key2

Pointer to the 4 x 32-bit key-material to be written to AES_KEY2_0 .. AES_KEY2_3 registers.

Returns

None

Referenced by AESGetCtrl().

                                        {
    HWREG(CRYPTO_BASE + CRYPTO_O_AESKEY20) = key2[0];
    HWREG(CRYPTO_BASE + CRYPTO_O_AESKEY21) = key2[1];
    HWREG(CRYPTO_BASE + CRYPTO_O_AESKEY22) = key2[2];
    HWREG(CRYPTO_BASE + CRYPTO_O_AESKEY23) = key2[3];
}

AESWriteKey3()

void AESWriteKey3

(

const uint32_t *

key3

)

Write the crypto module KEY3 registers.

Parameters

[in]

key3

Pointer to the 4 x 32-bit key-material to be written to AES_KEY3_0 .. AES_KEY3_3 registers.

Returns

None

Referenced by AESGetCtrl().

                                        {
    HWREG(CRYPTO_BASE + CRYPTO_O_AESKEY30) = key3[0];
    HWREG(CRYPTO_BASE + CRYPTO_O_AESKEY31) = key3[1];
    HWREG(CRYPTO_BASE + CRYPTO_O_AESKEY32) = key3[2];
    HWREG(CRYPTO_BASE + CRYPTO_O_AESKEY33) = key3[3];
}

AESWriteToKeyStore()

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.

Parameters

[in]	aesKey	Pointer to key. Does not need to be word-aligned.
[in]	aesKeyLength	The key size in bytes. 128-bit keys are supported. AES_128_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. 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

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.

• AES_KEYSTORE_ERROR
• AES_SUCCESS

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));

    uint32_t keySize = 0;

    switch (aesKeyLength) {
        case AES_128_KEY_LENGTH_BYTES:
            keySize = CRYPTO_KEYSIZE_SIZE_128_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).
    AESStartDMAOperation(aesKey, AES_128_KEY_LENGTH_BYTES, 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;
    }
}

Here is the call graph for this function:

Macro Definition Documentation

AES_128_KEY_LENGTH_BYTES

#define AES_128_KEY_LENGTH_BYTES   (128 / 8)

Referenced by AESWriteToKeyStore().

AES_ALGSEL_AES

#define AES_ALGSEL_AES   CRYPTO_ALGSEL_AES_M

Referenced by AESSelectAlgorithm().

AES_ALGSEL_KEY_STORE

#define AES_ALGSEL_KEY_STORE   CRYPTO_ALGSEL_KEY_STORE_M

Referenced by AESSelectAlgorithm().

AES_ALGSEL_TAG

#define AES_ALGSEL_TAG   CRYPTO_ALGSEL_TAG_M

Referenced by AESSelectAlgorithm().

AES_BLOCK_SIZE

#define AES_BLOCK_SIZE   16

Referenced by AESReadTag(), and AESVerifyTag().

AES_CTR_WIDTH_128

#define AES_CTR_WIDTH_128   0x3

AES_CTR_WIDTH_32

#define AES_CTR_WIDTH_32   0x0

AES_CTR_WIDTH_64

#define AES_CTR_WIDTH_64   0x1

AES_CTR_WIDTH_96

#define AES_CTR_WIDTH_96   0x2

AES_DMA_BUS_ERR

#define AES_DMA_BUS_ERR   CRYPTO_IRQCLR_DMA_BUS_ERR_M

AES_DMA_BUSY

#define AES_DMA_BUSY   3

AES_DMA_CHANNEL0_ACTIVE

#define AES_DMA_CHANNEL0_ACTIVE   CRYPTO_DMASTAT_CH0_ACT_M

AES_DMA_CHANNEL1_ACTIVE

#define AES_DMA_CHANNEL1_ACTIVE   CRYPTO_DMASTAT_CH1_ACT_M

AES_DMA_ERROR

#define AES_DMA_ERROR   4

AES_DMA_IN_DONE

#define AES_DMA_IN_DONE   CRYPTO_IRQEN_DMA_IN_DONE_M

Referenced by AESIntClear(), AESIntDisable(), and AESIntEnable().

AES_DMA_PORT_ERROR

#define AES_DMA_PORT_ERROR   CRYPTO_DMASTAT_PORT_ERR_M

AES_IV_LENGTH_BYTES

#define AES_IV_LENGTH_BYTES   16

AES_KEY_AREA_0

#define AES_KEY_AREA_0   0

Referenced by AESInvalidateKey(), AESReadFromKeyStore(), and AESWriteToKeyStore().

AES_KEY_AREA_1

#define AES_KEY_AREA_1   1

Referenced by AESInvalidateKey(), AESReadFromKeyStore(), and AESWriteToKeyStore().

AES_KEY_AREA_2

#define AES_KEY_AREA_2   2

Referenced by AESInvalidateKey(), AESReadFromKeyStore(), and AESWriteToKeyStore().

AES_KEY_AREA_3

#define AES_KEY_AREA_3   3

Referenced by AESInvalidateKey(), AESReadFromKeyStore(), and AESWriteToKeyStore().

AES_KEY_AREA_4

#define AES_KEY_AREA_4   4

Referenced by AESInvalidateKey(), AESReadFromKeyStore(), and AESWriteToKeyStore().

AES_KEY_AREA_5

#define AES_KEY_AREA_5   5

Referenced by AESInvalidateKey(), AESReadFromKeyStore(), and AESWriteToKeyStore().

AES_KEY_AREA_6

#define AES_KEY_AREA_6   6

Referenced by AESInvalidateKey(), AESReadFromKeyStore(), and AESWriteToKeyStore().

AES_KEY_AREA_7

#define AES_KEY_AREA_7   7

Referenced by AESInvalidateKey(), AESReadFromKeyStore(), and AESWriteToKeyStore().

AES_KEY_ST_RD_ERR

#define AES_KEY_ST_RD_ERR   CRYPTO_IRQCLR_KEY_ST_RD_ERR_M

AES_KEY_ST_WR_ERR

#define AES_KEY_ST_WR_ERR   CRYPTO_IRQCLR_KEY_ST_WR_ERR_M

AES_KEYSTORE_AREA_INVALID

#define AES_KEYSTORE_AREA_INVALID   2

Referenced by AESReadFromKeyStore().

AES_KEYSTORE_ERROR

#define AES_KEYSTORE_ERROR   1

Referenced by AESReadFromKeyStore(), and AESWriteToKeyStore().

AES_RESULT_RDY

#define AES_RESULT_RDY   CRYPTO_IRQEN_RESULT_AVAIL_M

Referenced by AESIntClear(), AESIntDisable(), and AESIntEnable().

AES_SUCCESS

#define AES_SUCCESS   0

Referenced by AESReadFromKeyStore(), AESReadTag(), AESVerifyTag(), and AESWriteToKeyStore().

AES_TAG_LENGTH_BYTES

#define AES_TAG_LENGTH_BYTES   16

AES_TAG_NOT_READY

#define AES_TAG_NOT_READY   5

AES_TAG_VERIFICATION_FAILED

#define AES_TAG_VERIFICATION_FAILED   6

Referenced by AESVerifyTag().