]>
Commit | Line | Data |
---|---|---|
dc4e74ef P |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | provider-rand - The random number generation library E<lt>-E<gt> provider | |
6 | functions | |
7 | ||
8 | =head1 SYNOPSIS | |
9 | ||
10 | =for openssl multiple includes | |
11 | ||
363b1e5d | 12 | #include <openssl/core_dispatch.h> |
dc4e74ef P |
13 | #include <openssl/core_names.h> |
14 | ||
15 | /* | |
16 | * None of these are actual functions, but are displayed like this for | |
17 | * the function signatures for functions that are offered as function | |
18 | * pointers in OSSL_DISPATCH arrays. | |
19 | */ | |
20 | ||
21 | /* Context management */ | |
363b1e5d DMSP |
22 | void *OSSL_FUNC_rand_newctx(void *provctx, void *parent, |
23 | const OSSL_DISPATCH *parent_calls); | |
24 | void OSSL_FUNC_rand_freectx(void *ctx); | |
dc4e74ef P |
25 | |
26 | /* Random number generator functions: NIST */ | |
363b1e5d DMSP |
27 | int OSSL_FUNC_rand_instantiate(void *ctx, unsigned int strength, |
28 | int prediction_resistance, | |
f8a5822c P |
29 | const unsigned char *pstr, size_t pstr_len, |
30 | const OSSL_PARAM params[]); | |
363b1e5d DMSP |
31 | int OSSL_FUNC_rand_uninstantiate(void *ctx); |
32 | int OSSL_FUNC_rand_generate(void *ctx, unsigned char *out, size_t outlen, | |
33 | unsigned int strength, int prediction_resistance, | |
34 | const unsigned char *addin, size_t addin_len); | |
35 | int OSSL_FUNC_rand_reseed(void *ctx, int prediction_resistance, | |
36 | const unsigned char *ent, size_t ent_len, | |
37 | const unsigned char *addin, size_t addin_len); | |
dc4e74ef P |
38 | |
39 | /* Random number generator functions: additional */ | |
363b1e5d | 40 | size_t OSSL_FUNC_rand_nonce(void *ctx, unsigned char *out, size_t outlen, |
68883d9d P |
41 | int strength, size_t min_noncelen, |
42 | size_t max_noncelen); | |
43 | size_t OSSL_FUNC_rand_get_seed(void *ctx, unsigned char **buffer, | |
44 | int entropy, size_t min_len, size_t max_len, | |
45 | int prediction_resistance, | |
46 | const unsigned char *adin, size_t adin_len); | |
47 | void OSSL_FUNC_rand_clear_seed(void *ctx, unsigned char *buffer, size_t b_len); | |
363b1e5d | 48 | int OSSL_FUNC_rand_verify_zeroization(void *ctx); |
dc4e74ef P |
49 | |
50 | /* Context Locking */ | |
363b1e5d DMSP |
51 | int OSSL_FUNC_rand_enable_locking(void *ctx); |
52 | int OSSL_FUNC_rand_lock(void *ctx); | |
53 | void OSSL_FUNC_rand_unlock(void *ctx); | |
dc4e74ef P |
54 | |
55 | /* RAND parameter descriptors */ | |
992492f5 | 56 | const OSSL_PARAM *OSSL_FUNC_rand_gettable_params(void *provctx); |
90fec26d P |
57 | const OSSL_PARAM *OSSL_FUNC_rand_gettable_ctx_params(void *ctx, void *provctx); |
58 | const OSSL_PARAM *OSSL_FUNC_rand_settable_ctx_params(void *ctx, void *provctx); | |
dc4e74ef P |
59 | |
60 | /* RAND parameters */ | |
363b1e5d DMSP |
61 | int OSSL_FUNC_rand_get_params(OSSL_PARAM params[]); |
62 | int OSSL_FUNC_rand_get_ctx_params(void *ctx, OSSL_PARAM params[]); | |
63 | int OSSL_FUNC_rand_set_ctx_params(void *ctx, const OSSL_PARAM params[]); | |
dc4e74ef P |
64 | |
65 | =head1 DESCRIPTION | |
66 | ||
67 | This documentation is primarily aimed at provider authors. See L<provider(7)> | |
68 | for further information. | |
69 | ||
70 | The RAND operation enables providers to implement random number generation | |
71 | algorithms and random number sources and make | |
72 | them available to applications via the API function L<EVP_RAND(3)>. | |
73 | ||
74 | =head2 Context Management Functions | |
75 | ||
363b1e5d | 76 | OSSL_FUNC_rand_newctx() should create and return a pointer to a provider side |
dc4e74ef P |
77 | structure for holding context information during a rand operation. |
78 | A pointer to this context will be passed back in a number of the other rand | |
79 | operation function calls. | |
80 | The parameter I<provctx> is the provider context generated during provider | |
81 | initialisation (see L<provider(7)>). | |
82 | The parameter I<parent> specifies another rand instance to be used for | |
83 | seeding purposes. If NULL and the specific instance supports it, the | |
84 | operating system will be used for seeding. | |
85 | The parameter I<parent_calls> points to the dispatch table for I<parent>. | |
86 | Thus, the parent need not be from the same provider as the new instance. | |
87 | ||
363b1e5d | 88 | OSSL_FUNC_rand_freectx() is passed a pointer to the provider side rand context in |
dc4e74ef P |
89 | the I<mctx> parameter. |
90 | If it receives NULL as I<ctx> value, it should not do anything other than | |
91 | return. | |
92 | This function should free any resources associated with that context. | |
93 | ||
94 | =head2 Random Number Generator Functions: NIST | |
95 | ||
96 | These functions correspond to those defined in NIST SP 800-90A and SP 800-90C. | |
97 | ||
363b1e5d | 98 | OSSL_FUNC_rand_instantiate() is used to instantiate the DRBG I<ctx> at a requested |
dc4e74ef P |
99 | security I<strength>. In addition, I<prediction_resistance> can be requested. |
100 | Additional input I<addin> of length I<addin_len> bytes can optionally | |
f8a5822c P |
101 | be provided. The parameters specified in I<params> configure the DRBG and these |
102 | should be processed before instantiation. | |
dc4e74ef | 103 | |
363b1e5d | 104 | OSSL_FUNC_rand_uninstantiate() is used to uninstantiate the DRBG I<ctx>. After being |
dc4e74ef P |
105 | uninstantiated, a DRBG is unable to produce output until it is instantiated |
106 | anew. | |
107 | ||
363b1e5d | 108 | OSSL_FUNC_rand_generate() is used to generate random bytes from the DRBG I<ctx>. |
dc4e74ef P |
109 | It will generate I<outlen> bytes placing them into the buffer pointed to by |
110 | I<out>. The generated bytes will meet the specified security I<strength> and, | |
111 | if I<prediction_resistance> is true, the bytes will be produced after reseeding | |
112 | from a live entropy source. Additional input I<addin> of length I<addin_len> | |
113 | bytes can optionally be provided. | |
114 | ||
115 | =head2 Random Number Generator Functions: Additional | |
116 | ||
363b1e5d | 117 | OSSL_FUNC_rand_nonce() is used to generate a nonce of the given I<strength> with a |
dc4e74ef P |
118 | length from I<min_noncelen> to I<max_noncelen>. If the output buffer I<out> is |
119 | NULL, the length of the nonce should be returned. | |
120 | ||
68883d9d P |
121 | OSSL_FUNC_rand_get_seed() is used by deterministic generators to obtain their |
122 | seeding material from their parent. The seed bytes will meet the specified | |
123 | security level of I<entropy> bits and there will be between I<min_len> | |
124 | and I<max_len> inclusive bytes in total. If I<prediction_resistance> is | |
125 | true, the bytes will be produced from a live entropy source. Additional | |
126 | input I<addin> of length I<addin_len> bytes can optionally be provided. | |
127 | A pointer to the seed material is returned in I<*buffer> and this must be | |
128 | freed by a later call to OSSL_FUNC_rand_clear_seed(). | |
129 | ||
130 | OSSL_FUNC_rand_clear_seed() frees a seed I<buffer> of length I<b_len> bytes | |
131 | which was previously allocated by OSSL_FUNC_rand_get_seed(). | |
132 | ||
363b1e5d | 133 | OSSL_FUNC_rand_verify_zeroization() is used to determine if the internal state of the |
dc4e74ef P |
134 | DRBG is zero. This capability is mandated by NIST as part of the self |
135 | tests, it is unlikely to be useful in other circumstances. | |
136 | ||
137 | =head2 Context Locking | |
138 | ||
139 | When DRBGs are used by multiple threads, there must be locking employed to | |
140 | ensure their proper operation. Because locking introduces an overhead, it | |
141 | is disabled by default. | |
142 | ||
363b1e5d | 143 | OSSL_FUNC_rand_enable_locking() allows locking to be turned on for a DRBG and all of |
dc4e74ef P |
144 | its parent DRBGs. From this call onwards, the DRBG can be used in a thread |
145 | safe manner. | |
146 | ||
363b1e5d | 147 | OSSL_FUNC_rand_lock() is used to lock a DRBG. Once locked, exclusive access |
dc4e74ef P |
148 | is guaranteed. |
149 | ||
363b1e5d | 150 | OSSL_FUNC_rand_unlock() is used to unlock a DRBG. |
dc4e74ef P |
151 | |
152 | =head2 Rand Parameters | |
153 | ||
154 | See L<OSSL_PARAM(3)> for further details on the parameters structure used by | |
155 | these functions. | |
156 | ||
363b1e5d | 157 | OSSL_FUNC_rand_get_params() gets details of parameter values associated with the |
dc4e74ef P |
158 | provider algorithm and stores them in I<params>. |
159 | ||
363b1e5d | 160 | OSSL_FUNC_rand_set_ctx_params() sets rand parameters associated with the given |
dc4e74ef P |
161 | provider side rand context I<ctx> to I<params>. |
162 | Any parameter settings are additional to any that were previously set. | |
f59612fe | 163 | Passing NULL for I<params> should return true. |
dc4e74ef | 164 | |
363b1e5d | 165 | OSSL_FUNC_rand_get_ctx_params() gets details of currently set parameter values |
dc4e74ef P |
166 | associated with the given provider side rand context I<ctx> and stores them |
167 | in I<params>. | |
f59612fe | 168 | Passing NULL for I<params> should return true. |
dc4e74ef | 169 | |
90fec26d | 170 | OSSL_FUNC_rand_gettable_params(), OSSL_FUNC_rand_gettable_ctx_params(), |
318a9dfa | 171 | and OSSL_FUNC_rand_settable_ctx_params() all return constant L<OSSL_PARAM(3)> |
90fec26d P |
172 | arrays as descriptors of the parameters that OSSL_FUNC_rand_get_params(), |
173 | OSSL_FUNC_rand_get_ctx_params(), and OSSL_FUNC_rand_set_ctx_params() | |
174 | can handle, respectively. OSSL_FUNC_rand_gettable_ctx_params() | |
175 | and OSSL_FUNC_rand_settable_ctx_params() will return the parameters | |
176 | associated with the provider side context I<ctx> in its current state | |
177 | if it is not NULL. Otherwise, they return the parameters associated | |
178 | with the provider side algorithm I<provctx>. | |
179 | ||
dc4e74ef P |
180 | |
181 | Parameters currently recognised by built-in rands are as follows. Not all | |
182 | parameters are relevant to, or are understood by all rands: | |
183 | ||
184 | =over 4 | |
185 | ||
186 | =item "state" (B<OSSL_RAND_PARAM_STATE>) <integer> | |
187 | ||
188 | Returns the state of the random number generator. | |
189 | ||
190 | =item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer> | |
191 | ||
192 | Returns the bit strength of the random number generator. | |
193 | ||
194 | =back | |
195 | ||
196 | For rands that are also deterministic random bit generators (DRBGs), these | |
197 | additional parameters are recognised. Not all | |
198 | parameters are relevant to, or are understood by all DRBG rands: | |
199 | ||
200 | =over 4 | |
201 | ||
202 | =item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer> | |
203 | ||
204 | Reads or set the number of generate requests before reseeding the | |
205 | associated RAND ctx. | |
206 | ||
207 | =item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer> | |
208 | ||
209 | Reads or set the number of elapsed seconds before reseeding the | |
210 | associated RAND ctx. | |
211 | ||
212 | =item "max_request" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer> | |
213 | ||
214 | Specifies the maximum number of bytes that can be generated in a single | |
363b1e5d | 215 | call to OSSL_FUNC_rand_generate. |
dc4e74ef P |
216 | |
217 | =item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer> | |
218 | ||
219 | =item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer> | |
220 | ||
221 | Specify the minimum and maximum number of bytes of random material that | |
222 | can be used to seed the DRBG. | |
223 | ||
224 | =item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer> | |
225 | ||
226 | =item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer> | |
227 | ||
228 | Specify the minimum and maximum number of bytes of nonce that can be used to | |
229 | instantiate the DRBG. | |
230 | ||
231 | =item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer> | |
232 | ||
233 | =item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer> | |
234 | ||
235 | Specify the minimum and maximum number of bytes of personalisation string | |
236 | that can be used with the DRBG. | |
237 | ||
b0614f0a | 238 | =item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_COUNTER>) <unsigned integer> |
dc4e74ef P |
239 | |
240 | Specifies the number of times the DRBG has been seeded or reseeded. | |
241 | ||
242 | =item "digest" (B<OSSL_DRBG_PARAM_DIGEST>) <UTF8 string> | |
243 | ||
244 | =item "cipher" (B<OSSL_DRBG_PARAM_CIPHER>) <UTF8 string> | |
245 | ||
246 | =item "mac" (B<OSSL_DRBG_PARAM_MAC>) <UTF8 string> | |
247 | ||
248 | Sets the name of the underlying cipher, digest or MAC to be used. | |
249 | It must name a suitable algorithm for the DRBG that's being used. | |
250 | ||
251 | =item "properties" (B<OSSL_DRBG_PARAM_PROPERTIES>) <UTF8 string> | |
252 | ||
253 | Sets the properties to be queried when trying to fetch an underlying algorithm. | |
254 | This must be given together with the algorithm naming parameter to be | |
255 | considered valid. | |
256 | ||
257 | =back | |
258 | ||
259 | =head1 RETURN VALUES | |
260 | ||
363b1e5d | 261 | OSSL_FUNC_rand_newctx() should return the newly created |
dc4e74ef P |
262 | provider side rand context, or NULL on failure. |
263 | ||
363b1e5d | 264 | OSSL_FUNC_rand_gettable_params(), OSSL_FUNC_rand_gettable_ctx_params() and |
318a9dfa | 265 | OSSL_FUNC_rand_settable_ctx_params() should return a constant L<OSSL_PARAM(3)> |
dc4e74ef P |
266 | array, or NULL if none is offered. |
267 | ||
363b1e5d | 268 | OSSL_FUNC_rand_nonce() returns the size of the generated nonce, or 0 on error. |
dc4e74ef | 269 | |
68883d9d P |
270 | OSSL_FUNC_rand_get_seed() returns the size of the generated seed, or 0 on |
271 | error. | |
272 | ||
dc4e74ef P |
273 | All of the remaining functions should return 1 for success or 0 on error. |
274 | ||
632bc4df P |
275 | =head1 NOTES |
276 | ||
277 | The RAND life-cycle is described in L<life_cycle-rand(7)>. Providers should | |
278 | ensure that the various transitions listed there are supported. At some point | |
279 | the EVP layer will begin enforcing the listed transitions. | |
280 | ||
dc4e74ef P |
281 | =head1 SEE ALSO |
282 | ||
283 | L<provider(7)>, | |
284 | L<RAND(7)>, | |
632bc4df P |
285 | L<EVP_RAND(7)>, |
286 | L<life_cycle-rand(7)>, | |
287 | L<EVP_RAND(3)> | |
dc4e74ef P |
288 | |
289 | =head1 HISTORY | |
290 | ||
291 | The provider RAND interface was introduced in OpenSSL 3.0. | |
292 | ||
293 | =head1 COPYRIGHT | |
294 | ||
a28d06f3 | 295 | Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved. |
dc4e74ef P |
296 | |
297 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
298 | this file except in compliance with the License. You can obtain a copy | |
299 | in the file LICENSE in the source distribution or at | |
300 | L<https://www.openssl.org/source/license.html>. | |
301 | ||
302 | =cut |