(8a1a5fe)

CSRNG 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 "csrng_regs.h"
#include "sw/device/lib/dif/autogen/dif_csrng_autogen.h"

Go to the source code of this file.

Data Structures
struct	dif_csrng_cmd_status
	The status of the CSRNG block at a particular moment in time. More...

struct	dif_csrng_seed_material
	CSRNG common transaction parameters. More...

struct	dif_csrng_output_status
	Generated output state. More...

struct	dif_csrng_internal_state
	CSRNG internal state. More...

Typedefs
typedef enum dif_csrng_cmd_status_kind	dif_csrng_cmd_status_kind_t
	This API implements an interface for the CSRNG hardware. More...

typedef enum dif_csrng_fifo	dif_csrng_fifo_t
	Enumeration of CSRNG FIFOs, which indicates which part of the hardware produced an error.

typedef enum dif_csrng_error	dif_csrng_error_t
	Enumeration of CSRNG FIFO errors.

typedef enum dif_csrng_cmd_sts_error	dif_csrng_cmd_sts_t
	Enumeration of CSRNG command status errors.

typedef struct dif_csrng_cmd_status	dif_csrng_cmd_status_t
	The status of the CSRNG block at a particular moment in time.

typedef enum dif_csrng_entropy_src_toggle	dif_csrng_entropy_src_toggle_t
	CSRNG consume seed from entropy source enable.

typedef struct dif_csrng_seed_material	dif_csrng_seed_material_t
	CSRNG common transaction parameters.

typedef struct dif_csrng_output_status	dif_csrng_output_status_t
	Generated output state.

typedef enum dif_csrng_internal_state_id	dif_csrng_internal_state_id_t
	CSRNG internal state selector ID.

typedef struct dif_csrng_internal_state	dif_csrng_internal_state_t
	CSRNG internal state.

typedef enum dif_csrng_recoverable_alert	dif_csrng_recoverable_alert_t
	Recoverable alerts emitted by the CSRNG.

Enumerations
enum	dif_csrng_cmd_status_kind { kDifCsrngCmdStatusReady, kDifCsrngCmdStatusBusy, kDifCsrngCmdStatusError }
	This API implements an interface for the CSRNG hardware. More...

enum	dif_csrng_fifo { kDifCsrngFifoCmd, kDifCsrngFifoGenBits, kDifCsrngFifoCmdReq, kDifCsrngFifoRcStage, kDifCsrngFifoKeyVrc, kDifCsrngFifoUpdateReq, kDifCsrngFifoBencRec, kDifCsrngFifoBencAck, kDifCsrngFifoPData, kDifCsrngFifoFinal, kDifCsrngFifoGBencAck, kDifCsrngFifoGrcStage, kDifCsrngFifoGGenReq, kDifCsrngFifoGadStage, kDifCsrngFifoBlockEnc }
	Enumeration of CSRNG FIFOs, which indicates which part of the hardware produced an error.

enum	dif_csrng_error { kDifCsrngErrorCmdStageSm, kDifCsrngErrorMainSm, kDifCsrngErrorDrbgGenSm, kDifCsrngErrorDrbgUpdateBlockEncSm, kDifCsrngErrorDrbgUpdateOutBlockSm, kDifCsrngErrorAesSm, kDifCsrngErrorGenerateCmdCounter, kDifCsrngErrorFifoWrite, kDifCsrngErrorFifoRead, kDifCsrngErrorFifoFullAndEmpty }
	Enumeration of CSRNG FIFO errors. More...

enum	dif_csrng_cmd_sts_error { kDifCsrngCmdStsSuccess = 0, kDifCsrngCmdStsInvalidAcmd = 1, kDifCsrngCmdStsInvalidStateParams = 2, kDifCsrngCmdStsInvalidCtrDrbgCmd = 3, kDifCsrngCmdStsInvalidCmdSeq = 4 }
	Enumeration of CSRNG command status errors. More...

enum	dif_csrng_entropy_src_toggle { kDifCsrngEntropySrcToggleDisable = 1, kDifCsrngEntropySrcToggleEnable = 0 }
	CSRNG consume seed from entropy source enable. More...

enum	{ kDifCsrngSeedMaterialMaxWordLen = 12 }

