Software APIs
keymgr_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_TESTUTILS_H_
6#define OPENTITAN_SW_DEVICE_LIB_TESTING_KEYMGR_TESTUTILS_H_
7
8#include "sw/device/lib/base/status.h"
12
13/**
14 * Versioned key parameters for testing.
15 *
16 * Change destination in order to sideload keys to hardware.
17 */
18static const dif_keymgr_versioned_key_params_t kKeyVersionedParams = {
20 .salt =
21 {
22 0xb6521d8f,
23 0x13a0e876,
24 0x1ca1567b,
25 0xb4fb0fdf,
26 0x9f89bc56,
27 0x4bd127c7,
28 0x322288d8,
29 0xde919d54,
30 },
31 .version = 0x11,
32};
33
34/**
35 * Software binding value for advancing to creator root key state.
36 */
37static const dif_keymgr_state_params_t kCreatorParams = {
38 .binding_value = {0xdc96c23d, 0xaf36e268, 0xcb68ff71, 0xe92f76e2,
39 0xb8a8379d, 0x426dc745, 0x19f5cff7, 0x4ec9c6d6},
40 .max_key_version = 0x11,
41};
42
43/**
44 * Software binding value for advancing to owner intermediate key state.
45 */
46static const dif_keymgr_state_params_t kOwnerIntParams = {
47 .binding_value = {0xe4987b39, 0x3f83d390, 0xc2f3bbaf, 0x3195dbfa,
48 0x23fb480c, 0xb012ae5e, 0xf1394d28, 0x1940ceeb},
49 .max_key_version = 0xaa,
50};
51
52/**
53 * Software binding value for advancing to owner root key state.
54 *
55 * Values were randomly generated.
56 */
57static const dif_keymgr_state_params_t kOwnerRootKeyParams = {
58 .binding_value =
59 {
60 0xd8a812ea,
61 0xb6ebe129,
62 0x217773d4,
63 0x35b37c77,
64 0xec8298be,
65 0x1f7dec77,
66 0x1803199e,
67 0xa02ad81d,
68 },
69 .max_key_version = 0xaa,
70};
71
72/**
73 * Struct to hold the creator or owner secrets for the key manager.
74 */
76 uint32_t value[8];
77} keymgr_testutils_secret_t;
78
79/**
80 * Key manager Creator Secret stored in info flash page.
81 */
82static const keymgr_testutils_secret_t kCreatorSecret = {
83 .value = {0x4e919d54, 0x322288d8, 0x4bd127c7, 0x9f89bc56, 0xb4fb0fdf,
84 0x1ca1567b, 0x13a0e876, 0xa6521d8f}};
85
86/**
87 * Key manager Owner Secret stored in info flash page.
88 */
89static const keymgr_testutils_secret_t kOwnerSecret = {.value = {
90 0xa6521d8f,
91 0x13a0e876,
92 0x1ca1567b,
93 0xb4fb0fdf,
94 0x9f89bc56,
95 0x4bd127c7,
96 0x322288d8,
97 0x4e919d54,
98 }};
99
100/**
101 * Programs flash with secrets so that the keymgr can be advanced to
102 * CreatorRootKey state.
103 *
104 * This is normally a subfunction of keymgr_testutils_startup, but some tests
105 * use the function separately as well.
106 *
107 * @param flash An initialized flash_ctrl handle.
108 * @param creator_secret The creator secret to be programmed to flash.
109 * @param owner_secret The owner secret to be programmed to flash.
110 *
111 */
113status_t keymgr_testutils_flash_init(
115 const keymgr_testutils_secret_t *creator_secret,
116 const keymgr_testutils_secret_t *owner_secret);
117
118/**
119 * Initializes the key manager and its dependencies for testing.
120 *
121 * This function initializes the key manager and its dependencies for testing.
122 *
123 * This fuction will call `keymgr_testutils_try_startup()` if the boot stage is
124 * `kBootStageOwner`; otherwise, it will call `keymgr_testutils_startup()`.
125 * Additional checks are performed to ensure that the key manager is in a valid
126 * state, and ready to perform key derivations.
127 *
128 * @param keymgr A key manager handle, may be uninitialized.
129 * @param kmac A KMAC handle, may be uninitialized.
130 * @return The result of the operation.
131 */
133status_t keymgr_testutils_initialize(dif_keymgr_t *keymgr, dif_kmac_t *kmac);
134
135/**
136 * Wrapper function to `keymgr_testutils_startup()`.
137 *
138 * This function checks the state of the key manager before attempting to
139 * initialize its dependencies and state.
140 *
141 * The function will return an error if the keymgr is disabled or in invalid
142 * state.
143 *
144 * @param keymgr A key manager handle, may be uninitialized.
145 * @param kmac A KMAC handle, may be uninitialized.
146 * @param[out] keymgr_state The state of the keymgr after startup.
147 */
149status_t keymgr_testutils_try_startup(dif_keymgr_t *keymgr, dif_kmac_t *kmac,
150 dif_keymgr_state_t *keymgr_state);
151
152/**
153 * Initialize non-volatile memory (flash and OTP) for keymgr and then reset, so
154 * that the relevant OTP partitions become accessible to keymgr. After calling
155 * this function, keymgr can be initialized.
156 */
158status_t keymgr_testutils_init_nvm_then_reset(void);
159
160/**
161 * Programs flash, restarts, and advances keymgr to CreatorRootKey state. Note
162 * that this function assumes that the key manager is in the initial reset state
163 * after ROM execution.
164 *
165 * This procedure essentially gets the keymgr into the first state where it can
166 * be used for tests. Tests should call it before anything else, like below:
167 *
168 * void test_main(void) {
169 * // Set up and advance to CreatorRootKey state.
170 * dif_keymgr_t keymgr;
171 * dif_kmac_t kmac;
172 * keymgr_testutils_startup(&keymgr, &kmac);
173 *
174 * // Remainder of test; optionally advance to OwnerIntKey state, generate
175 * // keys and identities.
176 * ...
177 * }
178 *
179 * Because the key manager uses KMAC, this procedure also initializes and
180 * configures KMAC. Software should not rely on the configuration here and
181 * should reconfigure KMAC if needed. The purpose of configuring KMAC in this
182 * procedure is so that the key manager will not use KMAC with the default
183 * entropy settings.
184 *
185 * @param keymgr A key manager handle, may be uninitialized.
186 * @param kmac A KMAC handle, may be uninitialized.
187 */
189status_t keymgr_testutils_startup(dif_keymgr_t *keymgr, dif_kmac_t *kmac);
190
191/**
192 * Issues a keymgr advance operation and wait for it to complete
193 *
194 * @param keymgr A key manager handle.
195 * @param params The binding and max key version value for the next state.
196 */
198status_t keymgr_testutils_advance_state(
199 const dif_keymgr_t *keymgr, const dif_keymgr_state_params_t *params);
200
201/**
202 * Checks if the current keymgr state matches the expected state
203 *
204 * @param keymgr A key manager handle.
205 * @param exp_state The expected key manager state.
206 */
208status_t keymgr_testutils_check_state(const dif_keymgr_t *keymgr,
209 const dif_keymgr_state_t exp_state);
210
211/**
212 * Issues a keymgr identity generation and wait for it to complete
213 *
214 * @param keymgr A key manager handle.
215 */
217status_t keymgr_testutils_generate_identity(
218 const dif_keymgr_t *keymgr, const dif_keymgr_identity_seed_params_t params);
219
220/**
221 * Issues a keymgr HW/SW versioned key generation and wait for it to complete
222 *
223 * @param keymgr A key manager handle.
224 * @param params Key generation parameters.
225 */
227status_t keymgr_testutils_generate_versioned_key(
228 const dif_keymgr_t *keymgr, const dif_keymgr_versioned_key_params_t params);
229
230/**
231 * Issues a keymgr disable and wait for it to complete
232 */
234status_t keymgr_testutils_disable(const dif_keymgr_t *keymgr);
235
236/**
237 * Polling keymgr status until it becomes idle.
238 * Fail the test if the status code indicates any error.
239 *
240 * @param keymgr A key manager handle.
241 */
243status_t keymgr_testutils_wait_for_operation_done(const dif_keymgr_t *keymgr);
244
245/**
246 * Get the maximum key version supported by the key manager.
247 *
248 * @param keymgr A key manager handle.
249 * @param[out] max_key_version The maximum key version supported by the key
250 * manager for its current operating state.
251 * @return The result of the operation.
252 */
254status_t keymgr_testutils_max_key_version_get(const dif_keymgr_t *keymgr,
255 uint32_t *max_key_version);
256
257/**
258 * Get the current state of the key manager.
259 *
260 * @param keymgr A key manager handle.
261 * @param[out] state The current state of the key manager in C string format.
262 *
263 * @return The result of the operation.
264 */
266status_t keymgr_testutils_state_string_get(const dif_keymgr_t *keymgr,
267 const char **stage_name);
268
269#endif // OPENTITAN_SW_DEVICE_LIB_TESTING_KEYMGR_TESTUTILS_H_