(2c5ba75c1c)

KMAC Device Interface Functions More...

#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_kmac_autogen.h"

Go to the source code of this file.

Data Structures
struct	dif_kmac_config
	Runtime configuration for KMAC. More...

struct	dif_kmac_operation_state
	A KMAC operation state context. More...

struct	dif_kmac_key
	A key for KMAC operations. More...

struct	dif_kmac_customization_string
	An encoded bit string used for customization string (S). More...

struct	dif_kmac_function_name
	An encoded bit string used for function name (N). More...

struct	dif_kmac_status

Typedefs
typedef enum dif_kmac_entropy_mode	dif_kmac_entropy_mode_t
	This API implements an interface for the KMAC hardware. More...

typedef struct dif_kmac_config	dif_kmac_config_t
	Runtime configuration for KMAC. More...

typedef struct dif_kmac_operation_state	dif_kmac_operation_state_t
	A KMAC operation state context.

typedef enum dif_kmac_mode_sha3	dif_kmac_mode_sha3_t
	Supported SHA-3 modes of operation.

typedef enum dif_kmac_mode_shake	dif_kmac_mode_shake_t
	Supported SHAKE modes of operation.

typedef enum dif_kmac_mode_cshake	dif_kmac_mode_cshake_t
	Supported cSHAKE modes of operation.

typedef enum dif_kmac_mode_kmac	dif_kmac_mode_kmac_t
	Supported KMAC modes of operation.

typedef enum dif_kmac_key_length	dif_kmac_key_length_t
	Key length. More...

typedef struct dif_kmac_key	dif_kmac_key_t
	A key for KMAC operations. More...

typedef struct dif_kmac_customization_string	dif_kmac_customization_string_t
	An encoded bit string used for customization string (S). More...

typedef struct dif_kmac_function_name	dif_kmac_function_name_t
	An encoded bit string used for function name (N). More...

typedef enum dif_kmac_error	dif_kmac_error_t
	Error reported by KMAC unit. More...

typedef enum dif_kmac_fifo_state	dif_kmac_fifo_state_t
	The state of the message FIFO used to buffer absorbed data. More...

typedef enum dif_kmac_sha3_state	dif_kmac_sha3_state_t

typedef enum dif_kmac_alert_faults	dif_kmac_alert_faults_t
	The kmac error faults. More...

typedef struct dif_kmac_status	dif_kmac_status_t

Enumerations
enum	dif_kmac_entropy_mode { kDifKmacEntropyModeIdle = 0 , kDifKmacEntropyModeEdn , kDifKmacEntropyModeSoftware }
	This API implements an interface for the KMAC hardware. More...

enum	{ kDifKmacMaxCustomizationStringLen = 32 , kDifKmacMaxCustomizationStringOverhead = 3 , kDifKmacMaxFunctionNameLen = 4 , kDifKmacMaxFunctionNameOverhead = 2 , kDifKmacMaxOutputLenWords = (UINT32_MAX - 32) / 32 , kDifKmacMaxKeyLenWords = 512 / 32 , kDifKmacEntropySeedWords = 6 , kDifKmacStateShareOffset = 0x100 , kDifKmacStateWords = 1600 / 8 / sizeof(uint32_t) }
	Maximum lengths supported by the KMAC unit. More...

enum	dif_kmac_mode_sha3 { kDifKmacModeSha3Len224 , kDifKmacModeSha3Len256 , kDifKmacModeSha3Len384 , kDifKmacModeSha3Len512 }
	Supported SHA-3 modes of operation. More...

enum	dif_kmac_mode_shake { kDifKmacModeShakeLen128 , kDifKmacModeShakeLen256 }
	Supported SHAKE modes of operation. More...

enum	dif_kmac_mode_cshake { kDifKmacModeCshakeLen128 , kDifKmacModeCshakeLen256 }
	Supported cSHAKE modes of operation. More...

enum	dif_kmac_mode_kmac { kDifKmacModeKmacLen128 , kDifKmacModeKmacLen256 }
	Supported KMAC modes of operation. More...

enum	dif_kmac_key_length { kDifKmacKeyLen128 = 0 , kDifKmacKeyLen192 = 1 , kDifKmacKeyLen256 = 2 , kDifKmacKeyLen384 = 3 , kDifKmacKeyLen512 = 4 }
	Key length. More...

enum	dif_kmac_error { kDifErrorNone = 0 , kDifErrorKeyNotValid = 1 , kDifErrorSoftwarePushedMessageFifo = 2 , kDifErrorSoftwareIssuedCommandWhileAppInterfaceActive = 3 , kDifErrorEntropyWaitTimerExpired = 4 , kDifErrorEntropyModeIncorrect = 5 , kDifErrorUnexpectedModeStrength = 6 , kDifErrorIncorrectFunctionName = 7 , kDifErrorSoftwareCommandSequence = 8 , kDifErrorSoftwareHashingWithoutEntropyReady = 9 , kDifErrorFatalError = 0xC1 , kDifErrorPackerIntegrity = 0xC2 , kDifErrorMsgFifoIntegrity = 0xC3 }
	Error reported by KMAC unit. More...

