Software APIs
Data Structures | Typedefs | Enumerations | Functions
dif_aes.h File Reference

(dcee03a)

AES Device Interface Functions More...

#include <stdbool.h>
#include <stdint.h>
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_warn_unused_result.h"

Go to the source code of this file.

Data Structures

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...
 
struct  dif_aes_params
 Hardware instantiation parameters for AES. More...
 
struct  dif_aes
 A handle to AES. More...
 

Typedefs

typedef struct dif_aes_key_share dif_aes_key_share_t
 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. 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_key_length dif_aes_key_length_t
 AES key length in bits.
 
typedef enum dif_aes_mode dif_aes_mode_t
 AES mode.
 
typedef enum dif_aes_operation dif_aes_operation_t
 AES operation.
 
typedef enum dif_aes_masking dif_aes_masking_t
 AES masking. More...
 
typedef struct dif_aes_transaction dif_aes_transaction_t
 Parameters for an AES transaction.
 
typedef enum dif_aes_alert dif_aes_alert_t
 An AES alert type.
 
typedef struct dif_aes_params dif_aes_params_t
 Hardware instantiation parameters for AES. More...
 
typedef struct dif_aes dif_aes_t
 A handle to AES. More...
 
typedef enum dif_aes_result dif_aes_result_t
 The result of a AES operation.
 
typedef enum dif_aes_reset_result dif_aes_reset_result_t
 The result of a AES reset operation.
 
typedef enum dif_aes_start_result dif_aes_start_result_t
 The result of a AES start operation.
 
typedef enum dif_aes_end_result dif_aes_end_result_t
 The result of an AES end operation.
 
typedef enum dif_aes_load_data_result dif_aes_load_data_result_t
 The result of an AES load data operation.
 
typedef enum dif_aes_read_data_result dif_aes_read_output_result_t
 The result of an AES data read operation.
 
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_key_length {
  kDifAesKey128 = 0,
  kDifAesKey192,
  kDifAesKey256
}
 AES key length in bits. More...
 
enum  dif_aes_mode {
  kDifAesModeEncrypt = 0,
  kDifAesModeDecrypt
}
 AES mode. More...
 
enum  dif_aes_operation {
  kDifAesOperationAuto = 0,
  kDifAesOperationManual
}
 AES operation. More...
 
enum  dif_aes_masking {
  kDifAesMaskingInternalPrng = 0,
  kDifAesMaskingForceZero
}
 AES masking. More...
 
enum  dif_aes_alert {
  kDifAlertFatalFault = 0,
  kDifAlertRecovCtrlUpdateErr
}
 An AES alert type. More...
 
enum  dif_aes_result {
  kDifAesOk = 0,
  kDifAesError = 1,
  kDifAesBadArg = 2
}
 The result of a AES operation. More...
 
enum  dif_aes_reset_result {
  kDifAesResetOk = kDifAesOk,
  kDifAesResetError = kDifAesError,
  kDifAesResetBadArg = kDifAesBadArg,
  kDifAesResetBusy
}
 The result of a AES reset operation. More...
 
enum  dif_aes_start_result {
  kDifAesStartOk = kDifAesOk,
  kDifAesStartError = kDifAesError,
  kDifAesStartBadArg = kDifAesBadArg,
  kDifAesStartBusy
}
 The result of a AES start operation. More...
 
enum  dif_aes_end_result {
  kDifAesEndOk = kDifAesOk,
  kDifAesEndError = kDifAesError,
  kDifAesEndBadArg = kDifAesBadArg,
  kDifAesEndBusy
}
 The result of an AES end operation. More...
 
enum  dif_aes_load_data_result {
  kDifAesLoadDataOk = kDifAesOk,
  kDifAesLoadDataError = kDifAesError,
  kDifAesLoadDataBadArg = kDifAesBadArg,
  kDifAesLoadDataBusy
}
 The result of an AES load data operation. More...
 