enum	dif_csrng_internal_state_id { kCsrngInternalStateIdEdn0 = 0, kCsrngInternalStateIdEdn1 = 1, kCsrngInternalStateIdSw = 2 }
	CSRNG internal state selector ID. More...

enum	dif_csrng_recoverable_alert { kDifCsrngRecoverableAlertBadEnable, kDifCsrngRecoverableAlertBadSwAppEnable, kDifCsrngRecoverableAlertBadIntState, kDifCsrngRecoverableAlertBadFlag0, kDifCsrngRecoverableAlertRepeatedGenBits, kDifCsrngRecoverableAlertBadCsrngCmd, kDifCsrngRecoverableAlertBadCsrngCmdSeq, kDifCsrngRecoverableAlertMaxReseedsExceeded }
	Recoverable alerts emitted by the CSRNG. More...

Functions
OT_WARN_UNUSED_RESULT dif_result_t	dif_csrng_configure (const dif_csrng_t *csrng)
	Configures CSRNG. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_csrng_instantiate (const dif_csrng_t csrng, dif_csrng_entropy_src_toggle_t entropy_src_enable, const dif_csrng_seed_material_t seed_material)
	Initializes CSRNG instance with a new seed value. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_csrng_reseed (const dif_csrng_t csrng, const dif_csrng_seed_material_t seed_material)
	Reseeds CSRNG instance. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_csrng_update (const dif_csrng_t csrng, const dif_csrng_seed_material_t seed_material)
	Updates CSRNG state. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_csrng_generate_start (const dif_csrng_t *csrng, size_t len)
	Requests cryptographic entropy bits from the CSRNG. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_csrng_generate_read (const dif_csrng_t csrng, uint32_t buf, size_t len)
	Reads the output of the last CSRNG generate call. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_csrng_uninstantiate (const dif_csrng_t *csrng)
	Uninstantiates CSRNG. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_csrng_get_cmd_interface_status (const dif_csrng_t csrng, dif_csrng_cmd_status_t status)
	Gets the current command interface status. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_csrng_get_cmd_force_unhealthy_fifo (const dif_csrng_t *csrng, dif_csrng_fifo_t fifo)
	Forces the status registers to indicate `fifo` as being in an unhealthy state. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_csrng_get_cmd_force_error (const dif_csrng_t *csrng, dif_csrng_error_t error)
	Forces the status registers to indicate a particular error cause. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_csrng_get_main_state_machine (const dif_csrng_t csrng, uint32_t state)
	Returns an opaque blob indicating the main state machine's current state. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_csrng_get_hw_csrng_exceptions (const dif_csrng_t csrng, uint32_t exceptions)
	Returns a bitset indicating which hardware CSRNGs have encountered exceptions. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_csrng_clear_hw_csrng_exceptions (const dif_csrng_t *csrng)
	Clears recorded hardware CSRNG exceptions. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_csrng_get_output_status (const dif_csrng_t csrng, dif_csrng_output_status_t status)
	Gets the current cryptographic entropy output data status. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_csrng_get_internal_state (const dif_csrng_t csrng, dif_csrng_internal_state_id_t instance_id, dif_csrng_internal_state_t state)
	Gets the working state of a CSRNG instance. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_csrng_get_reseed_counter (const dif_csrng_t csrng, dif_csrng_internal_state_id_t instance_id, uint32_t reseed_counter)
	Gets the reseed counter of a CSRNG instance. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_csrng_lock (const dif_csrng_t *csrng)
	Locks out CSRNG functionality. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_csrng_is_locked (const dif_csrng_t csrng, bool is_locked)
	Checks whether this CSRNG is locked. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_csrng_stop (const dif_csrng_t *csrng)
	Disables the CSRNG module. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_csrng_get_recoverable_alerts (const dif_csrng_t csrng, uint32_t alerts)
	Gets the recoverable alerts currently recorded in the CSRNG block. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_csrng_clear_recoverable_alerts (const dif_csrng_t *csrng)
	Clears all recoverable alerts currently recorded in the CSRNG block. More...

Detailed Description

CSRNG Device Interface Functions

Definition in file dif_csrng.h.

Data Structure Documentation

◆ dif_csrng_cmd_status

