dif_aes.h File Reference

(036c58a)

AES Device Interface Functions More...

#include <stdbool.h>
#include <stdint.h>
#include "sw/device/lib/base/macros.h"
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_base.h"
#include "sw/device/lib/dif/autogen/dif_aes_autogen.h"

Go to the source code of this file.

Data Structures
struct	dif_aes_key_share
	A typed representation of the AES key share. More...
struct	dif_aes_iv
	A typed representation of the AES Initialisation Vector (IV). More...
struct	dif_aes_data
	A typed representation of the AES data. More...
struct	dif_aes_transaction
	Parameters for an AES transaction. More...

Typedefs
typedef struct dif_aes_key_share	dif_aes_key_share_t
	A typed representation of the AES key share. More...
typedef struct dif_aes_iv	dif_aes_iv_t
	A typed representation of the AES Initialisation Vector (IV).
typedef struct dif_aes_data	dif_aes_data_t
	A typed representation of the AES data.
typedef enum dif_aes_operation	dif_aes_operation_t
	AES operation.
typedef enum dif_aes_mode	dif_aes_mode_t
	AES block cipher mode of operation.
typedef enum dif_aes_key_length	dif_aes_key_length_t
	AES key length in bits.
typedef enum dif_aes_manual_operation	dif_aes_manual_operation_t
	AES manual operation.
typedef enum dif_aes_key_provider	dif_aes_key_provider_t
	AES key sideloaded. More...
typedef enum dif_aes_mask_reseeding	dif_aes_mask_reseeding_t
	AES reseeding rate. More...
typedef struct dif_aes_transaction	dif_aes_transaction_t
	Parameters for an AES transaction.
typedef enum dif_aes_trigger	dif_aes_trigger_t
	AES Trigger flags.
typedef enum dif_aes_status	dif_aes_status_t
	AES Status flags.

Enumerations
enum	dif_aes_operation {   kDifAesOperationEncrypt = 1,   kDifAesOperationDecrypt = 2 }
	AES operation. More...
enum	dif_aes_mode {   kDifAesModeEcb = 1,   kDifAesModeCbc = (1 << 1),   kDifAesModeCfb = (1 << 2),   kDifAesModeOfb = (1 << 3),   kDifAesModeCtr = (1 << 4) }
	AES block cipher mode of operation. More...
enum	dif_aes_key_length {   kDifAesKey128 = 1,   kDifAesKey192 = (1 << 1),   kDifAesKey256 = (1 << 2) }
	AES key length in bits. More...
enum	dif_aes_manual_operation {   kDifAesManualOperationAuto = 0,   kDifAesManualOperationManual }
	AES manual operation. More...
enum	dif_aes_key_provider {   kDifAesKeySoftwareProvided = 0,   kDifAesKeySideload }
	AES key sideloaded. More...
enum	dif_aes_mask_reseeding {   kDifAesReseedPerBlock = 1 << 0,   kDifAesReseedPer64Block = 1 << 1,   kDifAesReseedPer8kBlock = 1 << 2 }
	AES reseeding rate. More...
enum	dif_aes_trigger {   kDifAesTriggerStart = 0,   kDifAesTriggerKeyIvDataInClear,   kDifAesTriggerDataOutClear,   kDifAesTriggerPrngReseed }
	AES Trigger flags. More...
enum	dif_aes_status {   kDifAesStatusIdle = 0,   kDifAesStatusStall,   kDifAesStatusOutputLost,   kDifAesStatusOutputValid,   kDifAesStatusInputReady,   kDifAesStatusAlertFatalFault,   kDifAesStatusAlertRecovCtrlUpdateErr }
	AES Status flags. More...

Functions
OT_WARN_UNUSED_RESULT dif_result_t	dif_aes_reset (const dif_aes_t *aes)
	Resets an instance of AES. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_aes_start (const dif_aes_t *aes, const dif_aes_transaction_t *transaction, const dif_aes_key_share_t *key, const dif_aes_iv_t *iv)
	Begins an AES transaction in the mode selected by the transaction->mode. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_aes_end (const dif_aes_t *aes)
	Ends an AES transaction. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_aes_load_data (const dif_aes_t *aes, const dif_aes_data_t data)
	Loads AES Input Data. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_aes_read_output (const dif_aes_t *aes, dif_aes_data_t *data)
	Reads AES Output Data. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_aes_process_data (const dif_aes_t *aes, const dif_aes_data_t *plain_text, dif_aes_data_t *cipher_text, size_t block_amount)
	Process a stream of data containing the plain text and output a stream of data with the cipher text. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_aes_trigger (const dif_aes_t *aes, dif_aes_trigger_t trigger)
	Triggers one of dif_aes_trigger_t operations. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_aes_get_status (const dif_aes_t *aes, dif_aes_status_t flag, bool *set)
	Queries the AES status flags. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_aes_read_iv (const dif_aes_t *aes, dif_aes_iv_t *iv)
	Read the current initialization vector from its register. More...

