Skip to content

Latest commit

 

History

History
159 lines (144 loc) · 4.78 KB

programmers_guide.md

File metadata and controls

159 lines (144 loc) · 4.78 KB

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 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:

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

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)