Description

Advanced Encryption Standard Accelerator (AES) Peripheral API.

This module contains functions to control the AES peripheral of Silicon Labs 32-bit MCUs and SoCs.

The AES peripheral supports AES block cipher encryption and decryption with 128 bit and 256 bit keys. The following block cipher modes are supported:

CBC - Cipher Block Chaining mode
CFB - Cipher Feedback mode
CTR - Counter mode
ECB - Electronic Code Book mode
OFB - Output Feedback mode

The following input/output notations should be noted:

Input/output data (plaintext, ciphertext, key, and so on) are treated as byte arrays, starting with the most significant byte, i.e., 32 bytes of plaintext (B0...B31) is located in memory in the same order, with B0 at the lower address and B31 at the higher address.

Byte arrays must always be a multiple of AES block size, i.e., a multiple of 16. Padding, if required, is done at the end of the byte array.

Byte arrays should be word (32 bit) aligned for performance considerations, since the array is accessed with a 32 bit access type. Cortex-M supports unaligned accesses with a performance penalty.

It is possible to specify the same output buffer as an input buffer as long as they point to the same address. In that case, the provided input buffer is replaced with the encrypted/decrypted output. Notice that buffers must be exactly overlapping. If partly overlapping, the behavior is undefined.

Use a cipher mode according to its requirements to avoid breaking security. See a specific cipher mode theory for details.

References:

Wikipedia - Cipher modes, http://en.wikipedia.org/wiki/Cipher_modes

Recommendation for Block Cipher Modes of Operation, NIST Special Publication 800-38A, 2001 Edition, http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf

The following example shows how to perform an AES-128 CBC encryption:

Enable clocks:

/* AES is a HFCORECLK peripheral */

CMU_ClockEnable ( cmuClock_AES , true );

Execute AES-128 CBC encryption:

       
        /* Encrypt a plaintext message (64 bytes) using the AES CBC block cipher mode with a 128 bits key and initial vector (iv) of 16 bytes.  */
       
        const
       
       uint8_t plaintext[64] = { 0x6B, 0xC1, 0xBE, 0xE2, 0x2E, 0x40, 0x9F, 0x96,
      
       0xE9, 0x3D, 0x7E, 0x11, 0x73, 0x93, 0x17, 0x2A,
      
       0xAE, 0x2D, 0x8A, 0x57, 0x1E, 0x03, 0xAC, 0x9C,
      
       0x9E, 0xB7, 0x6F, 0xAC, 0x45, 0xAF, 0x8E, 0x51,
      
       0x30, 0xC8, 0x1C, 0x46, 0xA3, 0x5C, 0xE4, 0x11,
      
       0xE5, 0xFB, 0xC1, 0x19, 0x1A, 0x0A, 0x52, 0xEF,
      
       0xF6, 0x9F, 0x24, 0x45, 0xDF, 0x4F, 0x9B, 0x17,
      
       0xAD, 0x2B, 0x41, 0x7B, 0xE6, 0x6C, 0x37, 0x10 };
      
        const
       
       uint8_t key[16] = { 0x2B, 0x7E, 0x15, 0x16, 0x28, 0xAE, 0xD2, 0xA6,
      
       0xAB, 0xF7, 0x15, 0x88, 0x09, 0xCF, 0x4F, 0x3C };
      
        const
       
       uint8_t iv[16] = { 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
      
       0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F };
      
       uint8_t ciphertext[64];
       
        /* Output buffer for encrypted data (ciphertext). */
       
        AES_CBC128
       
       (ciphertext, plaintext, 64, key, iv,
       
        true
       
       );
       
        /* true means encrypt. */

Functions
void	AES_CBC128 (uint8_t out, const uint8_t in, unsigned int len, const uint8_t key, const uint8_t iv, bool encrypt)
	Cipher-block chaining (CBC) cipher mode encryption/decryption, 128 bit key.

void	AES_CBC256 (uint8_t out, const uint8_t in, unsigned int len, const uint8_t key, const uint8_t iv, bool encrypt)
	Cipher-block chaining (CBC) cipher mode encryption/decryption, 256 bit key.

