Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
SAM Advanced Encryption Standard (AES) Driver

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:

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):

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:

Hardware Countermeasures

The AES module features four types of hardware countermeasures that are useful for protecting data against differential power analysis attacks:

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

Modules

 

Data Structures

struct  aes_config
 AES Configuration structure. More...
 

Typedefs

typedef void(* aes_callback_t )(void)
 AES interrupt callback function type. More...
 

Enumerations

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...
 

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(), aes_get_status(), AESEncode(), ecb_mode_test(), and ecb_mode_test_dma().

#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.

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]modulePointer to the AES software instance struct

References Assert.

Referenced by AESEncode(), cbc_mode_test(), cfb128_mode_test(), ctr_mode_test(), ecb_mode_test(), ecb_mode_test_dma(), ofb_mode_test(), 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().

static void aes_clear_status ( struct aes_module *const  module,
const uint32_t  status_flags 
)
inlinestatic

Clears a module status flag.

Clears the given status flag of the module.

Parameters
[in]modulePointer to the AES software instance struct
[in]status_flagsBitmask 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.

Parameters
[in]modulePointer to the software instance struct

References Assert.

Referenced by aes_set_config().

static enum status_code aes_disable_callback ( struct aes_module *const  module,
const enum aes_callback_type  type 
)
inlinestatic

Disable an AES callback.

Parameters
[in,out]modulePointer to the software instance struct
[in]typeCallback source type
Returns
Status of the callback enable operation.
Return values
STATUS_OKThe callback was enabled successfully
STATUS_ERR_INVALID_ARGIf 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.

Parameters
[in,out]modulePointer to the software instance struct

References Assert.

Referenced by aes_set_config(), AESInit(), and main().

static enum status_code aes_enable_callback ( struct aes_module *const  module,
const enum aes_callback_type  type 
)
inlinestatic

Enable an AES callback.

Parameters
[in,out]modulePointer to the software instance struct
[in]typeCallback source type
Returns
Status of the callback enable operation.
Return values
STATUS_OKThe callback was enabled successfully
STATUS_ERR_INVALID_ARGIf 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.

Referenced by main().

static void aes_gcm_clear_end_message_status ( struct aes_module *const  module)
inlinestatic

Clear GCM end of input message status.

Parameters
[in]modulePointer 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]modulePointer 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]modulePointer to the AES software instance struct
[in]idIndex 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]modulePointer to the AES software instance struct
[in]idIndex 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]modulePointer 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]modulePointer 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]modulePointer to the AES software instance struct
[in]lenCipher 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]modulePointer to the AES software instance struct
[in]idIndex into the GHASHx array (range 0 to 3)
[in]ghashGCM 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]modulePointer to the AES software instance struct
[in]idIndex into the Hash key array (range 0 to 3)
[in]keyGCM 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]configPointer 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 AESInit(), and main().

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]modulePointer to the AES software instance struct
Return values
AES_ENCRYPTION_COMPLETEAES encryption complete
AES_GF_MULTI_COMPLETEAES GF multiplication complete

References AES_ENCRYPTION_COMPLETE, AES_GF_MULTI_COMPLETE, and Assert.

Referenced by AESEncode(), ecb_mode_test(), and ecb_mode_test_dma().

void aes_init ( struct aes_module *const  module,
Aes *const  hw,
struct aes_config *const  config 
)

Initialize the AES module.

Parameters
[out]modulePointer to the software instance struct
[in]hwModule hardware register base address pointer
[in]configPointer to an AES configuration structure

References aes_set_config(), Assert, system_apb_clock_set_mask(), and SYSTEM_CLOCK_APB_APBC.

Referenced by AESInit(), and main().

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]modulePointer to the software instance struct
[in]output_data_bufferPointer to an output buffer

References AES_CFB_MODE, AES_CFB_SIZE_16, AES_CFB_SIZE_32, AES_CFB_SIZE_64, Assert, and i.

Referenced by aes_callback(), AESEncode(), ecb_mode_test(), 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 
)
void aes_set_config ( struct aes_module *const  module,
Aes *const  hw,
struct aes_config *const  config 
)
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]modulePointer to the AES software instance struct

References Assert.

Referenced by AESEncode(), cbc_mode_test(), cfb128_mode_test(), ctr_mode_test(), ecb_mode_test(), ecb_mode_test_dma(), ofb_mode_test(), 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().

static void aes_start ( struct aes_module *const  module)
inlinestatic

Start a manual encryption/decryption process.

Parameters
[in]modulePointer to the AES software instance struct

References Assert.

Referenced by cbc_mode_test(), cfb128_mode_test(), ctr_mode_test(), and ofb_mode_test().

enum status_code aes_unregister_callback ( const aes_callback_t  callback,
const enum aes_callback_type  type 
)
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]modulePointer to the software instance struct
[in]vectorPointer to four contiguous 32-bit words

References AES_ECB_MODE, Assert, and i.

Referenced by cbc_mode_test(), cfb128_mode_test(), ctr_mode_test(), ofb_mode_test(), 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).

Parameters
[in]modulePointer to the software instance struct
[in]input_data_bufferPointer to an input data buffer

References AES_CFB_MODE, AES_CFB_SIZE_16, AES_CFB_SIZE_32, AES_CFB_SIZE_64, Assert, and i.

Referenced by AESEncode(), cbc_mode_test(), cfb128_mode_test(), ctr_mode_test(), ecb_mode_test(), ofb_mode_test(), 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.

Parameters
[in]modulePointer to the software instance struct
[in]keyPointer 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, Assert, and i.

Referenced by AESEncode(), cbc_mode_test(), cfb128_mode_test(), ctr_mode_test(), ecb_mode_test(), ecb_mode_test_dma(), ofb_mode_test(), 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().

static void aes_write_random_seed ( struct aes_module *const  module,
uint32_t  seed 
)
inlinestatic

Write AES random seed.

Parameters
[in]modulePointer to the AES software instance struct
[in]seedSeed for the random number generator

References Assert.