struct dif_csrng_cmd_status

The status of the CSRNG block at a particular moment in time.

Definition at line 190 of file dif_csrng.h.

Data Fields
dif_csrng_cmd_sts_t	cmd_sts	The status value CSRNG returns.
dif_csrng_cmd_status_kind_t	kind	The kind of status the CSRNG is in.

◆ dif_csrng_seed_material

struct dif_csrng_seed_material

CSRNG common transaction parameters.

Definition at line 232 of file dif_csrng.h.

Data Fields
uint32_t	seed_material[kDifCsrngSeedMaterialMaxWordLen]	Seed material used in CSRNG.
size_t	seed_material_len	Number of uint32_t words in `seed_material`. Up to 12 words can be set to initialize the CSRNG. CSRNG will extend the `seed_material` to zeros if the provided value is less that 12.

◆ dif_csrng_output_status

struct dif_csrng_output_status

Generated output state.

Definition at line 248 of file dif_csrng.h.

Data Fields
bool	fips_mode	Set to true when the cryptographic entropy data available to read is FIPS/CC compliant at the hardware level.
bool	valid_data	Set to true when there is cryptographic entropy data available to read using `dif_csrng_generate_read()`.

◆ dif_csrng_internal_state

struct dif_csrng_internal_state

CSRNG internal state.

Definition at line 282 of file dif_csrng.h.

Data Fields
bool	fips_compliance	Set to true when FIPS compliant entropy was provided directly by the entropy source to instantiate or reseed the CSRNG instance.
bool	instantiated	Set to true when the CSRNG instance has been instantiated.
uint32_t	key[8]	Internal key used to configure the internal CSRNG cipher.
uint32_t	reseed_counter	Indicates the number of requests for pseudorandom bits since instantiation or reseeding.
uint32_t	v[4]	Internal V working state with a 128bit block size.

Typedef Documentation

◆ dif_csrng_cmd_status_kind_t

typedef enum dif_csrng_cmd_status_kind dif_csrng_cmd_status_kind_t

This API implements an interface for the CSRNG hardware.

The API follows the naming conventions used in NIST SP 800-90Ar1:

Instantiate.
Update
Reseed
Generate
Uninstantiate

The seed used for instantiation can either be provided directly in hardware by an entropy source module; or directly by software. See dif_csrng_instantiate() and dif_csrng_entropy_src for more details.

The following sequence of operations are required to initialize and generate cryptographic entropy from the CSRNG module:

The following functions can be used for reseed and update operations:

The following utility functions are available to poll the state of the hardware:

Please see the following documentation for more information: https://docs.opentitan.org/hw/ip/csrng/doc/

Remaining work:

Add error status interface.
Add internal state control and debug interface. Enumeration of CSRNG command interface states.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Enumerator
kDifCsrngSeedMaterialMaxWordLen	Maximum seed material number of uint32_t words supported in CSRNG instantiate and seed commands.

Definition at line 221 of file dif_csrng.h.

◆ dif_csrng_cmd_status_kind

enum dif_csrng_cmd_status_kind

This API implements an interface for the CSRNG hardware.

The API follows the naming conventions used in NIST SP 800-90Ar1:

Instantiate.
Update
Reseed
Generate
Uninstantiate

The seed used for instantiation can either be provided directly in hardware by an entropy source module; or directly by software. See dif_csrng_instantiate() and dif_csrng_entropy_src for more details.

The following sequence of operations are required to initialize and generate cryptographic entropy from the CSRNG module:

The following functions can be used for reseed and update operations:

The following utility functions are available to poll the state of the hardware:

Please see the following documentation for more information: https://docs.opentitan.org/hw/ip/csrng/doc/

Remaining work:

Add error status interface.
Add internal state control and debug interface. Enumeration of CSRNG command interface states.

Enumerator
kDifCsrngCmdStatusReady	The command interface is ready to accept commands.
kDifCsrngCmdStatusBusy	The command interface is processing a command.
kDifCsrngCmdStatusError	The command interface completed with an error.

Definition at line 74 of file dif_csrng.h.

◆ dif_csrng_cmd_sts_error

enum dif_csrng_cmd_sts_error

Enumeration of CSRNG command status errors.

