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

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(), 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

AES callback type.

Enumerator
AES_CALLBACK_ENCRYPTION_COMPLETE	Encryption complete callback.
AES_CALLBACK_GF_MULTI_COMPLETE	GF Multiplication Complete callback.

enum aes_cfb_size

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.

enum aes_countermeature_type

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.

enum aes_encrypt_mode

AES processing mode.

Enumerator
AES_DECRYPTION	Decryption of data will be performed.
AES_ENCRYPTION	Encryption of data will be performed.

enum aes_key_size

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.

enum aes_operation_mode

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)

enum aes_start_mode

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.

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

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

Parameters

[in] module Pointer 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]	module	Pointer to the software instance struct
[in]	type	Callback source type

Returns: Status of the callback enable operation.

Return values

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.

Parameters

[in,out] module Pointer to the software instance struct

References Assert.

Referenced by aes_set_config(), 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]	module	Pointer to the software instance struct
[in]	type	Callback source type

Returns: Status of the callback enable operation.

Return values

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.

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.

Referenced by 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] 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
	)

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

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.

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.

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(), 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_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.

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

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.

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

Parameters

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

Parameters

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

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.

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

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.

Microchip® Advanced Software Framework

Prerequisites

Module Overview

Encryption and Decryption

Hardware Countermeasures

Galois Counter Mode (GCM)

Special Considerations

Extra Information

Examples

API Overview

Data Structures

Typedefs

Enumerations

Module Status Flags

Configuration and Initialization

Start, Enable, and Write

Status Management

Galois Counter Mode

Callback Configuration and Initialization

Callback Enabling and Disabling