 |
Software APIs
|
|
Software APIs
|
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_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. 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... | |
| 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. | |
| 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.
| struct dif_aes_iv |
| struct dif_aes_data |
| struct dif_aes_transaction |
| Data Fields | ||
|---|---|---|
| dif_aes_key_length_t | key_len | |
| dif_aes_masking_t | masking | |
| dif_aes_mode_t | mode | |
| dif_aes_operation_t | operation | |
| 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.
| Data Fields | ||
|---|---|---|
| mmio_region_t | base_addr | The base address for the AES hardware registers. |
| struct dif_aes |
A handle to AES.
This type should be treated as opaque by users.
| Data Fields | ||
|---|---|---|
| dif_aes_params_t | params | |
| 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.
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.
| typedef enum dif_aes_masking 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.
| typedef struct dif_aes_params 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.
| enum dif_aes_alert |
| enum dif_aes_end_result |
The result of an AES end operation.
| enum dif_aes_key_length |
The result of an AES load data operation.
| enum dif_aes_masking |
| enum dif_aes_mode |
| enum dif_aes_operation |
AES operation.
The result of an AES data read operation.
| enum dif_aes_reset_result |
The result of a AES reset operation.
| enum dif_aes_result |
| enum dif_aes_start_result |
The result of a AES start operation.
| enum dif_aes_status |
AES Status flags.
| enum dif_aes_trigger |
| DIF_WARN_UNUSED_RESULT dif_aes_result_t dif_aes_alert_force | ( | const dif_aes_t * | aes, |
| dif_aes_alert_t | alert | ||
| ) |
| DIF_WARN_UNUSED_RESULT dif_aes_end_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.
| aes | AES state data. |
| DIF_WARN_UNUSED_RESULT dif_aes_result_t dif_aes_get_status | ( | const dif_aes_t * | aes, |
| dif_aes_status_t | flag, | ||
| bool * | set | ||
| ) |
| DIF_WARN_UNUSED_RESULT dif_aes_result_t dif_aes_init | ( | dif_aes_params_t | params, |
| dif_aes_t * | aes | ||
| ) |
| 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.
| aes | AES state data. |
| data | AES Input Data. |
| 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.
| aes | AES state data. |
| data | AES Output Data. |
| DIF_WARN_UNUSED_RESULT dif_aes_reset_result_t dif_aes_reset | ( | const dif_aes_t * | aes | ) |
| 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.
| aes | AES state data. |
| transaction | Configuration data. |
| key | Masked AES key. |
| iv | AES Initialisation Vector. |
| 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.
| aes | AES state data. |
| transaction | Configuration data. |
| key | Masked AES key. |
| iv | AES Initial Counter Value. |
| 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.
| aes | AES state data. |
| transaction | Configuration data. |
| 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.
All the triggers are applicable to both (automatic and manual) modes, with the exception of kDifAesTriggerStart, which is ignored in automatic mode.
| aes | AES state data. |
| trigger | AES trigger. |