Software APIs
csrng_testutils.c
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#include "sw/device/lib/testing/csrng_testutils.h"
6
9#include "sw/device/lib/dif/dif_csrng_shared.h"
10#include "sw/device/lib/testing/rand_testutils.h"
11#include "sw/device/lib/testing/test_framework/check.h"
12
13#include "csrng_regs.h" // Generated
14
15#define MODULE_ID MAKE_MODULE_ID('r', 'n', 't')
16
17enum {
18 kNumOutputWordsMax = 16,
19};
20
21/**
22 * Generates randomized seed material.
23 */
24status_t csrng_testutils_seed_material_build(
25 bool disable_rand, dif_csrng_seed_material_t *seed_material) {
26 if (seed_material == NULL) {
27 return INVALID_ARGUMENT();
28 }
29 seed_material->seed_material_len =
30 disable_rand
31 ? 0
32 : rand_testutils_gen32_range(0, kDifCsrngSeedMaterialMaxWordLen);
33 for (size_t i = 0; i < seed_material->seed_material_len; ++i) {
34 seed_material->seed_material[i] = rand_testutils_gen32();
35 }
36 return OK_STATUS();
37}
38
39/**
40 * Returns a randomized CSRNG application command.
41 */
42csrng_app_cmd_t csrng_testutils_app_cmd_build(
43 bool disable_rand, csrng_app_cmd_id_t id,
44 dif_csrng_entropy_src_toggle_t entropy_src_en, unsigned int glen_val,
45 dif_csrng_seed_material_t *seed_material) {
46 CHECK_STATUS_OK(
47 csrng_testutils_seed_material_build(disable_rand, seed_material));
48
49 // If disable_rand is true, we set flag0 to the provided value.
50 // If disable_rand is false, we pick a value at random.
51 dif_csrng_entropy_src_toggle_t entropy_src_enable =
52 disable_rand ? entropy_src_en
53 : rand_testutils_gen32_range(0, 1) ? kDifCsrngEntropySrcToggleEnable
55
56 // If glen_val > 0, the generate length is set to glen_val.
57 // If disable_rand is false we pick a random value between 1 and 10 with a
58 // bias towards 1. Otherwise, if glen would be too high, we would not see
59 // any reseeds because we do not consume enough entropy.
60 unsigned int glen = glen_val ? glen_val
61 : (disable_rand || rand_testutils_gen32_range(0, 1))
62 ? 1
63 : rand_testutils_gen32_range(2, 10);
64
65 return (csrng_app_cmd_t){
66 .id = id,
67 .entropy_src_enable = entropy_src_enable,
68 .seed_material = seed_material,
69 .generate_len = glen,
70 };
71}
72
73status_t csrng_testutils_cmd_ready_wait(const dif_csrng_t *csrng) {
74 dif_csrng_cmd_status_t cmd_status;
75 do {
76 TRY(dif_csrng_get_cmd_interface_status(csrng, &cmd_status));
77 TRY_CHECK(cmd_status.kind != kDifCsrngCmdStatusError);
78 } while (cmd_status.kind != kDifCsrngCmdStatusReady);
79 return OK_STATUS();
80}
81
82status_t csrng_testutils_cmd_generate_run(const dif_csrng_t *csrng,
83 uint32_t *output, size_t output_len) {
84 TRY(csrng_testutils_cmd_ready_wait(csrng));
85 TRY(dif_csrng_generate_start(csrng, output_len));
86
87 dif_csrng_output_status_t output_status;
88 do {
89 TRY(dif_csrng_get_output_status(csrng, &output_status));
90 } while (!output_status.valid_data);
91
92 TRY(dif_csrng_generate_read(csrng, output, output_len));
93 return OK_STATUS();
94}
95
96status_t csrng_testutils_check_internal_state(
97 const dif_csrng_t *csrng, const dif_csrng_internal_state_t *expected) {
98 TRY(csrng_testutils_cmd_ready_wait(csrng));
100 TRY(dif_csrng_get_internal_state(csrng, kCsrngInternalStateIdSw, &got));
101 uint32_t reseed_counter;
102 TRY(dif_csrng_get_reseed_counter(csrng, kCsrngInternalStateIdSw,
103 &reseed_counter));
104
105 TRY_CHECK(got.instantiated == expected->instantiated);
106 TRY_CHECK(got.reseed_counter == expected->reseed_counter);
107 TRY_CHECK(reseed_counter == expected->reseed_counter);
108 TRY_CHECK(got.fips_compliance == expected->fips_compliance);
109
110 TRY_CHECK(memcmp(got.v, expected->v, sizeof(expected->v)) == 0);
111
112 TRY_CHECK(memcmp(got.key, expected->key, sizeof(expected->key)) == 0);
113 return OK_STATUS();
114}
115
116status_t csrng_testutils_kat_instantiate(
117 const dif_csrng_t *csrng, bool fail_expected,
118 const dif_csrng_seed_material_t *seed_material,
119 const dif_csrng_internal_state_t *expected_state) {
120 LOG_INFO("CSRNG KAT instantiate");
121 TRY(csrng_testutils_cmd_ready_wait(csrng));
122 TRY(dif_csrng_uninstantiate(csrng));
123
124 // Instantiate CSRNG - use the provided seed material only.
125 TRY(csrng_testutils_cmd_ready_wait(csrng));
126 TRY(dif_csrng_instantiate(csrng, kDifCsrngEntropySrcToggleDisable,
127 seed_material));
128
129 // Check the internal state of created CSRNG instance.
131 memset(&zero_state, 0, sizeof(zero_state));
132 return csrng_testutils_check_internal_state(
133 csrng, fail_expected ? &zero_state : expected_state);
134}
135
136status_t csrng_testutils_kat_generate(
137 const dif_csrng_t *csrng, size_t num_generates, size_t output_len,
138 const uint32_t *expected_output,
139 const dif_csrng_internal_state_t *expected_state) {
140 LOG_INFO("CSRNG KAT generate");
141
142 // Run the generate and check the output.
143 uint32_t got[kNumOutputWordsMax];
144 for (int i = 0; i < num_generates; ++i) {
145 TRY(csrng_testutils_cmd_generate_run(csrng, got, output_len));
146 }
147 TRY_CHECK(memcmp(got, expected_output, output_len) == 0);
148
149 // Check the internal state.
150 return csrng_testutils_check_internal_state(csrng, expected_state);
151}
152
153status_t csrng_testutils_kat_reseed(
154 const dif_csrng_t *csrng, const dif_csrng_seed_material_t *seed_material,
155 const dif_csrng_internal_state_t *expected_state) {
156 LOG_INFO("CSRNG KAT reseed");
157
158 // Reseed CSRNG - use the provided seed material only.
159 TRY(csrng_testutils_cmd_ready_wait(csrng));
160 TRY(csrng_send_app_cmd(
161 csrng->base_addr, kCsrngAppCmdTypeCsrng,
162 (csrng_app_cmd_t){
163 .id = kCsrngAppCmdReseed,
164 .entropy_src_enable = kDifCsrngEntropySrcToggleDisable,
165 .seed_material = seed_material,
166 }));
167
168 // Check the internal state.
169 return csrng_testutils_check_internal_state(csrng, expected_state);
170}
171
172status_t csrng_testutils_fips_instantiate_kat(const dif_csrng_t *csrng,
173 bool fail_expected) {
174 // CTR_DRBG Known-Answer-Tests (KATs).
175 //
176 // Test vector sourced from NIST's CAVP website:
177 // https://csrc.nist.gov/projects/cryptographic-algorithm-validation-program/random-number-generators
178 //
179 // The number format in this docstring follows the CAVP format to simplify
180 // auditing of this test case.
181 //
182 // Test vector: CTR_DRBG AES-256 no DF.
183 //
184 // - EntropyInput =
185 // df5d73faa468649edda33b5cca79b0b05600419ccb7a879ddfec9db32ee494e5531b51de16a30f769262474c73bec010
186 // - Nonce = EMPTY
187 // - PersonalizationString = EMPTY
188 //
189 // Command: Instantiate
190 // - Key = 8c52f901632d522774c08fad0eb2c33b98a701a1861aecf3d8a25860941709fd
191 // - V = 217b52142105250243c0b2c206b8f59e
192 //
193 // Command: Generate (first call):
194 // - Key = 72f4af5c93258eb3eeec8c0cacea6c1d1978a4fad44312725f1ac43b167f2d52
195 // - V = e86f6d07dfb551cebad80e6bf6830ac4
196 //
197 // Command: Generate (second call):
198 // - Key = 1a1c6e5f1cccc6974436e5fd3f015bc8e9dc0f90053b73e3c19d4dfd66d1b85a
199 // - V = 53c78ac61a0bac9d7d2e92b1e73e3392
200 // - ReturnedBits =
201 // d1c07cd95af8a7f11012c84ce48bb8cb87189e99d40fccb1771c619bdf82ab2280b1dc2f2581f39164f7ac0c510494b3a43c41b7db17514c87b107ae793e01c5
202
203 const dif_csrng_seed_material_t kEntropyInput = {
204 .seed_material = {0x73bec010, 0x9262474c, 0x16a30f76, 0x531b51de,
205 0x2ee494e5, 0xdfec9db3, 0xcb7a879d, 0x5600419c,
206 0xca79b0b0, 0xdda33b5c, 0xa468649e, 0xdf5d73fa},
207 .seed_material_len = 12,
208 };
209 const dif_csrng_internal_state_t kExpectedState = {
210 .reseed_counter = 0,
211 .v = {0x06b8f59e, 0x43c0b2c2, 0x21052502, 0x217b5214},
212 .key = {0x941709fd, 0xd8a25860, 0x861aecf3, 0x98a701a1, 0x0eb2c33b,
213 0x74c08fad, 0x632d5227, 0x8c52f901},
214 .instantiated = true,
215 .fips_compliance = false,
216 };
217 return csrng_testutils_kat_instantiate(csrng, fail_expected, &kEntropyInput,
218 &kExpectedState);
219}
220
221status_t csrng_testutils_fips_generate_kat(const dif_csrng_t *csrng) {
222 enum {
223 kExpectedOutputLen = 16,
224 };
225 // TODO(#13342): csrng does not provide a linear output order. For example,
226 // note the test vector output word order: 12,13,14,15 8,9,10,11 4,5,6,7
227 // 0,1,2,3.
228 const uint32_t kExpectedOutput[kExpectedOutputLen] = {
229 0xe48bb8cb, 0x1012c84c, 0x5af8a7f1, 0xd1c07cd9, 0xdf82ab22, 0x771c619b,
230 0xd40fccb1, 0x87189e99, 0x510494b3, 0x64f7ac0c, 0x2581f391, 0x80b1dc2f,
231 0x793e01c5, 0x87b107ae, 0xdb17514c, 0xa43c41b7,
232 };
233 const dif_csrng_internal_state_t kExpectedState = {
234 .reseed_counter = 2,
235 .v = {0xe73e3392, 0x7d2e92b1, 0x1a0bac9d, 0x53c78ac6},
236 .key = {0x66d1b85a, 0xc19d4dfd, 0x053b73e3, 0xe9dc0f90, 0x3f015bc8,
237 0x4436e5fd, 0x1cccc697, 0x1a1c6e5f},
238 .instantiated = true,
239 .fips_compliance = false,
240 };
241 return csrng_testutils_kat_generate(csrng, 2, kExpectedOutputLen,
242 kExpectedOutput, &kExpectedState);
243}
244
245status_t csrng_testutils_cmd_status_check(const dif_csrng_t *csrng) {
247 TRY(dif_csrng_get_cmd_interface_status(csrng, &status));
248 TRY_CHECK(status.cmd_sts == kDifCsrngCmdStsSuccess);
249 return OK_STATUS();
250}
251
252status_t csrng_testutils_recoverable_alerts_check(const dif_csrng_t *csrng) {
253 uint32_t alerts = UINT32_MAX;
254 TRY(dif_csrng_get_recoverable_alerts(csrng, &alerts));
255 TRY_CHECK(alerts == 0);
256 return OK_STATUS();
257}