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:
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):
The following peripheral is used by this module:
The following devices can use this module:
The outline of this documentation is as follows:
There are no prerequisites for this module.
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):
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.
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:
The AES module features four types of hardware countermeasures that are useful for protecting data against differential power analysis attacks:
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.
There are no special considerations for this module.
For extra information, see Extra Information for Advanced Encryption Standard. This includes:
For a list of examples related to this driver, see Examples for Advanced Encryption Standard.
Data Structures | |
struct | aes_config |
AES Configuration structure. More... | |
Typedefs | |
typedef void(* | aes_callback_t )(void) |
AES interrupt callback function type. More... | |
Module Status Flags | |
AES status flags, returned by aes_get_status() and cleared by aes_clear_status(). | |
#define | AES_ENCRYPTION_COMPLETE (1UL << 0) |
AES encryption complete. More... | |
#define | AES_GF_MULTI_COMPLETE (1UL << 1) |
AES GF multiplication complete. More... | |
Configuration and Initialization | |
void | aes_get_config_defaults (struct aes_config *const config) |
Initializes an AES configuration structure to defaults. More... | |
void | aes_set_config (struct aes_module *const module, Aes *const hw, struct aes_config *const config) |
Configure the AES module. More... | |
void | aes_init (struct aes_module *const module, Aes *const hw, struct aes_config *const config) |
Initialize the AES module. More... | |
Start, Enable, and Write | |
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... | |
Status Management | |
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... | |
Galois Counter Mode | |
static uint32_t | aes_gcm_read_ghash (struct aes_module *const module, uint32_t id) |
Get the AES GCM Hash Value. More... | |
static void | aes_gcm_write_ghash (struct aes_module *const module, uint32_t id, uint32_t ghash) |
Set the AES GCM Hash Value. More... | |
static uint32_t | aes_gcm_read_hash_key (struct aes_module *const module, uint32_t id) |
Get AES GCM Hash key. More... | |
static void | aes_gcm_write_hash_key (struct aes_module *const module, uint32_t id, uint32_t key) |
Set the AES GCM Hash key. More... | |
static uint32_t | aes_gcm_read_cipher_len (struct aes_module *const module) |
Get the AES GCM cipher length. More... | |
static void | aes_gcm_write_cipher_len (struct aes_module *const module, uint32_t len) |
Set the AES GCM cipher length. More... | |
static void | aes_gcm_set_end_message_status (struct aes_module *const module) |
Set GCM end of input message status. More... | |
static void | aes_gcm_clear_end_message_status (struct aes_module *const module) |
Clear GCM end of input message status. More... | |
static void | aes_gcm_set_gf_multiplication (struct aes_module *const module) |
Set GF multiplication of GCM mode. More... | |
Callback Configuration and Initialization | |
enum status_code | aes_register_callback (const aes_callback_t callback, const enum aes_callback_type type) |
enum status_code | aes_unregister_callback (const aes_callback_t callback, const enum aes_callback_type type) |
Callback Enabling and Disabling | |
static enum status_code | aes_enable_callback (struct aes_module *const module, const enum aes_callback_type type) |
Enable an AES callback. More... | |
static enum status_code | aes_disable_callback (struct aes_module *const module, const enum aes_callback_type type) |
Disable an AES callback. More... | |
#define AES_ENCRYPTION_COMPLETE (1UL << 0) |
AES encryption complete.
Referenced by aes_clear_status(), and aes_get_status().
#define AES_GF_MULTI_COMPLETE (1UL << 1) |
AES GF multiplication complete.
Referenced by aes_clear_status(), and aes_get_status().
typedef void(* aes_callback_t)(void) |
AES interrupt callback function type.
enum aes_callback_type |
enum aes_cfb_size |
AES Cipher FeedBack (CFB) size.
AES countermeasure type.
enum aes_encrypt_mode |
enum aes_key_size |
enum aes_operation_mode |
enum aes_start_mode |
|
inlinestatic |
Clear the indication of the beginning for a new message.
[in] | module | Pointer to the AES software instance struct |
References Assert.
Referenced by run_cbc_mode_test(), run_cfb128_mode_test(), run_ctr_mode_test(), run_ecb_mode_test(), run_ecb_mode_test_dma(), and run_ofb_mode_test().
|
inlinestatic |
Clears a module status flag.
Clears the given status flag of the module.
[in] | module | Pointer to the AES software instance struct |
[in] | status_flags | Bitmask flags to clear |
References AES_ENCRYPTION_COMPLETE, AES_GF_MULTI_COMPLETE, and Assert.
void aes_disable | ( | struct aes_module *const | module | ) |
Disable the AES module.
[in] | module | Pointer to the software instance struct |
References Assert.
Referenced by aes_set_config().
|
inlinestatic |
Disable an AES callback.
[in,out] | module | Pointer to the software instance struct |
[in] | type | Callback source type |
STATUS_OK | The callback was enabled successfully |
STATUS_ERR_INVALID_ARG | If an invalid callback type was supplied |
References AES_CALLBACK_ENCRYPTION_COMPLETE, AES_CALLBACK_GF_MULTI_COMPLETE, Assert, STATUS_ERR_INVALID_ARG, STATUS_OK, system_interrupt_disable(), and SYSTEM_INTERRUPT_MODULE_AES.
void aes_enable | ( | struct aes_module *const | module | ) |
Enable the AES module.
[in,out] | module | Pointer to the software instance struct |
References Assert.
Referenced by aes_set_config(), and main().
|
inlinestatic |
Enable an AES callback.
[in,out] | module | Pointer to the software instance struct |
[in] | type | Callback source type |
STATUS_OK | The callback was enabled successfully |
STATUS_ERR_INVALID_ARG | If an invalid callback type was supplied |
References AES_CALLBACK_ENCRYPTION_COMPLETE, AES_CALLBACK_GF_MULTI_COMPLETE, Assert, STATUS_ERR_INVALID_ARG, STATUS_OK, system_interrupt_enable(), and SYSTEM_INTERRUPT_MODULE_AES.
|
inlinestatic |
Clear GCM end of input message status.
[in] | module | Pointer to the AES software instance struct |
References Assert.
|
inlinestatic |
Get the AES GCM cipher length.
[in] | module | Pointer to the AES software instance struct |
References Assert.
|
inlinestatic |
Get the AES GCM Hash Value.
[in] | module | Pointer to the AES software instance struct |
[in] | id | Index into the GHASH array (range 0 to 3) |
References Assert.
|
inlinestatic |
Get AES GCM Hash key.
[in] | module | Pointer to the AES software instance struct |
[in] | id | Index into the Hash key array (range 0 to 3) |
References Assert.
|
inlinestatic |
Set GCM end of input message status.
[in] | module | Pointer to the AES software instance struct |
References Assert.
|
inlinestatic |
Set GF multiplication of GCM mode.
[in] | module | Pointer to the AES software instance struct |
References Assert.
|
inlinestatic |
Set the AES GCM cipher length.
[in] | module | Pointer to the AES software instance struct |
[in] | len | Cipher length |
References Assert.
|
inlinestatic |
Set the AES GCM Hash Value.
[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.
|
inlinestatic |
Set the AES GCM Hash key.
[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.
The default configuration is as follows:
[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.
Referenced by main().
|
inlinestatic |
Retrieves the current module status.
Retrieves the status of the module, giving overall state information.
[in] | module | Pointer to the AES software instance struct |
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 | ||
) |
Initialize the AES module.
[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_set_config(), Assert, system_apb_clock_set_mask(), and SYSTEM_CLOCK_APB_APBC.
Referenced by main().
void aes_read_output_data | ( | struct aes_module *const | module, |
uint32_t * | output_data_buffer | ||
) |
Read the output data.
[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.
Referenced by run_cbc_mode_test(), run_cfb128_mode_test(), run_ctr_mode_test(), run_ecb_mode_test(), and run_ofb_mode_test().
enum status_code aes_register_callback | ( | const aes_callback_t | callback, |
const enum aes_callback_type | type | ||
) |
References aes_callback_pointer, AES_CALLBACK_TYPE_NUM, Assert, STATUS_ERR_INVALID_ARG, and STATUS_OK.
void aes_set_config | ( | struct aes_module *const | module, |
Aes *const | hw, | ||
struct aes_config *const | config | ||
) |
Configure the AES module.
[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(), run_cbc_mode_test(), run_cfb128_mode_test(), run_ctr_mode_test(), run_ecb_mode_test(), run_ecb_mode_test_dma(), and run_ofb_mode_test().
|
inlinestatic |
Notifies the module that the next input data block is the beginning of a new message.
[in] | module | Pointer to the AES software instance struct |
References Assert.
Referenced by run_cbc_mode_test(), run_cfb128_mode_test(), run_ctr_mode_test(), run_ecb_mode_test(), run_ecb_mode_test_dma(), and run_ofb_mode_test().
|
inlinestatic |
Start a manual encryption/decryption process.
[in] | module | Pointer to the AES software instance struct |
References Assert.
enum status_code aes_unregister_callback | ( | const aes_callback_t | callback, |
const enum aes_callback_type | type | ||
) |
References aes_callback_pointer, AES_CALLBACK_TYPE_NUM, Assert, STATUS_ERR_INVALID_ARG, and STATUS_OK.
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).
[in] | module | Pointer to the software instance struct |
[in] | vector | Pointer to four contiguous 32-bit words |
References AES_ECB_MODE, and Assert.
Referenced by run_cbc_mode_test(), run_cfb128_mode_test(), run_ctr_mode_test(), and run_ofb_mode_test().
void aes_write_input_data | ( | struct aes_module *const | module, |
const uint32_t * | input_data_buffer | ||
) |
Write the input data (four consecutive 32-bit words).
[in] | module | Pointer to the software instance struct |
[in] | input_data_buffer | Pointer to an input data buffer |
References AES_CFB_MODE, AES_CFB_SIZE_16, AES_CFB_SIZE_32, AES_CFB_SIZE_64, and Assert.
Referenced by run_cbc_mode_test(), run_cfb128_mode_test(), run_ctr_mode_test(), run_ecb_mode_test(), and run_ofb_mode_test().
void aes_write_key | ( | struct aes_module *const | module, |
const uint32_t * | key | ||
) |
Write the 128/192/256-bit cryptographic key.
[in] | module | Pointer to the software instance struct |
[in] | key | Pointer to 4/6/8 contiguous 32-bit words |
References AES_KEY_SIZE_128, AES_KEY_SIZE_192, AES_KEY_SIZE_256, and Assert.
Referenced by run_cbc_mode_test(), run_cfb128_mode_test(), run_ctr_mode_test(), run_ecb_mode_test(), run_ecb_mode_test_dma(), and run_ofb_mode_test().
|
inlinestatic |
Write AES random seed.
[in] | module | Pointer to the AES software instance struct |
[in] | seed | Seed for the random number generator |
References Assert.