Enumerator
kDifCsrngCmdStsSuccess	Indicates that the command completed successfully.
kDifCsrngCmdStsInvalidAcmd	Indicates that an invalid apllication command has been issued.
kDifCsrngCmdStsInvalidStateParams	Indicates that the state wasn't zeroized properly after an uninstantiate command due to invalid state parameters in the cmd drbg.
kDifCsrngCmdStsInvalidCtrDrbgCmd	Indicates that CSRNG entropy was generated for a command that is not a generate command.
kDifCsrngCmdStsInvalidCmdSeq	Indicates that last command was not issued in sequence. E.g. an instantiate on an instantiated state or any command other than an instantiate on an uninstantiated state.

Definition at line 160 of file dif_csrng.h.

◆ dif_csrng_entropy_src_toggle

enum dif_csrng_entropy_src_toggle

CSRNG consume seed from entropy source enable.

Enumerator

kDifCsrngEntropySrcToggleDisable

Seed material used as the only seed material.

This configuration option will toggle the hardware state of the CSRNG to non-FIPS compliant until it is re-instantiated.

Note: Software may opt to XOR the seed material with a seed to implement a software assisted FIPS mode of operation.

kDifCsrngEntropySrcToggleEnable

Entropy source XOR'ed with the provided seed material.

Definition at line 204 of file dif_csrng.h.

◆ dif_csrng_error

enum dif_csrng_error

Enumeration of CSRNG FIFO errors.

Enumerator
kDifCsrngErrorCmdStageSm	Indicates an error in the command stage state machine.
kDifCsrngErrorMainSm	Indicates an error in the main state machine.
kDifCsrngErrorDrbgGenSm	Indicates an error in the DRBG's generator state machine.
kDifCsrngErrorDrbgUpdateBlockEncSm	Indicates an error in the DRBG's block encoding state machine.
kDifCsrngErrorDrbgUpdateOutBlockSm	Indicates an error in the DRBG's block output state machine.
kDifCsrngErrorAesSm	Indicates an error in the AES state machine.
kDifCsrngErrorGenerateCmdCounter	Indicates an error in the generate command's counter.
kDifCsrngErrorFifoWrite	Indicates a write to a full FIFO occured.
kDifCsrngErrorFifoRead	Indicates a read from an empty FIFO occured.
kDifCsrngErrorFifoFullAndEmpty	Indicates a FIFO was somehow both full and empty.

Definition at line 114 of file dif_csrng.h.

◆ dif_csrng_internal_state_id

enum dif_csrng_internal_state_id

CSRNG internal state selector ID.

Enumerator
kCsrngInternalStateIdEdn0	CSRNG instance assigned to Entropy Distribution Network (EDN) 0.
kCsrngInternalStateIdEdn1	CSRNG instance assigned to Entropy Distribution Network (EDN) 1.
kCsrngInternalStateIdSw	CSRNG instance assigned to software interface.

Definition at line 264 of file dif_csrng.h.

◆ dif_csrng_recoverable_alert

enum dif_csrng_recoverable_alert

Recoverable alerts emitted by the CSRNG.

Enumerator
kDifCsrngRecoverableAlertBadEnable	Indicates a bad value was written to the ENABLE field of the control register.
kDifCsrngRecoverableAlertBadSwAppEnable	Indicates a bad value was written to the SW_APP_ENABLE field of the control register.
kDifCsrngRecoverableAlertBadIntState	Indicates a bad value was written to the READ_INT_STATE field of the control register.
kDifCsrngRecoverableAlertBadFlag0	Indicates the FLAG0 field in the Application Command is set to a value other than kMultiBitBool4True or kMultiBitBool4False.
kDifCsrngRecoverableAlertRepeatedGenBits	Indicates the genbits bus saw two identical values, indicating a possible attack.
kDifCsrngRecoverableAlertBadCsrngCmd	Indicates an unsupported CSRNG command was issued.
kDifCsrngRecoverableAlertBadCsrngCmdSeq	Indicates a supported CSRNG command was issued out of sequence.
kDifCsrngRecoverableAlertMaxReseedsExceeded	Indicates that too many generate commands were issued in a row.

Definition at line 310 of file dif_csrng.h.

Function Documentation