void	AES_CFB128 (uint8_t out, const uint8_t in, unsigned int len, const uint8_t key, const uint8_t iv, bool encrypt)
	Cipher feedback (CFB) cipher mode encryption/decryption, 128 bit key.

void	AES_CFB256 (uint8_t out, const uint8_t in, unsigned int len, const uint8_t key, const uint8_t iv, bool encrypt)
	Cipher feedback (CFB) cipher mode encryption/decryption, 256 bit key.

void	AES_CTR128 (uint8_t out, const uint8_t in, unsigned int len, const uint8_t key, uint8_t ctr, AES_CtrFuncPtr_TypeDef ctrFunc)
	Counter (CTR) cipher mode encryption/decryption, 128 bit key.

void	AES_CTR256 (uint8_t out, const uint8_t in, unsigned int len, const uint8_t key, uint8_t ctr, AES_CtrFuncPtr_TypeDef ctrFunc)
	Counter (CTR) cipher mode encryption/decryption, 256 bit key.

void	AES_CTRUpdate32Bit (uint8_t *ctr)
	Update last 32 bits of 128 bit counter by incrementing with 1.

void	AES_DecryptKey128 (uint8_t out, const uint8_t in)
	Generate a 128 bit decryption key from the 128 bit encryption key.

void	AES_DecryptKey256 (uint8_t out, const uint8_t in)
	Generate a 256 bit decryption key from the 256 bit encryption key.

void	AES_ECB128 (uint8_t out, const uint8_t in, unsigned int len, const uint8_t *key, bool encrypt)
	Electronic Codebook (ECB) cipher mode encryption/decryption, 128 bit key.

void	AES_ECB256 (uint8_t out, const uint8_t in, unsigned int len, const uint8_t *key, bool encrypt)
	Electronic Codebook (ECB) cipher mode encryption/decryption, 256 bit key.

void	AES_OFB128 (uint8_t out, const uint8_t in, unsigned int len, const uint8_t key, const uint8_t iv)
	Output feedback (OFB) cipher mode encryption/decryption, 128 bit key.

void	AES_OFB256 (uint8_t out, const uint8_t in, unsigned int len, const uint8_t key, const uint8_t iv)
	Output feedback (OFB) cipher mode encryption/decryption, 256 bit key.

void	AES_IntClear (uint32_t flags)
	Clear one or more pending AES interrupts.

void	AES_IntDisable (uint32_t flags)
	Disable one or more AES interrupts.

void	AES_IntEnable (uint32_t flags)
	Enable one or more AES interrupts.

uint32_t	AES_IntGet (void)
	Get pending AES interrupt flags.

uint32_t	AES_IntGetEnabled (void)
	Get enabled and pending AES interrupt flags.

void	AES_IntSet (uint32_t flags)
	Set one or more pending AES interrupts from software.

Typedefs
typedef void(*	AES_CtrFuncPtr_TypeDef ) (uint8_t *ctr)
	An AES counter modification function pointer.

Function Documentation

◆ AES_CBC128()

void AES_CBC128	(	uint8_t *	`out,`
		const uint8_t *	`in,`
		unsigned int	`len,`
		const uint8_t *	`key,`
		const uint8_t *	`iv,`
		bool	`encrypt`
	)

Cipher-block chaining (CBC) cipher mode encryption/decryption, 128 bit key.

Encryption:

*           Plaintext                  Plaintext
*               |                          |
*               V                          V
* InitVector ->XOR        +-------------->XOR
*               |         |                |
*               V         |                V
*       +--------------+  |        +--------------+
* Key ->| Block cipher |  |  Key ->| Block cipher |
*       |  encryption  |  |        |  encryption  |
*       +--------------+  |        +--------------+
*               |---------+                |
*               V                          V
*           Ciphertext                 Ciphertext
*

Decryption:

*         Ciphertext                 Ciphertext
*              |----------+                |
*              V          |                V
*       +--------------+  |        +--------------+
* Key ->| Block cipher |  |  Key ->| Block cipher |
*       |  decryption  |  |        |  decryption  |
*       +--------------+  |        +--------------+
*               |         |                |
*               V         |                V
* InitVector ->XOR        +-------------->XOR
*               |                          |
*               V                          V
*           Plaintext                  Plaintext
*