enum	dif_kmac_fifo_state { kDifKmacFifoStatePartial = 0 , kDifKmacFifoStateEmpty = 1 << 0 , kDifKmacFifoStateFull = 1 << 1 }
	The state of the message FIFO used to buffer absorbed data. More...

enum	dif_kmac_sha3_state { kDifKmacSha3StateIdle = 1 << 0 , kDifKmacSha3StateAbsorbing = 1 << 1 , kDifKmacSha3StateSqueezing = 1 << 2 }

enum	dif_kmac_alert_faults { kDifKmacAlertNone = 0 , kDifKmacAlertFatalFault = 1 << 0 , kDifKmacAlertRecovCtrlUpdate = 1 << 1 }
	The kmac error faults. More...

Functions
OT_WARN_UNUSED_RESULT dif_result_t	dif_kmac_configure (dif_kmac_t *kmac, dif_kmac_config_t config)
	Configures KMAC with runtime information. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_kmac_customization_string_init (const char data, size_t len, dif_kmac_customization_string_t out)
	Encode a customization string (S). More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_kmac_function_name_init (const char data, size_t len, dif_kmac_function_name_t out)
	Encode a function name (N). More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_kmac_mode_sha3_start (const dif_kmac_t kmac, dif_kmac_operation_state_t operation_state, dif_kmac_mode_sha3_t mode)
	Start a SHA-3 operation. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_kmac_mode_shake_start (const dif_kmac_t kmac, dif_kmac_operation_state_t operation_state, dif_kmac_mode_shake_t mode)
	Start a SHAKE operation. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_kmac_mode_cshake_start (const dif_kmac_t kmac, dif_kmac_operation_state_t operation_state, dif_kmac_mode_cshake_t mode, const dif_kmac_function_name_t n, const dif_kmac_customization_string_t s)
	Start a cSHAKE operation. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_kmac_mode_kmac_start (const dif_kmac_t kmac, dif_kmac_operation_state_t operation_state, dif_kmac_mode_kmac_t mode, size_t l, const dif_kmac_key_t k, const dif_kmac_customization_string_t s)
	Start a KMAC operation. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_kmac_absorb (const dif_kmac_t kmac, dif_kmac_operation_state_t operation_state, const void msg, size_t len, size_t processed)
	Absorb bytes from the message provided. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_kmac_squeeze (const dif_kmac_t kmac, dif_kmac_operation_state_t operation_state, uint32_t out, size_t len, size_t processed, uint32_t *capacity)
	Squeeze bytes into the output buffer provided. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_kmac_end (const dif_kmac_t kmac, dif_kmac_operation_state_t operation_state)
	Ends a squeeze operation and resets the hardware so it is ready for a new operation. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_kmac_get_error (const dif_kmac_t kmac, dif_kmac_error_t error, uint32_t *info)
	Read the kmac error register to get the error code indicated the interrupt state. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_kmac_reset (const dif_kmac_t kmac, dif_kmac_operation_state_t operation_state)
	Clear the current error code and reset the state machine to the idle state ready to accept new operations. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_kmac_err_processed (const dif_kmac_t *kmac)
	Let the KMAC HW know that SW has processed the errors the HW has flagged. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_kmac_has_error_occurred (const dif_kmac_t kmac, bool error)
	Report whether the hardware currently indicates an error. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_kmac_clear_err_irq (const dif_kmac_t *kmac)
	Clear the `kmac_err` IRQ. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_kmac_get_status (const dif_kmac_t kmac, dif_kmac_status_t kmac_status)
	Fetch the current status of the message FIFO used to buffer absorbed data. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_kmac_get_hash_counter (const dif_kmac_t kmac, uint32_t hash_ctr)
	Returns the current value of the refresh hash counter. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_kmac_config_is_locked (const dif_kmac_t kmac, bool is_locked)
	Reports whether or not the KMAC configuration register is locked. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_kmac_poll_status (const dif_kmac_t *kmac, uint32_t flag)
	Poll until a given flag in the status register is set. More...

Detailed Description

KMAC Device Interface Functions

Definition in file dif_kmac.h.

Data Structure Documentation

◆ dif_kmac_config

struct dif_kmac_config

Runtime configuration for KMAC.

This struct describes runtime information for configuration of the hardware.

Definition at line 153 of file dif_kmac.h.

