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... | |
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.
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.
|
inlinestatic |
Clear key registers as required for AES CBC-MAC.
void AESClearDataIn | ( | void | ) |
void AESClearKey2 | ( | void | ) |
Clear the crypto module KEY2 registers.
Referenced by AESCBCMACClearKeys(), and AESGetCtrl().
void AESClearKey3 | ( | void | ) |
Clear the crypto module KEY3 registers.
Referenced by AESCBCMACClearKeys(), and AESGetCtrl().
void AESConfigureCCMCtrl | ( | uint32_t | nonceLength, |
uint32_t | macLength, | ||
bool | encrypt | ||
) |
Configure AES engine for CCM operation.
[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.
|
void AESDMAReset | ( | void | ) |
|
inlinestatic |
|
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.
[in] | intFlags | is a bit mask of the interrupt sources to be cleared. |
|
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.
[in] | intFlags | is the bitwise OR of the interrupt sources to be enabled. |
|
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.
[in] | intFlags | is the bitwise OR of the interrupt sources to be enabled. |
|
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.
handlerFxn | is a pointer to the function to be called when the crypto interrupt occurs. |
|
inlinestatic |
Get the current masked interrupt status.
This function returns the masked interrupt status of the crypto module.
|
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.
|
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.
|
inlinestatic |
Invalidate a key in the key store.
[in] | keyStoreArea | is the entry in the key store to invalidate. This permanently deletes the key from the key store. |
Referenced by AESWriteToKeyStore().
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
.
[out] | iv | Pointer to an array with four 32-bit elements (16-bytes). |
Referenced by AESReadNonAuthenticationModeIV().
void AESReadDataOut | ( | uint32_t * | dataOutBuffer | ) |
Read the crypto module DATA_OUT registers.
[out] | dataOutBuffer | Pointer to the 4 x 32-bit buffer to output data from AES_DATA_OUT_0 .. AES_DATA_OUT_3 registers. |
Referenced by AESGetCtrl().
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.
[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. |
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.
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
.
[out] | iv | Pointer to an array with four 32-bit elements (16-bytes). |
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
.
[out] | tag | Pointer to an array of tagLength bytes. |
[in] | tagLength | Number of bytes to copy to tag . |
Referenced by AESVerifyTag().
void AESReset | ( | void | ) |
Reset the accelerator and cancel ongoing operations.
Referenced by AESSetAuthLength().
|
inlinestatic |
Select type of operation.
[in] | algorithm | Flags that specify which type of operation the crypto module shall perform. The flags are mutually exclusive.
|
|
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.
[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:
|
Referenced by AESReset().
|
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:
[in] | ctrlMask | Specifies which register fields shall be set. |
Referenced by AESConfigureCCMCtrl(), and AESReset().
|
inlinestatic |
Specify length of the crypto operation.
Despite specifying it here, the crypto DMA must still be set up with the correct data length.
[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:
|
Referenced by AESReset().
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:
[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. |
Referenced by AESWriteCCMInitializationVector().
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.
[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.
|
[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.
|
Referenced by AESWriteToKeyStore().
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
.
[in] | tag | Pointer to an array of tagLength bytes. |
[in] | tagLength | Number of bytes to compare. |
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.
[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 : |
irqFlags
. May be any bitwise OR of the following masks:
Referenced by AESWriteToKeyStore().
void AESWriteCCMInitializationVector | ( | const uint8_t * | nonce, |
uint32_t | nonceLength | ||
) |
Generate and load the initialization vector for a CCM operation.
[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. |
void AESWriteDataIn | ( | const uint32_t * | dataInBuffer | ) |
Write the crypto module DATA_IN registers.
[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. |
Referenced by AESGetCtrl().
void AESWriteKey2 | ( | const uint32_t * | key2 | ) |
Write the crypto module KEY2 registers.
[in] | key2 | Pointer to the 4 x 32-bit key-material to be written to AES_KEY2_0 .. AES_KEY2_3 registers. |
Referenced by AESGetCtrl().
void AESWriteKey3 | ( | const uint32_t * | key3 | ) |
Write the crypto module KEY3 registers.
[in] | key3 | Pointer to the 4 x 32-bit key-material to be written to AES_KEY3_0 .. AES_KEY3_3 registers. |
Referenced by AESGetCtrl().
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.
[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. |
[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.
|
#define AES_128_KEY_LENGTH_BYTES (128 / 8) |
Referenced by AESWriteToKeyStore().
#define AES_192_KEY_LENGTH_BYTES (192 / 8) |
Referenced by AESWriteToKeyStore().
#define AES_256_KEY_LENGTH_BYTES (256 / 8) |
Referenced by AESWriteToKeyStore().
#define AES_ALGSEL_AES CRYPTO_ALGSEL_AES_M |
Referenced by AESSelectAlgorithm().
#define AES_ALGSEL_KEY_STORE CRYPTO_ALGSEL_KEY_STORE_M |
Referenced by AESSelectAlgorithm().
#define AES_ALGSEL_TAG CRYPTO_ALGSEL_TAG_M |
Referenced by AESSelectAlgorithm().
#define AES_BLOCK_SIZE 16 |
Referenced by AESReadTag(), and AESVerifyTag().
#define AES_CTR_WIDTH_128 0x3 |
#define AES_CTR_WIDTH_32 0x0 |
#define AES_CTR_WIDTH_64 0x1 |
#define AES_CTR_WIDTH_96 0x2 |
#define AES_DMA_BUS_ERR CRYPTO_IRQCLR_DMA_BUS_ERR_M |
#define AES_DMA_BUSY 3 |
#define AES_DMA_CHANNEL0_ACTIVE CRYPTO_DMASTAT_CH0_ACT_M |
#define AES_DMA_CHANNEL1_ACTIVE CRYPTO_DMASTAT_CH1_ACT_M |
#define AES_DMA_ERROR 4 |
#define AES_DMA_IN_DONE CRYPTO_IRQEN_DMA_IN_DONE_M |
Referenced by AESIntClear(), AESIntDisable(), and AESIntEnable().
#define AES_DMA_PORT_ERROR CRYPTO_DMASTAT_PORT_ERR_M |
#define AES_IV_LENGTH_BYTES 16 |
#define AES_KEY_AREA_0 0 |
Referenced by AESInvalidateKey(), AESReadFromKeyStore(), and AESWriteToKeyStore().
#define AES_KEY_AREA_1 1 |
Referenced by AESInvalidateKey(), AESReadFromKeyStore(), and AESWriteToKeyStore().
#define AES_KEY_AREA_2 2 |
Referenced by AESInvalidateKey(), AESReadFromKeyStore(), and AESWriteToKeyStore().
#define AES_KEY_AREA_3 3 |
Referenced by AESInvalidateKey(), AESReadFromKeyStore(), and AESWriteToKeyStore().
#define AES_KEY_AREA_4 4 |
Referenced by AESInvalidateKey(), AESReadFromKeyStore(), and AESWriteToKeyStore().
#define AES_KEY_AREA_5 5 |
Referenced by AESInvalidateKey(), AESReadFromKeyStore(), and AESWriteToKeyStore().
#define AES_KEY_AREA_6 6 |
Referenced by AESInvalidateKey(), AESReadFromKeyStore(), and AESWriteToKeyStore().
#define AES_KEY_AREA_7 7 |
Referenced by AESInvalidateKey(), AESReadFromKeyStore(), and AESWriteToKeyStore().
#define AES_KEY_ST_RD_ERR CRYPTO_IRQCLR_KEY_ST_RD_ERR_M |
#define AES_KEY_ST_WR_ERR CRYPTO_IRQCLR_KEY_ST_WR_ERR_M |
#define AES_KEYSTORE_AREA_INVALID 2 |
Referenced by AESReadFromKeyStore().
#define AES_KEYSTORE_ERROR 1 |
Referenced by AESReadFromKeyStore(), and AESWriteToKeyStore().
#define AES_RESULT_RDY CRYPTO_IRQEN_RESULT_AVAIL_M |
Referenced by AESIntClear(), AESIntDisable(), and AESIntEnable().
#define AES_SUCCESS 0 |
Referenced by AESReadFromKeyStore(), AESReadTag(), AESVerifyTag(), and AESWriteToKeyStore().
#define AES_TAG_LENGTH_BYTES 16 |
#define AES_TAG_NOT_READY 5 |
#define AES_TAG_VERIFICATION_FAILED 6 |
Referenced by AESVerifyTag().