Programmer’s Guide

This section discusses how software can interface with CSRNG.

Module enable and disable

CSRNG may only be disabled if all EDNs are disabled.

The recommended enable sequence for the entropy complex is to first enable ENTROPY_SRC, then CSRNG, and finally the EDNs.

Running CSRNG with ENTROPY_SRC disabled

Once the entropy complex has been enabled and all configured CSRNG instances have been seeded with entropy, software can again disable ENTROPY_SRC (and the PTRNG noise source to e.g. save power) while CSRNG and the EDNs remain running to keep serving entropy to consumers.

Depending on the mode in which the CSRNG instance is running, software can use a different mechanism to efficiently operate the entropy complex without having the ENTROPY_SRC continuously running:

Regular, non-deterministic mode

If a CSRNG instance is running in regular, non-deterministic mode (flag0 being false, see Generated Bits (genbits) Interface for details), the cs_entropy_req interrupt will assert whenever the instance requests entropy from ENTROPY_SRC. Once software observes the interrupt, it has to enable ENTROPY_SRC. The ENTROPY_SRC block will then perform the startup health testing and eventually deliver a new seed to the CSRNG instance. Note that the startup health testing may take a non-negligible time (see Startup Health Testing during which the CSRNG instance is blocked. Thus, it is recommended that software tracks the age of the seed currently in use via the corresponding RESEED_COUNTER register to re-enable ENTROPY_SRC ahead of the cs_entropy_req interrupt firing.

Fully deterministic mode

For CSRNG instances running in fully deterministic mode (flag0 being true, see Generated Bits (genbits) Interface for details), software has to provide entropy for instantiation and reseeding via the additional data field of the instantiate and reseed command, respectively. If no additional data is provided, CSRNG will use an all-zero seed. Additional entropy can be provided via the additional data field of every generate command. The entropy to be provided to these commands can for example be generated by running the ENTROPY_SRC block in a dedicated mode, see Reading Entropy Output for details. Software is recommended to manage a buffer of seeds which is filled whenever it enables ENTROPY_SRC in this mode to reduce the duty cycle of ENTROPY_SRC (and the PTRNG noise source) thereby improving power efficiency and latency.

Endianness and Known-Answer Tests

All CSRNG registers are little-endian.

When providing additional data for an instantiate, reseed or update command the data words have to be written to CMD_REQ in the correct order. Consider a byte string B₁, B₂, …, B_n as defined in Appendix A of NIST’s SP 800-90A, i.e., where B₁ is the most significant byte and B_n the least significant byte. Providing this sequence as additional data to CSRNG requires software to write the following 32-bit words to CMD_REQ in the following order:

When reading the internal state from INT_STATE_VAL, CSRNG returns the bytes of V and Key in the following order:

Finally, when reading a byte string of say 64 bytes (16 words) B₁, B₂, …, B₆₄ from GENBITS as defined in Appendix A of NIST’s SP 800-90A, the bytes are returned in the following order. Note that always 4 words return 1 128-bit GENBITS block. Within each block, the least significant bytes are returned first and the most significant bytes are returned last. In particular, the most significant byte B₁ of the string is read in Word 4 and the least significant byte B₆₄ of the string is read in Word 13.

Device Interface Functions (DIFs)

• Device Interface Functions