Detailed Description

AES Device Interface Functions

This API assumes transactional nature of work, where the peripheral is configured once per message (data consisting of 1..N 128-bit blocks), and then "de-initialised" when this message has been fully encrypted/decrypted.

The peripheral is configured through one of the cipher mode "start" functions: dif_aes_start_ecb, dif_aes_start_cbc, ... .

Then the encryption/decryption data is fed one 128-bit block at the time through dif_aes_load_data function. The cipher mode operation details are described in the description of above mentioned "start" functions. When configured in "automatic" operation mode, every "load data" call, will trigger encryption/decryption. This is not true when in "manual" operation mode, where encryption/decryption is triggered by explicitly setting the aes.TRIGGER.START flag through dif_aes_trigger call.

When an entire requested message has been processed the internal state of AES registers must be securely cleared, by calling dif_aes_end.

Please see the following documentation for further information: https://docs.opentitan.org/hw/ip/aes/doc/ https://csrc.nist.gov/csrc/media/publications/fips/197/final/documents/fips-197.pdf https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38a.pdf

Definition in file dif_aes.h.

---

Data Structure Documentation

dif_aes_key_share

struct dif_aes_key_share

A typed representation of the AES key share.

Two part masked AES key, where XOR operation of these two parts results in the actual key.

Definition at line 57 of file dif_aes.h.

Data Fields
uint32_t	share0[8]	One share of the key that when XORed with share1 results in the actual key.
uint32_t	share1[8]	One share of the key that when XORed with share0 results in the actual key.

dif_aes_iv

struct dif_aes_iv

A typed representation of the AES Initialisation Vector (IV).

Definition at line 73 of file dif_aes.h.

Data Fields
uint32_t	iv[4]

dif_aes_data

struct dif_aes_data

A typed representation of the AES data.

Definition at line 80 of file dif_aes.h.

Data Fields
uint32_t	data[4]

dif_aes_transaction

struct dif_aes_transaction

Parameters for an AES transaction.

Definition at line 248 of file dif_aes.h.

Data Fields
bool	ctrl_aux_lock	If true reseed_on_key_change and force_masks will be locked until the device is reset.
bool	force_masks	If true, the internal pseudo-random number generator used for masking is not advancing leading to constant masks. NOTE: This should only be used for development purpose (SCA), and is expected to be removed for the production version.
dif_aes_key_length_t	key_len
dif_aes_key_provider_t	key_provider
dif_aes_manual_operation_t	manual_operation
dif_aes_mask_reseeding_t	mask_reseeding
dif_aes_mode_t	mode
dif_aes_operation_t	operation
bool	reseed_on_key_change	If true the internal pseudo-random number generators used for clearing and masking will be reseeded every time the key changes.

Typedef Documentation

dif_aes_key_provider_t

typedef enum dif_aes_key_provider dif_aes_key_provider_t

AES key sideloaded.

Controls whether the AES uses the key provided by the key manager or software.

dif_aes_key_share_t

typedef struct dif_aes_key_share dif_aes_key_share_t

A typed representation of the AES key share.

Two part masked AES key, where XOR operation of these two parts results in the actual key.

dif_aes_mask_reseeding_t

typedef enum dif_aes_mask_reseeding dif_aes_mask_reseeding_t

AES reseeding rate.

Controls the reseeding rate of the internal pseudo-random number generator (PRNG) used for masking.

Enumeration Type Documentation

dif_aes_key_length

enum dif_aes_key_length

AES key length in bits.

Enumerator
kDifAesKey128	128 bit wide AES key.
kDifAesKey192	192 bit wide AES key.
kDifAesKey256	256 bit wide AES key.

Definition at line 176 of file dif_aes.h.

dif_aes_key_provider

enum dif_aes_key_provider

AES key sideloaded.

Controls whether the AES uses the key provided by the key manager or software.

Enumerator
kDifAesKeySoftwareProvided	The key is provided by software via dif_aes_key_share_t.
kDifAesKeySideload	The key be provided by the key manager.

Definition at line 213 of file dif_aes.h.

dif_aes_manual_operation

enum dif_aes_manual_operation

AES manual operation.

