dif_edn.h File Reference

(30d7e787c7)

Entropy Distribution Network 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_edn_autogen.h"

Go to the source code of this file.

Data Structures
struct	dif_edn_seed_material
	CSRNG seed material for instantiate, reseed and generate commands. More...
struct	dif_edn_cmd
	CSRNG command parameters for instantiate, reseed and generate commands. More...
struct	dif_edn_auto_params
	Auto-generate EDN module configuration parameters. More...

Typedefs
typedef struct dif_edn_seed_material	dif_edn_seed_material_t
	CSRNG seed material for instantiate, reseed and generate commands.
typedef struct dif_edn_cmd	dif_edn_cmd_t
	CSRNG command parameters for instantiate, reseed and generate commands.
typedef struct dif_edn_auto_params	dif_edn_auto_params_t
	Auto-generate EDN module configuration parameters.
typedef enum dif_edn_status	dif_edn_status_t
	EDN Status flags.
typedef enum dif_edn_sm_state	dif_edn_sm_state_t
	EDN SM states as defined in the EDN state machine RTL.
typedef enum dif_edn_fifo	dif_edn_fifo_t
	Enumeration of EDN FIFOs, which indicates which part of the hardware produced an error.
typedef enum dif_edn_error	dif_edn_error_t
	Enumeration of EDN FIFO errors.
typedef enum dif_edn_entropy_src_toggle	dif_edn_entropy_src_toggle_t
	CSRNG consume seed from entropy source enable.
typedef enum dif_edn_recoverable_alert	dif_edn_recoverable_alert_t
	Recoverable alerts emitted by the EDN.

Enumerations
enum	{ kDifEntropySeedMaterialMaxWordLen = 12 }
enum	{ kDifEntropySeedMaterialMaxGlen = 4095 }
enum	{ kDifMaxNumReqsBetweenReseeds = 0xffffffff }
enum	{   kDifEdnCmdInstantiate = 1 ,   kDifEdnCmdReseed = 2 ,   kDifEdnCmdGenerate = 3 }
enum	dif_edn_status {   kDifEdnStatusRegReady ,   kDifEdnStatusReady ,   kDifEdnStatusCsrngStatus ,   kDifEdnStatusCsrngAck }
	EDN Status flags. More...
enum	dif_edn_sm_state {   kDifEdnSmStateIdle = 193 ,   kDifEdnSmStateBootLoadIns = 455 ,   kDifEdnSmStateBootInsAckWait = 121 ,   kDifEdnSmStateBootLoadGen = 3 ,   kDifEdnSmStateBootGenAckWait = 119 ,   kDifEdnSmStateBootPulse = 169 ,   kDifEdnSmStateBootDone = 240 ,   kDifEdnSmStateBootLoadUni = 309 ,   kDifEdnSmStateBootUniAckWait = 44 ,   kDifEdnSmStateAutoLoadIns = 444 ,   kDifEdnSmStateAutoFirstAckWait = 419 ,   kDifEdnSmStateAutoAckWait = 146 ,   kDifEdnSmStateAutoDispatch = 353 ,   kDifEdnSmStateAutoCaptGenCnt = 270 ,   kDifEdnSmStateAutoSendGenCmd = 477 ,   kDifEdnSmStateAutoCaptReseedCnt = 191 ,   kDifEdnSmStateAutoSendReseedCmd = 106 ,   kDifEdnSmStateSWPortMode = 149 ,   kDifEdnSmStateRejectCsrngEntropy = 24 ,   kDifEdnSmStateError = 382 }
	EDN SM states as defined in the EDN state machine RTL. More...
enum	dif_edn_fifo {   kDifEdnFifoReseedCmd ,   kDifEdnFifoGenerateCmd }
	Enumeration of EDN FIFOs, which indicates which part of the hardware produced an error.
enum	dif_edn_error {   kDifEdnErrorAckSm ,   kDifEdnErrorMainSm ,   kDifEdnErrorCounterFault ,   kDifEdnErrorFifoWrite ,   kDifEdnErrorFifoRead ,   kDifEdnErrorFifoFullAndEmpty }
	Enumeration of EDN FIFO errors. More...