Data Fields
bool	entropy_fast_process	Entropy fast process mode when enabled prevents the KMAC unit consuming entropy unless it is processing a secret key. This process should not be used when resistance against side-channel attacks is required, because it may lead to leakage of the secret key in the power trace.
uint16_t	entropy_hash_threshold	The number of KMAC invocations that triggers an automatic seed request from EDN.
dif_kmac_entropy_mode_t	entropy_mode	Entropy mode specifying the source of entropy (EDN or software).
uint16_t	entropy_prescaler	Prescaler value that determines how many clock pulse triggers an increment in the timer counter.
uint32_t	entropy_seed[kDifKmacEntropySeedWords]	Entropy seed. Only used when the source of entropy is software.
uint16_t	entropy_wait_timer	Number of clock cycles to wait for the EDN to reseed the entropy generator before an error is raised (see `dif_kmac_get_error`). If 0 the unit will wait forever.
bool	message_big_endian	Convert the message to big-endian byte order. Note: this option currently had no effect since the message is sent a byte at a time but will in the future.
bool	msg_mask	Message Masking with PRNG. If true, KMAC applies PRNG to the input messages to the Keccak module when KMAC mode is on.
bool	output_big_endian	Convert the output state (digest) to big-endian byte order on a word granularity.
bool	sideload	Place kmac inside key sideload mode.

◆ dif_kmac_operation_state

struct dif_kmac_operation_state

A KMAC operation state context.

Definition at line 221 of file dif_kmac.h.

Data Fields
bool	append_d	Flag indicating whether the output length (d) should be right encoded in software and appended to the end of the message. The output length is required to be appended to the message as part of a KMAC operation.
size_t	d	The output length (d) in 32-bit words. If the output length is not fixed then this field will be set to 0. Note: if the output length is fixed length will be modified to ensure that `d - offset` always accurately reflects the number of words remaining.
size_t	offset	Offset into the output state.
size_t	r	The rate (r) in 32-bit words.
bool	squeezing	Whether the 'squeezing' phase has been started.

◆ dif_kmac_key

struct dif_kmac_key

A key for KMAC operations.

The key is provided in two parts, share0 and share1. These are combined using a bitwise XOR operation in the KMAC unit to produce the real key.

The key shares are encoded in little endian byte order. This is fixed and cannot be changed (unlike the byte order used for the message and state).

Unused words in the key shares must be set to 0.

Definition at line 329 of file dif_kmac.h.

Data Fields
dif_kmac_key_length_t	length
uint32_t	share0[kDifKmacMaxKeyLenWords]
uint32_t	share1[kDifKmacMaxKeyLenWords]

◆ dif_kmac_customization_string

struct dif_kmac_customization_string

An encoded bit string used for customization string (S).

Use dif_kmac_customization_string_init to initialize.

Definition at line 340 of file dif_kmac.h.

Data Fields
char	buffer[kDifKmacMaxCustomizationStringLen+kDifKmacMaxCustomizationStringOverhead]	Encoded S: left_encode(len(S)) \|\| S.
uint32_t	length	Length of data in buffer in bytes.

◆ dif_kmac_function_name

struct dif_kmac_function_name

An encoded bit string used for function name (N).

Use dif_kmac_function_name_init to initialize.

Definition at line 353 of file dif_kmac.h.

Data Fields
char	buffer[kDifKmacMaxFunctionNameLen+kDifKmacMaxFunctionNameOverhead]	Encoded N: left_encode(len(N)) \|\| N.
uint32_t	length	Length of data in buffer in bytes.

◆ dif_kmac_status

struct dif_kmac_status

Definition at line 474 of file dif_kmac.h.

Data Fields
dif_kmac_alert_faults_t	faults	Kmac faults and errors state.
uint32_t	fifo_depth	Message FIFO entry count.
dif_kmac_fifo_state_t	fifo_state	Kmac fifo state.
dif_kmac_sha3_state_t	sha3_state	Sha3 state.

Typedef Documentation

◆ dif_kmac_alert_faults_t

typedef enum dif_kmac_alert_faults dif_kmac_alert_faults_t

The kmac error faults.

The hardware defined these status in different bit fields, however they work better in the same field. Then the values chosen for this enum allow the conversion from the register bits to this enum without branches.

◆ dif_kmac_config_t

typedef struct dif_kmac_config dif_kmac_config_t

Runtime configuration for KMAC.

This struct describes runtime information for configuration of the hardware.

◆ dif_kmac_customization_string_t

typedef struct dif_kmac_customization_string dif_kmac_customization_string_t

An encoded bit string used for customization string (S).

Use dif_kmac_customization_string_init to initialize.

◆ dif_kmac_entropy_mode_t

typedef enum dif_kmac_entropy_mode dif_kmac_entropy_mode_t

This API implements an interface for the KMAC hardware.

The KMAC hardware implements the following cryptographic hash and message authentication code (MAC) functions:

SHA-3 [1]
SHAKE [1]
cSHAKE [2]
KMAC [2]

