Software APIs
keymgr_dpe_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_KEYMGR_DPE_TESTUTILS_H_
6#define OPENTITAN_SW_DEVICE_LIB_TESTING_KEYMGR_DPE_TESTUTILS_H_
7
8// This #if define ... ensures backwards compatibility with darjeeling. Either
9// both tops will get their own testutils or this define guard can be
10// implemented at a more granular level (i.e. at function level).
11// TODO(#30919): Split the keymgr_dpe_testutil on a finer level.
12#if defined(OPENTITAN_IS_DARJEELING)
13
14#include "sw/device/lib/base/status.h"
16
17/**
18 * Locks OTP, restarts and initializes keymgr_dpe with UDS (a.k.a. the OTP
19 * root key).
20 *
21 * This procedure essentially gets the keymgr_dpe into the stage where it
22 * can be used for tests. An example is given below:
23 *
24 * ```c
25 * void test_main(void) {
26 * // The following sets up keymgr_dpe and asks it to latch UDS.
27 * dif_keymgr_dpe_t keymgr_dpe;
28 * keymgr_dpe_testutils_startup(&keymgr_dpe);
29 *
30 * // Remainder of test; optionally advance to CreatorRootKey state, generate
31 * // keys and identities.
32 * ...
33 * }
34 * ```
35 *
36 * @param[out] keymgr_dpe A key manager handle, may be uninitialized.
37 * @return The result of the operation.
38 */
40status_t keymgr_dpe_testutils_startup(dif_keymgr_dpe_t *keymgr_dpe,
41 uint32_t slot_dst_sel);
42
43/**
44 * Issues a keymgr_dpe advance operation and wait for it to complete.
45 *
46 * @param keymgr_dpe A key manager handle.
47 * @param params Inputs that are consumed by HW during advance operation.
48 * @return The result of the operation.
49 */
51status_t keymgr_dpe_testutils_advance_state(
52 const dif_keymgr_dpe_t *keymgr_dpe,
54
55/**
56 * Issues a keymgr_dpe key generation operation and wait for it to complete.
57 *
58 * @param keymgr_dpe A key manager handle.
59 * @param params Inputs that are consumed by HW during generate operation.
60 * @return The result of the operation.
61 */
63status_t keymgr_dpe_testutils_generate(
64 const dif_keymgr_dpe_t *keymgr_dpe,
67
68/**
69 * Erase a keymgr_dpe slot.
70 *
71 * @param keymgr_dpe A key manager handle.
72 * @param params A wrapper struct that contains the destination slot to be
73 * erased.
74 * @return The result of the operation.
75 */
77status_t keymgr_dpe_testutils_erase_slot(
78 const dif_keymgr_dpe_t *keymgr_dpe,
79 const dif_keymgr_dpe_erase_params_t *params);
80
81/**
82 * Checks if the current keymgr_dpe state matches the expected state
83 *
84 * @param keymgr_dpe A key manager handle.
85 * @param exp_state The expected key manager state.
86 * @return The result of the operation.
87 */
89status_t keymgr_dpe_testutils_check_state(
90 const dif_keymgr_dpe_t *keymgr_dpe, const dif_keymgr_dpe_state_t exp_state);
91
92/**
93 * Polling keymgr_dpe status until it becomes idle.
94 * Fail the test if the status code indicates any error.
95 *
96 * @param keymgr_dpe A key manager handle.
97 * @return The result of the operation.
98 */
100status_t keymgr_dpe_testutils_wait_for_operation_done(
101 const dif_keymgr_dpe_t *keymgr_dpe);
102
103#elif defined(OPENTITAN_IS_EARLGREY) || defined(OPENTITAN_IS_ENGLISHBREAKFAST)
104
105#include "sw/device/lib/base/status.h"
108
109// Note: In the testutil only a single key derivation chain is generated,
110// rather than two key chains (attestation and sealing keys)
111
112/**
113 * Versioned key parameters for testing.
114 *
115 * Change destination in order to sideload keys to hardware.
116 */
117static const dif_keymgr_dpe_generate_params_t kKeyVersionedParams = {
118 .key_dest = kDifKeymgrDpeKeyDestNone,
119 .sideload_key = false,
120 .salt = {0xb6521d8f, 0x13a0e876, 0x1ca1567b, 0xb4fb0fdf, 0x9f89bc56,
121 0x4bd127c7, 0x322288d8, 0xde919d54},
122 .version = 0x0,
123 .slot_src_sel = 1,
124};
125
126/**
127 * Parameter list for the initial advancement. The slot_dst_sel determines in
128 * which slot the UDS is loaded. Any other parameters are discarded.
129 */
130static const dif_keymgr_dpe_advance_params_t kInitialParams = {
131 .binding_value = {0, 0, 0, 0, 0, 0, 0, 0},
132 .max_key_version = 0,
133 .slot_src_sel = 0,
134 .slot_dst_sel = 1,
135 .slot_policy = 0};
136
137/**
138 * Parameters for advancing: UDS > creator root key
139 */
140static const dif_keymgr_dpe_advance_params_t kCreatorRootKeyParams = {
141 .binding_value = {0xdc96c23d, 0xaf36e268, 0xcb68ff71, 0xe92f76e2,
142 0xb8a8379d, 0x426dc745, 0x19f5cff7, 0x4ec9c6d6},
143 .max_key_version = 0x11,
144 .slot_src_sel = 1,
145 .slot_dst_sel = 1,
146 .slot_policy = 9 // 0b1001 Allow keygen and children, erase the parent
147};
148
149/**
150 * Parameter for advancing: creator root key > creator int key
151 */
152static const dif_keymgr_dpe_advance_params_t kCreatorIntKeyParams = {
153 .binding_value = {0x5a3c9e17, 0x8b2f41d6, 0xc70e5a93, 0x2d6b18f4,
154 0x91e47c0a, 0x3f85b26d, 0xe6d2093b, 0x47a1cf58},
155 .max_key_version = 0x55,
156 .slot_src_sel = 1,
157 .slot_dst_sel = 1,
158 .slot_policy = 9 // 0b1001 Allow keygen and children, erase the parent
159};
160
161/**
162 * Parameter for advancing: creator int key > owner int key
163 */
164static const dif_keymgr_dpe_advance_params_t kOwnerIntKeyParams = {
165 .binding_value = {0xe4987b39, 0x3f83d390, 0xc2f3bbaf, 0x3195dbfa,
166 0x23fb480c, 0xb012ae5e, 0xf1394d28, 0x1940ceeb},
167 .max_key_version = 0xaa,
168 .slot_src_sel = 1,
169 .slot_dst_sel = 1,
170 .slot_policy = 9 // 0b1001 Allow keygen and children, erase the parent
171};
172
173/**
174 * Parameter for advancing: owner int key > owner key
175 */
176static const dif_keymgr_dpe_advance_params_t kOwnerKeyParams = {
177 .binding_value = {0xd8a812ea, 0xb6ebe129, 0x217773d4, 0x35b37c77,
178 0xec8298be, 0x1f7dec77, 0x1803199e, 0xa02ad81d},
179 .max_key_version = 0xaa,
180 .slot_src_sel = 1,
181 .slot_dst_sel = 1,
182 .slot_policy = 13 // 0b1101 Allow keygen and children, retain the parent
183};
184
185/**
186 * Struct to hold the creator or owner secrets for the key manager dpe.
187 */
188typedef struct keymgr_dpe_testutils_secret {
189 uint32_t value[8];
190} keymgr_dpe_testutils_secret_t;
191
192/**
193 * Key manager dpe Creator Secret (seed) stored in info flash page.
194 */
195static const keymgr_dpe_testutils_secret_t kCreatorSecret = {
196 .value = {0x4e919d54, 0x322288d8, 0x4bd127c7, 0x9f89bc56, 0xb4fb0fdf,
197 0x1ca1567b, 0x13a0e876, 0xa6521d8f}};
198
199/**
200 * Key manager dpe Owner Secret (seed) stored in info flash page.
201 */
202static const keymgr_dpe_testutils_secret_t kOwnerSecret = {
203 .value = {0xa6521d8f, 0x13a0e876, 0x1ca1567b, 0xb4fb0fdf, 0x9f89bc56,
204 0x4bd127c7, 0x322288d8, 0x4e919d54}};
205
206/**
207 * Programs nvm with secrets so that the keymgr dpe can be advanced to
208 * CreatorRootKey state.
209 *
210 * This is normally a subfunction of keymgr_testutils_startup, but some tests
211 * use the function separately as well.
212 *
213 * @param creator_secret The creator secret to be programmed to flash, or NULL
214 * to skip writing the creator secret.
215 * @param owner_secret The owner secret to be programmed to flash.
216 *
217 */
219status_t keymgr_dpe_testutils_nvm_init(
220 const keymgr_dpe_testutils_secret_t *creator_secret,
221 const keymgr_dpe_testutils_secret_t *owner_secret);
222
223/**
224 * Initializes the key manager dpe and its dependencies for testing.
225 *
226 * This function initializes the key manager dpe and its dependencies for
227 * testing.
228 *
229 * This function will call `keymgr_dpe_testutils_try_startup()` if the boot
230 * stage is `kBootStageOwner`; otherwise, it will call
231 * `keymgr_testutils_startup()`. Additional checks are performed to ensure that
232 * the key manager is in a valid state, and ready to perform key derivations.
233 *
234 * @param keymgr_dpe A key manager dpe handle, may be uninitialized.
235 * @param kmac A KMAC handle, may be uninitialized.
236 * @return The result of the operation.
237 */
239status_t keymgr_dpe_testutils_initialize(dif_keymgr_dpe_t *keymgr_dpe,
240 dif_kmac_t *kmac);
241
242/**
243 * Wrapper function to `keymgr_testutils_startup()`.
244 *
245 * This function checks the state of the key manager before attempting to
246 * initialize its dependencies and state.
247 *
248 * The function will return an error if the keymgr is disabled or in invalid
249 * state.
250 *
251 * @param keymgr_dpe A key manager dpe handle, may be uninitialized.
252 * @param kmac A KMAC handle, may be uninitialized.
253 * @param[out] keymgr_dpe_state The state of the keymgr dpe after startup.
254 */
256status_t keymgr_dpe_testutils_try_startup(
257 dif_keymgr_dpe_t *keymgr_dpe, dif_kmac_t *kmac,
258 dif_keymgr_dpe_state_t *keymgr_dpe_state);
259
260/**
261 * Initialize non-volatile memory (flash and OTP) for keymgr dpe and then
262 * reset, so that the relevant OTP partitions become accessible to keymgr dpe.
263 * After calling this function, keymgr dpe can be initialized.
264 */
266status_t keymgr_dpe_testutils_init_nvm_then_reset(void);
267
268/**
269 * Programs flash, restarts, and advances keymgr to Available state.
270 * Afterwards the CreatorRootKey is generated in the slot defined by
271 * kCreatorRootKeyParams. Note that this function assumes that the keymgr dpe
272 * is in the initial reset state after ROM execution.
273 *
274 * This procedure essentially gets the keymgr into the first state where it can
275 * be used for tests. Tests should call it before anything else, like below:
276 *
277 * ```c
278 * void test_main(void) {
279 * // Set up and generate the CreatorRootKey.
280 * dif_keymgr_dpe_t keymgr_dpe;
281 * dif_kmac_t kmac;
282 * keymgr_dpe_testutils_startup(&keymgr_dpe, &kmac);
283 *
284 * // Remainder of test; optionally advance the CreatorRootKey to the
285 * // CreatorIntKey, generate keys and identities.
286 * ...
287 * }
288 * ```
289 *
290 * Because the key manager dpe uses KMAC, this procedure also initializes and
291 * configures KMAC. Software should not rely on the configuration here and
292 * should reconfigure KMAC if needed. The purpose of configuring KMAC in this
293 * procedure is so that the key manager dpe will not use KMAC with the default
294 * entropy settings.
295 *
296 * @param keymgr_dpe A key manager dpe handle, may be uninitialized.
297 * @param kmac A KMAC handle, may be uninitialized.
298 */
300status_t keymgr_dpe_testutils_startup(dif_keymgr_dpe_t *keymgr_dpe,
301 dif_kmac_t *kmac);
302
303/**
304 * Advances the DPE context of the keymgr_dpe and wait for it to complete
305 *
306 * @param keymgr_dpe A key manager dpe handle.
307 * @param params The binding and max key version value for the next state.
308 */
310status_t keymgr_dpe_testutils_advance_state(
311 const dif_keymgr_dpe_t *keymgr_dpe,
312 const dif_keymgr_dpe_advance_params_t *params);
313
314/**
315 * Loads the UDS into the keymgr dpe and move the state from `Reset`
316 * to `Available`.
317 *
318 * The first advance call is automatically mapped to latch the UDS into the
319 * designated destination slot rather than advancing any DPE context.
320 * Therefore most registers used in the regular advance call are ignored
321 * during initialization.
322 *
323 * @param keymgr_dpe A key manager dpe handle.
324 * @param params The .slot_dst_sel subfield determines the slot for the UDS
325 */
327status_t keymgr_dpe_testutils_initial_load_uds(
328 const dif_keymgr_dpe_t *keymgr_dpe,
329 const dif_keymgr_dpe_advance_params_t *params);
330
331/**
332 * Checks if the current keymgr dpe state matches the expected state
333 *
334 * @param keymgr_dpe A key manager dpe handle.
335 * @param exp_state The expected key manager state.
336 */
338status_t keymgr_dpe_testutils_check_state(
339 const dif_keymgr_dpe_t *keymgr_dpe, const dif_keymgr_dpe_state_t exp_state);
340
341/**
342 * Checks that a keymgr dpe HW slot holds a valid DPE context with the expected
343 * maximum key version, boot stage and slot policy.
344 *
345 * @param keymgr_dpe A key manager dpe handle.
346 * @param slot The HW slot to check.
347 * @param exp_max_key_version The expected maximum key version for the DPE
348 * context in `slot`.
349 * @param exp_boot_stage The expected boot stage for the DPE context in
350 * `slot`.
351 * @param exp_policy The expected policy bits for the DPE context in `slot`,
352 * using the same bit layout as the `SLOT_POLICY` register.
353 */
355status_t keymgr_dpe_testutils_check_metadata(const dif_keymgr_dpe_t *keymgr_dpe,
356 uint32_t slot,
357 uint32_t exp_max_key_version,
358 uint32_t exp_boot_stage,
359 uint32_t exp_policy);
360
361/**
362 * Issues a keymgr dpe HW/SW versioned key generation and wait for it
363 * to complete.
364 *
365 * @param keymgr_dpe A key manager dpe handle.
366 * @param params Key generation parameters.
367 */
369status_t keymgr_dpe_testutils_generate_key(
370 const dif_keymgr_dpe_t *keymgr_dpe,
372
373/**
374 * Erase a keymgr_dpe slot.
375 *
376 * @param keymgr_dpe A key manager handle.
377 * @param params A wrapper struct that contains the destination slot to be
378 * erased.
379 * @return The result of the operation.
380 */
382status_t keymgr_dpe_testutils_erase_slot(
383 const dif_keymgr_dpe_t *keymgr_dpe,
384 const dif_keymgr_dpe_erase_params_t *params);
385
386/**
387 * Issues a keymgr dpe disable and wait for it to complete
388 */
390status_t keymgr_dpe_testutils_disable(const dif_keymgr_dpe_t *keymgr_dpe);
391
392/**
393 * Polling keymgr dpe status until it becomes idle.
394 * Fail the test if the status code indicates any error.
395 *
396 * @param keymgr_dpe A key manager dpe handle.
397 */
399status_t keymgr_dpe_testutils_wait_for_operation_done(
400 const dif_keymgr_dpe_t *keymgr_dpe);
401
402/**
403 * Get the current state of the key manager dpe.
404 *
405 * @param keymgr_dpe A key manager dpe handle.
406 * @param[out] state The current state of the key manager dpe in
407 * C string format.
408 *
409 * @return The result of the operation.
410 */
412status_t keymgr_dpe_testutils_state_string_get(
413 const dif_keymgr_dpe_t *keymgr_dpe, const char **stage_name);
414
415/**
416 * Clears the key from one sideload slot
417 *
418 * @param keymgr_dpe A key manager dpe handle.
419 * @param clear_dest Destination for the clear operation
420 *
421 * @return The result of the operation.
422 */
424status_t keymgr_dpe_testutils_clear_sideload_key(
425 const dif_keymgr_dpe_t *keymgr_dpe,
427
428#else
429#error "[Keymgr_dpe, testutils] None of the supported tops defined!"
430#endif
431
432#endif // OPENTITAN_SW_DEVICE_LIB_TESTING_KEYMGR_DPE_TESTUTILS_H_