Software APIs
keymgr_dpe_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// This #if define ... ensures backwards compatibility with darjeeling. Either
6// both tops will get their own testutils or this define guard can be
7// implemented at a more granular level (i.e. at function level).
8// TODO(#30919): Split the keymgr_dpe_testutil on a finer level.
9#if defined(OPENTITAN_IS_DARJEELING)
10
11#include "sw/device/lib/testing/keymgr_dpe_testutils.h"
12
13#include "hw/top/dt/keymgr_dpe.h"
14#include "hw/top/dt/otp_ctrl.h"
15#include "hw/top/dt/rstmgr.h"
21#include "sw/device/lib/testing/otp_ctrl_testutils.h"
22#include "sw/device/lib/testing/rstmgr_testutils.h"
23#include "sw/device/lib/testing/test_framework/check.h"
25
26status_t keymgr_dpe_testutils_startup(dif_keymgr_dpe_t *keymgr_dpe,
27 uint32_t slot_dst_sel) {
28 dif_rstmgr_t rstmgr;
30
31 TRY(dif_rstmgr_init_from_dt(kDtRstmgr, &rstmgr));
32 info = rstmgr_testutils_reason_get();
33
34 // POR reset.
35 if (info == kDifRstmgrResetInfoPor) {
37 "Powered up for the first time, lock SECRET2 and SECRET3 partitions");
39 TRY(dif_otp_ctrl_init_from_dt(kDtOtpCtrl, &otp));
40 TRY(otp_ctrl_testutils_lock_partition(&otp, kDifOtpCtrlPartitionSecret2,
41 0));
42 TRY(otp_ctrl_testutils_lock_partition(&otp, kDifOtpCtrlPartitionSecret3,
43 0));
44
45 // Reboot device.
46 rstmgr_testutils_reason_clear();
47 LOG_INFO("Triggering software reset");
48 TRY(dif_rstmgr_software_device_reset(&rstmgr));
49
50 // Wait here until device reset.
51 wait_for_interrupt();
52
53 } else {
54 TRY_CHECK(info == kDifRstmgrResetInfoSw, "Unexpected reset reason: %08x",
55 info);
57 "Powered up for the second time, actuate keymgr_dpe and perform test.");
58
59 // Initialize keymgr_dpe context.
60 TRY(dif_keymgr_dpe_init_from_dt(kDtKeymgrDpe, keymgr_dpe));
61
62 // Advance to Initialized state.
63 TRY(keymgr_dpe_testutils_check_state(keymgr_dpe, kDifKeymgrDpeStateReset));
64 TRY(dif_keymgr_dpe_initialize(keymgr_dpe, slot_dst_sel));
65 TRY(keymgr_dpe_testutils_wait_for_operation_done(keymgr_dpe));
66 TRY(keymgr_dpe_testutils_check_state(keymgr_dpe,
67 kDifKeymgrDpeStateAvailable));
68 LOG_INFO("UDS is latched.");
69 }
70 return OK_STATUS();
71}
72
73status_t keymgr_dpe_testutils_advance_state(
74 const dif_keymgr_dpe_t *keymgr_dpe,
75 const dif_keymgr_dpe_advance_params_t *params) {
76 TRY(dif_keymgr_dpe_advance_state(keymgr_dpe, params));
77 return keymgr_dpe_testutils_wait_for_operation_done(keymgr_dpe);
78}
79
80status_t keymgr_dpe_testutils_erase_slot(
81 const dif_keymgr_dpe_t *keymgr_dpe,
82 const dif_keymgr_dpe_erase_params_t *params) {
83 TRY(dif_keymgr_dpe_erase_slot(keymgr_dpe, params));
84 return keymgr_dpe_testutils_wait_for_operation_done(keymgr_dpe);
85}
86
87status_t keymgr_dpe_testutils_generate(
88 const dif_keymgr_dpe_t *keymgr_dpe,
91 TRY(dif_keymgr_dpe_generate(keymgr_dpe, params));
92 TRY(keymgr_dpe_testutils_wait_for_operation_done(keymgr_dpe));
93 TRY(dif_keymgr_dpe_read_output(keymgr_dpe, key));
94 return OK_STATUS();
95}
96
97status_t keymgr_dpe_testutils_check_state(
98 const dif_keymgr_dpe_t *keymgr_dpe,
99 const dif_keymgr_dpe_state_t exp_state) {
100 dif_keymgr_dpe_state_t act_state;
101 TRY(dif_keymgr_dpe_get_state(keymgr_dpe, &act_state));
102 TRY_CHECK(act_state == exp_state,
103 "KeymgrDPE in unexpected state: %x, expected to be %x", act_state,
104 exp_state);
105 return OK_STATUS();
106}
107
108status_t keymgr_dpe_testutils_wait_for_operation_done(
109 const dif_keymgr_dpe_t *keymgr_dpe) {
111 do {
112 TRY(dif_keymgr_dpe_get_status_codes(keymgr_dpe, &status));
113 } while (status == 0);
114 TRY_CHECK(status == kDifKeymgrDpeStatusCodeIdle, "Unexpected status: %x",
115 status);
116 return OK_STATUS();
117}
118
119#elif defined(OPENTITAN_IS_EARLGREY) || defined(OPENTITAN_IS_ENGLISHBREAKFAST)
120#include "hw/top/dt/otp_ctrl.h"
126#include "sw/device/lib/testing/entropy_testutils.h"
127#include "sw/device/lib/testing/keymgr_dpe_testutils.h"
128#include "sw/device/lib/testing/kmac_testutils.h"
129#include "sw/device/lib/testing/nvm_testutils.h"
130#include "sw/device/lib/testing/otp_ctrl_testutils.h"
131#include "sw/device/lib/testing/rstmgr_testutils.h"
132#include "sw/device/lib/testing/test_framework/check.h"
134#include "sw/device/silicon_creator/lib/drivers/retention_sram.h"
135
137
138#define MODULE_ID MAKE_MODULE_ID('k', 'm', 'd')
139
140const static char *kKeymgrStageNames[] = {
141 [kDifKeymgrDpeStateReset] = "Reset",
142 [kDifKeymgrDpeStateAvailable] = "Available",
143 [kDifKeymgrDpeStateDisabled] = "Disabled",
144 [kDifKeymgrDpeStateInvalid] = "Invalid"};
145
146status_t keymgr_dpe_testutils_nvm_init(
147 const keymgr_dpe_testutils_secret_t *creator_secret,
148 const keymgr_dpe_testutils_secret_t *owner_secret) {
149 // Initialize flash secrets.
150 if (creator_secret) {
151 TRY(nvm_testutils_info_page_setup(kNvmInfoPageCreatorSecret, kPageReadWrite,
152 kPageScrambleCfg));
153 TRY(nvm_testutils_write_info_page(kNvmInfoPageCreatorSecret,
154 /*byte_offset=*/0, creator_secret->value,
155 ARRAYSIZE(creator_secret->value),
156 /*erase_before_write=*/true,
157 /*readback=*/true));
158 }
159 TRY(nvm_testutils_info_page_setup(kNvmInfoPageOwnerSecret, kPageReadWrite,
160 kPageScrambleCfg));
161 return nvm_testutils_write_info_page(kNvmInfoPageOwnerSecret,
162 /*byte_offset=*/0, owner_secret->value,
163 ARRAYSIZE(owner_secret->value),
164 /*erase_before_write=*/true,
165 /*readback=*/true);
166}
167
168static status_t check_lock_otp_partition(void) {
169 dif_otp_ctrl_t otp;
170 TRY(dif_otp_ctrl_init_from_dt(kDtOtpCtrl, &otp));
171
172 bool is_computed;
173 TRY(dif_otp_ctrl_is_digest_computed(&otp, kDifOtpCtrlPartitionSecret2,
174 &is_computed));
175 if (is_computed) {
176 uint64_t digest;
177 TRY(dif_otp_ctrl_get_digest(&otp, kDifOtpCtrlPartitionSecret2, &digest));
178 LOG_INFO("OTP partition locked. Digest: %x-%x", ((uint32_t *)&digest)[0],
179 ((uint32_t *)&digest)[1]);
180 return OK_STATUS();
181 }
182
183 return otp_ctrl_testutils_lock_partition(&otp, kDifOtpCtrlPartitionSecret2,
184 0);
185}
186
187static status_t dif_init(dif_keymgr_dpe_t *keymgr_dpe, dif_kmac_t *kmac) {
188 // Initialize KMAC in preparation for keymgr use.
189 TRY(dif_kmac_init(mmio_region_from_addr(TOP_EARLGREY_KMAC_BASE_ADDR), kmac));
190
191 // We shouldn't use the KMAC block's default entropy setting for keymgr, so
192 // configure it to use software entropy (and a sideloaded key, although it
193 // shouldn't matter here and tests should reconfigure if needed).
194 TRY(kmac_testutils_config(kmac, /*sideload=*/true));
195
196 // Initialize keymgr context.
197 TRY(dif_keymgr_dpe_init(
198 mmio_region_from_addr(TOP_EARLGREY_KEYMGR_DPE_BASE_ADDR), keymgr_dpe));
199 return OK_STATUS();
200}
201
202/**
203 * Wrapper around the erase slot call.
204 */
205status_t keymgr_dpe_testutils_erase_slot(
206 const dif_keymgr_dpe_t *keymgr_dpe,
207 const dif_keymgr_dpe_erase_params_t *params) {
208 TRY(dif_keymgr_dpe_erase_slot(keymgr_dpe, params));
209 return keymgr_dpe_testutils_wait_for_operation_done(keymgr_dpe);
210}
211
212status_t keymgr_dpe_initialize_sim_dv(dif_keymgr_dpe_t *keymgr_dpe,
213 dif_kmac_t *kmac) {
214 // Initialize keymgr and advance to CreatorRootKey state.
215 TRY(keymgr_dpe_testutils_startup(keymgr_dpe, kmac));
216 LOG_INFO("Keymgr DPE generated the CreatorRootKey in slot %d",
217 kCreatorRootKeyParams.slot_dst_sel);
218 // Generate key at CreatorRootKey (to follow same sequence and reuse
219 // chip_sw_keymgr_key_derivation_vseq.sv).
220 TRY(keymgr_dpe_testutils_generate_key(keymgr_dpe, &kKeyVersionedParams));
221 LOG_INFO("Keymgr DPE generated key at CreatorRootKey State");
222
223 // Advance to CreatorIntermediateKey state.
224 TRY(keymgr_dpe_testutils_advance_state(keymgr_dpe, &kCreatorIntKeyParams));
225 LOG_INFO("Keymgr DPE generated the CreatorIntKey in slot %d",
226 kCreatorIntKeyParams.slot_dst_sel);
227
228 // Advance to OwnerIntermediateKey state and check that the state is correct.
229 // The sim_dv testbench expects this state.
230 TRY(keymgr_dpe_testutils_advance_state(keymgr_dpe, &kOwnerIntKeyParams));
231 LOG_INFO("Keymgr DPE generated the OwnerIntKey in slot %d",
232 kOwnerIntKeyParams.slot_dst_sel);
233 return OK_STATUS();
234}
235
236status_t keymgr_dpe_initialize_sival(dif_keymgr_dpe_t *keymgr_dpe,
237 dif_kmac_t *kmac) {
238 dif_keymgr_dpe_state_t keymgr_dpe_state;
239
240 // keymgr_dpe should have loaded the Creator Key after this function
241 TRY(keymgr_dpe_testutils_try_startup(keymgr_dpe, kmac, &keymgr_dpe_state));
242
243 // Advance the Creator Key to the Creator Int Key
244 TRY(keymgr_dpe_testutils_advance_state(keymgr_dpe, &kCreatorIntKeyParams));
245
246 // Advance the Creator Int Key to the Owner Int Key
247 TRY(keymgr_dpe_testutils_advance_state(keymgr_dpe, &kOwnerIntKeyParams));
248
249 // Advance the Owner Int Key to the Owner Key
250 TRY(keymgr_dpe_testutils_advance_state(keymgr_dpe, &kOwnerKeyParams));
251
252 return keymgr_dpe_testutils_check_state(keymgr_dpe,
253 kDifKeymgrDpeStateAvailable);
254}
255
256status_t keymgr_dpe_testutils_initialize(dif_keymgr_dpe_t *keymgr_dpe,
257 dif_kmac_t *kmac) {
259 return keymgr_dpe_initialize_sival(keymgr_dpe, kmac);
260 }
261 // All other configurations use the sim_dv initialization.
262 return keymgr_dpe_initialize_sim_dv(keymgr_dpe, kmac);
263}
264
265status_t keymgr_dpe_testutils_try_startup(
266 dif_keymgr_dpe_t *keymgr_dpe, dif_kmac_t *kmac,
267 dif_keymgr_dpe_state_t *keymgr_dpe_state) {
268 TRY(dif_init(keymgr_dpe, kmac));
269
270 // Check keymgr dpe state. If initialized, there is no need to proceed with
271 // the initialization process.
272 TRY(dif_keymgr_dpe_get_state(keymgr_dpe, keymgr_dpe_state));
273
274 TRY_CHECK(*keymgr_dpe_state != kDifKeymgrDpeStateInvalid &&
275 *keymgr_dpe_state != kDifKeymgrDpeStateDisabled,
276 "Unexpected keymgr dpe state: 0x%x", *keymgr_dpe_state);
277
278 if (*keymgr_dpe_state == kDifKeymgrDpeStateReset) {
279 TRY(keymgr_dpe_testutils_startup(keymgr_dpe, kmac));
280 TRY(dif_keymgr_dpe_get_state(keymgr_dpe, keymgr_dpe_state));
281 }
282
283 return OK_STATUS();
284}
285
286status_t keymgr_dpe_testutils_init_nvm_then_reset(void) {
287 dif_rstmgr_t rstmgr;
288 dif_otp_ctrl_t otp_ctrl;
289
290 TRY(dif_rstmgr_init(mmio_region_from_addr(TOP_EARLGREY_RSTMGR_BASE_ADDR),
291 &rstmgr));
292 const dif_rstmgr_reset_info_bitfield_t reset_info =
293 rstmgr_testutils_reason_get();
294
295 // POR reset.
296 if (reset_info == kDifRstmgrResetInfoPor) {
297 LOG_INFO("Powered up for the first time, program flash");
298
299 TRY(dif_otp_ctrl_init(
300 mmio_region_from_addr(TOP_EARLGREY_OTP_CTRL_CORE_BASE_ADDR),
301 &otp_ctrl));
302
303 bool secret2_computed = false;
304 TRY(dif_otp_ctrl_is_digest_computed(&otp_ctrl, kDifOtpCtrlPartitionSecret2,
305 &secret2_computed));
306
307 // Only initialise the creator secret if `SECRET2` digest has not been
308 // computed.
309 const keymgr_dpe_testutils_secret_t *creator_secret = NULL;
310 if (!secret2_computed) {
311 creator_secret = &kCreatorSecret;
312 }
313 TRY(keymgr_dpe_testutils_nvm_init(creator_secret, &kOwnerSecret));
314
315 TRY(check_lock_otp_partition());
316
317 // Reboot device.
318 LOG_INFO(
319 "Requesting a reset to make OTP partitions accessible to keymgr DPE");
320 rstmgr_testutils_reason_clear();
321 TRY(dif_rstmgr_software_device_reset(&rstmgr));
322
323 // Wait here until device reset.
324 wait_for_interrupt();
325
326 // Should never reach this.
327 return INTERNAL();
328
329 } else {
330 // Not POR reset: this function has done its job (or can't run because it's
331 // supposed to run after POR).
332 return OK_STATUS();
333 }
334}
335
336status_t keymgr_dpe_testutils_startup(dif_keymgr_dpe_t *keymgr_dpe,
337 dif_kmac_t *kmac) {
338 dif_rstmgr_t rstmgr;
339
340 // Check the last word of the retention SRAM creator area to determine the
341 // type of the ROM.
342 bool is_using_test_rom =
343 retention_sram_get()
344 ->creator
345 .reserved[ARRAYSIZE((retention_sram_t){0}.creator.reserved) - 1] ==
347
348 // Only init NVM when run from the test_rom. Real ROM should already
349 // have loaded all necessary secrets.
350 if (is_using_test_rom) {
351 TRY(keymgr_dpe_testutils_init_nvm_then_reset());
352
353 TRY(dif_rstmgr_init(mmio_region_from_addr(TOP_EARLGREY_RSTMGR_BASE_ADDR),
354 &rstmgr));
355 const dif_rstmgr_reset_info_bitfield_t info = rstmgr_testutils_reason_get();
356
357 TRY_CHECK(info == kDifRstmgrResetInfoSw, "Unexpected reset reason: %08x",
358 info);
359 }
360
361 LOG_INFO("Initializing entropy complex in Auto mode");
362
363 TRY(entropy_testutils_auto_mode_init());
364
365 TRY(dif_init(keymgr_dpe, kmac));
366
367 // Advance to CreatorRootKey state.
368 if (is_using_test_rom) {
369 // Verify keymgr_dpe state and load UDS into predefined hw slot
370 LOG_INFO("Using test_rom, setting inputs and advancing state...");
371 TRY(keymgr_dpe_testutils_check_state(keymgr_dpe, kDifKeymgrDpeStateReset));
372 TRY(keymgr_dpe_testutils_initial_load_uds(keymgr_dpe, &kInitialParams));
373 TRY(keymgr_dpe_testutils_check_state(keymgr_dpe,
374 kDifKeymgrDpeStateAvailable));
375 // DV sync message (keymgr_dpe_key_derivation_vseq)
376 LOG_INFO("Keymgr DPE loaded the UDS and entered Available state.");
377
378 // Generate the creator root key
379 TRY(keymgr_dpe_testutils_advance_state(keymgr_dpe, &kCreatorRootKeyParams));
380 LOG_INFO("Keymgr DPE testutils derived the CreatorRootKey");
381 } else {
382 LOG_INFO("Using ROM");
383 LOG_INFO(
384 "The Keymgr DPE should already contain the derived CreatorRootKey");
385 }
386
387 // Key generation is not really necessary for all tests, but it is
388 // added to make sure each test using this function is also compatible with
389 // the DV_WAIT sequences from keymgr_key_derivation vseq
390 TRY(keymgr_dpe_testutils_generate_key(keymgr_dpe, &kKeyVersionedParams));
391 LOG_INFO("Keymgr DPE generated sw key from the CreatorRootKey");
392
393 return OK_STATUS();
394}
395
396/**
397 * Wrapper around the initial advance call. It is not possible to subsidize
398 * this call with a normal advance call as the rtl does not handle them
399 * equally. If writing to any lockable register (sw-binding, max key version,
400 * policy register) then these locks are not removed after the initial advance
401 * call completes.
402 */
403status_t keymgr_dpe_testutils_initial_load_uds(
404 const dif_keymgr_dpe_t *keymgr_dpe,
405 const dif_keymgr_dpe_advance_params_t *params) {
406 TRY(dif_keymgr_dpe_initialize(keymgr_dpe, params->slot_dst_sel));
407 return keymgr_dpe_testutils_wait_for_operation_done(keymgr_dpe);
408}
409
410status_t keymgr_dpe_testutils_advance_state(
411 const dif_keymgr_dpe_t *keymgr_dpe,
412 const dif_keymgr_dpe_advance_params_t *params) {
413 TRY(dif_keymgr_dpe_advance_state(keymgr_dpe, params));
414 return keymgr_dpe_testutils_wait_for_operation_done(keymgr_dpe);
415}
416
417status_t keymgr_dpe_testutils_check_state(
418 const dif_keymgr_dpe_t *keymgr_dpe,
419 const dif_keymgr_dpe_state_t exp_state) {
420 dif_keymgr_dpe_state_t act_state;
421 TRY(dif_keymgr_dpe_get_state(keymgr_dpe, &act_state));
422 TRY_CHECK(act_state == exp_state,
423 "Keymgr DPE in unexpected state: %x, expected to be %x", act_state,
424 exp_state);
425 return OK_STATUS();
426}
427
428status_t keymgr_dpe_testutils_check_metadata(const dif_keymgr_dpe_t *keymgr_dpe,
429 uint32_t slot,
430 uint32_t exp_max_key_version,
431 uint32_t exp_boot_stage,
432 uint32_t exp_policy) {
434 TRY(dif_keymgr_dpe_get_metadata(keymgr_dpe, slot, &metadata));
435 TRY_CHECK(metadata.valid, "Keymgr DPE slot %d is not valid", slot);
436 TRY_CHECK(metadata.max_key_version == exp_max_key_version,
437 "Keymgr DPE slot %d has unexpected max key version: %x, expected "
438 "to be %x",
439 slot, metadata.max_key_version, exp_max_key_version);
440 TRY_CHECK(
441 metadata.boot_stage == exp_boot_stage,
442 "Keymgr DPE slot %d in unexpected boot stage: %x, expected to be %x",
443 slot, metadata.boot_stage, exp_boot_stage);
444 TRY_CHECK(metadata.slot_policy == exp_policy,
445 "Keymgr DPE slot %d has unexpected policy: %x, expected to be %x",
446 slot, metadata.slot_policy, exp_policy);
447 return OK_STATUS();
448}
449
450status_t keymgr_dpe_testutils_generate_key(
451 const dif_keymgr_dpe_t *keymgr_dpe,
452 const dif_keymgr_dpe_generate_params_t *params) {
453 TRY(dif_keymgr_dpe_generate(keymgr_dpe, params));
454 return keymgr_dpe_testutils_wait_for_operation_done(keymgr_dpe);
455}
456
457status_t keymgr_dpe_testutils_disable(const dif_keymgr_dpe_t *keymgr_dpe) {
458 TRY(dif_keymgr_dpe_disable(keymgr_dpe));
459 TRY(keymgr_dpe_testutils_wait_for_operation_done(keymgr_dpe));
460 return keymgr_dpe_testutils_check_state(keymgr_dpe,
461 kDifKeymgrDpeStateDisabled);
462}
463
464status_t keymgr_dpe_testutils_wait_for_operation_done(
465 const dif_keymgr_dpe_t *keymgr_dpe) {
467 do {
468 TRY(dif_keymgr_dpe_get_status_codes(keymgr_dpe, &status));
469 } while (status == 0);
470 // If status code indicate any error (not only idle flag is set) then this
471 // try_check will fail!
472 TRY_CHECK(status == kDifKeymgrDpeStatusCodeIdle, "Unexpected status: %x",
473 status);
474 return OK_STATUS();
475}
476
477status_t keymgr_dpe_testutils_state_string_get(
478 const dif_keymgr_dpe_t *keymgr_dpe, const char **stage_name) {
480 TRY(dif_keymgr_dpe_get_state(keymgr_dpe, &state));
481
482 if (state >= ARRAYSIZE(kKeymgrStageNames)) {
483 *stage_name = NULL;
484 return INTERNAL();
485 }
486
487 *stage_name = kKeymgrStageNames[state];
488 return OK_STATUS();
489}
490
491status_t keymgr_dpe_testutils_clear_sideload_key(
492 const dif_keymgr_dpe_t *keymgr_dpe,
494 TRY(dif_keymgr_dpe_clear_sideload_key(keymgr_dpe, clear_dest));
495 return OK_STATUS();
496}
497#else
498#error "[Keymgr_dpe, testutils] None of the supported tops defined!"
499#endif