AESEMLIB
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 etc) are treated as byte arrays, starting with most significant byte. Ie, 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, ie 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 32 bit access type. The Cortex-M supports unaligned accesses, but with a performance penalty.
- It is possible to specify the same output buffer as 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 the buffers must be exactly overlapping. If partly overlapping, the behaviour is undefined.
It is up to the user to use a cipher mode according to its requirements in order to not break security. Please refer to 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
E.g. the following example shows how to perform an AES-128 CBC encryption:
Enable clocks:
Execute AES-128 CBC encryption:
Typedefs |
|
typedef void(* | AES_CtrFuncPtr_TypeDef ) (uint8_t *ctr) |
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) |
Cipher-block chaining (CBC) cipher mode encryption/decryption, 128 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_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_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 128 bit decryption key from 128 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.
|
|
__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 SW.
|
|
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.
|
|
Typedef Documentation
typedef void(* AES_CtrFuncPtr_TypeDef) (uint8_t *ctr) |
AES counter modification function pointer.
Parameters:
- ctr - Ptr to byte array (16 bytes) holding counter to be modified.
Definition at line
116
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
|
||
) |
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 *
Please refer to general comments on layout and byte ordering of parameters.
- Parameters
-
[out] out
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
Buffer holding data to encrypt/decrypt. Must be at least len
long.[in] len
Number of bytes to encrypt/decrypt. Must be a multiple of 16. [in] key
When doing encryption, this is the 128 bit encryption key. When doing decryption, 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 initalization vector to use. [in] encrypt
Set to true to encrypt, false to decrypt.
Definition at line
124
of file
em_aes.c
.
References AES , AES_CTRL_DATASTART , AES_CTRL_DECRYPT , AES_CTRL_XORSTART , and AES_STATUS_RUNNING .
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 *
Please refer to general comments on layout and byte ordering of parameters.
- Parameters
-
[out] out
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
Buffer holding data to encrypt/decrypt. Must be at least len
long.[in] len
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 initalization vector to use. [in] encrypt
Set to true to encrypt, false to decrypt.
Definition at line
423
of file
em_aes.c
.
References AES , AES_CTRL_DATASTART , and AES_STATUS_RUNNING .
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 *
Please refer to general comments on layout and byte ordering of parameters.
- Parameters
-
[out] out
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
Buffer holding data to encrypt/decrypt. Must be at least len
long.[in] len
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
Function used to update counter value.
Definition at line
639
of file
em_aes.c
.
References AES , AES_CTRL_DATASTART , and AES_STATUS_RUNNING .
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.
Please refer to general comments on layout and byte ordering of parameters.
- Parameters
-
[in,out] ctr
Buffer holding 128 bit counter to be updated.
Definition at line
791
of file
em_aes.c
.
void AES_DecryptKey128 | ( | uint8_t * |
out,
|
const uint8_t * |
in
|
||
) |
Generate 128 bit decryption key from 128 bit encryption key. The decryption key is used for some cipher modes when decrypting.
Please refer to general comments on layout and byte ordering of parameters.
- Parameters
-
[out] out
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
Buffer holding 128 bit encryption key. Must be at least 16 bytes long.
Definition at line
813
of file
em_aes.c
.
References AES , AES_CMD_START , AES_IF_DONE , AES_IntClear() , and AES_STATUS_RUNNING .
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 *
Please refer to general comments on layout and byte ordering of parameters.
- Parameters
-
[out] out
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
Buffer holding data to encrypt/decrypt. Must be at least len
long.[in] len
Number of bytes to encrypt/decrypt. Must be a multiple of 16. [in] key
When doing encryption, this is the 128 bit encryption key. When doing decryption, 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
935
of file
em_aes.c
.
References AES , AES_CTRL_DATASTART , AES_CTRL_DECRYPT , and AES_STATUS_RUNNING .
__STATIC_INLINE void AES_IntClear | ( | uint32_t |
flags
|
) |
Clear one or more pending AES interrupts.
- Parameters
-
[in] flags
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
200
of file
em_aes.h
.
References AES .
Referenced by AES_DecryptKey128() .
__STATIC_INLINE void AES_IntDisable | ( | uint32_t |
flags
|
) |
Disable one or more AES interrupts.
- Parameters
-
[in] flags
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
213
of file
em_aes.h
.
References AES .
__STATIC_INLINE void AES_IntEnable | ( | uint32_t |
flags
|
) |
Enable one or more AES interrupts.
- Note
- Depending on the use, a pending interrupt may already be set prior to enabling the interrupt. Consider using AES_IntClear() prior to enabling if such 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
231
of file
em_aes.h
.
References AES .
__STATIC_INLINE uint32_t AES_IntGet | ( | void |
|
) |
Get pending AES interrupt flags.
- Note
- The event bits are not cleared by the use of this function.
- Returns
- AES interrupt sources pending. A bitwise logic OR combination of valid interrupt flags for the AES module (AES_IF_nnn).
Definition at line
247
of file
em_aes.h
.
References AES .
__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
- Interrupt flags are not cleared by the use of this function.
- 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
266
of file
em_aes.h
.
References AES .
__STATIC_INLINE void AES_IntSet | ( | uint32_t |
flags
|
) |
Set one or more pending AES interrupts from SW.
- Parameters
-
[in] flags
AES interrupt sources to set to pending. Use a bitwise logic OR combination of valid interrupt flags for the AES module (AES_IF_nnn).
Definition at line
282
of file
em_aes.h
.
References AES .
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 *
Please refer to general comments on layout and byte ordering of parameters.
- Parameters
-
[out] out
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
Buffer holding data to encrypt/decrypt. Must be at least len
long.[in] len
Number of bytes to encrypt/decrypt. Must be a multiple of 16. [in] key
128 bit encryption key. [in] iv
128 bit initalization vector to use.
Definition at line
1131
of file
em_aes.c
.
References AES , AES_CMD_START , and AES_STATUS_RUNNING .