The following sequence of operations is required to initialize the KMAC hardware:

If configuration changes are required then dif_kmac_configure can be called again so long as there are no operations in progress.

The following sequence of operations is required to execute an operation:

dif_kmac_{sha3,shake,cshake,kmac}_start()
dif_kmac_absorb()
dif_kmac_squeeze()
dif_kmac_end()

This is a streaming API and the dif_kmac_absorb and dif_kmac_squeeze functions may be called multiple times during a single operation. Once dif_kmac_squeeze has been called however no further dif_kmac_absorb calls may be made. See NIST FIPS 202 [1] for more information about the sponge construction and the 'absorbing' and 'squeezing' states.

Please see the following documentation for more information about the KMAC hardware: https://docs.opentitan.org/hw/ip/kmac/doc/

References: [1] - NIST FIPS 202 SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions http://dx.doi.org/10.6028/NIST.FIPS.202 [2] - NIST Special Publication 800-185 SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash and ParallelHash https://doi.org/10.6028/NIST.SP.800-185 Supported entropy modes.

Entropy may be provided by the entropy distribution network (EDN) or using a seed provided by software.

◆ dif_kmac_error_t

typedef enum dif_kmac_error dif_kmac_error_t

Error reported by KMAC unit.

Codes taken from hw/ip/kmac/rtl/kmac_pkg.sv:err_code_e

◆ dif_kmac_fifo_state_t

typedef enum dif_kmac_fifo_state dif_kmac_fifo_state_t

The state of the message FIFO used to buffer absorbed data.

The hardware defined these status in different bit fields, however they work better in the same field. i.e the fifo can't be empty and full at the same time. That said, the values chosen for this enum allow the conversion from the register bits to this enum without branches.

◆ dif_kmac_function_name_t

typedef struct dif_kmac_function_name dif_kmac_function_name_t

An encoded bit string used for function name (N).

Use dif_kmac_function_name_init to initialize.

◆ dif_kmac_key_length_t

typedef enum dif_kmac_key_length dif_kmac_key_length_t

Key length.

The key length is specified in bits.

◆ dif_kmac_key_t

typedef struct dif_kmac_key dif_kmac_key_t

A key for KMAC operations.

The key is provided in two parts, share0 and share1. These are combined using a bitwise XOR operation in the KMAC unit to produce the real key.

The key shares are encoded in little endian byte order. This is fixed and cannot be changed (unlike the byte order used for the message and state).

Unused words in the key shares must be set to 0.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Maximum lengths supported by the KMAC unit.

Enumerator
kDifKmacMaxCustomizationStringLen	The maximum length in bytes of a customization string (S) before it has been encoded.
kDifKmacMaxCustomizationStringOverhead	The maximum number of bytes required to encode the length of the customization string. Assumes maximum customization string length of 32 bytes (256 bits).
kDifKmacMaxFunctionNameLen	The maximum length in bytes of a function name (N) before it has been encoded.
kDifKmacMaxFunctionNameOverhead	The maximum number of bytes required to encode the length of the function name. Assumes maximum function name length of 4 bytes (32 bits).
kDifKmacMaxOutputLenWords	The maximum output length (L) that can be set when starting a KMAC operation. The length is in 32-bit words and is designed to be low enough that the length in bits can still be represented by an unsigned 32-bit integer.
kDifKmacMaxKeyLenWords	The maximum key length supported by the KMAC operation. The length is in 32-bit words.
kDifKmacEntropySeedWords	The length of the software entropy seed. The length is in 32-bit words.
kDifKmacStateShareOffset	The offset of the second share within the output state register.
kDifKmacStateWords	The size of the Keccak state in words (i.e. 1600 bits).

Definition at line 86 of file dif_kmac.h.

◆ dif_kmac_alert_faults

enum dif_kmac_alert_faults

The kmac error faults.

The hardware defined these status in different bit fields, however they work better in the same field. Then the values chosen for this enum allow the conversion from the register bits to this enum without branches.

Enumerator

kDifKmacAlertNone

Neither errors nor fault has occurred.

kDifKmacAlertFatalFault

A fatal fault has occurred and the KMAC unit needs to be reset (1), Examples for such faults include i) TL-UL bus integrity fault ii) storage errors in the shadow registers iii) errors in the message, round, or key counter iv) any internal FSM entering an invalid state v) an error in the redundant lfsr.

kDifKmacAlertRecovCtrlUpdate

An update error has occurred in the shadowed Control Register.

KMAC operation needs to be restarted by re-writing the Control Register.

Definition at line 454 of file dif_kmac.h.

◆ dif_kmac_entropy_mode

enum dif_kmac_entropy_mode

This API implements an interface for the KMAC hardware.

The KMAC hardware implements the following cryptographic hash and message authentication code (MAC) functions:

SHA-3 [1]
SHAKE [1]
cSHAKE [2]
KMAC [2]

