AES
Detailed Description
Advanced Encryption Standard Accelerator (AES) Peripheral API.
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. CortexM 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 80038A, 2001 Edition, http://csrc.nist.gov/publications/nistpubs/80038a/sp80038a.pdf
The following example shows how to perform an AES128 CBC encryption:
Enable clocks:
Execute AES128 CBC encryption:
This module contains functions to control the AES peripheral of Silicon Labs 32bit MCUs and SoCs.
Typedefs 

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


Functions 

void  AES_CBC128 (uint8_t *out, const uint8_t *in, unsigned int len, const uint8_t *key, const uint8_t *iv, bool encrypt) 
Cipherblock 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) 
Cipherblock 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. The decryption key is used for some cipher modes when decrypting.


void  AES_DecryptKey256 (uint8_t *out, const uint8_t *in) 
Generate a 256 bit decryption key from the 256 bit encryption key. The decryption key is used for some cipher modes when decrypting.


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.


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


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


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


__STATIC_INLINE uint32_t  AES_IntGet (void) 
Get pending AES interrupt flags.


__STATIC_INLINE uint32_t  AES_IntGetEnabled (void) 
Get enabled and pending AES interrupt flags. Useful for handling more interrupt sources in the same interrupt handler.


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


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.


Typedef Documentation
typedef void(* AES_CtrFuncPtr_TypeDef) (uint8_t *ctr) 
An AES counter modification function pointer.
Parameters:
 ctr  Ptr to byte array (16 bytes) holding a counter to be modified.
Definition at line
114
of file
em_aes.h
.
Function Documentation
void AES_CBC128  (  uint8_t * 
out,

const uint8_t * 
in,


unsigned int 
len,


const uint8_t * 
key,


const uint8_t * 
iv,


bool 
encrypt


) 
Cipherblock 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 toin
, 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.
Definition at line
125
of file
em_aes.c
.
void AES_CBC256  (  uint8_t * 
out,

const uint8_t * 
in,


unsigned int 
len,


const uint8_t * 
key,


const uint8_t * 
iv,


bool 
encrypt


) 
Cipherblock 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 toin
, 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.
Definition at line
273
of file
em_aes.c
.
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 toin
, 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.
Definition at line
424
of file
em_aes.c
.
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 toin
, 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.
Definition at line
523
of file
em_aes.c
.
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 toin
, 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.
Definition at line
640
of file
em_aes.c
.
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 toin
, 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.
Definition at line
731
of file
em_aes.c
.
void AES_CTRUpdate32Bit  (  uint8_t * 
ctr

) 
Update last 32 bits of 128 bit counter by incrementing with 1.
Notice that no special consideration is given to possible wrap around. If 32 least significant bits are 0xFFFFFFFF, they will be updated to 0x00000000, ignoring overflow.
See general comments on layout and byte ordering of parameters.
 Parameters

[in,out] ctr
A buffer holding 128 bit counter to be updated.
Definition at line
792
of file
em_aes.c
.
void AES_DecryptKey128  (  uint8_t * 
out,

const uint8_t * 
in


) 
Generate a 128 bit decryption key from the 128 bit encryption key. The decryption key is used for some cipher modes when decrypting.
See general comments on layout and byte ordering of parameters.
 Parameters

[out] out
A buffer to place 128 bit decryption key. Must be at least 16 bytes long. It may be set equal to in
, in which case the input buffer is overwritten.[in] in
A buffer holding 128 bit encryption key. Must be at least 16 bytes long.
Definition at line
814
of file
em_aes.c
.
References AES_IntClear() .
void AES_DecryptKey256  (  uint8_t * 
out,

const uint8_t * 
in


) 
Generate a 256 bit decryption key from the 256 bit encryption key. The decryption key is used for some cipher modes when decrypting.
See general comments on layout and byte ordering of parameters.
 Parameters

[out] out
A buffer to place 256 bit decryption key. Must be at least 32 bytes long. It may be set equal to in
, in which case the input buffer is overwritten.[in] in
A buffer holding 256 bit encryption key. Must be at least 32 bytes long.
Definition at line
856
of file
em_aes.c
.
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.
Encryption:
* Plaintext Plaintext *   * 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 * 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 toin
, 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() . [in] encrypt
Set to true to encrypt, false to decrypt.
Definition at line
936
of file
em_aes.c
.
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.
See AES_ECB128() for the ECB 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 toin
, 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] encrypt
Set to true to encrypt, false to decrypt.
Definition at line
1028
of file
em_aes.c
.
__STATIC_INLINE void AES_IntClear  (  uint32_t 
flags

) 
Clear one or more pending AES interrupts.
 Parameters

[in] flags
A pending AES interrupt source to clear. Use a bitwise logic OR combination of valid interrupt flags for the AES module (AES_IF_nnn).
Definition at line
198
of file
em_aes.h
.
Referenced by AES_DecryptKey128() .
__STATIC_INLINE void AES_IntDisable  (  uint32_t 
flags

) 
Disable one or more AES interrupts.
 Parameters

[in] flags
An AES interrupt sources to disable. Use a bitwise logic OR combination of valid interrupt flags for the AES module (AES_IF_nnn).
Definition at line
211
of file
em_aes.h
.
__STATIC_INLINE void AES_IntEnable  (  uint32_t 
flags

) 
Enable one or more AES interrupts.
 Note
 Depending on use, a pending interrupt may already be set prior to enabling the interrupt. Consider using AES_IntClear() prior to enabling if a pending interrupt should be ignored.
 Parameters

[in] flags
AES interrupt sources to enable. Use a bitwise logic OR combination of valid interrupt flags for the AES module (AES_IF_nnn).
Definition at line
229
of file
em_aes.h
.
__STATIC_INLINE uint32_t AES_IntGet  (  void 

) 
Get pending AES interrupt flags.
 Note
 This function does not clear event bits.
 Returns
 AES interrupt sources pending. A bitwise logic OR combination of valid interrupt flags for the AES module (AES_IF_nnn).
Definition at line
245
of file
em_aes.h
.
__STATIC_INLINE uint32_t AES_IntGetEnabled  (  void 

) 
Get enabled and pending AES interrupt flags. Useful for handling more interrupt sources in the same interrupt handler.
 Note
 This function does not clear interrupt flags.
 Returns

Pending and enabled AES interrupt sources. The return value is the bitwise AND of
 the enabled interrupt sources in AES_IEN and
 the pending interrupt flags AES_IF
Definition at line
264
of file
em_aes.h
.
__STATIC_INLINE void AES_IntSet  (  uint32_t 
flags

) 
Set one or more pending AES interrupts from software.
 Parameters

[in] flags
AES interrupt sources to set as pending. Use a bitwise logic OR combination of valid interrupt flags for the AES module (AES_IF_nnn).
Definition at line
280
of file
em_aes.h
.
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.
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 * 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 toin
, 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. [in] iv
128 bit initialization vector to use.
Definition at line
1132
of file
em_aes.c
.
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.
See AES_OFB128() for OFB 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 toin
, 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] iv
128 bit initialization vector to use.
Definition at line
1213
of file
em_aes.c
.