Advanced Encryption Standard library
  mikroC PRO for ARM Libraries > Crypto Libraries > 
  

Advanced Encryption Standard Library

This Library provides a set of routines for easier handling of the Advanced Encryption Standard module available on CEC1x02 and MSP432 devices.

Library Routines

aes_hash_power

Prototype

void aes_hash_power(uint8_t pwr_state);
Description

This function is used to enable or disable AES and Hash Hardware Block.
Parameters
  • pwr_state: the power state. Valid values :
    Value Description
    Non-zero Ungate clocks to block.
    0 Gate clocks to block.
Returns

Nothing.
Requires

Nothing.
Notes

AES and Hash hardware accelerators do not implement a block level clock gate control and also share AHB resources (master, internal DMA, clocking).
A single PCR sleep control will sleep both blocks. Before setting the PCR sleep bit, clear AES and Hash Control registers to stop both engines. To wake (ungated clocks) clear the PCR sleep enable bit.

aes_hash_reset

Prototype

void aes_hash_reset();
Description

This function is used to reset the AES and Hash block.
Parameters

None.
Returns

Nothing.
Requires

Nothing.
Notes

None.

aes_busy

Prototype

uint16_t aes_busy();
Description

This function is used to check if the AES block is running.
Parameters

None.
Returns
  • 1: the AES block is running.
  • 0: the AES block is not running.
Requires

Nothing.
Notes

None.

aes_status

Prototype

uint32_t aes_status();
Description

This function is used to read the status of the AES block.
Parameters

None.
Returns

The status of the AES block is reflected in the return value. The bit definitions of AES Status value is presented below :

Bit Number Definition (all bits are read only)
0 AES Busy Status (1 if busy, 0 otherwise).
1 AES CCM Mode MAC_T Calculation is valid (1 if valid, 0 otherwise; Not Supported).
2 DMA Error. (1 if error, indicates that the AES DMA Master received AHB Bus error).
Requires

Nothing.
Notes

None.

aes_done_status

Prototype

uint16_t aes_done_status(uint32_t* status_value);
Description

The function updates the status value of the AES block in the pointer argument. The done status is evaluated and it is returned as a Boolean value.
Parameters
  • status_value: pointer where the status value will be stored. Refer aes_status for bit definition of status register.
Returns
  • 1: the done status is set.
  • 0: otherwise.
Requires

Nothing.
Notes

None.

aes_stop

Prototype

uint8_t aes_stop();
Description

This function is used to stop the AES block. The function accesses the AES control register to stop the AES Operations.
Parameters

None.
Returns

The function returns the aes_busy function return value.
Requires

Nothing.
Notes

None.

aes_start

Prototype

void aes_start(uint8_t ien);
Description

This function is used to start the AES Block.
Parameters
  • ien: Boolean value to specifying the interrupt status. This value, if true, enables interrupt; if false disables interrupt.
Returns

The function returns the aes_busy function return value.
Requires

Nothing.
Notes

None.

aes_iclr

Prototype

uint32_t aes_iclr();
Description

The function is used to clear Hash interrupts. The function will return the status of AES Block. AES Status register is a read-to-clear register. If it is zero, no status is set.
Parameters

None.
Returns

The AES Status will be reflected in the return value.
Requires

Nothing.
Notes

None.

aes_set_key

Prototype // for CEC1302 MCU :

uint8_t aes_set_key(const uint32_t *pkey, const uint32_t *piv, uint8_t key_len, int16_t msbf);

// for CEC1702 MCU :

uint8_t aes_set_key(const uint32_t *pkey, const uint32_t *piv, uint8_t key_len, uint8_t msbf);
Description

The function programs the AES accelerator with key and optional initialization. AES key size and pre calculation mode are set. The AES engine is not started.
Parameters
  • pkey: Pointer to a word (32-bit) aligned buffer containing the AES key, LSB first.
  • piv: Pointer to a word (32-bit) aligned buffer containing AES initialization vector, LSB first. NULL if no Initialization vector is required.
  • key_len: key length. The permitted values are :
    • AES_KEYLEN_128,
    • AES_KEYLEN_192,
    • AES_KEYLEN_256.
  • msbf: A Boolean value indicating most significant bit first.
Returns
  • AES_OK,
    • Success,
  • AES_ERR_BAD_POINTER, if pkey is NULL,
  • AES_ERR_BAD_KEY_LEN, if key_lenkey_len is not supported.
Requires

Nothing.
Notes

Do not call this routine if the AES engine is busy.

aes_crypt

Prototype

uint8_t aes_crypt(const uint32_t *data_in, uint32_t *data_out, uint32_t num_128bit_blocks, uint8_t modes);
Description