The following sequence of operations is required to initialize the KMAC hardware:

If configuration changes are required then dif_kmac_configure can be called again so long as there are no operations in progress.

The following sequence of operations is required to execute an operation:

dif_kmac_{sha3,shake,cshake,kmac}_start()
dif_kmac_absorb()
dif_kmac_squeeze()
dif_kmac_end()

This is a streaming API and the dif_kmac_absorb and dif_kmac_squeeze functions may be called multiple times during a single operation. Once dif_kmac_squeeze has been called however no further dif_kmac_absorb calls may be made. See NIST FIPS 202 [1] for more information about the sponge construction and the 'absorbing' and 'squeezing' states.

Please see the following documentation for more information about the KMAC hardware: https://docs.opentitan.org/hw/ip/kmac/doc/

References: [1] - NIST FIPS 202 SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions http://dx.doi.org/10.6028/NIST.FIPS.202 [2] - NIST Special Publication 800-185 SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash and ParallelHash https://doi.org/10.6028/NIST.SP.800-185 Supported entropy modes.

Entropy may be provided by the entropy distribution network (EDN) or using a seed provided by software.

Definition at line 77 of file dif_kmac.h.

◆ dif_kmac_error

enum dif_kmac_error

Error reported by KMAC unit.

Codes taken from hw/ip/kmac/rtl/kmac_pkg.sv:err_code_e

Enumerator
kDifErrorNone	No error has occured.
kDifErrorKeyNotValid	The Key Manager has raised an error because the secret key is not valid.
kDifErrorSoftwarePushedMessageFifo	An attempt was made to write data into the message FIFO but the KMAC unit was not in the correct state to receive the data.
kDifErrorSoftwareIssuedCommandWhileAppInterfaceActive	SW issued a command while a HW application interface was using KMAC.
kDifErrorEntropyWaitTimerExpired	The entropy wait timer has expired.
kDifErrorEntropyModeIncorrect	Incorrect entropy mode when entropy is ready.

Definition at line 365 of file dif_kmac.h.

◆ dif_kmac_fifo_state

enum dif_kmac_fifo_state

The state of the message FIFO used to buffer absorbed data.

The hardware defined these status in different bit fields, however they work better in the same field. i.e the fifo can't be empty and full at the same time. That said, the values chosen for this enum allow the conversion from the register bits to this enum without branches.

Enumerator

kDifKmacFifoStatePartial

The message FIFO is not empty or full.

kDifKmacFifoStateEmpty

The message FIFO is empty.

kDifKmacFifoStateFull

The message FIFO is full.

Further writes will block.

Definition at line 420 of file dif_kmac.h.

◆ dif_kmac_key_length

enum dif_kmac_key_length

Key length.

The key length is specified in bits.

Enumerator
kDifKmacKeyLen128	Software provided 128 bit key.
kDifKmacKeyLen192	Software provided 192 bit key.
kDifKmacKeyLen256	Software provided 256 bit key.
kDifKmacKeyLen384	Software provided 384 bit key.
kDifKmacKeyLen512	Software provided 512 bit key.

Definition at line 304 of file dif_kmac.h.

◆ dif_kmac_mode_cshake

enum dif_kmac_mode_cshake

Supported cSHAKE modes of operation.

Enumerator
kDifKmacModeCshakeLen128	cSHAKE with 128 bit strength.
kDifKmacModeCshakeLen256	cSHAKE with 256 bit strength.

Definition at line 282 of file dif_kmac.h.

◆ dif_kmac_mode_kmac

enum dif_kmac_mode_kmac

Supported KMAC modes of operation.

Enumerator
kDifKmacModeKmacLen128	KMAC with 128 bit strength.
kDifKmacModeKmacLen256	KMAC with 256 bit strength.

Definition at line 292 of file dif_kmac.h.

◆ dif_kmac_mode_sha3

enum dif_kmac_mode_sha3

Supported SHA-3 modes of operation.

Enumerator
kDifKmacModeSha3Len224	SHA-3 with 224 bit strength.
kDifKmacModeSha3Len256	SHA-3 with 256 bit strength.
kDifKmacModeSha3Len384	SHA-3 with 384 bit strength.
kDifKmacModeSha3Len512	SHA-3 with 512 bit strength.

Definition at line 258 of file dif_kmac.h.

◆ dif_kmac_mode_shake

enum dif_kmac_mode_shake

Supported SHAKE modes of operation.

Enumerator
kDifKmacModeShakeLen128	SHAKE with 128 bit strength.
kDifKmacModeShakeLen256	SHAKE with 256 bit strength.

Definition at line 272 of file dif_kmac.h.

◆ dif_kmac_sha3_state

enum dif_kmac_sha3_state

Enumerator

kDifKmacSha3StateIdle

SHA3 hashing engine is in idle state.

