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

(7e0843b8b9)

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

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

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

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

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

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

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

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
csrngAn 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
csrngA 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
csrngA 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
csrngA CSRNG handle.
[out]bufA buffer to fill with words from the pipeline.
lenThe 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
csrngA CSRNG handle.
lenNumber 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
csrngAn CSRNG handle
errorThe 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
csrngAn CSRNG handle
fifoThe 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
csrngAn CSRNG handle
[out]statusCommand 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
csrngAn 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
csrngA CSRNG handle
instance_idCSRNG instance ID.
[out]stateThe 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
csrngAn 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
csrngA CSRNG handle.
[out]statusCSRNG 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
csrngA CSRNG handle.
[out]alertsBitset 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
csrngA CSRNG handle
instance_idCSRNG instance ID.
[out]reseedcounter 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
csrngA CSRNG handle.
entropy_src_enableEntropy source input enable.
seed_materialSeed 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
csrngA CSRNG handle.
[out]is_lockedOut-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
csrngA 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
csrngA CSRNG handle.
seed_materialReseed 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
csrngA 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
csrngAn 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
csrngA CSRNG handle.
seed_materialUpdate parameters.
Returns
The result of the operation.

Definition at line 89 of file dif_csrng.c.