This function programs specified AES operation using currently programmed key. The hardware permits the following modes of operation: ECB, CBC, CTR and OFB modes.
Parameters
  • data_in: pointer to word (32-bit) aligned input data buffer.
  • data_out: pointer to word (32-bit) algined output data buffer.
  • num_128bit_blocks: Size of input data as number of 128-bit(16-byte) blocks.
  • modes: AES encryption/decryption mode. Valid values :
    • AES_MODE_ECB: Electronic Codebook mode,
    • AES_MODE_CBC: Cipher Block Chaining mode,
    • AES_MODE_CTR: Counter mode,
    • AES_MODE_OFB: Output Feedback mode.
Returns
  • AES_OK - if AES HW is programmed,
  • AES_ERR_BAD_POINTER - NULL pointers or number of blocks is 0 or buffers cross CEC132x DMA boundary at 0x118000.
Requires

Nothing.
Notes

Hardware is limited to ECB, CBC, CTR and OFB modes!

AES256_setCipherKey

Prototype

uint8_t AES256_setCipherKey(uint32_t moduleInstance, const uint8_t *cipherKey, uint_fast16_t keyLength);
Description

This function loads a 128, 192 or 256 bit cipher key to AES256 module.
Parameters
  • moduleInstance: base address of the AES256 module.
  • cipherKey: pointer to an array with a length of 16 bytes that contains a 128 bit cipher key.
  • keyLength: length of the key. Valid values :
    • AES256_KEYLENGTH_128BIT
    • AES256_KEYLENGTH_192BIT
    • AES256_KEYLENGTH_256BIT
Returns
  • 1: if set correctly.
  • 0: if otherwise.
Requires

Nothing.
Notes

Available only for MSP432 devices.

AES256_encryptData

Prototype

void AES256_encryptData(uint32_t moduleInstance, const uint8_t *_data, uint8_t *encryptedData);
Description

This function encrypts a block of data using the AES256 module. The cipher key that is used for encryption should be loaded in advance by using function AES256_setCipherKey.
Parameters
  • moduleInstance: base address of the AES256 module.
  • cipherKey: pointer to an array with a length of 16 bytes that contains data to be encrypted.
  • encryptedData: pointer to an array with a length of 16 bytes in that the encrypted data will be written.
Returns

Nothing.
Requires

Nothing.
Notes

Available only for MSP432 devices.

AES256_decryptData

Prototype

void AES256_decryptData(uint32_t moduleInstance, const uint8_t *_data, uint8_t *decryptedData);
Description

This function decrypts a block of data using the AES256 module. The decryption takes 167 MCLK.
Parameters
  • moduleInstance: base address of the AES256 module.
  • _data: pointer to an array with a length of 16 bytes that contains encrypted data to be decrypted.
  • decryptedData: pointer to an array with a length of 16 bytes in that the decrypted data will be written.
Returns

Nothing.
Requires

This function requires a pregenerated decryption key. A key can be loaded and pregenerated by using function AES256_setDecipherKey or AES256_startSetDecipherKey.
Notes

Available only for MSP432 devices.

AES256_setDecipherKey

Prototype

uint8_t AES256_setDecipherKey(uint32_t moduleInstance, const uint8_t *cipherKey, uint_fast16_t keyLength);
Description

This function sets the decipher key.
Parameters
  • moduleInstance: base address of the AES256 module.
  • cipherKey: pointer to an array with a length of 16 bytes that contains 128 bit cipher key.
  • keyLength: length of the key. Valid values :
    • AES256_KEYLENGTH_128BIT
    • AES256_KEYLENGTH_192BIT
    • AES256_KEYLENGTH_256BIT
Returns
  • 1: if set correctly.
  • 0: otherwise.
Requires

The API AES256_setDecipherKey or AES256_startSetDecipherKey must be invoked before invoking AES256_setDecipherKey or AES256_startDecryptData.
Notes

Available only for MSP432 devices.

AES256_reset

Prototype

void AES256_reset(uint32_t moduleInstance);
Description

This function resets AES256 Module immediately. Modified bits are AESSWRST of AESACTL0 register.
Parameters
  • moduleInstance: base address of the AES256 module.
Returns

Nothing.
Requires

Nothing.
Notes

Available only for MSP432 devices.

AES256_startEncryptData

Prototype

void AES256_startEncryptData(uint32_t moduleInstance, const uint8_t *_data);
Description

This function starts an encryption process on the AES256 module. This is a non-blocking equivalent of AES256_encryptData.
Parameters
  • moduleInstance: base address of the AES256 module.
  • _data: pointer to an array with a length of 16 bytes that contains data to be encrypted.
Returns

Nothing.
Requires
  • The cipher key that is used for encryption should be loaded in advance by using function AES256_setCipherKey.
  • It is recommended to use the interrupt functionality to check for procedure completion then use the AES256_getDataOut API to retrieve the encrypted data.
Notes

Available only for MSP432 devices.

AES256_startDecryptData

Prototype

void AES256_startDecryptData(uint32_t moduleInstance, const uint8_t *_data);
Description

This function decypts a block of data using the AES256 module. This is a non-blocking equivalent of AES256_decryptData.
The decryption takes 167 MCLK.
Parameters
  • moduleInstance: base address of the AES256 module.
  • _data: pointer to an array with a length of 16 bytes that contains encrypted data to be decrypted.