enum  dif_aes_read_data_result {
  kDifAesReadOutputOk = kDifAesOk,
  kDifAesReadOutputError = kDifAesError,
  kDifAesReadOutputBadArg = kDifAesBadArg,
  kDifAesReadOutputInvalid
}
 The result of an AES data read operation. 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

DIF_WARN_UNUSED_RESULT dif_aes_result_t dif_aes_init (dif_aes_params_t params, dif_aes_t *aes)
 Creates a new handle for AES. More...
 
DIF_WARN_UNUSED_RESULT dif_aes_reset_result_t dif_aes_reset (const dif_aes_t *aes)
 Resets an instance of AES. More...
 
DIF_WARN_UNUSED_RESULT dif_aes_start_result_t dif_aes_start_ecb (const dif_aes_t *aes, const dif_aes_transaction_t *transaction, dif_aes_key_share_t key)
 Begins an AES transaction in ECB mode. More...
 
DIF_WARN_UNUSED_RESULT dif_aes_start_result_t dif_aes_start_cbc (const dif_aes_t *aes, const dif_aes_transaction_t *transaction, dif_aes_key_share_t key, dif_aes_iv_t iv)
 Begins an AES transaction in CBC mode. More...
 
DIF_WARN_UNUSED_RESULT dif_aes_start_result_t dif_aes_start_ctr (const dif_aes_t *aes, const dif_aes_transaction_t *transaction, dif_aes_key_share_t key, dif_aes_iv_t iv)
 Begins an AES transaction in CTR mode. More...
 
DIF_WARN_UNUSED_RESULT dif_aes_end_result_t dif_aes_end (const dif_aes_t *aes)
 Ends an AES transaction. More...
 
DIF_WARN_UNUSED_RESULT dif_aes_load_data_result_t dif_aes_load_data (const dif_aes_t *aes, const dif_aes_data_t data)
 Loads AES Input Data. More...
 
DIF_WARN_UNUSED_RESULT dif_aes_read_output_result_t dif_aes_read_output (const dif_aes_t *aes, dif_aes_data_t *data)
 Reads AES Output Data. More...
 
DIF_WARN_UNUSED_RESULT dif_aes_result_t dif_aes_trigger (const dif_aes_t *aes, dif_aes_trigger_t trigger)
 Triggers one of dif_aes_trigger_t operations. More...
 
DIF_WARN_UNUSED_RESULT dif_aes_result_t dif_aes_get_status (const dif_aes_t *aes, dif_aes_status_t flag, bool *set)
 Queries the AES status flags. More...
 
DIF_WARN_UNUSED_RESULT dif_aes_result_t dif_aes_alert_force (const dif_aes_t *aes, dif_aes_alert_t alert)
 Forces a particular alert, causing it to be serviced as if hardware had asserted it. More...
 

Detailed Description

AES Device Interface Functions

Definition in file dif_aes.h.


Data Structure Documentation

◆ dif_aes_key_share

struct dif_aes_key_share

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 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 55 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 71 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 78 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 151 of file dif_aes.h.

Data Fields
dif_aes_key_length_t key_len
dif_aes_masking_t masking
dif_aes_mode_t mode
dif_aes_operation_t operation

◆ dif_aes_params

struct dif_aes_params

Hardware instantiation parameters for AES.

This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.

Definition at line 180 of file dif_aes.h.

Data Fields
mmio_region_t base_addr The base address for the AES hardware registers.

◆ dif_aes

struct dif_aes

A handle to AES.

This type should be treated as opaque by users.

Definition at line 192 of file dif_aes.h.

Data Fields
dif_aes_params_t params

Typedef Documentation

◆ dif_aes_key_share_t

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

AES masking.

NOTE: This should only be used for development purpose (SCA), and expected to be removed before the production version.

◆ dif_aes_params_t

Hardware instantiation parameters for AES.

This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.

◆ dif_aes_t

typedef struct dif_aes dif_aes_t

A handle to AES.

This type should be treated as opaque by users.

Enumeration Type Documentation

◆ dif_aes_alert

An AES alert type.

Enumerator
kDifAlertFatalFault 