enum	dif_edn_entropy_src_toggle {   kDifEdnEntropySrcToggleDisable = 1 ,   kDifEdnEntropySrcToggleEnable = 0 }
	CSRNG consume seed from entropy source enable. More...
enum	dif_edn_recoverable_alert {   kDifEdnRecoverableAlertBadEnable ,   kDifEdnRecoverableAlertBadBootReqMode ,   kDifEdnRecoverableAlertBadAutoReqMode ,   kDifEdnRecoverableAlertBadFifoClear ,   kDifEdnRecoverableAlertRepeatedGenBits }
	Recoverable alerts emitted by the EDN. More...

Functions
OT_WARN_UNUSED_RESULT dif_result_t	dif_edn_configure (const dif_edn_t *edn)
	Configures EDN with runtime information. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_edn_lock (const dif_edn_t *edn)
	Locks out EDN functionality. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_edn_is_locked (const dif_edn_t *edn, bool *is_locked)
	Checks whether this EDN is locked. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_edn_set_boot_mode (const dif_edn_t *edn)
	Enables the EDN in boot-time mode. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_edn_set_auto_mode (const dif_edn_t *edn, dif_edn_auto_params_t config)
	Enables the EDN in auto refresh mode. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_edn_get_status (const dif_edn_t *edn, dif_edn_status_t flag, bool *set)
	Queries the EDN status flags. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_edn_get_errors (const dif_edn_t *edn, uint32_t *unhealthy_fifos, uint32_t *errors)
	Queries the EDN error flags. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_edn_get_cmd_unhealthy_fifo_force (const dif_edn_t *edn, dif_edn_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_edn_get_cmd_error_force (const dif_edn_t *edn, dif_edn_error_t error)
	Forces the status registers to indicate a particular error cause. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_edn_get_main_state_machine (const dif_edn_t *edn, uint32_t *state)
	Returns an opaque blob indicating the main state machine's current state. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_edn_instantiate (const dif_edn_t *edn, dif_edn_entropy_src_toggle_t entropy_src_enable, const dif_edn_seed_material_t *seed_material)
	Initializes CSRNG instance with a new seed value. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_edn_reseed (const dif_edn_t *edn, const dif_edn_seed_material_t *seed_material)
	Reseeds CSRNG instance. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_edn_update (const dif_edn_t *edn, const dif_edn_seed_material_t *seed_material)
	Updates CSRNG state. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_edn_generate_start (const dif_edn_t *edn, size_t len)
	Requests cryptographic entropy bits from the CSRNG. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_edn_uninstantiate (const dif_edn_t *edn)
	Uninstantiates CSRNG. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_edn_stop (const dif_edn_t *edn)
	Stops the current mode of operation and disables the entropy module. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_edn_get_recoverable_alerts (const dif_edn_t *edn, uint32_t *alerts)
	Gets the recoverable alerts currently recorded in the EDN block. More...
OT_WARN_UNUSED_RESULT dif_result_t	dif_edn_clear_recoverable_alerts (const dif_edn_t *edn)
	Clears all recoverable alerts currently recorded in the EDN block. More...

Detailed Description

Entropy Distribution Network Device Interface Functions

This API implements the interface for the Entropy Distribution Network (EDN) hardware.

There are two main modes of operation:

• boot-time: EDN configures the associated CSRNG instance to fetch pre-FIPS entropy immediately at boot-time or after reset.
• auto refresh: EDN sends reseed and generate commands to the associated CSRNG instance. The API allows the user to set the CSRNG instantiate, reseed and generate para meters, as well as the reseed frequency.

Definition in file dif_edn.h.

---

Data Structure Documentation

dif_edn_seed_material

struct dif_edn_seed_material

CSRNG seed material for instantiate, reseed and generate commands.

Definition at line 72 of file dif_edn.h.

Data Fields
uint32_t	data[kDifEntropySeedMaterialMaxWordLen]	Seed material used in CSRNG instantiate, reseed or generate call.
size_t	len	Number of uint32_t words in data. Up to kDifEntropySeedMaterialMaxWordLen words can be set to initialize or reseed the CSRNG. CSRNG will extend the data to zeros if the provided value is less than kDifEntropySeedMaterialMaxWordLen.

dif_edn_cmd

struct dif_edn_cmd

CSRNG command parameters for instantiate, reseed and generate commands.

Definition at line 89 of file dif_edn.h.

Data Fields
uint32_t	cmd	The CSRNG application interface command header. For details, refer to the CSRNG documentation.
dif_edn_seed_material_t	seed_material	Optional seed material.

dif_edn_auto_params

struct dif_edn_auto_params

Auto-generate EDN module configuration parameters.

Definition at line 104 of file dif_edn.h.

Data Fields
dif_edn_cmd_t	generate_cmd	CSRNG generate command material.
dif_edn_cmd_t	instantiate_cmd	CSRNG instantiate command material.
dif_edn_cmd_t	reseed_cmd	CSRNG reseed command material.
uint32_t	reseed_interval	Number of generate calls that can be made before a reseed request is made.

Enumeration Type Documentation

anonymous enum

anonymous enum

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

Definition at line 37 of file dif_edn.h.

anonymous enum

anonymous enum

Enumerator
kDifEntropySeedMaterialMaxGlen	Maximum generate length supported in CSRNG generate commands.

Definition at line 45 of file dif_edn.h.

anonymous enum

anonymous enum

Enumerator
kDifMaxNumReqsBetweenReseeds	Maximum number of generate commands between reseed commands in the EDN auto mode.

Definition at line 52 of file dif_edn.h.

anonymous enum

anonymous enum

Enumerator
kDifEdnCmdInstantiate	Csrng commands.

Definition at line 60 of file dif_edn.h.

dif_edn_entropy_src_toggle

enum dif_edn_entropy_src_toggle

CSRNG consume seed from entropy source enable.

Enumerator
kDifEdnEntropySrcToggleDisable	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.
kDifEdnEntropySrcToggleEnable	Entropy source XOR'ed with the provided seed material.

Definition at line 273 of file dif_edn.h.

dif_edn_error

enum dif_edn_error

Enumeration of EDN FIFO errors.

Enumerator
kDifEdnErrorAckSm	Indicates an error in the command ack state machine.
kDifEdnErrorMainSm	Indicates an error in the main state machine.
kDifEdnErrorCounterFault	Indicates an error in a hardened counter.
kDifEdnErrorFifoWrite	Indicates a write to a full FIFO occured.
kDifEdnErrorFifoRead	Indicates a read from an empty FIFO occured.
kDifEdnErrorFifoFullAndEmpty	Indicates a FIFO was somehow both full and empty.

Definition at line 243 of file dif_edn.h.

dif_edn_recoverable_alert

enum dif_edn_recoverable_alert

Recoverable alerts emitted by the EDN.

Enumerator
kDifEdnRecoverableAlertBadEnable	Indicates a bad value was written to the EDN_ENABLE field of the control register.
kDifEdnRecoverableAlertBadBootReqMode	Indicates a bad value was written to the BOOT_REQ_MODE field of the control register.
kDifEdnRecoverableAlertBadAutoReqMode	Indicates a bad value was written to the AUTO_REQ_MODE field of the control register.
kDifEdnRecoverableAlertBadFifoClear	Indicates a bad value was written to the CMD_FIFO_RST field of the control register.
kDifEdnRecoverableAlertRepeatedGenBits	Indicates the genbits bus saw two identical values, indicating a possible attack.

Definition at line 293 of file dif_edn.h.

dif_edn_sm_state

enum dif_edn_sm_state

EDN SM states as defined in the EDN state machine RTL.

Enumerator
kDifEdnSmStateIdle	Device is idle.
kDifEdnSmStateBootLoadIns	Boot mode: load the instantiate command.
kDifEdnSmStateBootInsAckWait	Boot mode: wait for instantiate command ack.
kDifEdnSmStateBootLoadGen	Boot mode: load the generate command.
kDifEdnSmStateBootGenAckWait	Boot mode: wait for generate command ack.
kDifEdnSmStateBootPulse	Boot mode: signal a done pulse.
kDifEdnSmStateBootDone	Boot mode: stay in done state until reset.
kDifEdnSmStateBootLoadUni	Boot mode: load the uninstantiate command.
kDifEdnSmStateBootUniAckWait	Boot mode: wait for uninstantiate command ack.
kDifEdnSmStateAutoLoadIns	Auto mode: load the instantiate command.
kDifEdnSmStateAutoFirstAckWait	Auto mode: wait for first instantiate command ack.
kDifEdnSmStateAutoAckWait	Auto mode: wait for instantiate command ack.
kDifEdnSmStateAutoDispatch	Auto mode: determine next command to be sent.
kDifEdnSmStateAutoCaptGenCnt	Auto mode: capture the gen fifo count.
kDifEdnSmStateAutoSendGenCmd	Auto mode: send the generate command.
kDifEdnSmStateAutoCaptReseedCnt	Auto mode: capture the reseed fifo count.
kDifEdnSmStateAutoSendReseedCmd	Auto mode: send the reseed command.
kDifEdnSmStateSWPortMode	Sw port: no hw request mode.
kDifEdnSmStateRejectCsrngEntropy	Stop accepting entropy from CSRNG.
kDifEdnSmStateError	Illegal state reached and hang.

Definition at line 148 of file dif_edn.h.

dif_edn_status

enum dif_edn_status

EDN Status flags.

Enumerator
kDifEdnStatusRegReady	SW command register is ready to receive the next word of a command.
kDifEdnStatusReady	Device is ready to receive a command.
kDifEdnStatusCsrngStatus	Device has received an error from the CSRNG block.
kDifEdnStatusCsrngAck	Device has recieved an ACK from the CSRNG block.

Definition at line 126 of file dif_edn.h.

Function Documentation

dif_edn_clear_recoverable_alerts()

OT_WARN_UNUSED_RESULT dif_result_t dif_edn_clear_recoverable_alerts

(

const dif_edn_t *

edn

)

Clears all recoverable alerts currently recorded in the EDN block.

Parameters

edn	An EDN handle.

Returns

The result of the operation.

Definition at line 396 of file dif_edn.c.

dif_edn_configure()

OT_WARN_UNUSED_RESULT dif_result_t dif_edn_configure

(

const dif_edn_t *

edn

)

Configures EDN with runtime information.

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

Parameters

edn	An EDN handle.

Returns

The result of the operation.

Definition at line 20 of file dif_edn.c.

dif_edn_generate_start()

OT_WARN_UNUSED_RESULT dif_result_t dif_edn_generate_start	(	const dif_edn_t *	edn,
		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 directly 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

edn	An EDN 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 327 of file dif_edn.c.

dif_edn_get_cmd_error_force()

OT_WARN_UNUSED_RESULT dif_result_t dif_edn_get_cmd_error_force	(	const dif_edn_t *	edn,
		dif_edn_error_t	error
	)

Forces the status registers to indicate a particular error cause.

Parameters

edn	An EDN handle
error	The error to force.

Returns

The result of the operation.

Definition at line 238 of file dif_edn.c.

dif_edn_get_cmd_unhealthy_fifo_force()

OT_WARN_UNUSED_RESULT dif_result_t dif_edn_get_cmd_unhealthy_fifo_force	(	const dif_edn_t *	edn,
		dif_edn_fifo_t	fifo
	)

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

Parameters

edn	An EDN handle
fifo	The FIFO to mark as unhealthy.

Returns

The result of the operation.

Definition at line 215 of file dif_edn.c.

dif_edn_get_errors()

OT_WARN_UNUSED_RESULT dif_result_t dif_edn_get_errors	(	const dif_edn_t *	edn,
		uint32_t *	unhealthy_fifos,
		uint32_t *	errors
	)

Queries the EDN error flags.

Parameters

	edn	An EDN handle.
[out]	unhealthy_fifos	Bitset of FIFOs in an unhealthy state; indices are dif_edn_fifo_t.
[out]	errors	Bitset of errors relating to the above FIFOs; indices are dif_edn_error_t.

Returns

The result of the operation.

Definition at line 183 of file dif_edn.c.

dif_edn_get_main_state_machine()

OT_WARN_UNUSED_RESULT dif_result_t dif_edn_get_main_state_machine	(	const dif_edn_t *	edn,
		uint32_t *	state
	)

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

Parameters

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

Returns

The result of the operation.

Definition at line 273 of file dif_edn.c.

dif_edn_get_recoverable_alerts()

OT_WARN_UNUSED_RESULT dif_result_t dif_edn_get_recoverable_alerts	(	const dif_edn_t *	edn,
		uint32_t *	alerts
	)

Gets the recoverable alerts currently recorded in the EDN block.

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

Parameters

	edn	An EDN handle.
[out]	alerts	Bitset of alerts currently recorded.

Returns

The result of the operation.

Definition at line 371 of file dif_edn.c.

dif_edn_get_status()

OT_WARN_UNUSED_RESULT dif_result_t dif_edn_get_status	(	const dif_edn_t *	edn,
		dif_edn_status_t	flag,
		bool *	set
	)

Queries the EDN status flags.

Parameters

edn	An EDN handle.
flag	Status flag to query.
set	Flag state (set/unset).

Returns

The result of the operation.

Definition at line 154 of file dif_edn.c.

dif_edn_instantiate()

OT_WARN_UNUSED_RESULT dif_result_t dif_edn_instantiate	(	const dif_edn_t *	edn,
		dif_edn_entropy_src_toggle_t	entropy_src_enable,
		const dif_edn_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.

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

Parameters

edn	An EDN handle.
entropy_src_enable	Entropy source input enable.
seed_material	Seed initialization parameters.

Returns

The result of the operation.

Definition at line 283 of file dif_edn.c.

dif_edn_is_locked()

OT_WARN_UNUSED_RESULT dif_result_t dif_edn_is_locked	(	const dif_edn_t *	edn,
		bool *	is_locked
	)

Checks whether this EDN is locked.

Parameters

	edn	An EDN handle.
[out]	is_locked	Out-param for the locked state.

Returns

The result of the operation.

Definition at line 42 of file dif_edn.c.

dif_edn_lock()

OT_WARN_UNUSED_RESULT dif_result_t dif_edn_lock

(

const dif_edn_t *

edn

)

Locks out EDN functionality.

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

Parameters

edn	An EDN handle.

Returns

The result of the operation.

Definition at line 34 of file dif_edn.c.

dif_edn_reseed()

OT_WARN_UNUSED_RESULT dif_result_t dif_edn_reseed	(	const dif_edn_t *	edn,
		const dif_edn_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

edn	An EDN handle.
seed_material	Reseed parameters.

Returns

The result of the operation.

Definition at line 299 of file dif_edn.c.

dif_edn_set_auto_mode()

OT_WARN_UNUSED_RESULT dif_result_t dif_edn_set_auto_mode	(	const dif_edn_t *	edn,
		dif_edn_auto_params_t	config
	)

Enables the EDN in auto refresh mode.

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

Parameters

edn	An EDN handle.
config	Auto request configuration parameters.

Returns

The result of the operation.

Definition at line 64 of file dif_edn.c.

dif_edn_set_boot_mode()

OT_WARN_UNUSED_RESULT dif_result_t dif_edn_set_boot_mode

(

const dif_edn_t *

edn

)

Enables the EDN in boot-time mode.

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

Parameters

edn	An EDN handle.

Returns

The result of the operation.

Definition at line 50 of file dif_edn.c.

dif_edn_stop()

OT_WARN_UNUSED_RESULT dif_result_t dif_edn_stop

(

const dif_edn_t *

edn

)

Stops the current mode of operation and disables the entropy module.

Parameters

edn	An EDN handle.

Returns

The result of the operation.

Definition at line 352 of file dif_edn.c.

dif_edn_uninstantiate()

OT_WARN_UNUSED_RESULT dif_result_t dif_edn_uninstantiate

(

const dif_edn_t *

edn

)

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

edn	An EDN handle.

Returns

The result of the operation.

Definition at line 342 of file dif_edn.c.

dif_edn_update()

OT_WARN_UNUSED_RESULT dif_result_t dif_edn_update	(	const dif_edn_t *	edn,
		const dif_edn_seed_material_t *	seed_material
	)

Updates CSRNG state.

This function is similar to dif_edn_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

edn	An EDN handle.
seed_material	Update parameters.

Returns

The result of the operation.

Definition at line 313 of file dif_edn.c.