◆ dif_csrng_clear_hw_csrng_exceptions()

OT_WARN_UNUSED_RESULT dif_result_t dif_csrng_clear_hw_csrng_exceptions ( const dif_csrng_t * csrng )

Clears recorded hardware CSRNG exceptions.

Parameters

csrng An CSRNG handle

Returns: The result of the operation.

Definition at line 302 of file dif_csrng.c.

◆ dif_csrng_clear_recoverable_alerts()

OT_WARN_UNUSED_RESULT dif_result_t dif_csrng_clear_recoverable_alerts ( const dif_csrng_t * csrng )

Clears all recoverable alerts currently recorded in the CSRNG block.

Parameters

csrng A CSRNG handle.

Returns: The result of the operation.

Definition at line 429 of file dif_csrng.c.

◆ dif_csrng_configure()

OT_WARN_UNUSED_RESULT dif_result_t dif_csrng_configure ( const dif_csrng_t * csrng )

Configures CSRNG.

This function should need to be called once for the lifetime of csrng.

Parameters

csrng A CSRNG handle.

Returns: The result of the operation.

Definition at line 45 of file dif_csrng.c.

◆ dif_csrng_generate_read()

OT_WARN_UNUSED_RESULT dif_result_t dif_csrng_generate_read	(	const dif_csrng_t *	csrng,
		uint32_t *	buf,
		size_t	len
	)

Reads the output of the last CSRNG generate call.

This function reads len words out of the CSRNG. This function should be called repeatedly until the number of words requested in dif_csrng_generate_start() is exhausted. This function will block until len words are read.

dif_csrng_get_output_status() can be called before this function to ensure there is data available in the CSRNG output buffer.

Parameters

	csrng	A CSRNG handle.
[out]	buf	A buffer to fill with words from the pipeline.
	len	The number of words to read into `buf`.

Returns: The result of the operation.

Definition at line 116 of file dif_csrng.c.

◆ dif_csrng_generate_start()

OT_WARN_UNUSED_RESULT dif_result_t dif_csrng_generate_start	(	const dif_csrng_t *	csrng,
		size_t	len
	)

Requests cryptographic entropy bits from the CSRNG.

The prediction resistance flag as specified in SP 800-90Ar1 section 10.2.1.1 is not directily supported by the hardware. It is the responsibility of the caller to reseed as needed before calling this function.

The CSRNG accepts generation requests with 128-bit granularity, with a minimum 128-bit request size. This function will increase the size of the request to align it to the nearest 128-bit boundary.

Parameters

csrng	A CSRNG handle.
len	Number of uint32_t words to generate.

Returns: The result of the operation. KDifOutOfRange if the len parameter results in a 128bit block level size greater than 0x800.

Definition at line 101 of file dif_csrng.c.

◆ dif_csrng_get_cmd_force_error()

OT_WARN_UNUSED_RESULT dif_result_t dif_csrng_get_cmd_force_error	(	const dif_csrng_t *	csrng,
		dif_csrng_error_t	error
	)

Forces the status registers to indicate a particular error cause.

Parameters

csrng	An CSRNG handle
error	The error to force.

Returns: The result of the operation.

Definition at line 233 of file dif_csrng.c.

◆ dif_csrng_get_cmd_force_unhealthy_fifo()

OT_WARN_UNUSED_RESULT dif_result_t dif_csrng_get_cmd_force_unhealthy_fifo	(	const dif_csrng_t *	csrng,
		dif_csrng_fifo_t	fifo
	)

Forces the status registers to indicate fifo as being in an unhealthy state.

Parameters

csrng	An CSRNG handle
fifo	The FIFO to mark as unhealthy.

Returns: The result of the operation.

Definition at line 170 of file dif_csrng.c.

◆ dif_csrng_get_cmd_interface_status()

OT_WARN_UNUSED_RESULT dif_result_t dif_csrng_get_cmd_interface_status	(	const dif_csrng_t *	csrng,
		dif_csrng_cmd_status_t *	status
	)

Gets the current command interface status.

This function can be called before or after any of the following functions:

Parameters

	csrng	An CSRNG handle
[out]	status	Command interface status.

Returns: The result of the operation.

Definition at line 142 of file dif_csrng.c.

