Software APIs
drbg.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_CRYPTO_INCLUDE_DRBG_H_
6 #define OPENTITAN_SW_DEVICE_LIB_CRYPTO_INCLUDE_DRBG_H_
7 
8 #include "datatypes.h"
9 
10 /**
11  * @file
12  * @brief DRBG for the OpenTitan cryptography library.
13  */
14 
15 #ifdef __cplusplus
16 extern "C" {
17 #endif // __cplusplus
18 
19 /**
20  * Instantiates the DRBG system.
21  *
22  * Initializes the DRBG and the context for DRBG. Gets the required entropy
23  * input automatically from the entropy source.
24  *
25  * The personalization string may empty, and may be up to 48 bytes long; any
26  * longer will result in an error.
27  *
28  * @param perso_string Pointer to personalization bitstring.
29  * @return Result of the DRBG instantiate operation.
30  */
31 otcrypto_status_t otcrypto_drbg_instantiate(
32  otcrypto_const_byte_buf_t perso_string);
33 
34 /**
35  * Reseeds the DRBG with fresh entropy.
36  *
37  * Reseeds the DRBG with fresh entropy that is automatically fetched from the
38  * entropy source and updates the working state parameters.
39  *
40  * @param additional_input Pointer to the additional input for DRBG.
41  * @return Result of the DRBG reseed operation.
42  */
43 otcrypto_status_t otcrypto_drbg_reseed(
44  otcrypto_const_byte_buf_t additional_input);
45 
46 /**
47  * Instantiates the DRBG system.
48  *
49  * Initializes DRBG and the DRBG context. Gets the required entropy input from
50  * the user through the `entropy` parameter. Calling this function breaks FIPS
51  * compliance until the DRBG is uninstantiated.
52  *
53  * The entropy input must be exactly 384 bits long (48 bytes). The
54  * personalization string must not be longer than the entropy input, and may be
55  * empty.
56  *
57  * @param entropy Pointer to the user defined entropy value.
58  * @param personalization_string Pointer to personalization bitstring.
59  * @return Result of the DRBG manual instantiation.
60  */
61 otcrypto_status_t otcrypto_drbg_manual_instantiate(
62  otcrypto_const_byte_buf_t entropy, otcrypto_const_byte_buf_t perso_string);
63 
64 /**
65  * Reseeds the DRBG with fresh entropy.
66  *
67  * Reseeds the DRBG with entropy input from the user through the `entropy`
68  * parameter and updates the working state parameters. Calling this function
69  * breaks FIPS compliance until the DRBG is uninstantiated.
70  *
71  * @param entropy Pointer to the user defined entropy value.
72  * @param additional_input Pointer to the additional input for DRBG.
73  * @return Result of the manual DRBG reseed operation.
74  */
75 otcrypto_status_t otcrypto_drbg_manual_reseed(
76  otcrypto_const_byte_buf_t entropy,
77  otcrypto_const_byte_buf_t additional_input);
78 
79 /**
80  * DRBG function for generating random bits.
81  *
82  * This function checks the hardware flags for FIPS compatibility of the
83  * generated bits, so it will fail after `otcrypto_drbg_manual_instantiate` or
84  * `otcrypto_drbg_manual_reseed`.
85  *
86  * The caller should allocate space for the `drbg_output` buffer and set the
87  * length of expected output in the `len` field.
88  *
89  * The output is generated in 16-byte blocks; if `drbg_output->len` is not a
90  * multiple of 4, some output from the hardware will be discarded. This detail
91  * may be important for known-answer tests.
92  *
93  * @param additional_input Pointer to the additional data.
94  * @param[out] drbg_output Pointer to the generated pseudo random bits.
95  * @return Result of the DRBG generate operation.
96  */
97 otcrypto_status_t otcrypto_drbg_generate(
98  otcrypto_const_byte_buf_t additional_input,
99  otcrypto_word32_buf_t drbg_output);
100 
101 /**
102  * DRBG function for generating random bits.
103  *
104  * This function does NOT check the hardware flags for FIPS compatibility of the
105  * generated bits, so it may be called after `otcrypto_drbg_manual_instantiate`
106  * or `otcrypto_drbg_manual_reseed`.
107  *
108  * The caller should allocate space for the `drbg_output` buffer and set the
109  * length of expected output in the `len` field.
110  *
111  * The output is generated in 16-byte blocks; if `drbg_output->len` is not a
112  * multiple of 4, some output from the hardware will be discarded. This detail
113  * may be important for known-answer tests.
114  *
115  * @param additional_input Pointer to the additional data.
116  * @param[out] drbg_output Pointer to the generated pseudo random bits.
117  * @return Result of the DRBG generate operation.
118  */
119 otcrypto_status_t otcrypto_drbg_manual_generate(
120  otcrypto_const_byte_buf_t additional_input,
121  otcrypto_word32_buf_t drbg_output);
122 
123 /**
124  * Uninstantiates DRBG and clears the context.
125  *
126  * @return Result of the DRBG uninstantiate operation.
127  */
128 otcrypto_status_t otcrypto_drbg_uninstantiate(void);
129 
130 #ifdef __cplusplus
131 } // extern "C"
132 #endif // __cplusplus
133 
134 #endif // OPENTITAN_SW_DEVICE_LIB_CRYPTO_INCLUDE_DRBG_H_
Return to OpenTitan Documentation