]>
Commit | Line | Data |
---|---|---|
dc4e74ef P |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_RAND, EVP_RAND_fetch, EVP_RAND_free, EVP_RAND_up_ref, EVP_RAND_CTX, | |
6 | EVP_RAND_CTX_new, EVP_RAND_CTX_free, EVP_RAND_instantiate, | |
7 | EVP_RAND_uninstantiate, EVP_RAND_generate, EVP_RAND_reseed, | |
7d615e21 | 8 | EVP_RAND_nonce, EVP_RAND_enable_locking, |
dc4e74ef P |
9 | EVP_RAND_verify_zeroization, EVP_RAND_strength, EVP_RAND_state, |
10 | EVP_RAND_provider, EVP_RAND_CTX_rand, EVP_RAND_is_a, EVP_RAND_number, | |
11 | EVP_RAND_name, EVP_RAND_names_do_all, EVP_RAND_get_ctx_params, | |
12 | EVP_RAND_set_ctx_params, EVP_RAND_do_all_provided, EVP_RAND_get_params, | |
13 | EVP_RAND_gettable_ctx_params, EVP_RAND_settable_ctx_params, | |
14 | EVP_RAND_gettable_params, EVP_RAND_STATE_UNINITIALISED, EVP_RAND_STATE_READY, | |
15 | EVP_RAND_STATE_ERROR - EVP RAND routines | |
16 | ||
17 | =head1 SYNOPSIS | |
18 | ||
19 | #include <openssl/evp.h> | |
20 | ||
21 | typedef struct evp_rand_st EVP_RAND; | |
22 | typedef struct evp_rand_ctx_st EVP_RAND_CTX; | |
23 | ||
24 | EVP_RAND *EVP_RAND_fetch(OPENSSL_CTX *libctx, const char *algorithm, | |
25 | const char *properties); | |
26 | int EVP_RAND_up_ref(EVP_RAND *rand); | |
27 | void EVP_RAND_free(EVP_RAND *rand); | |
28 | EVP_RAND_CTX *EVP_RAND_CTX_new(EVP_RAND *rand, EVP_RAND_CTX *parent); | |
29 | void EVP_RAND_CTX_free(EVP_RAND_CTX *ctx); | |
30 | EVP_RAND *EVP_RAND_CTX_rand(EVP_RAND_CTX *ctx); | |
31 | int EVP_RAND_get_params(EVP_RAND *rand, OSSL_PARAM params[]); | |
32 | int EVP_RAND_get_ctx_params(EVP_RAND_CTX *ctx, OSSL_PARAM params[]); | |
33 | int EVP_RAND_set_ctx_params(EVP_RAND_CTX *ctx, const OSSL_PARAM params[]); | |
34 | const OSSL_PARAM *EVP_RAND_gettable_params(const EVP_RAND *rand); | |
35 | const OSSL_PARAM *EVP_RAND_gettable_ctx_params(const EVP_RAND *rand); | |
36 | const OSSL_PARAM *EVP_RAND_settable_ctx_params(const EVP_RAND *rand); | |
37 | int EVP_RAND_number(const EVP_RAND *rand); | |
38 | const char *EVP_RAND_name(const EVP_RAND *rand); | |
39 | int EVP_RAND_is_a(const EVP_RAND *rand, const char *name); | |
40 | const OSSL_PROVIDER *EVP_RAND_provider(const EVP_RAND *rand); | |
41 | void EVP_RAND_do_all_provided(OPENSSL_CTX *libctx, | |
42 | void (*fn)(EVP_RAND *rand, void *arg), | |
43 | void *arg); | |
44 | void EVP_RAND_names_do_all(const EVP_RAND *rand, | |
45 | void (*fn)(const char *name, void *data), | |
46 | void *data); | |
47 | ||
48 | int EVP_RAND_instantiate(EVP_RAND_CTX *ctx, unsigned int strength, | |
49 | int prediction_resistance, | |
50 | const unsigned char *pstr, size_t pstr_len); | |
51 | int EVP_RAND_uninstantiate(EVP_RAND_CTX *ctx); | |
52 | int EVP_RAND_generate(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen, | |
53 | unsigned int strength, int prediction_resistance, | |
54 | const unsigned char *addin, size_t addin_len); | |
55 | int EVP_RAND_reseed(EVP_RAND_CTX *ctx, int prediction_resistance, | |
56 | const unsigned char *ent, size_t ent_len, | |
57 | const unsigned char *addin, size_t addin_len); | |
58 | int EVP_RAND_nonce(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen); | |
59 | int EVP_RAND_enable_locking(EVP_RAND_CTX *ctx); | |
dc4e74ef P |
60 | int EVP_RAND_verify_zeroization(EVP_RAND_CTX *ctx); |
61 | unsigned int EVP_RAND_strength(EVP_RAND_CTX *ctx); | |
62 | int EVP_RAND_state(EVP_RAND_CTX *ctx); | |
63 | ||
64 | #define EVP_RAND_STATE_UNINITIALISED 0 | |
65 | #define EVP_RAND_STATE_READY 1 | |
66 | #define EVP_RAND_STATE_ERROR 2 | |
67 | ||
68 | =head1 DESCRIPTION | |
69 | ||
8c1cbc72 | 70 | The EVP RAND routines are a high-level interface to random number generators |
dc4e74ef P |
71 | both deterministic and not. |
72 | If you just want to generate random bytes then you don't need to use | |
73 | these functions: just call RAND_bytes() or RAND_priv_bytes(). | |
74 | If you want to do more, these calls should be used instead of the older | |
75 | RAND and RAND_DRBG functions. | |
76 | ||
77 | After creating a B<EVP_RAND_CTX> for the required algorithm using | |
78 | EVP_RAND_CTX_new(), inputs to the algorithm are supplied | |
79 | using calls to EVP_RAND_set_ctx_params() before | |
80 | calling EVP_RAND_instantiate() and then EVP_RAND_generate() to produce | |
81 | cryptographically secure random bytes. | |
82 | ||
83 | =head2 Types | |
84 | ||
85 | B<EVP_RAND> is a type that holds the implementation of a RAND. | |
86 | ||
87 | B<EVP_RAND_CTX> is a context type that holds the algorithm inputs. | |
4640cd00 | 88 | B<EVP_RAND_CTX> structures are reference counted. |
dc4e74ef P |
89 | |
90 | =head2 Algorithm implementation fetching | |
91 | ||
92 | EVP_RAND_fetch() fetches an implementation of a RAND I<algorithm>, given | |
93 | a library context I<libctx> and a set of I<properties>. | |
94 | See L<provider(7)/Fetching algorithms> for further information. | |
95 | ||
96 | The returned value must eventually be freed with | |
97 | L<EVP_RAND_free(3)>. | |
98 | ||
99 | EVP_RAND_up_ref() increments the reference count of an already fetched | |
100 | RAND. | |
101 | ||
102 | EVP_RAND_free() frees a fetched algorithm. | |
103 | NULL is a valid parameter, for which this function is a no-op. | |
104 | ||
105 | =head2 Context manipulation functions | |
106 | ||
107 | EVP_RAND_CTX_new() creates a new context for the RAND implementation I<rand>. | |
108 | If not NULL, I<parent> specifies the seed source for this implementation. | |
109 | Not all random number generators need to have a seed source specified. | |
110 | If a parent is required, a NULL I<parent> will utilise the operating | |
111 | system entropy sources. | |
112 | It is recommended to minimise the number of random number generators that | |
113 | rely on the operating system for their randomness because this is often scarce. | |
114 | ||
115 | EVP_RAND_CTX_free() frees up the context I<ctx>. If I<ctx> is NULL, nothing | |
116 | is done. | |
117 | ||
118 | EVP_RAND_CTX_rand() returns the B<EVP_RAND> associated with the context | |
119 | I<ctx>. | |
120 | ||
121 | =head2 Random Number Generator Functions | |
122 | ||
123 | EVP_RAND_instantiate() instantiates the RAND I<ctx> with a minimum security | |
124 | strength of <strength> and personalisation string I<pstr> of length <pstr_len>. | |
125 | If I<prediction_resistance> is specified, fresh entropy from a live source | |
126 | will be sought. This call operates as per NIST SP 800-90A and SP 800-90C. | |
127 | ||
128 | EVP_RAND_uninstantiate() uninstantiates the RAND I<ctx> as per | |
129 | NIST SP 800-90A and SP 800-90C. Subsequent to this call, the RAND cannot | |
130 | be used to generate bytes. It can only be freed or instantiated again. | |
131 | ||
132 | EVP_RAND_generate() produces random bytes from the RAND I<ctx> with the | |
133 | additional input I<addin> of length I<addin_len>. The bytes | |
134 | produced will meet the security I<strength>. | |
135 | If I<prediction_resistance> is specified, fresh entropy from a live source | |
136 | will be sought. This call operates as per NIST SP 800-90A and SP 800-90C. | |
137 | ||
138 | EVP_RAND_reseed() reseeds the RAND with new entropy. | |
139 | Entropy I<ent> of length I<ent_len> bytes can be supplied as can additional | |
140 | input I<addin> of length I<addin_len> bytes. In the FIPS provider, both are | |
141 | treated as additional input as per NIST SP-800-90Ar1, Sections 9.1 and 9.2. | |
142 | Additional seed material is also drawn from the RAND's parent or the | |
143 | operating system. If I<prediction_resistance> is specified, fresh entropy | |
144 | from a live source will be sought. This call operates as per NIST SP 800-90A | |
145 | and SP 800-90C. | |
146 | ||
147 | EVP_RAND_nonce() creates a nonce in I<out> of maximum length I<outlen> | |
148 | bytes from the RAND I<ctx>. The function returns the length of the generated | |
149 | nonce. If I<out> is NULL, the length is still returned but no generation | |
150 | takes place. This allows a caller to dynamically allocate a buffer of the | |
151 | appropriate size. | |
152 | ||
153 | EVP_RAND_enable_locking() enables locking for the RAND I<ctx> and all of | |
154 | its parents. After this I<ctx> will operate in a thread safe manner, albeit | |
155 | more slowly. | |
156 | ||
dc4e74ef P |
157 | EVP_RAND_get_params() retrieves details about the implementation |
158 | I<rand>. | |
159 | The set of parameters given with I<params> determine exactly what | |
160 | parameters should be retrieved. | |
161 | Note that a parameter that is unknown in the underlying context is | |
162 | simply ignored. | |
163 | ||
164 | EVP_RAND_get_ctx_params() retrieves chosen parameters, given the | |
165 | context I<ctx> and its underlying context. | |
166 | The set of parameters given with I<params> determine exactly what | |
167 | parameters should be retrieved. | |
168 | Note that a parameter that is unknown in the underlying context is | |
169 | simply ignored. | |
170 | ||
171 | EVP_RAND_set_ctx_params() passes chosen parameters to the underlying | |
172 | context, given a context I<ctx>. | |
173 | The set of parameters given with I<params> determine exactly what | |
174 | parameters are passed down. | |
175 | Note that a parameter that is unknown in the underlying context is | |
176 | simply ignored. | |
177 | Also, what happens when a needed parameter isn't passed down is | |
178 | defined by the implementation. | |
179 | ||
180 | EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and | |
181 | EVP_RAND_settable_ctx_params() get a constant B<OSSL_PARAM> array that | |
182 | describes the retrievable and settable parameters, i.e. parameters that | |
183 | can be used with EVP_RAND_get_params(), EVP_RAND_get_ctx_params() | |
184 | and EVP_RAND_set_ctx_params(), respectively. | |
185 | See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor. | |
186 | ||
187 | =head2 Information functions | |
188 | ||
189 | EVP_RAND_strength() returns the security strength of the RAND I<ctx>. | |
190 | ||
191 | EVP_RAND_state() returns the current state of the RAND I<ctx>. | |
7d615e21 | 192 | States defined by the OpenSSL RNGs are: |
dc4e74ef P |
193 | |
194 | =over 4 | |
195 | ||
196 | =item * | |
197 | ||
7d615e21 | 198 | EVP_RAND_STATE_UNINITIALISED: this RNG is currently uninitialised. |
dc4e74ef P |
199 | The instantiate call will change this to the ready state. |
200 | ||
201 | =item * | |
202 | ||
7d615e21 | 203 | EVP_RAND_STATE_READY: this RNG is currently ready to generate output. |
dc4e74ef P |
204 | |
205 | =item * | |
206 | ||
7d615e21 | 207 | EVP_RAND_STATE_ERROR: this RNG is in an error state. |
dc4e74ef P |
208 | |
209 | =back | |
210 | ||
211 | EVP_RAND_is_a() returns 1 if I<rand> is an implementation of an | |
212 | algorithm that's identifiable with I<name>, otherwise 0. | |
213 | ||
214 | EVP_RAND_provider() returns the provider that holds the implementation | |
215 | of the given I<rand>. | |
216 | ||
217 | EVP_RAND_do_all_provided() traverses all RAND implemented by all activated | |
218 | providers in the given library context I<libctx>, and for each of the | |
219 | implementations, calls the given function I<fn> with the implementation method | |
220 | and the given I<arg> as argument. | |
221 | ||
222 | EVP_RAND_number() returns the internal dynamic number assigned to | |
223 | I<rand>. | |
224 | ||
225 | EVP_RAND_name() returns the canonical name of I<rand>. | |
226 | ||
227 | EVP_RAND_names_do_all() traverses all names for I<rand>, and calls | |
228 | I<fn> with each name and I<data>. | |
229 | ||
230 | EVP_RAND_verify_zeroization() confirms if the internal DRBG state is | |
231 | currently zeroed. This is used by the FIPS provider to support the mandatory | |
232 | self tests. | |
233 | ||
234 | =head1 PARAMETERS | |
235 | ||
236 | The standard parameter names are: | |
237 | ||
238 | =over 4 | |
239 | ||
240 | =item "state" (B<OSSL_RAND_PARAM_STATE>) <integer> | |
241 | ||
242 | Returns the state of the random number generator. | |
243 | ||
244 | =item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer> | |
245 | ||
246 | Returns the bit strength of the random number generator. | |
247 | ||
248 | =back | |
249 | ||
250 | For rands that are also deterministic random bit generators (DRBGs), these | |
251 | additional parameters are recognised. Not all | |
252 | parameters are relevant to, or are understood by all DRBG rands: | |
253 | ||
254 | =over 4 | |
255 | ||
256 | =item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer> | |
257 | ||
258 | Reads or set the number of generate requests before reseeding the | |
259 | associated RAND ctx. | |
260 | ||
261 | =item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer> | |
262 | ||
263 | Reads or set the number of elapsed seconds before reseeding the | |
264 | associated RAND ctx. | |
265 | ||
266 | =item "max_request" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer> | |
267 | ||
268 | Specifies the maximum number of bytes that can be generated in a single | |
363b1e5d | 269 | call to OSSL_FUNC_rand_generate. |
dc4e74ef P |
270 | |
271 | =item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer> | |
272 | ||
273 | =item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer> | |
274 | ||
275 | Specify the minimum and maximum number of bytes of random material that | |
276 | can be used to seed the DRBG. | |
277 | ||
278 | =item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer> | |
279 | ||
280 | =item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer> | |
281 | ||
282 | Specify the minimum and maximum number of bytes of nonce that can be used to | |
283 | seed the DRBG. | |
284 | ||
285 | =item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer> | |
286 | ||
287 | =item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer> | |
288 | ||
289 | Specify the minimum and maximum number of bytes of personalisation string | |
290 | that can be used with the DRBG. | |
291 | ||
b0614f0a | 292 | =item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_COUNTER>) <unsigned integer> |
dc4e74ef P |
293 | |
294 | Specifies the number of times the DRBG has been seeded or reseeded. | |
295 | ||
296 | =item "properties" (B<OSSL_RAND_PARAM_PROPERTIES>) <UTF8 string> | |
297 | ||
298 | =item "mac" (B<OSSL_RAND_PARAM_MAC>) <UTF8 string> | |
299 | ||
300 | =item "digest" (B<OSSL_RAND_PARAM_DIGEST>) <UTF8 string> | |
301 | ||
302 | =item "cipher" (B<OSSL_RAND_PARAM_CIPHER>) <UTF8 string> | |
303 | ||
304 | For RAND implementations that use an underlying computation MAC, digest or | |
305 | cipher, these parameters set what the algorithm should be. | |
306 | ||
307 | The value is always the name of the intended algorithm, | |
308 | or the properties in the case of B<OSSL_RAND_PARAM_PROPERTIES>. | |
309 | ||
310 | =back | |
311 | ||
312 | =head1 RETURN VALUES | |
313 | ||
314 | EVP_RAND_fetch() returns a pointer to a newly fetched B<EVP_RAND>, or | |
315 | NULL if allocation failed. | |
316 | ||
317 | EVP_RAND_provider() returns a pointer to the provider for the RAND, or | |
318 | NULL on error. | |
319 | ||
320 | EVP_RAND_CTX_rand() returns a pointer to the B<EVP_RAND> associated with the | |
321 | context. | |
322 | ||
323 | EVP_RAND_name() returns the name of the random number generation algorithm. | |
324 | ||
325 | EVP_RAND_number() returns the provider specific identification number | |
326 | for the specified algorithm. | |
327 | ||
328 | EVP_RAND_up_ref() returns 1 on success, 0 on error. | |
329 | ||
330 | EVP_RAND_CTX_new() returns either the newly allocated | |
331 | B<EVP_RAND_CTX> structure or NULL if an error occurred. | |
332 | ||
333 | EVP_RAND_CTX_free() does not return a value. | |
334 | ||
335 | EVP_RAND_nonce() returns the length of the nonce. | |
336 | ||
8c1cbc72 | 337 | EVP_RAND_strength() returns the strength of the random number generator in bits. |
dc4e74ef P |
338 | |
339 | EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and | |
340 | EVP_RAND_settable_ctx_params() return an array of OSSL_PARAMs. | |
341 | ||
342 | EVP_RAND_verify_zeroization() returns 1 if the internal DRBG state is | |
343 | currently zeroed, and 0 if not. | |
344 | ||
345 | The remaining functions return 1 for success and 0 or a negative value for | |
346 | failure. | |
347 | ||
348 | =head1 SEE ALSO | |
349 | ||
350 | L<RAND_bytes(3)>, | |
351 | L<EVP_RAND-CTR-DRBG(7)>, | |
352 | L<EVP_RAND-HASH-DRBG(7)>, | |
353 | L<EVP_RAND-HMAC-DRBG(7)>, | |
354 | L<EVP_RAND-TEST-RAND(7)>, | |
355 | L<provider-rand(7)> | |
356 | ||
357 | =head1 HISTORY | |
358 | ||
359 | This functionality was added to OpenSSL 3.0. | |
360 | ||
361 | =head1 COPYRIGHT | |
362 | ||
363 | Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. | |
364 | ||
365 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
366 | this file except in compliance with the License. You can obtain a copy | |
367 | in the file LICENSE in the source distribution or at | |
368 | L<https://www.openssl.org/source/license.html>. | |
369 | ||
370 | =cut |