◆ dif_csrng_get_hw_csrng_exceptions()

OT_WARN_UNUSED_RESULT dif_result_t dif_csrng_get_hw_csrng_exceptions	(	const dif_csrng_t *	csrng,
		uint32_t *	exceptions
	)

Returns a bitset indicating which hardware CSRNGs have encountered exceptions.

Parameters

csrng	An CSRNG handle
exceptions[out]	The bitset of exception states.

Returns: The result of the operation.

Definition at line 291 of file dif_csrng.c.

◆ dif_csrng_get_internal_state()

OT_WARN_UNUSED_RESULT dif_result_t dif_csrng_get_internal_state	(	const dif_csrng_t *	csrng,
		dif_csrng_internal_state_id_t	instance_id,
		dif_csrng_internal_state_t *	state
	)

Gets the working state of a CSRNG instance.

Parameters

	csrng	A CSRNG handle
	instance_id	CSRNG instance ID.
[out]	state	The working state of a CSRNG instance.

Returns: The result of the operation.

Definition at line 320 of file dif_csrng.c.

◆ dif_csrng_get_main_state_machine()

OT_WARN_UNUSED_RESULT dif_result_t dif_csrng_get_main_state_machine	(	const dif_csrng_t *	csrng,
		uint32_t *	state
	)

Returns an opaque blob indicating the main state machine's current state.

Parameters

csrng	An CSRNG handle
state[out]	The state machine state as an opaque blob.

Returns: The result of the operation.

Definition at line 281 of file dif_csrng.c.

◆ dif_csrng_get_output_status()

OT_WARN_UNUSED_RESULT dif_result_t dif_csrng_get_output_status	(	const dif_csrng_t *	csrng,
		dif_csrng_output_status_t *	status
	)

Gets the current cryptographic entropy output data status.

This function can be used before calling dif_csrng_generate_read() to check if there is data available to read.

Parameters

	csrng	A CSRNG handle.
[out]	status	CSRNG output status.

Returns: The result of the operation.

Definition at line 311 of file dif_csrng.c.

◆ dif_csrng_get_recoverable_alerts()

OT_WARN_UNUSED_RESULT dif_result_t dif_csrng_get_recoverable_alerts	(	const dif_csrng_t *	csrng,
		uint32_t *	alerts
	)

Gets the recoverable alerts currently recorded in the CSRNG block.

This function returns the alerts in a bitset whose indices are given by dif_csrng_recoverable_alert_t.

Parameters

	csrng	A CSRNG handle.
[out]	alerts	Bitset of alerts currently recorded.

Returns: The result of the operation.

Definition at line 417 of file dif_csrng.c.

◆ dif_csrng_get_reseed_counter()

OT_WARN_UNUSED_RESULT dif_result_t dif_csrng_get_reseed_counter	(	const dif_csrng_t *	csrng,
		dif_csrng_internal_state_id_t	instance_id,
		uint32_t *	reseed_counter
	)

Gets the reseed counter of a CSRNG instance.

Parameters

	csrng	A CSRNG handle
	instance_id	CSRNG instance ID.
[out]	reseed	counter The current reseed counter value of a CSRNG instance.

Returns: The result of the operation.

Definition at line 363 of file dif_csrng.c.

◆ dif_csrng_instantiate()

OT_WARN_UNUSED_RESULT dif_result_t dif_csrng_instantiate	(	const dif_csrng_t *	csrng,
		dif_csrng_entropy_src_toggle_t	entropy_src_enable,
		const dif_csrng_seed_material_t *	seed_material
	)

Initializes CSRNG instance with a new seed value.

seed_material is used as specified in NIST SP 800-90Ar1 section 10.2.1.3.1. See dif_csrng_entropy_src for details on how this value is mixed with the CSRNG seed.

seed_material can be NULL, in which case CSRNG will use a zero vector instead.

Parameters

csrng	A CSRNG handle.
entropy_src_enable	Entropy source input enable.
seed_material	Seed initialization parameters.

Returns: The result of the operation.

Definition at line 63 of file dif_csrng.c.

◆ dif_csrng_is_locked()

OT_WARN_UNUSED_RESULT dif_result_t dif_csrng_is_locked	(	const dif_csrng_t *	csrng,
		bool *	is_locked
	)