Fatal alert conditions include i) storage errors in the Control Register, and ii) if any internal FSM enters an invalid state.

kDifAlertRecovCtrlUpdateErr 

Recoverable alert conditions include update errors in the Control Register.

Definition at line 161 of file dif_aes.h.

◆ dif_aes_end_result

The result of an AES end operation.

Enumerator
kDifAesEndOk 

Indicates that the operation succeeded.

kDifAesEndError 

Indicates some unspecified failure.

kDifAesEndBadArg 

Indicates that some parameter passed into a function failed a precondition.

When this value is returned, no hardware operations occurred.

kDifAesEndBusy 

Device is busy, and cannot perform the requested operation.

Definition at line 370 of file dif_aes.h.

◆ 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 85 of file dif_aes.h.

◆ dif_aes_load_data_result

The result of an AES load data operation.

Enumerator
kDifAesLoadDataOk 

Indicates that the operation succeeded.

kDifAesLoadDataError 

Indicates some unspecified failure.

kDifAesLoadDataBadArg 

Indicates that some parameter passed into a function failed a precondition.

When this value is returned, no hardware operations occurred.

kDifAesLoadDataBusy 

Device is busy, and cannot perform the requested operation.

Definition at line 410 of file dif_aes.h.

◆ dif_aes_masking

AES masking.

NOTE: This should only be used for development purpose (SCA), and expected to be removed before the production version.

Enumerator
kDifAesMaskingInternalPrng 

Pseudo-random generator is used for masking.

kDifAesMaskingForceZero 

Completely disables masking by forcing all masks to zero.

Definition at line 137 of file dif_aes.h.

◆ dif_aes_mode

AES mode.

Enumerator
kDifAesModeEncrypt 

AES encryption mode.

kDifAesModeDecrypt 

AES decryption mode.

Definition at line 103 of file dif_aes.h.

◆ dif_aes_operation

AES operation.

Enumerator
kDifAesOperationAuto 

AES operates in automatic mode - which means that the encryption/decryption is automatically triggered on every successful dif_aes_*_load_data().

kDifAesOperationManual 

AES operates in manual mode - which means that the encryption/decryption is manually triggered by dif_aes_trigger(kDifAesTriggerStart).

Definition at line 117 of file dif_aes.h.

◆ dif_aes_read_data_result

The result of an AES data read operation.

Enumerator
kDifAesReadOutputOk 

Indicates that the operation succeeded.

kDifAesReadOutputError 

Indicates some unspecified failure.

kDifAesReadOutputBadArg 

Indicates that some parameter passed into a function failed a precondition.

When this value is returned, no hardware operations occurred.

kDifAesReadOutputInvalid 

The AES unit has no valid output.

Definition at line 452 of file dif_aes.h.

◆ dif_aes_reset_result

The result of a AES reset operation.

Enumerator
kDifAesResetOk 

Indicates that the operation succeeded.

kDifAesResetError 

Indicates some unspecified failure.

kDifAesResetBadArg 

Indicates that some parameter passed into a function failed a precondition.

When this value is returned, no hardware operations occurred.

kDifAesResetBusy 

Device is busy, and cannot perform the requested operation.

Definition at line 232 of file dif_aes.h.

◆ dif_aes_result

The result of a AES operation.

Enumerator
kDifAesOk 

Indicates that the operation succeeded.

kDifAesError 

Indicates some unspecified failure.

kDifAesBadArg 

Indicates that some parameter passed into a function failed a precondition.

When this value is returned, no hardware operations occurred.

Definition at line 199 of file dif_aes.h.

◆ dif_aes_start_result

The result of a AES start operation.

Enumerator
kDifAesStartOk 

Indicates that the operation succeeded.

kDifAesStartError 

Indicates some unspecified failure.

kDifAesStartBadArg 

Indicates that some parameter passed into a function failed a precondition.

When this value is returned, no hardware operations occurred.

kDifAesStartBusy 

Device is busy, and cannot perform the requested operation.

Definition at line 268 of file dif_aes.h.

