Standard preamble:
========================================================================
..
.... Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. \*(C+ will
give a nicer C++. Capital omega is used to do unbreakable dashes and
therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
nothing in troff, for use with C<>.
.tr \(*W- . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.
If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.
Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF
Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ========================================================================
Title "EVP_RAND 3"
way too many mistakes in technical documents.
After creating a \s-1EVP_RAND_CTX\s0 for the required algorithm using \fBEVP_RAND_CTX_new(), inputs to the algorithm are supplied either by passing them as part of the EVP_RAND_instantiate() call or using calls to \fBEVP_RAND_CTX_set_params() before calling EVP_RAND_instantiate(). Finally, call EVP_RAND_generate() to produce cryptographically secure random bytes.
\fB\s-1EVP_RAND_CTX\s0 is a context type that holds the algorithm inputs. \fB\s-1EVP_RAND_CTX\s0 structures are reference counted.
The returned value must eventually be freed with \fBEVP_RAND_free\|(3).
\fBEVP_RAND_up_ref() increments the reference count of an already fetched \s-1RAND.\s0
\fBEVP_RAND_free() frees a fetched algorithm. \s-1NULL\s0 is a valid parameter, for which this function is a no-op.
\fBEVP_RAND_CTX_free() frees up the context ctx. If ctx is \s-1NULL,\s0 nothing is done.
\fBEVP_RAND_CTX_get0_rand() returns the \s-1EVP_RAND\s0 associated with the context \fIctx.
\fBEVP_RAND_uninstantiate() uninstantiates the \s-1RAND\s0 ctx as per \s-1NIST SP 800-90A\s0 and \s-1SP 800-90C.\s0 Subsequent to this call, the \s-1RAND\s0 cannot be used to generate bytes. It can only be freed or instantiated again.
\fBEVP_RAND_generate() produces random bytes from the \s-1RAND\s0 ctx with the additional input addin of length addin_len. The bytes produced will meet the security strength. If prediction_resistance is specified, fresh entropy from a live source will be sought. This call operates as per \s-1NIST SP 800-90A\s0 and \s-1SP 800-90C.\s0
\fBEVP_RAND_reseed() reseeds the \s-1RAND\s0 with new entropy. Entropy ent of length ent_len bytes can be supplied as can additional input addin of length addin_len bytes. In the \s-1FIPS\s0 provider, both are treated as additional input as per \s-1NIST\s0 SP-800-90Ar1, Sections 9.1 and 9.2. Additional seed material is also drawn from the \s-1RAND\s0's parent or the operating system. If prediction_resistance is specified, fresh entropy from a live source will be sought. This call operates as per \s-1NIST SP 800-90A\s0 and \s-1SP 800-90C.\s0
\fBEVP_RAND_nonce() creates a nonce in out of maximum length outlen bytes from the \s-1RAND\s0 ctx. The function returns the length of the generated nonce. If out is \s-1NULL,\s0 the length is still returned but no generation takes place. This allows a caller to dynamically allocate a buffer of the appropriate size.
\fBEVP_RAND_enable_locking() enables locking for the \s-1RAND\s0 ctx and all of its parents. After this ctx will operate in a thread safe manner, albeit more slowly. This function is not itself thread safe if called with the same \fIctx from multiple threads. Typically locking should be enabled before a \fIctx is shared across multiple threads.
\fBEVP_RAND_get_params() retrieves details about the implementation \fIrand. The set of parameters given with params determine exactly what parameters should be retrieved. Note that a parameter that is unknown in the underlying context is simply ignored.
\fBEVP_RAND_CTX_get_params() retrieves chosen parameters, given the context ctx and its underlying context. The set of parameters given with params determine exactly what parameters should be retrieved. Note that a parameter that is unknown in the underlying context is simply ignored.
\fBEVP_RAND_CTX_set_params() passes chosen parameters to the underlying context, given a context ctx. The set of parameters given with params determine exactly what parameters are passed down. Note that a parameter that is unknown in the underlying context is simply ignored. Also, what happens when a needed parameter isn't passed down is defined by the implementation.
\fBEVP_RAND_gettable_params() returns an \s-1OSSL_PARAM\s0\|(3) array that describes the retrievable and settable parameters. EVP_RAND_gettable_params() returns parameters that can be used with EVP_RAND_get_params().
\fBEVP_RAND_gettable_ctx_params() and EVP_RAND_CTX_gettable_params() return constant \s-1OSSL_PARAM\s0\|(3) arrays that describe the retrievable parameters that can be used with EVP_RAND_CTX_get_params(). EVP_RAND_gettable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas \fBEVP_RAND_CTX_gettable_params() returns the parameters that can be retrieved in the context's current state.
\fBEVP_RAND_settable_ctx_params() and EVP_RAND_CTX_settable_params() return constant \s-1OSSL_PARAM\s0\|(3) arrays that describe the settable parameters that can be used with EVP_RAND_CTX_set_params(). EVP_RAND_settable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas \fBEVP_RAND_CTX_settable_params() returns the parameters that can be retrieved in the context's current state.
\fBEVP_RAND_get_state() returns the current state of the \s-1RAND\s0 ctx. States defined by the OpenSSL RNGs are:
\fBEVP_RAND_is_a() returns 1 if rand is an implementation of an algorithm that's identifiable with name, otherwise 0.
\fBEVP_RAND_get0_provider() returns the provider that holds the implementation of the given rand.
\fBEVP_RAND_do_all_provided() traverses all \s-1RAND\s0 implemented by all activated providers in the given library context libctx, and for each of the implementations, calls the given function fn with the implementation method and the given arg as argument.
\fBEVP_RAND_get0_name() returns the canonical name of rand.
\fBEVP_RAND_names_do_all() traverses all names for rand, and calls \fIfn with each name and data.
\fBEVP_RAND_get0_description() returns a description of the rand, meant for display and human consumption. The description is at the discretion of the rand implementation.
\fBEVP_RAND_verify_zeroization() confirms if the internal \s-1DRBG\s0 state is currently zeroed. This is used by the \s-1FIPS\s0 provider to support the mandatory self tests.
For rands that are also deterministic random bit generators (DRBGs), these additional parameters are recognised. Not all parameters are relevant to, or are understood by all \s-1DRBG\s0 rands: Item "reseed_requests (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>" Reads or set the number of generate requests before reseeding the associated \s-1RAND\s0 ctx. Item "reseed_time_interval (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) <integer>" Reads or set the number of elapsed seconds before reseeding the associated \s-1RAND\s0 ctx. Item "max_request (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>" Specifies the maximum number of bytes that can be generated in a single call to OSSL_FUNC_rand_generate. Item "min_entropylen (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <unsigned integer>"
0 Item "max_entropylen (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <unsigned integer>"
Specify the minimum and maximum number of bytes of random material that can be used to seed the \s-1DRBG.\s0 Item "min_noncelen (OSSL_DRBG_PARAM_MIN_NONCELEN) <unsigned integer>"
0 Item "max_noncelen (OSSL_DRBG_PARAM_MAX_NONCELEN) <unsigned integer>"
Specify the minimum and maximum number of bytes of nonce that can be used to seed the \s-1DRBG.\s0 Item "max_perslen (OSSL_DRBG_PARAM_MAX_PERSLEN) <unsigned integer>"
0 Item "max_adinlen (OSSL_DRBG_PARAM_MAX_ADINLEN) <unsigned integer>"
Specify the minimum and maximum number of bytes of personalisation string that can be used with the \s-1DRBG.\s0 Item "reseed_counter (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>" Specifies the number of times the \s-1DRBG\s0 has been seeded or reseeded. Item "properties (OSSL_RAND_PARAM_PROPERTIES) <UTF8 string>"
0 Item "mac (OSSL_RAND_PARAM_MAC) <UTF8 string>" Item "digest (OSSL_RAND_PARAM_DIGEST) <UTF8 string>" Item "cipher (OSSL_RAND_PARAM_CIPHER) <UTF8 string>"
For \s-1RAND\s0 implementations that use an underlying computation \s-1MAC,\s0 digest or cipher, these parameters set what the algorithm should be. .Sp The value is always the name of the intended algorithm, or the properties in the case of \s-1OSSL_RAND_PARAM_PROPERTIES\s0.
An \s-1EVP_RAND_CTX\s0 needs to have locking enabled if it acts as the parent of more than one child and the children can be accessed concurrently. This must be done by explicitly calling EVP_RAND_enable_locking().
The \s-1RAND\s0 life-cycle is described in life_cycle-rand\|(7). In the future, the transitions described there will be enforced. When this is done, it will not be considered a breaking change to the \s-1API.\s0
\fBEVP_RAND_get0_provider() returns a pointer to the provider for the \s-1RAND,\s0 or \s-1NULL\s0 on error.
\fBEVP_RAND_CTX_get0_rand() returns a pointer to the \s-1EVP_RAND\s0 associated with the context.
\fBEVP_RAND_get0_name() returns the name of the random number generation algorithm.
\fBEVP_RAND_up_ref() returns 1 on success, 0 on error.
\fBEVP_RAND_names_do_all() returns 1 if the callback was called for all names. A return value of 0 means that the callback was not called for any names.
\fBEVP_RAND_CTX_new() returns either the newly allocated \fB\s-1EVP_RAND_CTX\s0 structure or \s-1NULL\s0 if an error occurred.
\fBEVP_RAND_CTX_free() does not return a value.
\fBEVP_RAND_nonce() returns the length of the nonce.
\fBEVP_RAND_get_strength() returns the strength of the random number generator in bits.
\fBEVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and \fBEVP_RAND_settable_ctx_params() return an array of OSSL_PARAMs.
\fBEVP_RAND_verify_zeroization() returns 1 if the internal \s-1DRBG\s0 state is currently zeroed, and 0 if not.
The remaining functions return 1 for success and 0 or a negative value for failure.
Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>.