diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man7/RAND.7')
| -rw-r--r-- | secure/lib/libcrypto/man/man7/RAND.7 | 141 |
1 files changed, 37 insertions, 104 deletions
diff --git a/secure/lib/libcrypto/man/man7/RAND.7 b/secure/lib/libcrypto/man/man7/RAND.7 index f2b8e4545944..f4e08aa1b066 100644 --- a/secure/lib/libcrypto/man/man7/RAND.7 +++ b/secure/lib/libcrypto/man/man7/RAND.7 @@ -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,91 +52,31 @@ . \} .\} .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 "RAND 7ossl" -.TH RAND 7ossl "2023-09-19" "3.0.11" "OpenSSL" +.TH RAND 7ossl 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 RAND \&\- the OpenSSL random generator -.SH "DESCRIPTION" +.SH DESCRIPTION .IX Header "DESCRIPTION" Random numbers are a vital part of cryptography, they are needed to provide unpredictability for tasks like key generation, creating salts, and many more. Software-based generators must be seeded with external randomness before they can be used as a cryptographically-secure pseudo-random number generator -(\s-1CSPRNG\s0). +(CSPRNG). The availability of common hardware with special instructions and modern operating systems, which may use items such as interrupt jitter and network packet timings, can be reasonable sources of seeding material. .PP -OpenSSL comes with a default implementation of the \s-1RAND API\s0 which is based on -the deterministic random bit generator (\s-1DRBG\s0) model as described in -[\s-1NIST SP 800\-90A\s0 Rev. 1]. The default random generator will initialize +OpenSSL comes with a default implementation of the RAND API which is based on +the deterministic random bit generator (DRBG) model as described in +[NIST SP 800\-90A Rev. 1]. The default random generator will initialize automatically on first use and will be fully functional without having to be initialized ('seeded') explicitly. It seeds and reseeds itself automatically using trusted random sources @@ -165,46 +89,55 @@ return value of \fBRAND_bytes\fR\|(3) and do not take randomness for granted. Although (re\-)seeding is automatic, it can fail because no trusted random source is available or the trusted source(s) temporarily fail to provide sufficient random seed material. -In this case the \s-1CSPRNG\s0 enters an error state and ceases to provide output, +In this case the CSPRNG enters an error state and ceases to provide output, until it is able to recover from the error by reseeding itself. -For more details on reseeding and error recovery, see \s-1\fBEVP_RAND\s0\fR\|(7). +For more details on reseeding and error recovery, see \fBEVP_RAND\fR\|(7). .PP For values that should remain secret, you can use \fBRAND_priv_bytes\fR\|(3) instead. This method does not provide 'better' randomness, it uses the same type of -\&\s-1CSPRNG.\s0 -The intention behind using a dedicated \s-1CSPRNG\s0 exclusively for private +CSPRNG. +The intention behind using a dedicated CSPRNG exclusively for private values is that none of its output should be visible to an attacker (e.g., used as salt value), in order to reveal as little information as -possible about its internal state, and that a compromise of the \*(L"public\*(R" -\&\s-1CSPRNG\s0 instance will not affect the secrecy of these private values. +possible about its internal state, and that a compromise of the "public" +CSPRNG instance will not affect the secrecy of these private values. .PP In the rare case where the default implementation does not satisfy your special -requirements, the default \s-1RAND\s0 internals can be replaced by your own -\&\s-1\fBEVP_RAND\s0\fR\|(3) objects. +requirements, the default RAND internals can be replaced by your own +\&\fBEVP_RAND\fR\|(3) objects. .PP Changing the default random generator should be necessary only in exceptional cases and is not recommended, unless you have a profound knowledge of cryptographic principles and understand the implications of your changes. +.PP +Finally, it is possible for a provider to bypass the default RAND setup for +\&\fBRAND_bytes\fR\|(3) and associated functions. A provider can be specified as the +single randomness source via the \fBRAND_set1_random_provider\fR\|(3) function or via +configuration using the \fBrandom_provider\fR option in \fBconfig\fR\|(5). Once specified, +the nominated provider will be used directly when calling the \fBRAND_bytes\fR\|(3) +family of functions. .SH "DEFAULT SETUP" .IX Header "DEFAULT SETUP" -The default OpenSSL \s-1RAND\s0 method is based on the \s-1EVP_RAND\s0 deterministic random -bit generator (\s-1DRBG\s0) classes. -A \s-1DRBG\s0 is a certain type of cryptographically-secure pseudo-random -number generator (\s-1CSPRNG\s0), which is described in [\s-1NIST SP 800\-90A\s0 Rev. 1]. +The default OpenSSL RAND method is based on the EVP_RAND deterministic random +bit generator (DRBG) classes. +A DRBG is a certain type of cryptographically-secure pseudo-random +number generator (CSPRNG), which is described in [NIST SP 800\-90A Rev. 1]. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBRAND_bytes\fR\|(3), \&\fBRAND_priv_bytes\fR\|(3), -\&\s-1\fBEVP_RAND\s0\fR\|(3), +\&\fBEVP_RAND\fR\|(3), \&\fBRAND_get0_primary\fR\|(3), -\&\s-1\fBEVP_RAND\s0\fR\|(7) -.SH "COPYRIGHT" +\&\fBconfig\fR\|(5), +\&\fBEVP_RAND\fR\|(7), +\&\fBRAND_set1_random_provider\fR\|(3). +.SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2018\-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>. |