kDifKmacSha3StateAbsorbing

SHA3 is receiving message stream and processing it.

kDifKmacSha3StateSqueezing

SHA3 completes sponge absorbing stage.

In this stage, SW can manually run the hashing engine.

Definition at line 429 of file dif_kmac.h.

Function Documentation

◆ dif_kmac_absorb()

OT_WARN_UNUSED_RESULT dif_result_t dif_kmac_absorb	(	const dif_kmac_t *	kmac,
		dif_kmac_operation_state_t *	operation_state,
		const void *	msg,
		size_t	len,
		size_t *	processed
	)

Absorb bytes from the message provided.

If processed is non-NULL, then this function will write the remaining space in the FIFO and update processed with the number of bytes written. The caller should adjust the msg pointer and len parameters and call again as needed until all input has been written.

If processed is NULL, then this function will block until the entire message has been processed or an error occurs.

If big-endian mode is enabled for messages (message_big_endian) only the part of the message aligned to 32-bit word boundaries will be byte swapped. Unaligned leading and trailing bytes will be written into the message as-is.

Parameters

	kmac	A KMAC handle.
	operation_state	A KMAC operation state context.
	msg	Pointer to data to absorb.
	len	Number of bytes of data to absorb.
[out]	processed	Number of bytes processed (optional). @preturn The result of the operation.

Definition at line 622 of file dif_kmac.c.

◆ dif_kmac_clear_err_irq()

OT_WARN_UNUSED_RESULT dif_result_t dif_kmac_clear_err_irq ( const dif_kmac_t * kmac )

Clear the kmac_err IRQ.

Parameters

kmac	A KMAC handle.

Returns: The result of the operation.

Definition at line 147 of file dif_kmac.c.

◆ dif_kmac_config_is_locked()

OT_WARN_UNUSED_RESULT dif_result_t dif_kmac_config_is_locked	(	const dif_kmac_t *	kmac,
		bool *	is_locked
	)

Reports whether or not the KMAC configuration register is locked.

If writes to the KMAC configuration register are disabled (locked) then it is not possible to change any configuration parameters or start a new operation. The configuration register is locked when an operation has been started and is unlocked again when it completes.

Parameters

	kmac	A KMAC handle.
[out]	is_locked	Out-param reporting the lock state.

Returns: The result of the operation.

Definition at line 825 of file dif_kmac.c.

◆ dif_kmac_configure()

OT_WARN_UNUSED_RESULT dif_result_t dif_kmac_configure	(	dif_kmac_t *	kmac,
		dif_kmac_config_t	config
	)

Configures KMAC with runtime information.

Parameters

kmac	A KMAC handle.
config	Runtime configuration parameters.

Returns: The result of the operation.

Definition at line 172 of file dif_kmac.c.

◆ dif_kmac_customization_string_init()

OT_WARN_UNUSED_RESULT dif_result_t dif_kmac_customization_string_init	(	const char *	data,
		size_t	len,
		dif_kmac_customization_string_t *	out
	)

Encode a customization string (S).

The length of the string must not exceed kDifKmacMaxCustomizationStringLen.

Note that this function will encode len bytes from data regardless of whether data is null-terminated or not.

See NIST Special Publication 800-185 [2] for more information about the customization string (S) parameter.

Parameters

	data	String to encode.
	len	Length of string to encode.
[out]	out	Encoded customization string.

Returns: The result of the operation.

Definition at line 36 of file dif_kmac.c.

◆ dif_kmac_end()

OT_WARN_UNUSED_RESULT dif_result_t dif_kmac_end	(	const dif_kmac_t *	kmac,
		dif_kmac_operation_state_t *	operation_state
	)

Ends a squeeze operation and resets the hardware so it is ready for a new operation.

Parameters

kmac	A KMAC handle.
operation_state	A KMAC operation state context.

Returns: The result of the operation.

Definition at line 792 of file dif_kmac.c.

◆ dif_kmac_err_processed()

OT_WARN_UNUSED_RESULT dif_result_t dif_kmac_err_processed ( const dif_kmac_t * kmac )

Let the KMAC HW know that SW has processed the errors the HW has flagged.

Parameters

kmac	A KMAC handle

Returns: The result of the operation.

Definition at line 903 of file dif_kmac.c.

◆ dif_kmac_function_name_init()

OT_WARN_UNUSED_RESULT dif_result_t dif_kmac_function_name_init	(	const char *	data,
		size_t	len,
		dif_kmac_function_name_t *	out
	)

Encode a function name (N).

The length of the string must not exceed kDifKmacMaxFunctionNameLen.

Note that this function will encode len bytes from data regardless of whether data is null-terminated or not.

See NIST Special Publication 800-185 [2] for more information about the function name (N) parameter.

Parameters

	data	String to encode.
	len	Length of string to encode.