◆ 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 528 of file dif_aes.h.

◆ 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 492 of file dif_aes.h.

Function Documentation

◆ dif_aes_alert_force()

DIF_WARN_UNUSED_RESULT dif_aes_result_t dif_aes_alert_force ( const dif_aes_t aes,
dif_aes_alert_t  alert 
)

Forces a particular alert, causing it to be serviced as if hardware had asserted it.

Parameters
aesAES state data.
alertAn alert type.
Returns
The result of the operation.

Definition at line 423 of file dif_aes.c.

◆ dif_aes_end()

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
aesAES state data.
Returns
The result of the operation.

Definition at line 309 of file dif_aes.c.

◆ dif_aes_get_status()

DIF_WARN_UNUSED_RESULT dif_aes_result_t dif_aes_get_status ( const dif_aes_t aes,
dif_aes_status_t  flag,
bool *  set 
)

Queries the AES status flags.

Parameters
aesAES state data.
flagStatus flag to query.
setFlag state (set/unset).
Returns
The result of the operation.

Definition at line 387 of file dif_aes.c.

◆ dif_aes_init()

DIF_WARN_UNUSED_RESULT dif_aes_result_t dif_aes_init ( dif_aes_params_t  params,
dif_aes_t aes 
)

Creates a new handle for AES.

This function does not actuate the hardware.

Parameters
paramsHardware instantiation parameters.
[out]aesOut param for the initialised handle.
Returns
The result of the operation.

Definition at line 195 of file dif_aes.c.

◆ dif_aes_load_data()

DIF_WARN_UNUSED_RESULT dif_aes_load_data_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
aesAES state data.
dataAES Input Data.
Returns
The result of the operation.

Definition at line 323 of file dif_aes.c.

◆ dif_aes_read_output()

DIF_WARN_UNUSED_RESULT dif_aes_read_output_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
aesAES state data.
dataAES Output Data.
Returns
The result of the operation.

Definition at line 339 of file dif_aes.c.

◆ dif_aes_reset()

Resets an instance of AES.

Clears the internal state along with the interface registers.

Parameters
aesAES state data.
Returns
The result of the operation.

Definition at line 205 of file dif_aes.c.

◆ dif_aes_start_cbc()

DIF_WARN_UNUSED_RESULT dif_aes_start_result_t dif_aes_start_cbc ( const dif_aes_t aes,
const dif_aes_transaction_t transaction,
dif_aes_key_share_t  key,
dif_aes_iv_t  iv 
)

Begins an AES transaction in CBC 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).

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

Parameters
aesAES state data.
transactionConfiguration data.
keyMasked AES key.
ivAES Initialisation Vector.
Returns
The result of the operation.

Definition at line 253 of file dif_aes.c.

◆ dif_aes_start_ctr()

DIF_WARN_UNUSED_RESULT dif_aes_start_result_t dif_aes_start_ctr ( const dif_aes_t aes,
const dif_aes_transaction_t transaction,
dif_aes_key_share_t  key,
dif_aes_iv_t  iv 
)

Begins an AES transaction in CTR 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).

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

Parameters
aesAES state data.
transactionConfiguration data.
keyMasked AES key.
ivAES Initial Counter Value.
Returns
The result of the operation.

Definition at line 281 of file dif_aes.c.

◆ dif_aes_start_ecb()

DIF_WARN_UNUSED_RESULT dif_aes_start_result_t dif_aes_start_ecb ( const dif_aes_t aes,
const dif_aes_transaction_t transaction,
dif_aes_key_share_t  key 
)

Begins an AES transaction in ECB 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.

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

Note: it is discouraged to use this cipher mode, due to inpractical amount of different keys required to encrypt/decrypt multi-block messages.

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

Parameters
aesAES state data.
transactionConfiguration data.
Returns
The result of the operation.

Definition at line 227 of file dif_aes.c.

◆ dif_aes_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
aesAES state data.
triggerAES trigger.
Returns
The result of the operation.

Definition at line 358 of file dif_aes.c.