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 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 Codebook (ECB)
Cipher Block Chaining (CBC)
Output Feedback (OFB)
Cipher Feedback (CFB)
Counter (CTR)

Devices from the following series can use this module:

Atmel | SMART SAM4C
Atmel | SMART SAM4E
Atmel | SMART SAMV71
Atmel | SMART SAMV70
Atmel | SMART SAME70
Atmel | SMART SAMS70

The outline of this documentation is as follows:

Prerequisites

There are no prerequisites for this module.

Module Overview

The Advanced Encryption Standard (AES) module 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 Codebook (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 (PDC) 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.

Special Considerations

Power Management

The AES module may be clocked through the Power Management Controller (PMC), in which case the user application must first configure the PMC to enable the AES clock.

Interrupt

When using the AES module's interrupt, the configuration of the device's Nested Vectored Interrupt Controller (NVIC) needs to be carried out before the AES module is configured.

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
	Related Project(s)
	In this section you can find all the projects related to the SAM4C/4E/V71/V70/S70/E70 Advanced Encryption Standard (AES) Driver.

	Quick Start Guide(s)
	In this section you can find a list of all Quick Start guides related to the SAM4C/4E/V71/V70/S70/E70 Advanced Encryption Standard (AES) Driver.

Data Structures
struct	aes_config
	AES Configuration structure. More...

Macros
#define	AES_DMA_RX_IDX 12
	AES DMAC RX channel interface number. More...

#define	AES_DMA_TX_IDX 11
	AES DMAC TX channel interface number. More...

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

typedef enum aes_interrupt_source	aes_interrupt_source_t
	AES interrupt source type. More...

Enumerations
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_encrypt_mode { AES_DECRYPTION = 0, AES_ENCRYPTION }
	AES processing mode. More...

enum	aes_interrupt_source { AES_INTERRUPT_DATA_READY = AES_IER_DATRDY, AES_INTERRUPT_UNSPECIFIED_REGISTER_ACCESS = AES_IER_URAD, AES_INTERRUPT_END_OF_RECEIVE_BUFFER = AES_IER_ENDRX, AES_INTERRUPT_END_OF_TRANSMIT_BUFFER = AES_IER_ENDTX, AES_INTERRUPT_RECEIVE_BUFFER_FULL = AES_IER_RXBUFF, AES_INTERRUPT_TRANSMIT_BUFFER_FULL = AES_IER_TXBUFE }
	AES interrupt source type. 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_opmode { AES_ECB_MODE = 0, AES_CBC_MODE, AES_OFB_MODE, AES_CFB_MODE, AES_CTR_MODE, AES_GCM_MODE }
	AES cipher block mode. More...

enum	aes_start_mode { AES_MANUAL_START = 0, AES_AUTO_START, AES_IDATAR0_START }
	AES start mode. More...

Functions
void	aes_disable (void)
	Disable the AES module. More...

static void	aes_disable_interrupt (Aes *const p_aes, aes_interrupt_source_t source)
	Disable an AES interrupt. More...

void	aes_enable (void)
	Enable the AES module. More...

static void	aes_enable_interrupt (Aes *const p_aes, aes_interrupt_source_t source)
	Enable an AES interrupt. More...

void	aes_get_config_defaults (struct aes_config *const p_cfg)
	Initializes an AES configuration structure to defaults. More...

Pdc *	aes_get_pdc_base (Aes *p_aes)
	Get AES PDC base address. More...

void	aes_init (Aes const p_aes, struct aes_config const p_cfg)
	Initialize the AES module. More...

static uint32_t	aes_read_authen_datalength (Aes *const p_aes)
	Get the AES Additional Authenticated Data (AAD) length in bytes. More...

static uint32_t	aes_read_gcm_counter (Aes *const p_aes)
	Get the AES GCM Encryption Counter. More...

static uint32_t	aes_read_gcmh (Aes *const p_aes, uint32_t id)
	Get AES GCM Hash subkey word. More...

static uint32_t	aes_read_ghash (Aes *const p_aes, uint32_t id)
	Get the AES GCM Intermediate Hash Word. More...

static uint32_t	aes_read_interrupt_mask (Aes *const p_aes)
	Get the AES interrupt mask status. More...

static uint32_t	aes_read_interrupt_status (Aes *const p_aes)
	Get the AES interrupt status. More...

void	aes_read_output_data (Aes const p_aes, uint32_t p_output_data_buffer)
	Read the output data. More...

static uint32_t	aes_read_pctext_length (Aes *const p_aes)
	Get the AES plaintext/ciphertext length in bytes. More...

static uint32_t	aes_read_tag (Aes *const p_aes, uint32_t id)
	Get AES GCM Authentication Tag Word. More...

static void	aes_reset (Aes *const p_aes)
	Perform an AES software reset. More...

void	aes_set_callback (Aes *const p_aes, aes_interrupt_source_t source, aes_callback_t callback, uint8_t irq_level)
	Set the AES interrupt callback. More...

void	aes_set_config (Aes const p_aes, struct aes_config const p_cfg)
	Configure the AES module. More...

static void	aes_start (Aes *const p_aes)
	Start a manual encryption/decryption process. More...

static void	aes_write_authen_datalength (Aes *const p_aes, uint32_t length)
	Set the AES Additional Authenticated Data (AAD) length in bytes. More...

static void	aes_write_gcmh (Aes *const p_aes, uint32_t id, uint32_t hword)
	Set the AES GCM Hash subkey word. More...

static void	aes_write_ghash (Aes *const p_aes, uint32_t id, uint32_t ghash)
	Set the AES GCM Intermediate Hash Word. More...

void	aes_write_initvector (Aes const p_aes, const uint32_t p_vector)
	Write the initialization vector (for the CBC, CFB, OFB, CTR & GCM cipher modes). More...

void	aes_write_input_data (Aes const p_aes, const uint32_t p_input_data_buffer)
	Write the input data (four consecutive 32-bit words). More...

void	aes_write_key (Aes const p_aes, const uint32_t p_key)
	Write the 128/192/256-bit cryptographic key. More...

static void	aes_write_pctext_length (Aes *const p_aes, uint32_t length)
	Set the AES plaintext/ciphertext length in bytes. More...

#define AES_DMA_RX_IDX 12

AES DMAC RX channel interface number.

#define AES_DMA_TX_IDX 11

AES DMAC TX channel interface number.

typedef void(* aes_callback_t)(void)

AES interrupt callback function type.

typedef enum aes_interrupt_source aes_interrupt_source_t

AES interrupt source type.

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_encrypt_mode

AES processing mode.

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

enum aes_interrupt_source

AES interrupt source type.

Enumerator
AES_INTERRUPT_DATA_READY	Data ready interrupt.
AES_INTERRUPT_UNSPECIFIED_REGISTER_ACCESS	Unspecified register access detection interrupt.
AES_INTERRUPT_END_OF_RECEIVE_BUFFER	End of receive buffer interrupt (SAM4C devices only).
AES_INTERRUPT_END_OF_TRANSMIT_BUFFER	End of transmit buffer interrupt (SAM4C devices only).
AES_INTERRUPT_RECEIVE_BUFFER_FULL	Receive buffer full interrupt (SAM4C devices only).
AES_INTERRUPT_TRANSMIT_BUFFER_FULL	Transmit buffer empty interrupt (SAM4C devices only).

enum aes_key_size

AES cryptographic key size.

Enumerator
AES_KEY_SIZE_128	AES key size is 128 bits.
AES_KEY_SIZE_192	AES key size is 192 bits.
AES_KEY_SIZE_256	AES key size is 256 bits.

enum aes_opmode

AES cipher block 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_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.
AES_IDATAR0_START	AES_IDATAR0 access only Auto Mode.

void aes_disable ( void )

Disable the AES module.

References SLEEPMGR_SLEEP_WFI, sleepmgr_unlock_mode(), and sysclk_disable_peripheral_clock().

static void aes_disable_interrupt	(	Aes *const	p_aes,
		aes_interrupt_source_t	source
	)

inlinestatic

Disable an AES interrupt.

Parameters

[out]	p_aes	Module hardware register base address pointer
[in]	source	Interrupt source

void aes_enable ( void )

Enable the AES module.

References sleepmgr_lock_mode(), SLEEPMGR_SLEEP_WFI, and sysclk_enable_peripheral_clock().

Referenced by main().

static void aes_enable_interrupt	(	Aes *const	p_aes,
		aes_interrupt_source_t	source
	)

inlinestatic

Enable an AES interrupt.

Parameters

[out]	p_aes	Module hardware register base address pointer
[in]	source	Interrupt source

Referenced by aes_set_callback(), and main().

void aes_get_config_defaults ( struct aes_config *const p_cfg )

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
Last output data mode is disabled
No extra delay

Parameters

[out] p_cfg Pointer to an AES configuration structure

References AES_CFB_SIZE_128, AES_ECB_MODE, AES_ENCRYPTION, AES_KEY_SIZE_128, AES_MANUAL_START, Assert, aes_config::cfb_size, aes_config::encrypt_mode, aes_config::gtag_en, aes_config::key_size, aes_config::lod, aes_config::opmode, aes_config::processing_delay, and aes_config::start_mode.

Referenced by main().

Pdc* aes_get_pdc_base ( Aes * p_aes )

Get AES PDC base address.

Note: This function is only available on SAM4C devices.

Parameters

[in] p_aes Module hardware register base address pointer

Returns: The PDC registers base address for the AES module.

References Assert, and NULL.

void aes_init	(	Aes *const	p_aes,
		struct aes_config *const	p_cfg
	)

Initialize the AES module.

Parameters

[out]	p_aes	Module hardware register base address pointer
[in]	p_cfg	Pointer to an AES configuration structure

References aes_reset(), aes_set_config(), Assert, sysclk_disable_peripheral_clock(), and sysclk_enable_peripheral_clock().

Referenced by main().

static uint32_t aes_read_authen_datalength ( Aes *const p_aes )

inlinestatic

Get the AES Additional Authenticated Data (AAD) length in bytes.

Note: This function is only available on SAM4C devices.

Parameters

[in] p_aes Module hardware register base address pointer

Returns: The Additional Authenticated Data (AAD) length in bytes.

static uint32_t aes_read_gcm_counter ( Aes *const p_aes )

inlinestatic

Get the AES GCM Encryption Counter.

Note: This function is only available on SAM4C devices.

Parameters

[in] p_aes Module hardware register base address pointer

Returns: The AES GCM encryption counter.

static uint32_t aes_read_gcmh	(	Aes *const	p_aes,
		uint32_t	id
	)

inlinestatic

Get AES GCM Hash subkey word.

Note: This function is only available on SAM4C devices.

Parameters

[in]	p_aes	Module hardware register base address pointer
[in]	id	Index into the GCMHR array (range 0 to 3)

Returns: The contents of the AES_GCMHRx[x = 0...3] register specified.

static uint32_t aes_read_ghash	(	Aes *const	p_aes,
		uint32_t	id
	)

inlinestatic

Get the AES GCM Intermediate Hash Word.

Note: This function is only available on SAM4C devices.

Parameters

[in]	p_aes	Module hardware register base address pointer
[in]	id	Index into the GHASH array (range 0 to 3)

Returns: The content of the AES_GHASHRx[x = 0...3] register.

static uint32_t aes_read_interrupt_mask ( Aes *const p_aes )

inlinestatic

Get the AES interrupt mask status.

Parameters

[in] p_aes Module hardware register base address pointer

Returns: The AES interrupt mask contents.

Referenced by AES_Handler().

static uint32_t aes_read_interrupt_status ( Aes *const p_aes )

inlinestatic

Get the AES interrupt status.

Parameters

[in] p_aes Module hardware register base address pointer

Returns: The AES interrupt status register contents.

Referenced by AES_Handler(), gcm_mode_decryption_test(), and gcm_mode_encryption_test().

void aes_read_output_data	(	Aes *const	p_aes,
		uint32_t *	p_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]	p_aes	Module hardware register base address pointer
[in]	*p_output_data_buffer	Pointer to an output buffer

References Assert.

Referenced by aes_callback(), gcm_mode_decryption_test(), and gcm_mode_encryption_test().

static uint32_t aes_read_pctext_length ( Aes *const p_aes )

inlinestatic

Get the AES plaintext/ciphertext length in bytes.

Note: This function is only available on SAM4C devices.

Parameters

[in] p_aes Module hardware register base address pointer

Returns: The plaintext/ciphertext length in bytes.

static uint32_t aes_read_tag	(	Aes *const	p_aes,
		uint32_t	id
	)

inlinestatic

Get AES GCM Authentication Tag Word.

Note: This function is only available on SAM4C devices.

Parameters

[in]	p_aes	Module hardware register base address pointer
[in]	id	Index into the TAGR array (range 0 to 3)

Returns: The contents of the AES_TAGRx[x = 0...3] register specified.

Referenced by aes_read_gcm_auth_tag().

static void aes_reset ( Aes *const p_aes )

inlinestatic

Perform an AES software reset.

Parameters

[out] p_aes Module hardware register base address pointer

Referenced by aes_init().

void aes_set_callback	(	Aes *const	p_aes,
		aes_interrupt_source_t	source,
		aes_callback_t	callback,
		uint8_t	irq_level
	)

Set the AES interrupt callback.

Parameters

[out]	p_aes	Module hardware register base address pointer
[in]	source	Interrupt source
[in]	callback	Interrupt callback function pointer
[in]	irq_level	Interrupt priority level

References aes_callback_pointer, aes_enable_interrupt(), AES_INTERRUPT_DATA_READY, AES_INTERRUPT_END_OF_RECEIVE_BUFFER, AES_INTERRUPT_END_OF_TRANSMIT_BUFFER, AES_INTERRUPT_RECEIVE_BUFFER_FULL, AES_INTERRUPT_TRANSMIT_BUFFER_FULL, AES_INTERRUPT_UNSPECIFIED_REGISTER_ACCESS, Assert, callback, and irq_register_handler.

Referenced by main().

void aes_set_config	(	Aes *const	p_aes,
		struct aes_config *const	p_cfg
	)

Configure the AES module.

Parameters

[out]	p_aes	Module hardware register base address pointer
[in]	p_cfg	Pointer to an AES configuration structure

References AES_GCM_MODE, AES_IDATAR0_START, Assert, aes_config::cfb_size, aes_config::encrypt_mode, aes_config::gtag_en, aes_config::key_size, aes_config::lod, aes_config::opmode, aes_config::processing_delay, and aes_config::start_mode.

Referenced by aes_init(), cbc_mode_test(), cfb128_mode_test(), ctr_mode_test(), ecb_mode_test(), gcm_mode_decryption_test(), gcm_mode_encryption_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().

static void aes_start ( Aes *const p_aes )

inlinestatic

Start a manual encryption/decryption process.

Parameters

[out] p_aes Module hardware register base address pointer

static void aes_write_authen_datalength	(	Aes *const	p_aes,
		uint32_t	length
	)

inlinestatic

Set the AES Additional Authenticated Data (AAD) length in bytes.

Note: This function is only available on SAM4C devices.

Parameters

[out]	p_aes	Module hardware register base address pointer
[in]	length	Length in bytes of the AAD data to be processed

Referenced by gcm_mode_decryption_test(), and gcm_mode_encryption_test().

static void aes_write_gcmh	(	Aes *const	p_aes,
		uint32_t	id,
		uint32_t	hword
	)

inlinestatic

Set the AES GCM Hash subkey word.

Note: This function is only available on SAM4C devices.

Parameters

[out]	p_aes	Module hardware register base address pointer
[in]	id	Index into the GCMHR array (range 0 to 3)
[in]	hword	GCM H Word

static void aes_write_ghash	(	Aes *const	p_aes,
		uint32_t	id,
		uint32_t	ghash
	)

inlinestatic

Set the AES GCM Intermediate Hash Word.

Note: This function is only available on SAM4C devices.

Parameters

[out]	p_aes	Module hardware register base address pointer
[in]	id	Index into the GHASHx array (range 0 to 3)
[in]	ghash	Intermediate GCM Hash Word x

void aes_write_initvector	(	Aes *const	p_aes,
		const uint32_t *	p_vector
	)

Write the initialization vector (for the CBC, CFB, OFB, CTR & GCM cipher modes).

Parameters

[out]	p_aes	Module hardware register base address pointer
[in]	p_vector	Pointer to four contiguous 32-bit words

References Assert.

Referenced by cbc_mode_test(), cfb128_mode_test(), ctr_mode_test(), gcm_mode_decryption_test(), gcm_mode_encryption_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	(	Aes *const	p_aes,
		const uint32_t *	p_input_data_buffer
	)

Write the input data (four consecutive 32-bit words).

Parameters

[out]	p_aes	Module hardware register base address pointer
[in]	p_input_data_buffer	Pointer to an input data buffer

References Assert.

Referenced by cbc_mode_test(), cfb128_mode_test(), ctr_mode_test(), ecb_mode_test(), gcm_mode_decryption_test(), gcm_mode_encryption_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	(	Aes *const	p_aes,
		const uint32_t *	p_key
	)

Write the 128/192/256-bit cryptographic key.

Parameters

[out]	p_aes	Module hardware register base address pointer
[in]	p_key	Pointer to 4/6/8 contiguous 32-bit words

Note: The key size depends on the current AES configuration.

References Assert.

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

static void aes_write_pctext_length	(	Aes *const	p_aes,
		uint32_t	length
	)

inlinestatic

Set the AES plaintext/ciphertext length in bytes.

Note: This function is only available on SAM4C devices.

Parameters

[out]	p_aes	Module hardware register base address pointer
[in]	length	Length in bytes of the plaintext/ciphertext data

Referenced by gcm_mode_decryption_test(), and gcm_mode_encryption_test().

Microchip® Advanced Software Framework

Prerequisites

Module Overview

Special Considerations

Power Management

Interrupt

Extra Information

Examples

API Overview

Modules

Data Structures

Macros

Typedefs

Enumerations

Functions