Returns

Nothing.
Requires
Notes

Available only for MSP432 devices.

AES256_startSetDecipherKey

Prototype

uint8_t AES256_startSetDecipherKey(uint32_t moduleInstance, const uint8_t *cipherKey, uint_fast16_t keyLength);
Description

This function sets the decipher key.
Parameters
  • moduleInstance: base address of the AES256 module.
  • cipherKey: pointer to an array with a length of 16 bytes that contains a 128 bit cipher key.
  • keyLength: length of the key. Valid values :
    • AES256_KEYLENGTH_128BIT
    • AES256_KEYLENGTH_192BIT
    • AES256_KEYLENGTH_256BIT
Returns
  • 1: if set correctly.
  • 0: otherwise.
Requires

The API AES256_setDecipherKey or AES256_startSetDecipherKey must be invoked before invoking AES256_startDecryptData.
Notes

Available only for MSP432 devices.

AES256_getDataOut

Prototype

uint8_t AES256_getDataOut(uint32_t moduleInstance, uint8_t outputData);
Description

This function reads back the output data from AES256 module.
Parameters
  • moduleInstance: base address of the AES256 module.
  • outputData: pointer to an array with a length of 16 bytes in that the data will be written.
Returns
  • 1: if data is valid.
  • 0: otherwise.
Requires

This function is meant to use after an encryption or decryption process that was started and finished by initiating an interrupt by use of AES256_startEncryptData or AES256_startDecryptData.
Notes

Available only for MSP432 devices.

AES256_isBusy

Prototype

uint8_t AES256_isBusy(uint32_t moduleInstance);
Description

This function gets the AES256 module busy status.
Parameters
  • moduleInstance: base address of the AES256 module.
Returns
  • 1: if busy.
  • 0: otherwise.
Requires

Nothing.
Notes

Available only for MSP432 devices.

AES256_clearErrorFlag

Prototype

void AES256_clearErrorFlag(uint32_t moduleInstance);
Description

This function clears the AES256 error flag. Modified bits are AESERRFG of AESACTL0 register.
Parameters
  • moduleInstance: base address of the AES256 module.
Returns

Nothing.
Requires

Nothing.
Notes

Available only for MSP432 devices.

AES256_getErrorFlagStatus

Prototype

uint32_t AES256_getErrorFlagStatus(uint32_t moduleInstance);
Description

This function gets the AES256 error flag status.
Parameters
  • moduleInstance: base address of the AES256 module.
Returns
  • AES256_ERROR_OCCURRED: if there were errors.
  • AES256_NO_ERROR: if no errors.
Requires

Nothing.
Notes

Available only for MSP432 devices.

AES256_clearInterruptFlag

Prototype

void AES256_clearInterruptFlag(uint32_t moduleInstance);
Description

This function clears the AES256 ready interrupt flag. Modified bits are AESRDYIFG of AESACTL0 register.
Parameters
  • moduleInstance: base address of the AES256 module.
Returns

Nothing.
Requires

Nothing.
Notes

Available only for MSP432 devices.

AES256_getInterruptStatus

Prototype

uint32_t AES256_getInterruptStatus(uint32_t moduleInstance);
Description

This function returns the current interrupt flag for the peripheral. References AES256_getInterruptFlagStatus.
Parameters
  • moduleInstance: base address of the AES256 module.
Returns

Returns the currently triggered interrupt flag for the module.
Requires

Nothing.
Notes

Available only for MSP432 devices.

AES256_enableInterrupt

Prototype

void AES256_enableInterrupt(uint32_t moduleInstance);
Description

This function enables AES256 ready interrupt. Modified bits are AESRDYIE of AESACTL0 register.
Parameters
  • moduleInstance: base address of the AES256 module.
Returns

Nothing.
Requires

Nothing.
Notes

Available only for MSP432 devices.

AES256_disableInterrupt

Prototype

void AES256_disableInterrupt(uint32_t moduleInstance);
Description

This function disables AES256 ready interrupt. Modified bits are AESRDYIE of AESACTL0 register.
Parameters
  • moduleInstance: base address of the AES256 module.
Returns

Nothing.
Requires

Nothing.
Notes

Available only for MSP432 devices.

AES256_getInterruptFlagStatus

Prototype

uint32_t AES256_getInterruptFlagStatus(uint32_t moduleInstance);
Description

This function gets the AES256 ready interrupt flag status. Referenced by AES256_getInterruptStatus..
Parameters
  • moduleInstance: base address of the AES256 module.
Returns
  • AES256_READY_INTERRUPT: interrupt ready.
  • AES256_NOTREADY_INTERRUPT: interrupt not ready.
Requires

Nothing.
Notes

Available only for MSP432 devices.
Copyright (c) 2002-2019 mikroElektronika. All rights reserved.
What do you think about this topic ? Send us feedback!
Want more examples and libraries? 
Find them on LibStock - A place for the code