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="/hw/ip/csrng/doc/">CSRNG</a> Device Interface Functions
11 */
12
13#include <stdint.h>
14
18
19#include "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://docs.opentitan.org/hw/ip/csrng/doc/
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 kDifCsrngFifoCmdReq,
97 kDifCsrngFifoRcStage,
98 kDifCsrngFifoKeyVrc,
99 kDifCsrngFifoUpdateReq,
100 kDifCsrngFifoBencRec,
101 kDifCsrngFifoBencAck,
102 kDifCsrngFifoPData,
103 kDifCsrngFifoFinal,
104 kDifCsrngFifoGBencAck,
105 kDifCsrngFifoGrcStage,
106 kDifCsrngFifoGGenReq,
107 kDifCsrngFifoGadStage,
108 kDifCsrngFifoBlockEnc,
110
111/**
112 * Enumeration of CSRNG FIFO errors.
113 */
114typedef enum dif_csrng_error {
115 /**
116 * Indicates an error in the command stage state machine.
117 */
119 /**
120 * Indicates an error in the main state machine.
121 */
123 /**
124 * Indicates an error in the DRBG's generator state machine.
125 */
127 /**
128 * Indicates an error in the DRBG's block encoding state machine.
129 */
131 /**
132 * Indicates an error in the DRBG's block output state machine.
133 */
135 /**
136 * Indicates an error in the AES state machine.
137 */
139 /**
140 * Indicates an error in the generate command's counter.
141 */
143 /**
144 * Indicates a write to a full FIFO occured.
145 */
147 /**
148 * Indicates a read from an empty FIFO occured.
149 */
151 /**
152 * Indicates a FIFO was somehow both full and empty.
153 */
156
157/**
158 * Enumeration of CSRNG command status errors.
159 */
161 /**
162 * Indicates that the command completed successfully.
163 */
165 /**
166 * Indicates that an invalid apllication command has been issued.
167 */
169 /**
170 * Indicates that the state wasn't zeroized properly after an uninstantiate
171 * command due to invalid state parameters in the cmd drbg.
172 */
174 /**
175 * Indicates that CSRNG entropy was generated for a command that is not a
176 * generate command.
177 */
179 /**
180 * Indicates that last command was not issued in sequence.
181 * E.g. an instantiate on an instantiated state or any command other than an
182 * instantiate on an uninstantiated state.
183 */
186
187/**
188 * The status of the CSRNG block at a particular moment in time.
189 */
190typedef struct dif_csrng_cmd_status {
191 /**
192 * The kind of status the CSRNG is in.
193 */
195 /**
196 * The status value CSRNG returns.
197 */
200
201/**
202 * CSRNG consume seed from entropy source enable.
203 */
205 /**
206 * Seed material used as the only seed material.
207 *
208 * This configuration option will toggle the hardware state of the
209 * CSRNG to non-FIPS compliant until it is re-instantiated.
210 *
211 * Note: Software may opt to XOR the seed material with a seed to implement
212 * a software assisted FIPS mode of operation.
213 */
215 /**
216 * Entropy source XOR'ed with the provided seed material.
217 */
220
221enum {
222 /**
223 * Maximum seed material number of uint32_t words supported in CSRNG
224 * instantiate and seed commands.
225 */
227};
228
229/**
230 * CSRNG common transaction parameters.
231 */
233 /**
234 * Number of uint32_t words in `seed_material`. Up to 12 words can be
235 * set to initialize the CSRNG. CSRNG will extend the `seed_material`
236 * to zeros if the provided value is less that 12.
237 */
239 /**
240 * Seed material used in CSRNG
241 */
244
245/**
246 * Generated output state.
247 */
249 /**
250 * Set to true when there is cryptographic entropy data available to
251 * read using `dif_csrng_generate_read()`.
252 */
254 /**
255 * Set to true when the cryptographic entropy data available to read
256 * is FIPS/CC compliant at the hardware level.
257 */
260
261/**
262 * CSRNG internal state selector ID.
263 */
265 /**
266 * CSRNG instance assigned to Entropy Distribution Network (EDN) 0.
267 */
269 /**
270 * CSRNG instance assigned to Entropy Distribution Network (EDN) 1.
271 */
273 /**
274 * CSRNG instance assigned to software interface.
275 */
278
279/**
280 * CSRNG internal state.
281 */
283 /**
284 * Indicates the number of requests for pseudorandom bits since instantiation
285 * or reseeding.
286 */
288 /**
289 * Internal V working state with a 128bit block size.
290 */
291 uint32_t v[4];
292 /**
293 * Internal key used to configure the internal CSRNG cipher.
294 */
295 uint32_t key[8];
296 /**
297 * Set to true when the CSRNG instance has been instantiated.
298 */
300 /**
301 * Set to true when FIPS compliant entropy was provided directly by the
302 * entropy source to instantiate or reseed the CSRNG instance.
303 */
306
307/**
308 * Recoverable alerts emitted by the CSRNG.
309 */
311 /**
312 * Indicates a bad value was written to the ENABLE field of the control
313 * register.
314 */
316 1U << CSRNG_RECOV_ALERT_STS_ENABLE_FIELD_ALERT_BIT,
317 /**
318 * Indicates a bad value was written to the SW_APP_ENABLE field of the control
319 * register.
320 */
322 1U << CSRNG_RECOV_ALERT_STS_SW_APP_ENABLE_FIELD_ALERT_BIT,
323 /**
324 * Indicates a bad value was written to the READ_INT_STATE field of the
325 * control register.
326 */
328 1U << CSRNG_RECOV_ALERT_STS_READ_INT_STATE_FIELD_ALERT_BIT,
329 /**
330 * Indicates the FLAG0 field in the Application Command is set to a value
331 * other than kMultiBitBool4True or kMultiBitBool4False.
332 */
334 1U << CSRNG_RECOV_ALERT_STS_ACMD_FLAG0_FIELD_ALERT_BIT,
335 /**
336 * Indicates the genbits bus saw two identical values, indicating a possible
337 * attack.
338 */
340 1U << CSRNG_RECOV_ALERT_STS_CS_BUS_CMP_ALERT_BIT,
341 /**
342 * Indicates an unsupported CSRNG command was issued.
343 */
345 1U << CSRNG_RECOV_ALERT_STS_CMD_STAGE_INVALID_ACMD_ALERT_BIT,
346 /**
347 * Indicates a supported CSRNG command was issued out of sequence.
348 */
350 1U << CSRNG_RECOV_ALERT_STS_CMD_STAGE_INVALID_CMD_SEQ_ALERT_BIT,
351 /**
352 * Indicates that too many generate commands were issued in a row.
353 */
355 1U << CSRNG_RECOV_ALERT_STS_CMD_STAGE_RESEED_CNT_ALERT_BIT,
357
358/**
359 * Configures CSRNG.
360 *
361 * This function should need to be called once for the lifetime of `csrng`.
362 *
363 * @param csrng A CSRNG handle.
364 * @return The result of the operation.
365 */
368
369/**
370 * Initializes CSRNG instance with a new seed value.
371 *
372 * `seed_material` is used as specified in NIST SP 800-90Ar1 section
373 * 10.2.1.3.1. See `dif_csrng_entropy_src` for details on how this value
374 * is mixed with the CSRNG seed.
375 *
376 * `seed_material` can be NULL, in which case CSRNG will use a zero
377 * vector instead.
378 *
379 * @param csrng A CSRNG handle.
380 * @param entropy_src_enable Entropy source input enable.
381 * @param seed_material Seed initialization parameters.
382 * @return The result of the operation.
383 */
386 const dif_csrng_t *csrng, dif_csrng_entropy_src_toggle_t entropy_src_enable,
387 const dif_csrng_seed_material_t *seed_material);
388
389/**
390 * Reseeds CSRNG instance.
391 *
392 * When `seed_material.seed_material_len` is set to 0, only the entropy source
393 * seed is used to reseed the instance, otherwise it will be XOR'ed with the
394 * entropy source.
395 *
396 * @param csrng A CSRNG handle.
397 * @param seed_material Reseed parameters.
398 * @return The result of the operation.
399 */
402 const dif_csrng_seed_material_t *seed_material);
403
404/**
405 * Updates CSRNG state.
406 *
407 * This function is similar to `dif_csrng_reseed()`, except:
408 *
409 * - Only `seed_material.seed_material` is used in the update operation.
410 * - The update operation does not reset the internal CSRNG reseed
411 * counter.
412 *
413 * @param csrng A CSRNG handle.
414 * @param seed_material Update parameters.
415 * @return The result of the operation.
416 */
419 const dif_csrng_seed_material_t *seed_material);
420
421/**
422 * Requests cryptographic entropy bits from the CSRNG.
423 *
424 * The prediction resistance flag as specified in SP 800-90Ar1 section
425 * 10.2.1.1 is not directily supported by the hardware. It is the
426 * responsibility of the caller to reseed as needed before calling
427 * this function.
428 *
429 * The CSRNG accepts generation requests with 128-bit granularity, with
430 * a minimum 128-bit request size. This function will increase the size
431 * of the request to align it to the nearest 128-bit boundary.
432 *
433 * @param csrng A CSRNG handle.
434 * @param len Number of uint32_t words to generate.
435 * @return The result of the operation. KDifOutOfRange if the `len` parameter
436 * results in a 128bit block level size greater than 0x800.
437 */
439dif_result_t dif_csrng_generate_start(const dif_csrng_t *csrng, size_t len);
440
441/**
442 * Reads the output of the last CSRNG generate call.
443 *
444 * This function reads `len` words out of the CSRNG. This function should be
445 * called repeatedly until the number of words requested in
446 * `dif_csrng_generate_start()` is exhausted. This function will block until
447 * `len` words are read.
448 *
449 * `dif_csrng_get_output_status()` can be called before this function to ensure
450 * there is data available in the CSRNG output buffer.
451 *
452 * @param csrng A CSRNG handle.
453 * @param[out] buf A buffer to fill with words from the pipeline.
454 * @param len The number of words to read into `buf`.
455 * @return The result of the operation.
456 */
458dif_result_t dif_csrng_generate_read(const dif_csrng_t *csrng, uint32_t *buf,
459 size_t len);
460
461/**
462 * Uninstantiates CSRNG
463 *
464 * Resets the CSRNG instance. Values in the CSRNG are zeroed out. This
465 * command effectively resets the CSRNG, clearing any errors that it
466 * may have encountered due to processing or entropy source errors.
467 *
468 * @param csrng An CSRNG handle.
469 * @return The result of the operation.
470 */
473
474/**
475 * Gets the current command interface status.
476 *
477 * This function can be called before or after any of the following functions:
478 *
479 * - `dif_csrng_instantiate()`
480 * - `dif_csrng_reseed()`
481 * - `dif_csrng_update()`
482 * - `dif_csrng_generate_start()`
483 * - `dif_csrng_uninstantiate()`
484 *
485 * @param csrng An CSRNG handle
486 * @param[out] status Command interface status.
487 * @return The result of the operation.
488 */
492
493/**
494 * Forces the status registers to indicate `fifo` as being in an unhealthy
495 * state.
496 *
497 * @param csrng An CSRNG handle
498 * @param fifo The FIFO to mark as unhealthy.
499 * @return The result of the operation.
500 */
503 dif_csrng_fifo_t fifo);
504
505/**
506 * Forces the status registers to indicate a particular error cause.
507 *
508 * @param csrng An CSRNG handle
509 * @param error The error to force.
510 * @return The result of the operation.
511 */
514 dif_csrng_error_t error);
515
516/**
517 * Returns an opaque blob indicating the main state machine's current state.
518 *
519 * @param csrng An CSRNG handle
520 * @param state[out] The state machine state as an opaque blob.
521 * @return The result of the operation.
522 */
525 uint32_t *state);
526
527/**
528 * Returns a bitset indicating which hardware CSRNGs have encountered
529 * exceptions.
530 *
531 * @param csrng An CSRNG handle
532 * @param exceptions[out] The bitset of exception states.
533 * @return The result of the operation.
534 */
537 uint32_t *exceptions);
538
539/**
540 * Clears recorded hardware CSRNG exceptions.
541 *
542 * @param csrng An CSRNG handle
543 * @return The result of the operation.
544 */
547
548/**
549 * Gets the current cryptographic entropy output data status.
550 *
551 * This function can be used before calling `dif_csrng_generate_read()` to
552 * check if there is data available to read.
553 *
554 * @param csrng A CSRNG handle.
555 * @param[out] status CSRNG output status.
556 * @return The result of the operation.
557 */
561
562/**
563 * Gets the working state of a CSRNG instance.
564 *
565 * @param csrng A CSRNG handle
566 * @param instance_id CSRNG instance ID.
567 * @param[out] state The working state of a CSRNG instance.
568 * @return The result of the operation.
569 */
572 const dif_csrng_t *csrng, dif_csrng_internal_state_id_t instance_id,
574
575/**
576 * Gets the reseed counter of a CSRNG instance.
577 *
578 * @param csrng A CSRNG handle
579 * @param instance_id CSRNG instance ID.
580 * @param[out] reseed counter The current reseed counter value of a CSRNG
581 * instance.
582 * @return The result of the operation.
583 */
586 const dif_csrng_t *csrng, dif_csrng_internal_state_id_t instance_id,
587 uint32_t *reseed_counter);
588
589/**
590 * Locks out CSRNG functionality.
591 *
592 * This function is reentrant: calling it while functionality is locked will
593 * have no effect and return `kDifCsrngOk`.
594 *
595 * @param csrng A CSRNG handle.
596 * @return The result of the operation.
597 */
600
601/**
602 * Checks whether this CSRNG is locked.
603 *
604 * @param csrng A CSRNG handle.
605 * @param[out] is_locked Out-param for the locked state.
606 * @return The result of the operation.
607 */
609dif_result_t dif_csrng_is_locked(const dif_csrng_t *csrng, bool *is_locked);
610
611/**
612 * Disables the CSRNG module.
613 *
614 * @param csrng A CSRNG handle.
615 * @return The result of the operation.
616 */
619
620/**
621 * Gets the recoverable alerts currently recorded in the CSRNG block.
622 *
623 * This function returns the alerts in a bitset whose indices are given by
624 * `dif_csrng_recoverable_alert_t`.
625 *
626 * @param csrng A CSRNG handle.
627 * @param[out] alerts Bitset of alerts currently recorded.
628 * @return The result of the operation.
629 */
632 uint32_t *alerts);
633
634/**
635 * Clears all recoverable alerts currently recorded in the CSRNG block.
636 *
637 * @param csrng A CSRNG handle.
638 * @return The result of the operation.
639 */
642
643#ifdef __cplusplus
644} // extern "C"
645#endif // __cplusplus
646
647#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_CSRNG_H_