Enumerator
kDifAesManualOperationAuto	AES operates in automatic mode - which means that the encryption/decryption is automatically triggered on every successful dif_aes_*_load_data().
kDifAesManualOperationManual	AES operates in manual mode - which means that the encryption/decryption is manually triggered by dif_aes_trigger(kDifAesTriggerStart).

Definition at line 194 of file dif_aes.h.

dif_aes_mask_reseeding

enum dif_aes_mask_reseeding

AES reseeding rate.

Controls the reseeding rate of the internal pseudo-random number generator (PRNG) used for masking.

Enumerator
kDifAesReseedPerBlock	The masking PRNG will be reseed every block.
kDifAesReseedPer64Block	The masking PRNG will be reseed every 64 blocks.
kDifAesReseedPer8kBlock	The masking PRNG will be reseed every 8192 blocks.

Definition at line 230 of file dif_aes.h.

dif_aes_mode

enum dif_aes_mode

AES block cipher mode of operation.

Enumerator
kDifAesModeEcb	The Electronic Codebook Mode. In ECB cipher mode the key must be changed for every new block of data. This is the only secure way to use ECB cipher mode. Note: The ECB cipher mode doesn't use the iv parameter of the dif_aes_start function. Note: it is discouraged to use this cipher mode, due to impractical amount of different keys required to encrypt/decrypt multi-block messages.
kDifAesModeCbc	The Cipher Block Chaining Mode. In CBC cipher mode, the same key can be used for all messages, however new Initialisation Vector (IV) must be generated for any new message. The following condition must be true: The IV must be unpredictable (it must not be possible to predict the IV that will be associated to the plaintext in advance of the generation of the IV). With key length less than 256 bits, the excess portion of the key can be written with any data (preferably random).
kDifAesModeCfb	The Cipher Feedback Mode. In CFB cipher mode, the same key can be used for all messages, however new Initialisation Vector (IV) must be generated for any new message. The following condition must be true: The IV must be unpredictable (it must not be possible to predict the IV that will be associated to the plaintext in advance of the generation of the IV). With key length less than 256 bits, the excess portion of the key can be written with any data (preferably random).
kDifAesModeOfb	The Output Feedback Mode. In OFB cipher mode, the same key can be used for all messages, and the Initialization Vector (IV) need NOT be unpredictable. The following conditions must be true: OFB mode requires a unique initialization vector for every message that is ever encrypted under a given key, across all messages. With key length less than 256 bits, the excess portion of the key can be written with any data (preferably random).
kDifAesModeCtr	The Counter Mode. In CTR cipher mode, the same key can be used for all messages, if the following condition is true: CTR mode requires a unique counter block for each plaintext block that is ever encrypted under a given key, across all messages. With key length less than 256 bits, the excess portion of the key can be written with any data (preferably random).

Definition at line 101 of file dif_aes.h.

dif_aes_operation

enum dif_aes_operation

AES operation.

Enumerator
kDifAesOperationEncrypt	AES encryption.
kDifAesOperationDecrypt	AES decryption.

Definition at line 87 of file dif_aes.h.

dif_aes_status

enum dif_aes_status

AES Status flags.

Enumerator
kDifAesStatusIdle	Device is idle.
kDifAesStatusStall	Device has stalled (only relevant in automatic operation mode). Output data overwrite protection.
kDifAesStatusOutputLost	Output data has been overwritten by the AES unit before the processor could fully read it. This bit is "sticky" for the entire duration of the current transaction.
kDifAesStatusOutputValid	Device output is valid/ready. Denotes a successful encrypt or decrypt operation.
kDifAesStatusInputReady	Device Input Data registers can be written to (ready to accept new input data).
kDifAesStatusAlertFatalFault	Fatal alert conditions include i) storage errors in the Control Register, and ii) if any internal FSM enters an invalid state.
kDifAesStatusAlertRecovCtrlUpdateErr	Recoverable alert conditions include update errors in the Control Register.

Definition at line 413 of file dif_aes.h.

dif_aes_trigger

enum dif_aes_trigger

AES Trigger flags.

Enumerator
kDifAesTriggerStart	Trigger encrypt/decrypt.
kDifAesTriggerKeyIvDataInClear	Clear key, Initialisation Vector/Initial Counter Value and input data.
kDifAesTriggerDataOutClear	Clear Output Data registers.
kDifAesTriggerPrngReseed	Perform reseed of the internal state.

Definition at line 378 of file dif_aes.h.

Function Documentation

dif_aes_end()

OT_WARN_UNUSED_RESULT dif_result_t dif_aes_end

(

const dif_aes_t *

aes

)

Ends an AES transaction.

This function must be called at the end of every dif_aes_<mode>_start operation.

