diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/EVP_RAND.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/EVP_RAND.3 | 341 |
1 files changed, 128 insertions, 213 deletions
diff --git a/secure/lib/libcrypto/man/man3/EVP_RAND.3 b/secure/lib/libcrypto/man/man3/EVP_RAND.3 index 2358620a90f0..d69daad48404 100644 --- a/secure/lib/libcrypto/man/man3/EVP_RAND.3 +++ b/secure/lib/libcrypto/man/man3/EVP_RAND.3 @@ -1,4 +1,5 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== @@ -15,29 +16,12 @@ .ft R .fi .. -.\" 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 C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ -. 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\} .el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' . ds C` . ds C' 'br\} @@ -68,77 +52,17 @@ . \} .\} .rr rF -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. 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 -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. 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 -.\} -.rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "EVP_RAND 3ossl" -.TH EVP_RAND 3ossl "2023-09-19" "3.0.11" "OpenSSL" +.TH EVP_RAND 3ossl 2025-07-01 3.5.1 OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh -.SH "NAME" +.SH NAME EVP_RAND, EVP_RAND_fetch, EVP_RAND_free, EVP_RAND_up_ref, EVP_RAND_CTX, -EVP_RAND_CTX_new, EVP_RAND_CTX_free, EVP_RAND_instantiate, +EVP_RAND_CTX_new, EVP_RAND_CTX_free, EVP_RAND_CTX_up_ref, EVP_RAND_instantiate, EVP_RAND_uninstantiate, EVP_RAND_generate, EVP_RAND_reseed, EVP_RAND_nonce, EVP_RAND_enable_locking, EVP_RAND_verify_zeroization, EVP_RAND_get_strength, EVP_RAND_get_state, @@ -151,7 +75,7 @@ EVP_RAND_gettable_ctx_params, EVP_RAND_settable_ctx_params, EVP_RAND_CTX_gettable_params, EVP_RAND_CTX_settable_params, EVP_RAND_gettable_params, EVP_RAND_STATE_UNINITIALISED, EVP_RAND_STATE_READY, EVP_RAND_STATE_ERROR \- EVP RAND routines -.SH "SYNOPSIS" +.SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& #include <openssl/evp.h> @@ -165,6 +89,7 @@ EVP_RAND_STATE_ERROR \- EVP RAND routines \& void EVP_RAND_free(EVP_RAND *rand); \& EVP_RAND_CTX *EVP_RAND_CTX_new(EVP_RAND *rand, EVP_RAND_CTX *parent); \& void EVP_RAND_CTX_free(EVP_RAND_CTX *ctx); +\& int EVP_RAND_CTX_up_ref(EVP_RAND_CTX *ctx); \& EVP_RAND *EVP_RAND_CTX_get0_rand(EVP_RAND_CTX *ctx); \& int EVP_RAND_get_params(EVP_RAND *rand, OSSL_PARAM params[]); \& int EVP_RAND_CTX_get_params(EVP_RAND_CTX *ctx, OSSL_PARAM params[]); @@ -206,89 +131,86 @@ EVP_RAND_STATE_ERROR \- EVP RAND routines \& #define EVP_RAND_STATE_READY 1 \& #define EVP_RAND_STATE_ERROR 2 .Ve -.SH "DESCRIPTION" +.SH DESCRIPTION .IX Header "DESCRIPTION" -The \s-1EVP RAND\s0 routines are a high-level interface to random number generators +The EVP RAND routines are a high-level interface to random number generators both deterministic and not. If you just want to generate random bytes then you don't need to use these functions: just call \fBRAND_bytes()\fR or \fBRAND_priv_bytes()\fR. If you want to do more, these calls should be used instead of the older -\&\s-1RAND\s0 and \s-1RAND_DRBG\s0 functions. +RAND and RAND_DRBG functions. .PP -After creating a \fB\s-1EVP_RAND_CTX\s0\fR for the required algorithm using +After creating a \fBEVP_RAND_CTX\fR for the required algorithm using \&\fBEVP_RAND_CTX_new()\fR, inputs to the algorithm are supplied either by passing them as part of the \fBEVP_RAND_instantiate()\fR call or using calls to \&\fBEVP_RAND_CTX_set_params()\fR before calling \fBEVP_RAND_instantiate()\fR. Finally, call \fBEVP_RAND_generate()\fR to produce cryptographically secure random bytes. -.SS "Types" +.SS Types .IX Subsection "Types" -\&\fB\s-1EVP_RAND\s0\fR is a type that holds the implementation of a \s-1RAND.\s0 +\&\fBEVP_RAND\fR is a type that holds the implementation of a RAND. .PP -\&\fB\s-1EVP_RAND_CTX\s0\fR is a context type that holds the algorithm inputs. -\&\fB\s-1EVP_RAND_CTX\s0\fR structures are reference counted. +\&\fBEVP_RAND_CTX\fR is a context type that holds the algorithm inputs. +\&\fBEVP_RAND_CTX\fR structures are reference counted. .SS "Algorithm implementation fetching" .IX Subsection "Algorithm implementation fetching" -\&\fBEVP_RAND_fetch()\fR fetches an implementation of a \s-1RAND\s0 \fIalgorithm\fR, given +\&\fBEVP_RAND_fetch()\fR fetches an implementation of a RAND \fIalgorithm\fR, given a library context \fIlibctx\fR and a set of \fIproperties\fR. -See \*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fBcrypto\fR\|(7) for further information. +See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further information. .PP The returned value must eventually be freed with \&\fBEVP_RAND_free\fR\|(3). .PP \&\fBEVP_RAND_up_ref()\fR increments the reference count of an already fetched -\&\s-1RAND.\s0 +RAND. .PP \&\fBEVP_RAND_free()\fR frees a fetched algorithm. -\&\s-1NULL\s0 is a valid parameter, for which this function is a no-op. +NULL is a valid parameter, for which this function is a no-op. .SS "Context manipulation functions" .IX Subsection "Context manipulation functions" -\&\fBEVP_RAND_CTX_new()\fR creates a new context for the \s-1RAND\s0 implementation \fIrand\fR. -If not \s-1NULL,\s0 \fIparent\fR specifies the seed source for this implementation. +\&\fBEVP_RAND_CTX_new()\fR creates a new context for the RAND implementation \fIrand\fR. +If not NULL, \fIparent\fR specifies the seed source for this implementation. Not all random number generators need to have a seed source specified. -If a parent is required, a \s-1NULL\s0 \fIparent\fR will utilise the operating +If a parent is required, a NULL \fIparent\fR will utilise the operating system entropy sources. It is recommended to minimise the number of random number generators that rely on the operating system for their randomness because this is often scarce. .PP -\&\fBEVP_RAND_CTX_free()\fR frees up the context \fIctx\fR. If \fIctx\fR is \s-1NULL,\s0 nothing +\&\fBEVP_RAND_CTX_free()\fR frees up the context \fIctx\fR. If \fIctx\fR is NULL, nothing is done. .PP -\&\fBEVP_RAND_CTX_get0_rand()\fR returns the \fB\s-1EVP_RAND\s0\fR associated with the context +\&\fBEVP_RAND_CTX_get0_rand()\fR returns the \fBEVP_RAND\fR associated with the context \&\fIctx\fR. .SS "Random Number Generator Functions" .IX Subsection "Random Number Generator Functions" \&\fBEVP_RAND_instantiate()\fR processes any parameters in \fIparams\fR and -then instantiates the \s-1RAND\s0 \fIctx\fR with a minimum security strength +then instantiates the RAND \fIctx\fR with a minimum security strength of <strength> and personalisation string \fIpstr\fR of length <pstr_len>. If \fIprediction_resistance\fR 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 +will be sought. This call operates as per NIST SP 800\-90A and SP 800\-90C. .PP -\&\fBEVP_RAND_uninstantiate()\fR uninstantiates the \s-1RAND\s0 \fIctx\fR as per -\&\s-1NIST SP 800\-90A\s0 and \s-1SP 800\-90C.\s0 Subsequent to this call, the \s-1RAND\s0 cannot +\&\fBEVP_RAND_uninstantiate()\fR uninstantiates the RAND \fIctx\fR as per +NIST SP 800\-90A and SP 800\-90C. Subsequent to this call, the RAND cannot be used to generate bytes. It can only be freed or instantiated again. .PP -\&\fBEVP_RAND_generate()\fR produces random bytes from the \s-1RAND\s0 \fIctx\fR with the +\&\fBEVP_RAND_generate()\fR produces random bytes from the RAND \fIctx\fR with the additional input \fIaddin\fR of length \fIaddin_len\fR. The bytes produced will meet the security \fIstrength\fR. If \fIprediction_resistance\fR 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 +will be sought. This call operates as per NIST SP 800\-90A and SP 800\-90C. .PP -\&\fBEVP_RAND_reseed()\fR reseeds the \s-1RAND\s0 with new entropy. +\&\fBEVP_RAND_reseed()\fR reseeds the RAND with new entropy. Entropy \fIent\fR of length \fIent_len\fR bytes can be supplied as can additional -input \fIaddin\fR of length \fIaddin_len\fR 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 +input \fIaddin\fR of length \fIaddin_len\fR bytes. In the FIPS provider, both are +treated as additional input as per NIST SP\-800\-90Ar1, Sections 9.1 and 9.2. +Additional seed material is also drawn from the RAND's parent or the operating system. If \fIprediction_resistance\fR 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 +from a live source will be sought. This call operates as per NIST SP 800\-90A +and SP 800\-90C. .PP -\&\fBEVP_RAND_nonce()\fR creates a nonce in \fIout\fR of maximum length \fIoutlen\fR -bytes from the \s-1RAND\s0 \fIctx\fR. The function returns the length of the generated -nonce. If \fIout\fR 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_nonce()\fR creates a nonce in \fIout\fR of length \fIoutlen\fR +bytes from the RAND \fIctx\fR. .PP -\&\fBEVP_RAND_enable_locking()\fR enables locking for the \s-1RAND\s0 \fIctx\fR and all of +\&\fBEVP_RAND_enable_locking()\fR enables locking for the RAND \fIctx\fR and all of its parents. After this \fIctx\fR will operate in a thread safe manner, albeit more slowly. This function is not itself thread safe if called with the same \&\fIctx\fR from multiple threads. Typically locking should be enabled before a @@ -317,36 +239,36 @@ simply ignored. Also, what happens when a needed parameter isn't passed down is defined by the implementation. .PP -\&\fBEVP_RAND_gettable_params()\fR returns an \s-1\fBOSSL_PARAM\s0\fR\|(3) array that describes +\&\fBEVP_RAND_gettable_params()\fR returns an \fBOSSL_PARAM\fR\|(3) array that describes the retrievable and settable parameters. \fBEVP_RAND_gettable_params()\fR returns parameters that can be used with \fBEVP_RAND_get_params()\fR. .PP \&\fBEVP_RAND_gettable_ctx_params()\fR and \fBEVP_RAND_CTX_gettable_params()\fR return -constant \s-1\fBOSSL_PARAM\s0\fR\|(3) arrays that describe the retrievable parameters that +constant \fBOSSL_PARAM\fR\|(3) arrays that describe the retrievable parameters that can be used with \fBEVP_RAND_CTX_get_params()\fR. \fBEVP_RAND_gettable_ctx_params()\fR returns the parameters that can be retrieved from the algorithm, whereas \&\fBEVP_RAND_CTX_gettable_params()\fR returns the parameters that can be retrieved in the context's current state. .PP \&\fBEVP_RAND_settable_ctx_params()\fR and \fBEVP_RAND_CTX_settable_params()\fR return -constant \s-1\fBOSSL_PARAM\s0\fR\|(3) arrays that describe the settable parameters that +constant \fBOSSL_PARAM\fR\|(3) arrays that describe the settable parameters that can be used with \fBEVP_RAND_CTX_set_params()\fR. \fBEVP_RAND_settable_ctx_params()\fR returns the parameters that can be retrieved from the algorithm, whereas \&\fBEVP_RAND_CTX_settable_params()\fR returns the parameters that can be retrieved in the context's current state. .SS "Information functions" .IX Subsection "Information functions" -\&\fBEVP_RAND_get_strength()\fR returns the security strength of the \s-1RAND\s0 \fIctx\fR. +\&\fBEVP_RAND_get_strength()\fR returns the security strength of the RAND \fIctx\fR. .PP -\&\fBEVP_RAND_get_state()\fR returns the current state of the \s-1RAND\s0 \fIctx\fR. +\&\fBEVP_RAND_get_state()\fR returns the current state of the RAND \fIctx\fR. States defined by the OpenSSL RNGs are: -.IP "\(bu" 4 -\&\s-1EVP_RAND_STATE_UNINITIALISED:\s0 this \s-1RNG\s0 is currently uninitialised. +.IP \(bu 4 +EVP_RAND_STATE_UNINITIALISED: this RNG is currently uninitialised. The instantiate call will change this to the ready state. -.IP "\(bu" 4 -\&\s-1EVP_RAND_STATE_READY:\s0 this \s-1RNG\s0 is currently ready to generate output. -.IP "\(bu" 4 -\&\s-1EVP_RAND_STATE_ERROR:\s0 this \s-1RNG\s0 is in an error state. +.IP \(bu 4 +EVP_RAND_STATE_READY: this RNG is currently ready to generate output. +.IP \(bu 4 +EVP_RAND_STATE_ERROR: this RNG is in an error state. .PP \&\fBEVP_RAND_is_a()\fR returns 1 if \fIrand\fR is an implementation of an algorithm that's identifiable with \fIname\fR, otherwise 0. @@ -354,7 +276,7 @@ algorithm that's identifiable with \fIname\fR, otherwise 0. \&\fBEVP_RAND_get0_provider()\fR returns the provider that holds the implementation of the given \fIrand\fR. .PP -\&\fBEVP_RAND_do_all_provided()\fR traverses all \s-1RAND\s0 implemented by all activated +\&\fBEVP_RAND_do_all_provided()\fR traverses all RAND implemented by all activated providers in the given library context \fIlibctx\fR, and for each of the implementations, calls the given function \fIfn\fR with the implementation method and the given \fIarg\fR as argument. @@ -368,93 +290,82 @@ and the given \fIarg\fR as argument. display and human consumption. The description is at the discretion of the rand implementation. .PP -\&\fBEVP_RAND_verify_zeroization()\fR confirms if the internal \s-1DRBG\s0 state is -currently zeroed. This is used by the \s-1FIPS\s0 provider to support the mandatory +\&\fBEVP_RAND_verify_zeroization()\fR confirms if the internal DRBG state is +currently zeroed. This is used by the FIPS provider to support the mandatory self tests. -.SH "PARAMETERS" +.SH PARAMETERS .IX Header "PARAMETERS" The standard parameter names are: -.ie n .IP """state"" (\fB\s-1OSSL_RAND_PARAM_STATE\s0\fR) <integer>" 4 -.el .IP "``state'' (\fB\s-1OSSL_RAND_PARAM_STATE\s0\fR) <integer>" 4 -.IX Item "state (OSSL_RAND_PARAM_STATE) <integer>" +.IP """state"" (\fBOSSL_RAND_PARAM_STATE\fR) <integer>" 4 +.IX Item """state"" (OSSL_RAND_PARAM_STATE) <integer>" Returns the state of the random number generator. -.ie n .IP """strength"" (\fB\s-1OSSL_RAND_PARAM_STRENGTH\s0\fR) <unsigned integer>" 4 -.el .IP "``strength'' (\fB\s-1OSSL_RAND_PARAM_STRENGTH\s0\fR) <unsigned integer>" 4 -.IX Item "strength (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>" +.IP """strength"" (\fBOSSL_RAND_PARAM_STRENGTH\fR) <unsigned integer>" 4 +.IX Item """strength"" (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>" Returns the bit strength of the random number generator. +.IP """fips-indicator"" (\fBOSSL_RAND_PARAM_FIPS_APPROVED_INDICATOR\fR) <integer>" 4 +.IX Item """fips-indicator"" (OSSL_RAND_PARAM_FIPS_APPROVED_INDICATOR) <integer>" +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This option is used by the OpenSSL FIPS provider and is not supported +by all EVP_RAND sources. .PP 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: -.ie n .IP """reseed_requests"" (\fB\s-1OSSL_DRBG_PARAM_RESEED_REQUESTS\s0\fR) <unsigned integer>" 4 -.el .IP "``reseed_requests'' (\fB\s-1OSSL_DRBG_PARAM_RESEED_REQUESTS\s0\fR) <unsigned integer>" 4 -.IX Item "reseed_requests (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>" +parameters are relevant to, or are understood by all DRBG rands: +.IP """reseed_requests"" (\fBOSSL_DRBG_PARAM_RESEED_REQUESTS\fR) <unsigned integer>" 4 +.IX 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. -.ie n .IP """reseed_time_interval"" (\fB\s-1OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL\s0\fR) <integer>" 4 -.el .IP "``reseed_time_interval'' (\fB\s-1OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL\s0\fR) <integer>" 4 -.IX Item "reseed_time_interval (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) <integer>" +associated RAND ctx. +.IP """reseed_time_interval"" (\fBOSSL_DRBG_PARAM_RESEED_TIME_INTERVAL\fR) <integer>" 4 +.IX 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. -.ie n .IP """max_request"" (\fB\s-1OSSL_DRBG_PARAM_RESEED_REQUESTS\s0\fR) <unsigned integer>" 4 -.el .IP "``max_request'' (\fB\s-1OSSL_DRBG_PARAM_RESEED_REQUESTS\s0\fR) <unsigned integer>" 4 -.IX Item "max_request (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>" +associated RAND ctx. +.IP """max_request"" (\fBOSSL_RAND_PARAM_MAX_REQUEST\fR) <unsigned integer>" 4 +.IX Item """max_request"" (OSSL_RAND_PARAM_MAX_REQUEST) <unsigned integer>" Specifies the maximum number of bytes that can be generated in a single call to OSSL_FUNC_rand_generate. -.ie n .IP """min_entropylen"" (\fB\s-1OSSL_DRBG_PARAM_MIN_ENTROPYLEN\s0\fR) <unsigned integer>" 4 -.el .IP "``min_entropylen'' (\fB\s-1OSSL_DRBG_PARAM_MIN_ENTROPYLEN\s0\fR) <unsigned integer>" 4 -.IX Item "min_entropylen (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <unsigned integer>" +.IP """min_entropylen"" (\fBOSSL_DRBG_PARAM_MIN_ENTROPYLEN\fR) <unsigned integer>" 4 +.IX Item """min_entropylen"" (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <unsigned integer>" .PD 0 -.ie n .IP """max_entropylen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_ENTROPYLEN\s0\fR) <unsigned integer>" 4 -.el .IP "``max_entropylen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_ENTROPYLEN\s0\fR) <unsigned integer>" 4 -.IX Item "max_entropylen (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <unsigned integer>" +.IP """max_entropylen"" (\fBOSSL_DRBG_PARAM_MAX_ENTROPYLEN\fR) <unsigned integer>" 4 +.IX Item """max_entropylen"" (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <unsigned integer>" .PD Specify the minimum and maximum number of bytes of random material that -can be used to seed the \s-1DRBG.\s0 -.ie n .IP """min_noncelen"" (\fB\s-1OSSL_DRBG_PARAM_MIN_NONCELEN\s0\fR) <unsigned integer>" 4 -.el .IP "``min_noncelen'' (\fB\s-1OSSL_DRBG_PARAM_MIN_NONCELEN\s0\fR) <unsigned integer>" 4 -.IX Item "min_noncelen (OSSL_DRBG_PARAM_MIN_NONCELEN) <unsigned integer>" +can be used to seed the DRBG. +.IP """min_noncelen"" (\fBOSSL_DRBG_PARAM_MIN_NONCELEN\fR) <unsigned integer>" 4 +.IX Item """min_noncelen"" (OSSL_DRBG_PARAM_MIN_NONCELEN) <unsigned integer>" .PD 0 -.ie n .IP """max_noncelen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_NONCELEN\s0\fR) <unsigned integer>" 4 -.el .IP "``max_noncelen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_NONCELEN\s0\fR) <unsigned integer>" 4 -.IX Item "max_noncelen (OSSL_DRBG_PARAM_MAX_NONCELEN) <unsigned integer>" +.IP """max_noncelen"" (\fBOSSL_DRBG_PARAM_MAX_NONCELEN\fR) <unsigned integer>" 4 +.IX Item """max_noncelen"" (OSSL_DRBG_PARAM_MAX_NONCELEN) <unsigned integer>" .PD Specify the minimum and maximum number of bytes of nonce that can be used to -seed the \s-1DRBG.\s0 -.ie n .IP """max_perslen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_PERSLEN\s0\fR) <unsigned integer>" 4 -.el .IP "``max_perslen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_PERSLEN\s0\fR) <unsigned integer>" 4 -.IX Item "max_perslen (OSSL_DRBG_PARAM_MAX_PERSLEN) <unsigned integer>" +seed the DRBG. +.IP """max_perslen"" (\fBOSSL_DRBG_PARAM_MAX_PERSLEN\fR) <unsigned integer>" 4 +.IX Item """max_perslen"" (OSSL_DRBG_PARAM_MAX_PERSLEN) <unsigned integer>" .PD 0 -.ie n .IP """max_adinlen"" (\fB\s-1OSSL_DRBG_PARAM_MAX_ADINLEN\s0\fR) <unsigned integer>" 4 -.el .IP "``max_adinlen'' (\fB\s-1OSSL_DRBG_PARAM_MAX_ADINLEN\s0\fR) <unsigned integer>" 4 -.IX Item "max_adinlen (OSSL_DRBG_PARAM_MAX_ADINLEN) <unsigned integer>" +.IP """max_adinlen"" (\fBOSSL_DRBG_PARAM_MAX_ADINLEN\fR) <unsigned integer>" 4 +.IX Item """max_adinlen"" (OSSL_DRBG_PARAM_MAX_ADINLEN) <unsigned integer>" .PD Specify the minimum and maximum number of bytes of personalisation string -that can be used with the \s-1DRBG.\s0 -.ie n .IP """reseed_counter"" (\fB\s-1OSSL_DRBG_PARAM_RESEED_COUNTER\s0\fR) <unsigned integer>" 4 -.el .IP "``reseed_counter'' (\fB\s-1OSSL_DRBG_PARAM_RESEED_COUNTER\s0\fR) <unsigned integer>" 4 -.IX Item "reseed_counter (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>" -Specifies the number of times the \s-1DRBG\s0 has been seeded or reseeded. -.ie n .IP """properties"" (\fB\s-1OSSL_RAND_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 -.el .IP "``properties'' (\fB\s-1OSSL_RAND_PARAM_PROPERTIES\s0\fR) <\s-1UTF8\s0 string>" 4 -.IX Item "properties (OSSL_RAND_PARAM_PROPERTIES) <UTF8 string>" +that can be used with the DRBG. +.IP """reseed_counter"" (\fBOSSL_DRBG_PARAM_RESEED_COUNTER\fR) <unsigned integer>" 4 +.IX Item """reseed_counter"" (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>" +Specifies the number of times the DRBG has been seeded or reseeded. +.IP """properties"" (\fBOSSL_RAND_PARAM_PROPERTIES\fR) <UTF8 string>" 4 +.IX Item """properties"" (OSSL_RAND_PARAM_PROPERTIES) <UTF8 string>" .PD 0 -.ie n .IP """mac"" (\fB\s-1OSSL_RAND_PARAM_MAC\s0\fR) <\s-1UTF8\s0 string>" 4 -.el .IP "``mac'' (\fB\s-1OSSL_RAND_PARAM_MAC\s0\fR) <\s-1UTF8\s0 string>" 4 -.IX Item "mac (OSSL_RAND_PARAM_MAC) <UTF8 string>" -.ie n .IP """digest"" (\fB\s-1OSSL_RAND_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 -.el .IP "``digest'' (\fB\s-1OSSL_RAND_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 -.IX Item "digest (OSSL_RAND_PARAM_DIGEST) <UTF8 string>" -.ie n .IP """cipher"" (\fB\s-1OSSL_RAND_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 -.el .IP "``cipher'' (\fB\s-1OSSL_RAND_PARAM_CIPHER\s0\fR) <\s-1UTF8\s0 string>" 4 -.IX Item "cipher (OSSL_RAND_PARAM_CIPHER) <UTF8 string>" +.IP """mac"" (\fBOSSL_RAND_PARAM_MAC\fR) <UTF8 string>" 4 +.IX Item """mac"" (OSSL_RAND_PARAM_MAC) <UTF8 string>" +.IP """digest"" (\fBOSSL_RAND_PARAM_DIGEST\fR) <UTF8 string>" 4 +.IX Item """digest"" (OSSL_RAND_PARAM_DIGEST) <UTF8 string>" +.IP """cipher"" (\fBOSSL_RAND_PARAM_CIPHER\fR) <UTF8 string>" 4 +.IX Item """cipher"" (OSSL_RAND_PARAM_CIPHER) <UTF8 string>" .PD -For \s-1RAND\s0 implementations that use an underlying computation \s-1MAC,\s0 digest or +For RAND implementations that use an underlying computation MAC, 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 \fB\s-1OSSL_RAND_PARAM_PROPERTIES\s0\fR. -.SH "NOTES" +or the properties in the case of \fBOSSL_RAND_PARAM_PROPERTIES\fR. +.SH NOTES .IX Header "NOTES" The use of a nonzero value for the \fIprediction_resistance\fR argument to \&\fBEVP_RAND_instantiate()\fR, \fBEVP_RAND_generate()\fR or \fBEVP_RAND_reseed()\fR should @@ -462,28 +373,28 @@ be used sparingly. In the default setup, this will cause all public and private DRBGs to be reseeded on next use. Since, by default, public and private DRBGs are allocated on a per thread basis, this can result in significant overhead for highly multi-threaded applications. For normal -use-cases, the default \*(L"reseed_requests\*(R" and \*(L"reseed_time_interval\*(R" +use-cases, the default "reseed_requests" and "reseed_time_interval" thresholds ensure sufficient prediction resistance over time and you can reduce those values if you think they are too high. Explicitly requesting prediction resistance is intended for more special use-cases like generating long-term secrets. .PP -An \fB\s-1EVP_RAND_CTX\s0\fR needs to have locking enabled if it acts as the parent of +An \fBEVP_RAND_CTX\fR 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 \fBEVP_RAND_enable_locking()\fR. .PP -The \s-1RAND\s0 life-cycle is described in \fBlife_cycle\-rand\fR\|(7). In the future, +The RAND life-cycle is described in \fBlife_cycle\-rand\fR\|(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 +not be considered a breaking change to the API. .SH "RETURN VALUES" .IX Header "RETURN VALUES" -\&\fBEVP_RAND_fetch()\fR returns a pointer to a newly fetched \fB\s-1EVP_RAND\s0\fR, or -\&\s-1NULL\s0 if allocation failed. +\&\fBEVP_RAND_fetch()\fR returns a pointer to a newly fetched \fBEVP_RAND\fR, or +NULL if allocation failed. .PP -\&\fBEVP_RAND_get0_provider()\fR returns a pointer to the provider for the \s-1RAND,\s0 or -\&\s-1NULL\s0 on error. +\&\fBEVP_RAND_get0_provider()\fR returns a pointer to the provider for the RAND, or +NULL on error. .PP -\&\fBEVP_RAND_CTX_get0_rand()\fR returns a pointer to the \fB\s-1EVP_RAND\s0\fR associated +\&\fBEVP_RAND_CTX_get0_rand()\fR returns a pointer to the \fBEVP_RAND\fR associated with the context. .PP \&\fBEVP_RAND_get0_name()\fR returns the name of the random number generation @@ -495,11 +406,13 @@ algorithm. return value of 0 means that the callback was not called for any names. .PP \&\fBEVP_RAND_CTX_new()\fR returns either the newly allocated -\&\fB\s-1EVP_RAND_CTX\s0\fR structure or \s-1NULL\s0 if an error occurred. +\&\fBEVP_RAND_CTX\fR structure or NULL if an error occurred. .PP \&\fBEVP_RAND_CTX_free()\fR does not return a value. .PP -\&\fBEVP_RAND_nonce()\fR returns the length of the nonce. +\&\fBEVP_RAND_CTX_up_ref()\fR returns 1 on success, 0 on error. +.PP +\&\fBEVP_RAND_nonce()\fR returns 1 on success, 0 on error. .PP \&\fBEVP_RAND_get_strength()\fR returns the strength of the random number generator in bits. @@ -507,7 +420,7 @@ in bits. \&\fBEVP_RAND_gettable_params()\fR, \fBEVP_RAND_gettable_ctx_params()\fR and \&\fBEVP_RAND_settable_ctx_params()\fR return an array of OSSL_PARAMs. .PP -\&\fBEVP_RAND_verify_zeroization()\fR returns 1 if the internal \s-1DRBG\s0 state is +\&\fBEVP_RAND_verify_zeroization()\fR returns 1 if the internal DRBG state is currently zeroed, and 0 if not. .PP The remaining functions return 1 for success and 0 or a negative value for @@ -515,20 +428,22 @@ failure. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBRAND_bytes\fR\|(3), -\&\s-1\fBEVP_RAND\-CTR\-DRBG\s0\fR\|(7), -\&\s-1\fBEVP_RAND\-HASH\-DRBG\s0\fR\|(7), -\&\s-1\fBEVP_RAND\-HMAC\-DRBG\s0\fR\|(7), -\&\s-1\fBEVP_RAND\-TEST\-RAND\s0\fR\|(7), +\&\fBEVP_RAND\-CTR\-DRBG\fR\|(7), +\&\fBEVP_RAND\-HASH\-DRBG\fR\|(7), +\&\fBEVP_RAND\-HMAC\-DRBG\fR\|(7), +\&\fBEVP_RAND\-TEST\-RAND\fR\|(7), \&\fBprovider\-rand\fR\|(7), \&\fBlife_cycle\-rand\fR\|(7) -.SH "HISTORY" +.SH HISTORY .IX Header "HISTORY" -This functionality was added to OpenSSL 3.0. -.SH "COPYRIGHT" +\&\fBEVP_RAND_CTX_up_ref()\fR was added in OpenSSL 3.1. +.PP +The remaining functions were added in OpenSSL 3.0. +.SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2020\-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020\-2025 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use +Licensed under the Apache License 2.0 (the "License"). 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 +in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>. |