Software APIs
dif_keymgr_dpe.h
Go to the documentation of this file.
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_DIF_DIF_KEYMGR_DPE_H_
6#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_KEYMGR_DPE_H_
7
8/**
9 * @file
10 * @brief <a href="/hw/ip/keymgr_dpe/doc/">Key Manager DPE</a> Device Interface
11 * Functions
12 */
13
14#include <stdint.h>
15
19
21
22#ifdef __cplusplus
23extern "C" {
24#endif // __cplusplus
25
26/**
27 * SW-visible key manager DPE states.
28 *
29 * Key manager RTL has more than 4 finite state machine (FSM) states, but it
30 * simply truncates the reported state into four states given below. The reason
31 * behind this truncation is that FSM lingers on some states temporarily (i.e.
32 * few clock cycles) and the transition into the next state does not require
33 * further invocation.
34 *
35 * From SW point of view, key manager FSM transitions follow a sequence
36 * sequential manner and these transitions are irreversible until a power cycle.
37 */
39 kDifKeymgrDpeStateReset = 0,
40 kDifKeymgrDpeStateAvailable = 1,
41 kDifKeymgrDpeStateDisabled = 2,
42 kDifKeymgrDpeStateInvalid = 3
44
45/**
46 * Input parameters for advancing a DPE context/slot.
47 */
49 /**
50 * This value is used by key manager as input to DICE computation and can be
51 * either a value that represents the measurement of a boot stage or simply a
52 * tag from a manifest.
53 */
54 uint32_t binding_value[8];
55
56 /**
57 * Maximum allowed version for keys to be generated at a state. This value is
58 * stored inside keymgr slot so that it can later be compared against the
59 * `key_version` input provided along with generation request.
60 */
62
63 /**
64 * The source slot to be used as parent DPE context.
65 */
66 uint32_t slot_src_sel;
67
68 /**
69 * The destination slot which recieves the derived child DPE context.
70 */
71 uint32_t slot_dst_sel;
72
73 /**
74 * The slot policy bits for the derived child DPE context.
75 */
76 uint32_t slot_policy;
78
79/**
80 * Key destination of a versioned key generation operation.
81 *
82 * Regardless of whether the generated key is SW or sideload key, HW uses a
83 * unique diversification constant for each cryptographic use case. In the case
84 * of sideload key, this enum value is also used to determine the target
85 * peripheral port to which the generated key is loaded.
86 */
88 /**
89 * Diversify the generated key for no HW IP (and don't sideload it).
90 */
92 /**
93 * Diversify the generated key for AES (and load it to AES peripheral port if
94 * sideload key).
95 */
97 /**
98 * Diversify the generated key for KMAC (and load it to KMAC peripheral port
99 * if sideload key).
100 */
102 /**
103 * Diversify the generated key for OTBN (and load it to OTBN peripheral port
104 * if sideload key).
105 */
108
109/**
110 * Input parameters for advancing a DPE context/slot.
111 */
113 /**
114 * Destination for {AES, KMAC, OTBN}, which is used for diversification.
115 */
117
118 /**
119 * Set to true, if this is a sideload key, otherwise set to false.
120 */
122
123 /**
124 * Salt value used as input for key generation (i.e. becomes part of the
125 * message payload sent to KMAC during computation).
126 */
127 uint32_t salt[8];
128
129 /**
130 * The key version used for generating versioned key. This value should not be
131 * greater than the `max_key_version` value stored inside the source slot that
132 * is used to generate the key.
133 */
134 uint32_t version;
135
136 /**
137 * The source slot from which the key is derived.
138 */
139 uint32_t slot_src_sel;
141
142/**
143 * Input parameters for erasing a DPE context/slot.
144 */
146 /**
147 * Index for the slot to be erased.
148 */
149 uint32_t slot_dst_sel;
151
152/**
153 * Useed to represent the output of SW generated key.
154 */
155typedef struct dif_keymgr_dpe_output {
156 uint32_t value[2][8];
158
159/**
160 * Status code bit flags.
161 *
162 * See also: `dif_keymgr_dpe_status_codes_t`.
163 */
165 /**
166 * Key manager is idle.
167 */
169 /**
170 * Software invoked an invalid operation.
171 */
173 /**
174 * Key manager issued invalid data to KMAC interface.
175 */
177 /**
178 * Key manager encountered invalid state.
179 */
181
183
184/**
185 * Define mask for error fields of `dif_keymgr_dpe_status_code_t`.
186 */
187static const bitfield_field32_t kIdleBitfield = (bitfield_field32_t){
188 .mask = 0x1,
189 .index = 0,
190};
191
192/**
193 * Define mask for idle field of `dif_keymgr_dpe_status_code_t`.
194 */
195static const bitfield_field32_t kErrorBitfield = (bitfield_field32_t){
196 .mask = 0x7,
197 .index = 1,
198};
199
200/**
201 * A bit vector of status codes.
202 *
203 * The following snippet can be used to check if key manager is idle:
204 *
205 * `bool is_idle = (status_codes & kDifKeymgrDpeStatusCodeIdle);`
206 *
207 * The following snippet can be used to check if key manager is idle and
208 * error-free:
209 *
210 * `bool is_idle_and_ok = (status_codes == kDifKeymgrDpeStatusCodeIdle);`
211 *
212 * See also: `dif_keymgr_dpe_status_code_t`.
213 */
215
216/**
217 * Initializes the keymgr_pde block by performing an advance operation.
218 *
219 * The hardware does not have an explicit initialize command. Initialization is
220 * simple the first advance call without software binding, max version or
221 * policy registers set. Use this call before calling
222 * `dif_keymgr_dpe_advance_state()`.
223 *
224 * @param keymgr_dpe A key manager handle.
225 * @param slot_dst_sel Target slot used to latch the UDS key.
226 * @return The result of the operation.
227 */
229 uint32_t slot_dst_sel);
230
231/**
232 * Advances a keymgr_dpe slot with given parameters.
233 *
234 * @param keymgr_dpe A key manager handle.
235 * @param params Struct to pass inputs consumed by HW during advance.
236 * @return The result of the operation.
237 */
240 const dif_keymgr_dpe_t *keymgr_dpe,
241 const dif_keymgr_dpe_advance_params_t *params);
242
243/**
244 * Erases a given keymgr_dpe slot.
245 *
246 * @param keymgr_dpe A key manager handle.
247 * @param params A struct that selects the slot to be erased.
248 * @return The result of the operation.
249 */
252 const dif_keymgr_dpe_t *keymgr_dpe,
253 const dif_keymgr_dpe_erase_params_t *params);
254
255/**
256 * Generate a SW/HW key from a chosen keymgr_dpe slot.
257 *
258 * @param keymgr_dpe A key manager handle.
259 * @param params Struct to pass inputs consumed by HW generate operation.
260 * @return The result of the operation.
261 */
264 const dif_keymgr_dpe_t *keymgr_dpe,
266
267/**
268 * Gets the operational status of keymgr_dpe.
269 *
270 * This function also clears OP_STATUS and ERR_CODE registers after reading
271 * them.
272 *
273 * @param keymgr_dpe A key manager handle.
274 * @param[out] status_codes Out-param for key manager status codes.
275 * @return The result of the operation.
276 */
279 const dif_keymgr_dpe_t *keymgr_dpe,
280 dif_keymgr_dpe_status_codes_t *status_codes);
281
282/**
283 * Gets the current state of key manager.
284 *
285 * @param keymgr_dpe A key manager handle.
286 * @param[out] state Out-param for current key manager state.
287 * @return The result of the operation.
288 */
291 uint32_t *state);
292
293/**
294 * Read the value of SW generated key from its related CSR. It is the
295 * responsibility of the caller to check that key generation has completed.
296 *
297 * @param keymgr_dpe A key manager handle.
298 * @param[out] output The key value in two shares.
299 * @return The result of the operation.
300 */
304
305#ifdef __cplusplus
306} // extern "C"
307#endif // __cplusplus
308
309#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_KEYMGR_DPE_H_