This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of the device's Advanced Encryption Standard functionality.
The following driver API modes are covered by this manual:
- Polled APIs
- Callback APIs
The Advanced Encryption Standard module supports all five confidentiality modes of operation for symmetrical key block cipher algorithms (as specified in the NIST Special Publication 800-38A Recommendation):
- Electronic Code Book (ECB)
- Cipher Block Chaining (CBC)
- Output Feedback (OFB)
- Cipher Feedback (CFB)
- Counter (CTR)
The following peripheral is used by this module:
- AES (Advanced Encryption Standard)
The following devices can use this module:
- Atmel | SMART SAM L21
- Atmel | SMART SAM L22
- Atmel | SMART SAM R34/R35
The outline of this documentation is as follows:
Prerequisites
There are no prerequisites for this module.
Module Overview
The Advanced Encryption Standard (AES) is a specification for the encryption of electronic data established by the U.S. National Institute of Standards and Technology (NIST) in 2001. It is compliant with the American FIPS (Federal Information Processing Standard) Publication 197 specification.
The AES supports all five confidentiality modes of operation for symmetrical key block cipher algorithms (as specified in the NIST Special Publication 800-38A Recommendation):
- Electronic Code Book (ECB)
- Cipher Block Chaining (CBC)
- Output Feedback (OFB)
- Cipher Feedback (CFB)
- Counter (CTR)
Data transfers both to and from the AES module can occur using the peripheral DMA controller channels, thus minimizing processor intervention for large data buffer transfers.
As soon as the initialization vector, the input data and the key are configured, the encryption/decryption process may be started. Once the process has completed the encrypted/decrypted data can be read out via registers or through DMA channels.
Encryption and Decryption
The AES is capable of using cryptographic keys of 128/192/256 bits to encrypt and decrypt data in blocks of 128 bits. In Cipher Feedback Mode (CFB), five data sizes are possible (8, 16, 32, 64, or 128 bits).
The input to the encryption processes of the CBC, CFB, and OFB modes includes, in addition to the plaintext, a 128-bit data block called the Initialization Vector (IV). The Initialization Vector is used in the initial step in the encryption of a message and in the corresponding decryption of the message.
There are three encryption/decryption start modes:
- Manual Mode: Start encryption/decryption manually
- Auto Start Mode: Once the correct number of input data registers is written, processing is automatically started, DMA operation uses this mode
- Last Output Data Mode (LOD): This mode is used to generate message authentication code (MAC) on data in CCM mode of operation
Hardware Countermeasures
The AES module features four types of hardware countermeasures that are useful for protecting data against differential power analysis attacks:
- Type 1: Randomly add one cycle to data processing
- Type 2: Randomly add one cycle to data processing (other version)
- Type 3: Add a random number of clock cycles to data processing, subject to a maximum of 11/13/15 clock cycles for key sizes of 128/192/256 bits
- Type 4: Add random spurious power consumption during data processing
Galois Counter Mode (GCM)
GCM is comprised of the AES engine in CTR mode along with a universal hash function (GHASH engine) that is defined over a binary Galois field to produce a message authentication tag. The GHASH engine processes data packets after the AES operation. GCM provides assurance of the confidentiality of data through the AES Counter mode of operation for DRAFT 920 encryption. Authenticity of the confidential data is assured through the GHASH engine. Refer to the NIST Special Publication 800-38D Recommendation for more complete information.
Special Considerations
There are no special considerations for this module.
Extra Information
For extra information, see Extra Information for Advanced Encryption Standard. This includes:
Examples
For a list of examples related to this driver, see Examples for Advanced Encryption Standard.
API Overview
|
enum | aes_callback_type {
AES_CALLBACK_ENCRYPTION_COMPLETE = 0,
AES_CALLBACK_GF_MULTI_COMPLETE = 1
} |
| AES callback type. More...
|
|
enum | aes_cfb_size {
AES_CFB_SIZE_128 = 0,
AES_CFB_SIZE_64,
AES_CFB_SIZE_32,
AES_CFB_SIZE_16,
AES_CFB_SIZE_8
} |
| AES Cipher FeedBack (CFB) size. More...
|
|
enum | aes_countermeature_type {
AES_COUNTERMEASURE_TYPE_disabled = 0x0,
AES_COUNTERMEASURE_TYPE_1 = 0x01,
AES_COUNTERMEASURE_TYPE_2 = 0x02,
AES_COUNTERMEASURE_TYPE_3 = 0x04,
AES_COUNTERMEASURE_TYPE_4 = 0x08,
AES_COUNTERMEASURE_TYPE_ALL = 0x0F
} |
| AES countermeasure type. More...
|
|
enum | aes_encrypt_mode {
AES_DECRYPTION = 0,
AES_ENCRYPTION
} |
| AES processing mode. More...
|
|
enum | aes_key_size {
AES_KEY_SIZE_128 = 0,
AES_KEY_SIZE_192,
AES_KEY_SIZE_256
} |
| AES cryptographic key size. More...
|
|
enum | aes_operation_mode {
AES_ECB_MODE = 0,
AES_CBC_MODE,
AES_OFB_MODE,
AES_CFB_MODE,
AES_CTR_MODE,
AES_CCM_MODE,
AES_GCM_MODE
} |
| AES operation mode. More...
|
|
enum | aes_start_mode {
AES_MANUAL_START = 0,
AES_AUTO_START
} |
| AES start mode. More...
|
|
|
static void | aes_start (struct aes_module *const module) |
| Start a manual encryption/decryption process. More...
|
|
static void | aes_set_new_message (struct aes_module *const module) |
| Notifies the module that the next input data block is the beginning of a new message. More...
|
|
static void | aes_clear_new_message (struct aes_module *const module) |
| Clear the indication of the beginning for a new message. More...
|
|
void | aes_enable (struct aes_module *const module) |
| Enable the AES module. More...
|
|
void | aes_disable (struct aes_module *const module) |
| Disable the AES module. More...
|
|
void | aes_write_key (struct aes_module *const module, const uint32_t *key) |
| Write the 128/192/256-bit cryptographic key. More...
|
|
void | aes_write_init_vector (struct aes_module *const module, const uint32_t *vector) |
| Write the initialization vector (for the CBC, CFB, OFB, CTR, and GCM cipher modes). More...
|
|
void | aes_write_input_data (struct aes_module *const module, const uint32_t *p_input_data_buffer) |
| Write the input data (four consecutive 32-bit words). More...
|
|
void | aes_read_output_data (struct aes_module *const module, uint32_t *p_output_data_buffer) |
| Read the output data. More...
|
|
static void | aes_write_random_seed (struct aes_module *const module, uint32_t seed) |
| Write AES random seed. More...
|
|
|
static uint32_t | aes_get_status (struct aes_module *const module) |
| Retrieves the current module status. More...
|
|
static void | aes_clear_status (struct aes_module *const module, const uint32_t status_flags) |
| Clears a module status flag. More...
|
|
#define AES_ENCRYPTION_COMPLETE (1UL << 0) |
#define AES_GF_MULTI_COMPLETE (1UL << 1) |
typedef void(* aes_callback_t)(void) |
AES interrupt callback function type.
AES callback type.
Enumerator |
---|
AES_CALLBACK_ENCRYPTION_COMPLETE |
Encryption complete callback.
|
AES_CALLBACK_GF_MULTI_COMPLETE |
GF Multiplication Complete callback.
|
AES Cipher FeedBack (CFB) size.
Enumerator |
---|
AES_CFB_SIZE_128 |
Cipher feedback data size is 128-bit.
|
AES_CFB_SIZE_64 |
Cipher feedback data size is 64-bit.
|
AES_CFB_SIZE_32 |
Cipher feedback data size is 32-bit.
|
AES_CFB_SIZE_16 |
Cipher feedback data size is 16-bit.
|
AES_CFB_SIZE_8 |
Cipher feedback data size is 8-bit.
|
AES countermeasure type.
Enumerator |
---|
AES_COUNTERMEASURE_TYPE_disabled |
Countermeasure type all disabled.
|
AES_COUNTERMEASURE_TYPE_1 |
Countermeasure1 enabled.
|
AES_COUNTERMEASURE_TYPE_2 |
Countermeasure2 enabled.
|
AES_COUNTERMEASURE_TYPE_3 |
Countermeasure3 enabled.
|
AES_COUNTERMEASURE_TYPE_4 |
Countermeasure4 enabled.
|
AES_COUNTERMEASURE_TYPE_ALL |
Countermeasure type all enabled.
|
AES processing mode.
Enumerator |
---|
AES_DECRYPTION |
Decryption of data will be performed.
|
AES_ENCRYPTION |
Encryption of data will be performed.
|
AES cryptographic key size.
Enumerator |
---|
AES_KEY_SIZE_128 |
AES key size is 128-bit.
|
AES_KEY_SIZE_192 |
AES key size is 192-bit.
|
AES_KEY_SIZE_256 |
AES key size is 256-bit.
|
AES operation mode.
Enumerator |
---|
AES_ECB_MODE |
Electronic Codebook (ECB)
|
AES_CBC_MODE |
Cipher Block Chaining (CBC)
|
AES_OFB_MODE |
Output Feedback (OFB)
|
AES_CFB_MODE |
Cipher Feedback (CFB)
|
AES_CTR_MODE |
Counter (CTR)
|
AES_CCM_MODE |
Counter (CCM)
|
AES_GCM_MODE |
Galois Counter Mode (GCM)
|
AES start mode.
Enumerator |
---|
AES_MANUAL_START |
Manual start mode.
|
AES_AUTO_START |
Auto start mode.
|
static void aes_clear_new_message |
( |
struct aes_module *const |
module | ) |
|
|
inlinestatic |
Clear the indication of the beginning for a new message.
- Parameters
-
[in] | module | Pointer to the AES software instance struct |
References Assert.
static void aes_clear_status |
( |
struct aes_module *const |
module, |
|
|
const uint32_t |
status_flags |
|
) |
| |
|
inlinestatic |
void aes_disable |
( |
struct aes_module *const |
module | ) |
|
Disable the AES module.
- Parameters
-
[in] | module | Pointer to the software instance struct |
References Assert.
Referenced by aes_set_config().
void aes_enable |
( |
struct aes_module *const |
module | ) |
|
Enable the AES module.
- Parameters
-
[in,out] | module | Pointer to the software instance struct |
References Assert.
Referenced by aes_set_config().
static void aes_gcm_clear_end_message_status |
( |
struct aes_module *const |
module | ) |
|
|
inlinestatic |
Clear GCM end of input message status.
- Parameters
-
[in] | module | Pointer to the AES software instance struct |
References Assert.
static uint32_t aes_gcm_read_cipher_len |
( |
struct aes_module *const |
module | ) |
|
|
inlinestatic |
Get the AES GCM cipher length.
- Parameters
-
[in] | module | Pointer to the AES software instance struct |
- Returns
- The contents of the HASHKEYx[x = 0...3] specified.
References Assert.
static uint32_t aes_gcm_read_ghash |
( |
struct aes_module *const |
module, |
|
|
uint32_t |
id |
|
) |
| |
|
inlinestatic |
Get the AES GCM Hash Value.
- Parameters
-
[in] | module | Pointer to the AES software instance struct |
[in] | id | Index into the GHASH array (range 0 to 3) |
- Returns
- The content of the GHASHRx[x = 0...3] value.
References Assert.
static uint32_t aes_gcm_read_hash_key |
( |
struct aes_module *const |
module, |
|
|
uint32_t |
id |
|
) |
| |
|
inlinestatic |
Get AES GCM Hash key.
- Parameters
-
[in] | module | Pointer to the AES software instance struct |
[in] | id | Index into the Hash key array (range 0 to 3) |
- Returns
- The contents of the HASHKEYx[x = 0...3] specified.
References Assert.
static void aes_gcm_set_end_message_status |
( |
struct aes_module *const |
module | ) |
|
|
inlinestatic |
Set GCM end of input message status.
- Parameters
-
[in] | module | Pointer to the AES software instance struct |
References Assert.
static void aes_gcm_set_gf_multiplication |
( |
struct aes_module *const |
module | ) |
|
|
inlinestatic |
Set GF multiplication of GCM mode.
- Parameters
-
[in] | module | Pointer to the AES software instance struct |
References Assert.
static void aes_gcm_write_cipher_len |
( |
struct aes_module *const |
module, |
|
|
uint32_t |
len |
|
) |
| |
|
inlinestatic |
Set the AES GCM cipher length.
- Parameters
-
[in] | module | Pointer to the AES software instance struct |
[in] | len | Cipher length |
References Assert.
static void aes_gcm_write_ghash |
( |
struct aes_module *const |
module, |
|
|
uint32_t |
id, |
|
|
uint32_t |
ghash |
|
) |
| |
|
inlinestatic |
Set the AES GCM Hash Value.
- Parameters
-
[in] | module | Pointer to the AES software instance struct |
[in] | id | Index into the GHASHx array (range 0 to 3) |
[in] | ghash | GCM hash value |
References Assert.
static void aes_gcm_write_hash_key |
( |
struct aes_module *const |
module, |
|
|
uint32_t |
id, |
|
|
uint32_t |
key |
|
) |
| |
|
inlinestatic |
Set the AES GCM Hash key.
- Parameters
-
[in] | module | Pointer to the AES software instance struct |
[in] | id | Index into the Hash key array (range 0 to 3) |
[in] | key | GCM Hash key |
References Assert.
void aes_get_config_defaults |
( |
struct aes_config *const |
config | ) |
|
Initializes an AES configuration structure to defaults.
Initializes the specified AES configuration structure to a set of known default values.
- Note
- This function should be called to initialize all new instances of AES configuration structures before they are further modified by the user application.
The default configuration is as follows:
- Data encryption
- 128-bit AES key size
- 128-bit cipher feedback size
- Manual start mode
- Electronic Codebook (ECB) mode
- All countermeasures are enabled
- XRO key is disabled
- Key generation is disabled
- Last output data mode is disabled
- Parameters
-
[out] | config | Pointer to an AES configuration structure |
References AES_CFB_SIZE_128, AES_COUNTERMEASURE_TYPE_ALL, AES_ECB_MODE, AES_ENCRYPTION, AES_KEY_SIZE_128, AES_MANUAL_START, Assert, aes_config::cfb_size, aes_config::ctype, aes_config::enable_key_gen, aes_config::enable_xor_key, aes_config::encrypt_mode, aes_config::key_size, aes_config::lod, aes_config::opmode, and aes_config::start_mode.
static uint32_t aes_get_status |
( |
struct aes_module *const |
module | ) |
|
|
inlinestatic |
Retrieves the current module status.
Retrieves the status of the module, giving overall state information.
- Parameters
-
[in] | module | Pointer to the AES software instance struct |
- Return values
-
AES_ENCRYPTION_COMPLETE | AES encryption complete |
AES_GF_MULTI_COMPLETE | AES GF multiplication complete |
References AES_ENCRYPTION_COMPLETE, AES_GF_MULTI_COMPLETE, and Assert.
void aes_init |
( |
struct aes_module *const |
module, |
|
|
Aes *const |
hw, |
|
|
struct aes_config *const |
config |
|
) |
| |
void aes_read_output_data |
( |
struct aes_module *const |
module, |
|
|
uint32_t * |
output_data_buffer |
|
) |
| |
Read the output data.
- Note
- The data buffer that holds the processed data must be large enough to hold four consecutive 32-bit words.
- Parameters
-
[in] | module | Pointer to the software instance struct |
[in] | output_data_buffer | Pointer to an output buffer |
References AES_CFB_MODE, AES_CFB_SIZE_16, AES_CFB_SIZE_32, AES_CFB_SIZE_64, and Assert.
void aes_set_config |
( |
struct aes_module *const |
module, |
|
|
Aes *const |
hw, |
|
|
struct aes_config *const |
config |
|
) |
| |
Configure the AES module.
- Parameters
-
[out] | module | Pointer to the software instance struct |
[in] | hw | Module hardware register base address pointer |
[in] | config | Pointer to an AES configuration structure |
References aes_disable(), aes_enable(), Assert, aes_config::cfb_size, aes_config::ctype, aes_config::enable_key_gen, aes_config::enable_xor_key, aes_config::encrypt_mode, aes_config::key_size, aes_config::lod, aes_config::opmode, and aes_config::start_mode.
Referenced by aes_init().
static void aes_set_new_message |
( |
struct aes_module *const |
module | ) |
|
|
inlinestatic |
Notifies the module that the next input data block is the beginning of a new message.
- Parameters
-
[in] | module | Pointer to the AES software instance struct |
References Assert.
static void aes_start |
( |
struct aes_module *const |
module | ) |
|
|
inlinestatic |
Start a manual encryption/decryption process.
- Parameters
-
[in] | module | Pointer to the AES software instance struct |
References Assert.
void aes_write_init_vector |
( |
struct aes_module *const |
module, |
|
|
const uint32_t * |
vector |
|
) |
| |
Write the initialization vector (for the CBC, CFB, OFB, CTR, and GCM cipher modes).
- Parameters
-
[in] | module | Pointer to the software instance struct |
[in] | vector | Pointer to four contiguous 32-bit words |
References AES_ECB_MODE, and Assert.
void aes_write_input_data |
( |
struct aes_module *const |
module, |
|
|
const uint32_t * |
input_data_buffer |
|
) |
| |
void aes_write_key |
( |
struct aes_module *const |
module, |
|
|
const uint32_t * |
key |
|
) |
| |
Write the 128/192/256-bit cryptographic key.
- Parameters
-
[in] | module | Pointer to the software instance struct |
[in] | key | Pointer to 4/6/8 contiguous 32-bit words |
- Note
- The key size depends on the current AES configuration.
References AES_KEY_SIZE_128, AES_KEY_SIZE_192, AES_KEY_SIZE_256, and Assert.
static void aes_write_random_seed |
( |
struct aes_module *const |
module, |
|
|
uint32_t |
seed |
|
) |
| |
|
inlinestatic |
Write AES random seed.
- Parameters
-
[in] | module | Pointer to the AES software instance struct |
[in] | seed | Seed for the random number generator |
References Assert.