The peripheral must be in IDLE state for this operation to take effect, and will return kDifAesEndBusy if this condition is not met.

Parameters

aes	AES state data.

Returns

The result of the operation.

Definition at line 258 of file dif_aes.c.

dif_aes_get_status()

OT_WARN_UNUSED_RESULT dif_result_t dif_aes_get_status	(	const dif_aes_t *	aes,
		dif_aes_status_t	flag,
		bool *	set
	)

Queries the AES status flags.

Parameters

	aes	AES state data.
	flag	Status flag to query.
[out]	set	Flag state (set/unset).

Returns

The result of the operation.

Definition at line 368 of file dif_aes.c.

dif_aes_load_data()

OT_WARN_UNUSED_RESULT dif_result_t dif_aes_load_data	(	const dif_aes_t *	aes,
		const dif_aes_data_t	data
	)

Loads AES Input Data.

This function will trigger encryption/decryption when configured in the automatic operation mode.

The peripheral must be able to accept the input (INPUT_READY set), and will return kDifAesLoadDataBusy if this condition is not met.

Parameters

aes	AES state data.
data	AES Input Data.

Returns

The result of the operation.

Definition at line 272 of file dif_aes.c.

dif_aes_process_data()

OT_WARN_UNUSED_RESULT dif_result_t dif_aes_process_data	(	const dif_aes_t *	aes,
		const dif_aes_data_t *	plain_text,
		dif_aes_data_t *	cipher_text,
		size_t	block_amount
	)

Process a stream of data containing the plain text and output a stream of data with the cipher text.

This function should be used when performance is desired. It requires the automatic operation mode activated.

The peripheral must be able to accept the input (INPUT_READY set), and will return kDifAesLoadDataBusy if this condition is not met.

Parameters

aes	AES handle.
plain_text	AES Input Data.
cipher_text	AES Output Data.
block_amount	The amount of blocks to be encrypted.

Returns

The result of the operation.

Definition at line 303 of file dif_aes.c.

dif_aes_read_iv()

OT_WARN_UNUSED_RESULT dif_result_t dif_aes_read_iv	(	const dif_aes_t *	aes,
		dif_aes_iv_t *	iv
	)

Read the current initialization vector from its register.

Parameters

aes	AES handle.
iv	The pointer to receive the initialization vector.

Returns

The result of the operation.

Definition at line 403 of file dif_aes.c.

dif_aes_read_output()

OT_WARN_UNUSED_RESULT dif_result_t dif_aes_read_output	(	const dif_aes_t *	aes,
		dif_aes_data_t *	data
	)

Reads AES Output Data.

The peripheral must have finished previous encryption/decryption operation, and have valid data in the output registers (OUTPUT_VALID set), and will return kDifAesReadOutputInvalid if this condition is not met.

Parameters

aes	AES state data.
data	AES Output Data.

Returns

The result of the operation.

Definition at line 288 of file dif_aes.c.

dif_aes_reset()

OT_WARN_UNUSED_RESULT dif_result_t dif_aes_reset

(

const dif_aes_t *

aes

)

Resets an instance of AES.

Clears the internal state along with the interface registers.

Parameters

aes	AES state data.

Returns

The result of the operation.

Definition at line 191 of file dif_aes.c.

dif_aes_start()

OT_WARN_UNUSED_RESULT dif_result_t dif_aes_start	(	const dif_aes_t *	aes,
		const dif_aes_transaction_t *	transaction,
		const dif_aes_key_share_t *	key,
		const dif_aes_iv_t *	iv
	)

Begins an AES transaction in the mode selected by the transaction->mode.

Each call to this function should be sequenced with a call to dif_aes_end().

The peripheral must be in IDLE state for this operation to take effect, and will return kDifAesBusy if this condition is not met.

Parameters

aes	AES state data.
transaction	Configuration data.
key	Encryption/decryption key when kDifAesKeySoftwareProvided, can be NULL otherwise.
iv	Initialization vector when the mode isn't kDifAesModeEcb, can be NULL otherwise.

Returns

The result of the operation.

Definition at line 213 of file dif_aes.c.

dif_aes_trigger()

OT_WARN_UNUSED_RESULT dif_result_t dif_aes_trigger	(	const dif_aes_t *	aes,
		dif_aes_trigger_t	trigger
	)

Triggers one of dif_aes_trigger_t operations.

All the triggers are applicable to both (automatic and manual) modes, with the exception of kDifAesTriggerStart, which is ignored in automatic mode.

Parameters

aes	AES state data.
trigger	AES trigger.

Returns

The result of the operation.

Definition at line 357 of file dif_aes.c.