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