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

(a649ec5)

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

AES key sideloaded.

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

◆ 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

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

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

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

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

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

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

AES operation.

Enumerator
kDifAesOperationEncrypt 

AES encryption.

kDifAesOperationDecrypt 

AES decryption.

Definition at line 87 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 413 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 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
aesAES 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
aesAES state data.
flagStatus flag to query.
[out]setFlag 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
aesAES state data.
dataAES 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
aesAES handle.
plain_textAES Input Data.
cipher_textAES Output Data.
block_amountThe 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
aesAES handle.
ivThe 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
aesAES state data.
dataAES 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
aesAES 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
aesAES state data.
transactionConfiguration data.
keyEncryption/decryption key when kDifAesKeySoftwareProvided, can be NULL otherwise.
ivInitialization 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()

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 357 of file dif_aes.c.