[out]	out	Encoded function name.

Returns: The result of the operation.

Definition at line 71 of file dif_kmac.c.

◆ dif_kmac_get_error()

OT_WARN_UNUSED_RESULT dif_result_t dif_kmac_get_error	(	const dif_kmac_t *	kmac,
		dif_kmac_error_t *	error,
		uint32_t *	info
	)

Read the kmac error register to get the error code indicated the interrupt state.

This function should be called in case of any of the start functions returns kDifError.

Parameters

	kmac	A KMAC handle.
[out]	error	The current error code.
[out]	info	Optional additional error information.

Returns: The result of the operation.

Definition at line 878 of file dif_kmac.c.

◆ dif_kmac_get_hash_counter()

OT_WARN_UNUSED_RESULT dif_result_t dif_kmac_get_hash_counter	(	const dif_kmac_t *	kmac,
		uint32_t *	hash_ctr
	)

Returns the current value of the refresh hash counter.

Parameters

kmac	A KMAC handle.
hash_ctr	The hash counter value that is returned.

Returns: The result of the operation.

Definition at line 863 of file dif_kmac.c.

◆ dif_kmac_get_status()

OT_WARN_UNUSED_RESULT dif_result_t dif_kmac_get_status	(	const dif_kmac_t *	kmac,
		dif_kmac_status_t *	kmac_status
	)

Fetch the current status of the message FIFO used to buffer absorbed data.

Parameters

	kmac	A KMAC handle.
[out]	kmac_status	The kmac status struct.

Returns: The result of the operation.

Definition at line 837 of file dif_kmac.c.

◆ dif_kmac_has_error_occurred()

OT_WARN_UNUSED_RESULT dif_result_t dif_kmac_has_error_occurred	(	const dif_kmac_t *	kmac,
		bool *	error
	)

Report whether the hardware currently indicates an error.

Parameters

	kmac	A KMAC handle.
[out]	error	Whether hardware currently indicates an error.

Returns: The result of the operation.

Definition at line 137 of file dif_kmac.c.

◆ dif_kmac_mode_cshake_start()

OT_WARN_UNUSED_RESULT dif_result_t dif_kmac_mode_cshake_start	(	const dif_kmac_t *	kmac,
		dif_kmac_operation_state_t *	operation_state,
		dif_kmac_mode_cshake_t	mode,
		const dif_kmac_function_name_t *	n,
		const dif_kmac_customization_string_t *	s
	)

Start a cSHAKE operation.

cSHAKE operations have a variable (XOF) output length.

See NIST Special Publication 800-185 [2] for more information about cSHAKE.

Parameters

kmac	A KMAC handle.
operation_state	A KMAC operation state context.
mode	The mode of operation.
n	Function name (optional).
s	Customization string (optional).

Returns: The result of the operation.

Definition at line 387 of file dif_kmac.c.

◆ dif_kmac_mode_kmac_start()

OT_WARN_UNUSED_RESULT dif_result_t dif_kmac_mode_kmac_start	(	const dif_kmac_t *	kmac,
		dif_kmac_operation_state_t *	operation_state,
		dif_kmac_mode_kmac_t	mode,
		size_t	l,
		const dif_kmac_key_t *	k,
		const dif_kmac_customization_string_t *	s
	)

Start a KMAC operation.

To use KMAC in eXtendable-Output Function (XOF) mode set the output length (l) to 0. The output length must not be greater than kDifKmacMaxOutputLenWords.

The key provided must have at least as many bits as the security strength of the mode.

See NIST Special Publication 800-185 [2] for more information about KMAC.

Parameters

kmac	A KMAC handle.
operation_state	A KMAC operation state context.
mode	The mode of operation.
l	Output length (number of 32-bit words that will be 'squeezed').
k	Pointer to secret key.
s	Customization string (optional).

Returns: The result of the operation.

Definition at line 487 of file dif_kmac.c.

◆ dif_kmac_mode_sha3_start()

OT_WARN_UNUSED_RESULT dif_result_t dif_kmac_mode_sha3_start	(	const dif_kmac_t *	kmac,
		dif_kmac_operation_state_t *	operation_state,
		dif_kmac_mode_sha3_t	mode
	)

Start a SHA-3 operation.

SHA-3 operations have a fixed output length.

See NIST FIPS 202 [1] for more information about SHA-3.

Parameters

kmac	A KMAC handle.
operation_state	A KMAC operation state context.
mode	The SHA-3 mode of operation.

Returns: The result of the operation.

Definition at line 272 of file dif_kmac.c.

◆ dif_kmac_mode_shake_start()

OT_WARN_UNUSED_RESULT dif_result_t dif_kmac_mode_shake_start	(	const dif_kmac_t *	kmac,
		dif_kmac_operation_state_t *	operation_state,
		dif_kmac_mode_shake_t	mode
	)