See general comments on layout and byte ordering of parameters.

Parameters

[out]	`out`	A buffer to place encrypted/decrypted data. Must be at least `len` long. It may be set equal to `in` , in which case the input buffer is overwritten.
[in]	`in`	A buffer holding data to encrypt/decrypt. Must be at least `len` long.
[in]	`len`	A number of bytes to encrypt/decrypt. Must be a multiple of 16.
[in]	`key`	When encrypting, this is the 128 bit encryption key. When decrypting, this is the 128 bit decryption key. The decryption key may be generated from the encryption key with AES_DecryptKey128() . On devices supporting key buffering, this argument can be null. If so, the key will not be loaded as it is assumed the key has been loaded into KEYHA previously.
[in]	`iv`	128 bit initialization vector.
[in]	`encrypt`	Set to true to encrypt, false to decrypt.

◆ AES_CBC256()

void AES_CBC256	(	uint8_t *	`out,`
		const uint8_t *	`in,`
		unsigned int	`len,`
		const uint8_t *	`key,`
		const uint8_t *	`iv,`
		bool	`encrypt`
	)

Cipher-block chaining (CBC) cipher mode encryption/decryption, 256 bit key.

See AES_CBC128() for the CBC figure.

See general comments on layout and byte ordering of parameters.

Parameters

[out]	`out`	A buffer to place encrypted/decrypted data. Must be at least `len` long. It may be set equal to `in` , in which case the input buffer is overwritten.
[in]	`in`	A buffer holding data to encrypt/decrypt. Must be at least `len` long.
[in]	`len`	A number of bytes to encrypt/decrypt. Must be a multiple of 16.
[in]	`key`	When encrypting, this is the 256 bit encryption key. When decrypting, this is the 256 bit decryption key. The decryption key may be generated from the encryption key with AES_DecryptKey256() .
[in]	`iv`	128 bit initialization vector to use.
[in]	`encrypt`	Set to true to encrypt, false to decrypt.

◆ AES_CFB128()

void AES_CFB128	(	uint8_t *	`out,`
		const uint8_t *	`in,`
		unsigned int	`len,`
		const uint8_t *	`key,`
		const uint8_t *	`iv,`
		bool	`encrypt`
	)

Cipher feedback (CFB) cipher mode encryption/decryption, 128 bit key.

Encryption:

*           InitVector    +----------------+
*               |         |                |
*               V         |                V
*       +--------------+  |        +--------------+
* Key ->| Block cipher |  |  Key ->| Block cipher |
*       |  encryption  |  |        |  encryption  |
*       +--------------+  |        +--------------+
*               |         |                |
*               V         |                V
*  Plaintext ->XOR        |   Plaintext ->XOR
*               |---------+                |
*               V                          V
*           Ciphertext                 Ciphertext
*

Decryption:

*          InitVector     +----------------+
*               |         |                |
*               V         |                V
*       +--------------+  |        +--------------+
* Key ->| Block cipher |  |  Key ->| Block cipher |
*       |  encryption  |  |        |  encryption  |
*       +--------------+  |        +--------------+
*               |         |                |
*               V         |                V
*              XOR<- Ciphertext           XOR<- Ciphertext
*               |                          |
*               V                          V
*           Plaintext                  Plaintext
*

See general comments on layout and byte ordering of parameters.

Parameters

[out]	`out`	A buffer to place encrypted/decrypted data. Must be at least `len` long. It may be set equal to `in` , in which case the input buffer is overwritten.
[in]	`in`	A buffer holding data to encrypt/decrypt. Must be at least `len` long.
[in]	`len`	A number of bytes to encrypt/decrypt. Must be a multiple of 16.
[in]	`key`	128 bit encryption key is used for both encryption and decryption modes.
[in]	`iv`	128 bit initialization vector to use.
[in]	`encrypt`	Set to true to encrypt, false to decrypt.

◆ AES_CFB256()

void AES_CFB256	(	uint8_t *	`out,`
		const uint8_t *	`in,`
		unsigned int	`len,`
		const uint8_t *	`key,`
		const uint8_t *	`iv,`
		bool	`encrypt`
	)