Checks whether this CSRNG is locked.

Parameters

	csrng	A CSRNG handle.
[out]	is_locked	Out-param for the locked state.

Returns: The result of the operation.

Definition at line 399 of file dif_csrng.c.

◆ dif_csrng_lock()

OT_WARN_UNUSED_RESULT dif_result_t dif_csrng_lock ( const dif_csrng_t * csrng )

Locks out CSRNG functionality.

This function is reentrant: calling it while functionality is locked will have no effect and return kDifCsrngOk.

Parameters

csrng A CSRNG handle.

Returns: The result of the operation.

Definition at line 391 of file dif_csrng.c.

◆ dif_csrng_reseed()

OT_WARN_UNUSED_RESULT dif_result_t dif_csrng_reseed	(	const dif_csrng_t *	csrng,
		const dif_csrng_seed_material_t *	seed_material
	)

Reseeds CSRNG instance.

When seed_material.seed_material_len is set to 0, only the entropy source seed is used to reseed the instance, otherwise it will be XOR'ed with the entropy source.

Parameters

csrng	A CSRNG handle.
seed_material	Reseed parameters.

Returns: The result of the operation.

Definition at line 77 of file dif_csrng.c.

◆ dif_csrng_stop()

OT_WARN_UNUSED_RESULT dif_result_t dif_csrng_stop ( const dif_csrng_t * csrng )

Disables the CSRNG module.

Parameters

csrng A CSRNG handle.

Returns: The result of the operation.

Definition at line 407 of file dif_csrng.c.

◆ dif_csrng_uninstantiate()

OT_WARN_UNUSED_RESULT dif_result_t dif_csrng_uninstantiate ( const dif_csrng_t * csrng )

Uninstantiates CSRNG.

Resets the CSRNG instance. Values in the CSRNG are zeroed out. This command effectively resets the CSRNG, clearing any errors that it may have encountered due to processing or entropy source errors.

Parameters

csrng An CSRNG handle.

Returns: The result of the operation.

Definition at line 132 of file dif_csrng.c.

◆ dif_csrng_update()

OT_WARN_UNUSED_RESULT dif_result_t dif_csrng_update	(	const dif_csrng_t *	csrng,
		const dif_csrng_seed_material_t *	seed_material
	)

Updates CSRNG state.

This function is similar to dif_csrng_reseed(), except:

Only seed_material.seed_material is used in the update operation.
The update operation does not reset the internal CSRNG reseed counter.

Parameters

csrng	A CSRNG handle.
seed_material	Update parameters.

Returns: The result of the operation.

Definition at line 89 of file dif_csrng.c.

(8a1a5fe)

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ dif_csrng_cmd_status

◆ dif_csrng_seed_material

◆ dif_csrng_output_status

◆ dif_csrng_internal_state

Typedef Documentation

◆ dif_csrng_cmd_status_kind_t

Enumeration Type Documentation

◆ anonymous enum

◆ dif_csrng_cmd_status_kind

◆ dif_csrng_cmd_sts_error

◆ dif_csrng_entropy_src_toggle

◆ dif_csrng_error

◆ dif_csrng_internal_state_id

◆ dif_csrng_recoverable_alert

Function Documentation

◆ dif_csrng_clear_hw_csrng_exceptions()

◆ dif_csrng_clear_recoverable_alerts()

◆ dif_csrng_configure()

◆ dif_csrng_generate_read()

◆ dif_csrng_generate_start()

◆ dif_csrng_get_cmd_force_error()

◆ dif_csrng_get_cmd_force_unhealthy_fifo()

◆ dif_csrng_get_cmd_interface_status()

◆ dif_csrng_get_hw_csrng_exceptions()

◆ dif_csrng_get_internal_state()

◆ dif_csrng_get_main_state_machine()

◆ dif_csrng_get_output_status()

◆ dif_csrng_get_recoverable_alerts()

◆ dif_csrng_get_reseed_counter()

◆ dif_csrng_instantiate()

◆ dif_csrng_is_locked()

◆ dif_csrng_lock()

◆ dif_csrng_reseed()

◆ dif_csrng_stop()

◆ dif_csrng_uninstantiate()

◆ dif_csrng_update()