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"
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 */
19status_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 */
35csrng_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 */
45status_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 */
55status_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 */
65status_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 */
77status_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 */
93status_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 */
106status_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 */
117status_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 */
126status_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 */
136status_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 */
146status_t csrng_testutils_recoverable_alerts_check(const dif_csrng_t *csrng);
147
148#endif // OPENTITAN_SW_DEVICE_LIB_TESTING_CSRNG_TESTUTILS_H_