Software APIs
csrng_testutils.h
1 // Copyright lowRISC contributors (OpenTitan project).
2 // Licensed under the Apache License, Version 2.0, see LICENSE for details.
3 // SPDX-License-Identifier: Apache-2.0
4 
5 #ifndef OPENTITAN_SW_DEVICE_LIB_TESTING_CSRNG_TESTUTILS_H_
6 #define OPENTITAN_SW_DEVICE_LIB_TESTING_CSRNG_TESTUTILS_H_
7 
8 #include "sw/device/lib/base/status.h"
9 #include "sw/device/lib/dif/dif_csrng.h"
10 #include "sw/device/lib/dif/dif_csrng_shared.h"
11 
12 /**
13  * Generates randomized seed material.
14  *
15  * @param disable_rand If set, the generated seed material has length zero.
16  * @param seed_material The seed material to generate.
17  */
18 OT_WARN_UNUSED_RESULT
19 status_t csrng_testutils_seed_material_build(
20  bool disable_rand, dif_csrng_seed_material_t *seed_material);
21 
22 /**
23  * Returns a randomized CSRNG application command.
24  *
25  * @param disable_rand If set, a struct containing default values is returned.
26  * @param id CSRNG application command to generate.
27  * @param entropy_src_en If set, Instantiate and Reseed commands use entropy
28  * from the entropy source.
29  * @param glen_val If > 0, the generate length is set to glen_val.
30  * @param seed_material The seed material to generate and use for the generated
31  * application command.
32  * @return The generated CSRNG application command.
33  */
34 OT_WARN_UNUSED_RESULT
35 csrng_app_cmd_t csrng_testutils_app_cmd_build(
36  bool disable_rand, csrng_app_cmd_id_t id,
37  dif_csrng_entropy_src_toggle_t entropy_src_en, unsigned int glen_val,
38  dif_csrng_seed_material_t *seed_material);
39 
40 /**
41  * Wait for the `csrng` instance command interface to be ready to accept
42  * commands. Aborts test execution if an error is found.
43  */
44 OT_WARN_UNUSED_RESULT
45 status_t csrng_testutils_cmd_ready_wait(const dif_csrng_t *csrng);
46 
47 /**
48  * Runs CSRNG generate command.
49  *
50  * @param csrng A CSRNG handle.
51  * @param output Output buffer.
52  * @param output_len Number of words of entropy to write to output buffer.
53  */
54 OT_WARN_UNUSED_RESULT
55 status_t csrng_testutils_cmd_generate_run(const dif_csrng_t *csrng,
56  uint32_t *output, size_t output_len);
57 
58 /**
59  * Checks the CSRNG internal state against `expected` values.
60  *
61  * @param csrng A CSRNG handle.
62  * @param expected Expected CSRNG internal state.
63  */
64 OT_WARN_UNUSED_RESULT
65 status_t csrng_testutils_check_internal_state(
66  const dif_csrng_t *csrng, const dif_csrng_internal_state_t *expected);
67 
68 /**
69  * CTR_DRBG Known-Answer-Test (KAT) for INSTANTIATE command.
70  *
71  * @param csrng A CSRNG handle.
72  * @param fail_expected Expected fail.
73  * @param seed_material Seed material to use for the command.
74  * @param expected_state Expected CSRNG internal state after the command.
75  */
76 OT_WARN_UNUSED_RESULT
77 status_t csrng_testutils_kat_instantiate(
78  const dif_csrng_t *csrng, bool fail_expected,
79  const dif_csrng_seed_material_t *seed_material,
80  const dif_csrng_internal_state_t *expected_state);
81 
82 /**
83  * CTR_DRBG Known-Answer-Test (KAT) for GENERATE command.
84  *
85  * @param csrng A CSRNG handle.
86  * @param num_generates Number of GENERATE commands to run.
87  * @param output_len Number of output words to read from CSRNG after the last
88  * command.
89  * @param expected_output Expected CSRNG output after the last command.
90  * @param expected_state Expected CSRNG internal state after the last command.
91  */
92 OT_WARN_UNUSED_RESULT
93 status_t csrng_testutils_kat_generate(
94  const dif_csrng_t *csrng, uint32_t num_generates, uint32_t output_len,
95  const uint32_t *expected_output,
96  const dif_csrng_internal_state_t *expected_state);
97 
98 /**
99  * CTR_DRBG Known-Answer-Test (KAT) for RESEED command.
100  *
101  * @param csrng A CSRNG handle.
102  * @param seed_material Seed material to use for the command.
103  * @param expected_state Expected CSRNG internal state after the command.
104  */
105 OT_WARN_UNUSED_RESULT
106 status_t csrng_testutils_kat_reseed(
107  const dif_csrng_t *csrng, const dif_csrng_seed_material_t *seed_material,
108  const dif_csrng_internal_state_t *expected_state);
109 
110 /**
111  * CTR DRBG Known-Answer-Test (KAT) for INSTANTIATE command.
112  *
113  * @param csrng Handle.
114  * @param fail_expected Expected fail.
115  */
116 OT_WARN_UNUSED_RESULT
117 status_t csrng_testutils_fips_instantiate_kat(const dif_csrng_t *csrng,
118  bool fail_expected);
119 
120 /**
121  * CTR DRBG Known-Answer-Test (KAT) for GENERATE command.
122  *
123  * @param csrng Handle.
124  */
125 OT_WARN_UNUSED_RESULT
126 status_t csrng_testutils_fips_generate_kat(const dif_csrng_t *csrng);
127 
128 /**
129  * Checks CSRNG command status.
130  *
131  * Asserts error if the command or internal FIFO status contains any errors.
132  *
133  * @param csrng Handle.
134  */
135 OT_WARN_UNUSED_RESULT
136 status_t csrng_testutils_cmd_status_check(const dif_csrng_t *csrng);
137 
138 /**
139  * Checks CSRNG recoverable alerts.
140  *
141  * Asserts error if there are any CSRNG recoverable alerts set.
142  *
143  * @param csrng Handle.
144  */
145 OT_WARN_UNUSED_RESULT
146 status_t csrng_testutils_recoverable_alerts_check(const dif_csrng_t *csrng);
147 
148 #endif // OPENTITAN_SW_DEVICE_LIB_TESTING_CSRNG_TESTUTILS_H_
Return to OpenTitan Documentation