Start a SHAKE operation.

SHAKE operations have a variable (XOF) output length.

See NIST FIPS 202 [1] for more information about SHAKE.

Parameters

kmac	A KMAC handle.
operation_state	A KMAC operation state context.
mode	The mode of operation.

Returns: The result of the operation.

Definition at line 338 of file dif_kmac.c.

◆ dif_kmac_poll_status()

OT_WARN_UNUSED_RESULT dif_result_t dif_kmac_poll_status	(	const dif_kmac_t *	kmac,
		uint32_t	flag
	)

Poll until a given flag in the status register is set.

Parameters

kmac	A KMAC handle.
flag	the

Returns: The result of the operation.

Definition at line 157 of file dif_kmac.c.

◆ dif_kmac_reset()

OT_WARN_UNUSED_RESULT dif_result_t dif_kmac_reset	(	const dif_kmac_t *	kmac,
		dif_kmac_operation_state_t *	operation_state
	)

Clear the current error code and reset the state machine to the idle state ready to accept new operations.

The state of any in-progress operation will be lost and the operation will need to be restarted.

Parameters

kmac	A KMAC handle.
operation_state	A KMAC operation state context.

Returns: The result of the operation.

Definition at line 890 of file dif_kmac.c.

◆ dif_kmac_squeeze()

OT_WARN_UNUSED_RESULT dif_result_t dif_kmac_squeeze	(	const dif_kmac_t *	kmac,
		dif_kmac_operation_state_t *	operation_state,
		uint32_t *	out,
		size_t	len,
		size_t *	processed,
		uint32_t *	capacity
	)

Squeeze bytes into the output buffer provided.

Requesting a squeeze operation will prevent any further absorption operations from taking place.

If kDifKmacIncomplete is returned then the hardware is currently recomputing the state and the output was only partially written. The output pointer and length should be updated according to the number of bytes processed and the squeeze operation continued at a later time.

If processed is not provided then this function will block until len bytes have been written to out or an error occurs.

Normally, the capacity part of Keccak state is and should not be read as part of a regular cryptographic operation. However, this function can also read the capacity for testing purposes. When capacity is a non-NULL pointer, at the end of the operation, the capacity part of the Keccak state is also read and written into this buffer. The capacity is read for each output round, meaning that if the requested digest is larger than a single Keccak round can provide (i.e. the rate), then the additional rounds also update this buffer. Hence it should be large enough to accommodate ceil(digest_len/rate_len) * capacity_len. capacity can be set to NULL to skip reading the capacity.

Parameters

	kmac	A KMAC handle.
	operation_state	A KMAC operation state context.
[out]	out	Pointer to output buffer.
[out]	len	Number of 32-bit words to write to output buffer.
[out]	processed	Number of 32-bit words written to output buffer (optional).
[out]	capacity	Optional buffer to read capacity along with the digest. @preturn The result of the operation.

Definition at line 673 of file dif_kmac.c.

(2c5ba75c1c)

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ dif_kmac_config

◆ dif_kmac_operation_state

◆ dif_kmac_key

◆ dif_kmac_customization_string

◆ dif_kmac_function_name

◆ dif_kmac_status

Typedef Documentation

◆ dif_kmac_alert_faults_t

◆ dif_kmac_config_t

◆ dif_kmac_customization_string_t

◆ dif_kmac_entropy_mode_t

◆ dif_kmac_error_t

◆ dif_kmac_fifo_state_t

◆ dif_kmac_function_name_t

◆ dif_kmac_key_length_t

◆ dif_kmac_key_t

Enumeration Type Documentation

◆ anonymous enum

◆ dif_kmac_alert_faults

◆ dif_kmac_entropy_mode

◆ dif_kmac_error

◆ dif_kmac_fifo_state

◆ dif_kmac_key_length

◆ dif_kmac_mode_cshake

◆ dif_kmac_mode_kmac

◆ dif_kmac_mode_sha3

◆ dif_kmac_mode_shake

◆ dif_kmac_sha3_state

Function Documentation

◆ dif_kmac_absorb()

◆ dif_kmac_clear_err_irq()

◆ dif_kmac_config_is_locked()

◆ dif_kmac_configure()

◆ dif_kmac_customization_string_init()

◆ dif_kmac_end()

◆ dif_kmac_err_processed()

◆ dif_kmac_function_name_init()

◆ dif_kmac_get_error()

◆ dif_kmac_get_hash_counter()

◆ dif_kmac_get_status()

◆ dif_kmac_has_error_occurred()

◆ dif_kmac_mode_cshake_start()

◆ dif_kmac_mode_kmac_start()

◆ dif_kmac_mode_sha3_start()

◆ dif_kmac_mode_shake_start()

◆ dif_kmac_poll_status()

◆ dif_kmac_reset()

◆ dif_kmac_squeeze()