Software APIs
dif_csrng.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_CSRNG_H_
6#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_CSRNG_H_
7
8/**
9 * @file
10 * @brief <a href="/book/hw/ip/csrng/">CSRNG</a> Device Interface Functions
11 */
12
13#include <stdint.h>
14
18
19#include "hw/top/csrng_regs.h" // Generated
20#include "sw/device/lib/dif/autogen/dif_csrng_autogen.h"
21
22#ifdef __cplusplus
23extern "C" {
24#endif // __cplusplus
25
26/**
27 * This API implements an interface for the CSRNG hardware.
28 *
29 * The API follows the naming conventions used in NIST SP 800-90Ar1:
30 *
31 * - Instantiate.
32 * - Update
33 * - Reseed
34 * - Generate
35 * - Uninstantiate
36 *
37 * The seed used for instantiation can either be provided directly in
38 * hardware by an entropy source module; or directly by software. See
39 * `dif_csrng_instantiate()` and `dif_csrng_entropy_src` for
40 * more details.
41 *
42 * The following sequence of operations are required to initialize
43 * and generate cryptographic entropy from the CSRNG module:
44 *
45 * - `dif_csrng_init()`
46 * - `dif_csrng_configure()`
47 * - `dif_csrng_instantiate()`
48 * - `dif_csrng_generate_start()`
49 * - `dif_csrng_uninstantiate()`
50 *
51 * The following functions can be used for reseed and update operations:
52 *
53 * - `dif_csrng_reseed()`
54 * - `dif_csrng_update()`
55 *
56 * The following utility functions are available to poll the state of
57 * the hardware:
58 *
59 * - `dif_csrng_get_cmd_interface_status()`
60 * - `dif_csrng_get_output_status()`
61 *
62 * Please see the following documentation for more information:
63 * https://opentitan.org/book/hw/ip/csrng/
64 *
65 * Remaining work:
66 *
67 * - Add error status interface.
68 * - Add internal state control and debug interface.
69 */
70
71/**
72 * Enumeration of CSRNG command interface states.
73 */
75 /**
76 * The command interface is ready to accept commands.
77 */
79 /**
80 * The command interface is processing a command.
81 */
83 /**
84 * The command interface completed with an error.
85 */
88
89/**
90 * Enumeration of CSRNG FIFOs, which indicates which part of the hardware
91 * produced an error.
92 */
93typedef enum dif_csrng_fifo {
94 kDifCsrngFifoCmd,
95 kDifCsrngFifoGenBits,
96 kDifCsrngFifoFinal,
97 kDifCsrngFifoGBencAck,
98 kDifCsrngFifoGrcStage,
99 kDifCsrngFifoGGenReq,
100 kDifCsrngFifoGadStage,
101 kDifCsrngFifoCmdId,
103
104/**
105 * Enumeration of CSRNG FIFO errors.
106 */
107typedef enum dif_csrng_error {
108 /**
109 * Indicates an error in the command stage state machine.
110 */
112 /**
113 * Indicates an error in the main state machine.
114 */
116 /**
117 * Indicates an error in the DRBG's command unit state machine.
118 */
120 /**
121 * Indicates an error in the DRBG's generator state machine.
122 */
124 /**
125 * Indicates an error in the DRBG's block encoding state machine.
126 */
128 /**
129 * Indicates an error in the DRBG's block output state machine.
130 */
132 /**
133 * Indicates an error in the AES state machine.
134 */
136 /**
137 * Indicates an error in the generate command's counter.
138 */
140 /**
141 * Indicates a write to a full FIFO occurred.
142 */
144 /**
145 * Indicates a read from an empty FIFO occurred.
146 */
148 /**
149 * Indicates a FIFO was somehow both full and empty.
150 */
153
154/**
155 * Enumeration of CSRNG command status errors.
156 */
158 /**
159 * Indicates that the command completed successfully.
160 */
162 /**
163 * Indicates that an invalid apllication command has been issued.
164 */
166 /**
167 * Indicates that the state wasn't zeroized properly after an uninstantiate
168 * command due to invalid state parameters in the cmd drbg.
169 */
171 /**
172 * Indicates that CSRNG entropy was generated for a command that is not a
173 * generate command.
174 */
176 /**
177 * Indicates that last command was not issued in sequence.
178 * E.g. an instantiate on an instantiated state or any command other than an
179 * instantiate on an uninstantiated state.
180 */
183
184/**
185 * The status of the CSRNG block at a particular moment in time.
186 */
187typedef struct dif_csrng_cmd_status {
188 /**
189 * The kind of status the CSRNG is in.
190 */
192 /**
193 * The status value CSRNG returns.
194 */
197
198/**
199 * CSRNG consume seed from entropy source enable.
200 */
202 /**
203 * Seed material used as the only seed material.
204 *
205 * This configuration option will toggle the hardware state of the
206 * CSRNG to non-FIPS compliant until it is re-instantiated.
207 *
208 * Note: Software may opt to XOR the seed material with a seed to implement
209 * a software assisted FIPS mode of operation.
210 */
212 /**
213 * Entropy source XOR'ed with the provided seed material.
214 */
217
218enum {
219 /**
220 * Maximum seed material number of uint32_t words supported in CSRNG
221 * instantiate and seed commands.
222 */
224};
225
226/**
227 * CSRNG common transaction parameters.
228 */
230 /**
231 * Number of uint32_t words in `seed_material`. Up to 12 words can be
232 * set to initialize the CSRNG. CSRNG will extend the `seed_material`
233 * to zeros if the provided value is less that 12.
234 */
236 /**
237 * Seed material used in CSRNG
238 */
241
242/**
243 * Generated output state.
244 */
246 /**
247 * Set to true when there is cryptographic entropy data available to
248 * read using `dif_csrng_generate_read()`.
249 */
251 /**
252 * Set to true when the cryptographic entropy data available to read
253 * is FIPS/CC compliant at the hardware level.
254 */
257
258/**
259 * CSRNG internal state selector ID.
260 */
262 /**
263 * CSRNG instance assigned to Entropy Distribution Network (EDN) 0.
264 */
266 /**
267 * CSRNG instance assigned to Entropy Distribution Network (EDN) 1.
268 */
270 /**
271 * CSRNG instance assigned to software interface.
272 */
275
276/**
277 * CSRNG internal state.
278 */
280 /**
281 * Indicates the number of requests for pseudorandom bits since instantiation
282 * or reseeding.
283 */
285 /**
286 * Internal V working state with a 128bit block size.
287 */
288 uint32_t v[4];
289 /**
290 * Internal key used to configure the internal CSRNG cipher.
291 */
292 uint32_t key[8];
293 /**
294 * Set to true when the CSRNG instance has been instantiated.
295 */
297 /**
298 * Set to true when FIPS compliant entropy was provided directly by the
299 * entropy source to instantiate or reseed the CSRNG instance.
300 */
303
304/**
305 * Recoverable alerts emitted by the CSRNG.
306 */
308 /**
309 * Indicates a bad value was written to the ENABLE field of the control
310 * register.
311 */
313 1U << CSRNG_RECOV_ALERT_STS_ENABLE_FIELD_ALERT_BIT,
314 /**
315 * Indicates a bad value was written to the SW_APP_ENABLE field of the control
316 * register.
317 */
319 1U << CSRNG_RECOV_ALERT_STS_SW_APP_ENABLE_FIELD_ALERT_BIT,
320 /**
321 * Indicates a bad value was written to the READ_INT_STATE field of the
322 * control register.
323 */
325 1U << CSRNG_RECOV_ALERT_STS_READ_INT_STATE_FIELD_ALERT_BIT,
326 /**
327 * Indicates the FLAG0 field in the Application Command is set to a value
328 * other than kMultiBitBool4True or kMultiBitBool4False.
329 */
331 1U << CSRNG_RECOV_ALERT_STS_ACMD_FLAG0_FIELD_ALERT_BIT,
332 /**
333 * Indicates the genbits bus saw two identical values, indicating a possible
334 * attack.
335 */
337 1U << CSRNG_RECOV_ALERT_STS_CS_BUS_CMP_ALERT_BIT,
338 /**
339 * Indicates an unsupported CSRNG command was issued.
340 */
342 1U << CSRNG_RECOV_ALERT_STS_CMD_STAGE_INVALID_ACMD_ALERT_BIT,
343 /**
344 * Indicates a supported CSRNG command was issued out of sequence.
345 */
347 1U << CSRNG_RECOV_ALERT_STS_CMD_STAGE_INVALID_CMD_SEQ_ALERT_BIT,
348 /**
349 * Indicates that too many generate commands were issued in a row.
350 */
352 1U << CSRNG_RECOV_ALERT_STS_CMD_STAGE_RESEED_CNT_ALERT_BIT,
354
355/**
356 * Configures CSRNG.
357 *
358 * This function should need to be called once for the lifetime of `csrng`.
359 *
360 * @param csrng A CSRNG handle.
361 * @return The result of the operation.
362 */
365
366/**
367 * Initializes CSRNG instance with a new seed value.
368 *
369 * `seed_material` is used as specified in NIST SP 800-90Ar1 section
370 * 10.2.1.3.1. See `dif_csrng_entropy_src` for details on how this value
371 * is mixed with the CSRNG seed.
372 *
373 * `seed_material` can be NULL, in which case CSRNG will use a zero
374 * vector instead.
375 *
376 * @param csrng A CSRNG handle.
377 * @param entropy_src_enable Entropy source input enable.
378 * @param seed_material Seed initialization parameters.
379 * @return The result of the operation.
380 */
383 const dif_csrng_t *csrng, dif_csrng_entropy_src_toggle_t entropy_src_enable,
384 const dif_csrng_seed_material_t *seed_material);
385
386/**
387 * Reseeds CSRNG instance.
388 *
389 * When `seed_material.seed_material_len` is set to 0, only the entropy source
390 * seed is used to reseed the instance, otherwise it will be XOR'ed with the
391 * entropy source.
392 *
393 * @param csrng A CSRNG handle.
394 * @param seed_material Reseed parameters.
395 * @return The result of the operation.
396 */
399 const dif_csrng_seed_material_t *seed_material);
400
401/**
402 * Updates CSRNG state.
403 *
404 * This function is similar to `dif_csrng_reseed()`, except:
405 *
406 * - Only `seed_material.seed_material` is used in the update operation.
407 * - The update operation does not reset the internal CSRNG reseed
408 * counter.
409 *
410 * @param csrng A CSRNG handle.
411 * @param seed_material Update parameters.
412 * @return The result of the operation.
413 */
416 const dif_csrng_seed_material_t *seed_material);
417
418/**
419 * Requests cryptographic entropy bits from the CSRNG.
420 *
421 * The prediction resistance flag as specified in SP 800-90Ar1 section
422 * 10.2.1.1 is not directily supported by the hardware. It is the
423 * responsibility of the caller to reseed as needed before calling
424 * this function.
425 *
426 * The CSRNG accepts generation requests with 128-bit granularity, with
427 * a minimum 128-bit request size. This function will increase the size
428 * of the request to align it to the nearest 128-bit boundary.
429 *
430 * @param csrng A CSRNG handle.
431 * @param additional_data Additional data for the generate command. Set to NULL
432 * if unused.
433 * @param len Number of uint32_t words to generate.
434 * @return The result of the operation. KDifOutOfRange if the `len` parameter
435 * results in a 128bit block level size greater than 0x800.
436 */
439 const dif_csrng_t *csrng, const dif_csrng_seed_material_t *additional_data,
440 size_t len);
441
442/**
443 * Reads the output of the last CSRNG generate call.
444 *
445 * This function reads `len` words out of the CSRNG. This function should be
446 * called repeatedly until the number of words requested in
447 * `dif_csrng_generate_start()` is exhausted. This function will block until
448 * `len` words are read.
449 *
450 * `dif_csrng_get_output_status()` can be called before this function to ensure
451 * there is data available in the CSRNG output buffer.
452 *
453 * @param csrng A CSRNG handle.
454 * @param[out] buf A buffer to fill with words from the pipeline.
455 * @param len The number of words to read into `buf`.
456 * @return The result of the operation.
457 */
459dif_result_t dif_csrng_generate_read(const dif_csrng_t *csrng, uint32_t *buf,
460 size_t len);
461
462/**
463 * Uninstantiates CSRNG
464 *
465 * Resets the CSRNG instance. Values in the CSRNG are zeroed out. This
466 * command effectively resets the CSRNG, clearing any errors that it
467 * may have encountered due to processing or entropy source errors.
468 *
469 * @param csrng An CSRNG handle.
470 * @return The result of the operation.
471 */
474
475/**
476 * Gets the current command interface status.
477 *
478 * This function can be called before or after any of the following functions:
479 *
480 * - `dif_csrng_instantiate()`
481 * - `dif_csrng_reseed()`
482 * - `dif_csrng_update()`
483 * - `dif_csrng_generate_start()`
484 * - `dif_csrng_uninstantiate()`
485 *
486 * @param csrng An CSRNG handle
487 * @param[out] status Command interface status.
488 * @return The result of the operation.
489 */
493
494/**
495 * Forces the status registers to indicate `fifo` as being in an unhealthy
496 * state.
497 *
498 * @param csrng An CSRNG handle
499 * @param fifo The FIFO to mark as unhealthy.
500 * @return The result of the operation.
501 */
504 dif_csrng_fifo_t fifo);
505
506/**
507 * Forces the status registers to indicate a particular error cause.
508 *
509 * @param csrng An CSRNG handle
510 * @param error The error to force.
511 * @return The result of the operation.
512 */
515 dif_csrng_error_t error);
516
517/**
518 * Returns an opaque blob indicating the main state machine's current state.
519 *
520 * @param csrng An CSRNG handle
521 * @param state[out] The state machine state as an opaque blob.
522 * @return The result of the operation.
523 */
526 uint32_t *state);
527
528/**
529 * Returns a bitset indicating which hardware CSRNGs have encountered
530 * exceptions.
531 *
532 * @param csrng An CSRNG handle
533 * @param exceptions[out] The bitset of exception states.
534 * @return The result of the operation.
535 */
538 uint32_t *exceptions);
539
540/**
541 * Clears recorded hardware CSRNG exceptions.
542 *
543 * @param csrng An CSRNG handle
544 * @return The result of the operation.
545 */
548
549/**
550 * Gets the current cryptographic entropy output data status.
551 *
552 * This function can be used before calling `dif_csrng_generate_read()` to
553 * check if there is data available to read.
554 *
555 * @param csrng A CSRNG handle.
556 * @param[out] status CSRNG output status.
557 * @return The result of the operation.
558 */
562
563/**
564 * Gets the working state of a CSRNG instance.
565 *
566 * @param csrng A CSRNG handle
567 * @param instance_id CSRNG instance ID.
568 * @param[out] state The working state of a CSRNG instance.
569 * @return The result of the operation.
570 */
573 const dif_csrng_t *csrng, dif_csrng_internal_state_id_t instance_id,
575
576/**
577 * Gets the reseed counter of a CSRNG instance.
578 *
579 * @param csrng A CSRNG handle
580 * @param instance_id CSRNG instance ID.
581 * @param[out] reseed counter The current reseed counter value of a CSRNG
582 * instance.
583 * @return The result of the operation.
584 */
587 const dif_csrng_t *csrng, dif_csrng_internal_state_id_t instance_id,
588 uint32_t *reseed_counter);
589
590/**
591 * Locks out CSRNG functionality.
592 *
593 * This function is reentrant: calling it while functionality is locked will
594 * have no effect and return `kDifCsrngOk`.
595 *
596 * @param csrng A CSRNG handle.
597 * @return The result of the operation.
598 */
601
602/**
603 * Checks whether this CSRNG is locked.
604 *
605 * @param csrng A CSRNG handle.
606 * @param[out] is_locked Out-param for the locked state.
607 * @return The result of the operation.
608 */
610dif_result_t dif_csrng_is_locked(const dif_csrng_t *csrng, bool *is_locked);
611
612/**
613 * Disables the CSRNG module.
614 *
615 * @param csrng A CSRNG handle.
616 * @return The result of the operation.
617 */
620
621/**
622 * Gets the recoverable alerts currently recorded in the CSRNG block.
623 *
624 * This function returns the alerts in a bitset whose indices are given by
625 * `dif_csrng_recoverable_alert_t`.
626 *
627 * @param csrng A CSRNG handle.
628 * @param[out] alerts Bitset of alerts currently recorded.
629 * @return The result of the operation.
630 */
633 uint32_t *alerts);
634
635/**
636 * Clears all recoverable alerts currently recorded in the CSRNG block.
637 *
638 * @param csrng A CSRNG handle.
639 * @return The result of the operation.
640 */
643
644#ifdef __cplusplus
645} // extern "C"
646#endif // __cplusplus
647
648#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_CSRNG_H_