programmers_guide.md

Programmer's Guide

This section discusses how software can interface with CSRNG.

Module enable and disable

CSRNG may only be enabled if ENTROPY_SRC is enabled. CSRNG may only be disabled if all EDNs are disabled. Once disabled, CSRNG may only be re-enabled after ENTROPY_SRC has been disabled and re-enabled.

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:

Byte order when writing to [`CMD_REQ`](data/csrng.hjson#cmd_req)

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:

Byte order when reading from [`INT_STATE_VAL`](data/csrng.hjson#int_state_val)

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) 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.

Byte order when reading from [`GENBITS`](data/csrng.hjson#genbits)

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

Device Interface Functions (DIFs)

• Device Interface Functions