Cipher feedback (CFB) cipher mode encryption/decryption, 256 bit key.

See AES_CFB128() for the CFB figure.

See general comments on layout and byte ordering of parameters.

Parameters

[out]	`out`	A buffer to place encrypted/decrypted data. Must be at least `len` long. It may be set equal to `in` , in which case the input buffer is overwritten.
[in]	`in`	A buffer holding data to encrypt/decrypt. Must be at least `len` long.
[in]	`len`	A number of bytes to encrypt/decrypt. Must be a multiple of 16.
[in]	`key`	256 bit encryption key is used for both encryption and decryption modes.
[in]	`iv`	128 bit initialization vector to use.
[in]	`encrypt`	Set to true to encrypt, false to decrypt.

◆ AES_CTR128()

void AES_CTR128	(	uint8_t *	`out,`
		const uint8_t *	`in,`
		unsigned int	`len,`
		const uint8_t *	`key,`
		uint8_t *	`ctr,`
		AES_CtrFuncPtr_TypeDef	`ctrFunc`
	)

Counter (CTR) cipher mode encryption/decryption, 128 bit key.

Encryption:

*           Counter                    Counter
*              |                          |
*              V                          V
*       +--------------+           +--------------+
* Key ->| Block cipher |     Key ->| Block cipher |
*       |  encryption  |           |  encryption  |
*       +--------------+           +--------------+
*              |                          |
* Plaintext ->XOR            Plaintext ->XOR
*              |                          |
*              V                          V
*         Ciphertext                 Ciphertext
*

Decryption:

*           Counter                    Counter
*              |                          |
*              V                          V
*       +--------------+           +--------------+
* Key ->| Block cipher |     Key ->| Block cipher |
*       |  encryption  |           |  encryption  |
*       +--------------+           +--------------+
*               |                          |
* Ciphertext ->XOR           Ciphertext ->XOR
*               |                          |
*               V                          V
*           Plaintext                  Plaintext
*

See general comments on layout and byte ordering of parameters.

Parameters

[out]	`out`	A buffer to place encrypted/decrypted data. Must be at least `len` long. It may be set equal to `in` , in which case the input buffer is overwritten.
[in]	`in`	A buffer holding data to encrypt/decrypt. Must be at least `len` long.
[in]	`len`	A number of bytes to encrypt/decrypt. Must be a multiple of 16.
[in]	`key`	128 bit encryption key. On devices supporting key buffering this argument can be null. If so, the key will not be loaded, as it is assumed the key has been loaded into KEYHA previously.
[in,out]	`ctr`	128 bit initial counter value. The counter is updated after each AES block encoding through use of `ctrFunc` .
[in]	`ctrFunc`	A function used to update the counter value.

◆ AES_CTR256()

void AES_CTR256	(	uint8_t *	`out,`
		const uint8_t *	`in,`
		unsigned int	`len,`
		const uint8_t *	`key,`
		uint8_t *	`ctr,`
		AES_CtrFuncPtr_TypeDef	`ctrFunc`
	)

Counter (CTR) cipher mode encryption/decryption, 256 bit key.

See AES_CTR128() for CTR figure.

See general comments on layout and byte ordering of parameters.

Parameters

[out]	`out`	A buffer to place encrypted/decrypted data. Must be at least `len` long. It may be set equal to `in` , in which case the input buffer is overwritten.
[in]	`in`	A buffer holding data to encrypt/decrypt. Must be at least `len` long.
[in]	`len`	A number of bytes to encrypt/decrypt. Must be a multiple of 16.
[in]	`key`	256 bit encryption key.
[in,out]	`ctr`	128 bit initial counter value. The counter is updated after each AES block encoding through use of `ctrFunc` .
[in]	`ctrFunc`	Function used to update counter value.

◆ AES_CTRUpdate32Bit()

void AES_CTRUpdate32Bit ( uint8_t *

AES - AES Accelerator

Description

Functions

Typedefs

Function Documentation

◆ AES_CBC128()

◆ AES_CBC256()

◆ AES_CFB128()

◆ AES_CFB256()

◆ AES_CTR128()

◆ AES_CTR256()

◆ AES_CTRUpdate32Bit()