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 B1, B2, …, Bn as defined in Appendix A of NIST’s SP 800-90A, i.e., where B1 is the most significant byte and Bn 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:
Word Index | Byte Indices of Additional Data |
---|---|
1 | 0xBn-3Bn-2Bn-1Bn |
... | ... |
n/4-1 | 0xB5B6B8B8 |
n/4 | 0xB1B2B3B4 |
When reading the internal state from INT_STATE_VAL
, CSRNG returns the bytes of V and Key in the following order:
Word Index | Byte Indices of V and Key |
---|---|
1 | 0xV13V14V15V16 |
... | ... |
4 | 0xV01V02V03V04 |
5 | 0xKey29Key30Key31Key32 |
... | ... |
11 | 0xKey05Key06Key07Key08 |
12 | 0xKey01Key02Key03Key04 |
Finally, when reading a byte string of say 64 bytes (16 words) B1, B2, …, B64 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 B1 of the string is read in Word 4 and the least significant byte B64 of the string is read in Word 13.
Word Index | Byte Indices of Generated Bits |
---|---|
1 | 0xB13B14B15B16 |
2 | 0xB09B10B11B12 |
3 | 0xB05B06B07B08 |
4 | 0xB01B02B03B04 |
5 | 0xB29B30B31B32 |
6 | 0xB25B26B27B28 |
7 | 0xB21B22B23B24 |
8 | 0xB17B18B19B20 |
... | ... |
13 | 0xB61B62B63B64 |
14 | 0xB57B58B59B60 |
15 | 0xB53B54B55B56 |
16 | 0xB49B50B51B52 |