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