diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man7/RAND_DRBG.7')
| -rw-r--r-- | secure/lib/libcrypto/man/man7/RAND_DRBG.7 | 396 |
1 files changed, 0 insertions, 396 deletions
diff --git a/secure/lib/libcrypto/man/man7/RAND_DRBG.7 b/secure/lib/libcrypto/man/man7/RAND_DRBG.7 deleted file mode 100644 index 816c53ac3cff..000000000000 --- a/secure/lib/libcrypto/man/man7/RAND_DRBG.7 +++ /dev/null @@ -1,396 +0,0 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.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' -.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\} -.\" -.\" Escape single quotes in literal strings from groff's Unicode transform. -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.\" -.\" 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'. -.de IX -.. -.nr rF 0 -.if \n(.g .if rF .nr rF 1 -.if (\n(rF:(\n(.g==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 -.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_DRBG 7" -.TH RAND_DRBG 7 "2022-07-05" "1.1.1q" "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" -RAND_DRBG \- the deterministic random bit generator -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 1 -\& #include <openssl/rand_drbg.h> -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The default OpenSSL \s-1RAND\s0 method is based on the \s-1RAND_DRBG\s0 class, -which implements a deterministic random bit generator (\s-1DRBG\s0). -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]. -.PP -While the \s-1RAND API\s0 is the 'frontend' which is intended to be used by -application developers for obtaining random bytes, the \s-1RAND_DRBG API\s0 -serves as the 'backend', connecting the former with the operating -systems's entropy sources and providing access to the \s-1DRBG\s0's -configuration parameters. -.SS "Disclaimer" -.IX Subsection "Disclaimer" -Unless you have very specific requirements for your random generator, -it is in general not necessary to utilize the \s-1RAND_DRBG API\s0 directly. -The usual way to obtain random bytes is to use \fBRAND_bytes\fR\|(3) or -\&\fBRAND_priv_bytes\fR\|(3), see also \s-1\fBRAND\s0\fR\|(7). -.SS "Typical Use Cases" -.IX Subsection "Typical Use Cases" -Typical examples for such special use cases are the following: -.IP "\(bu" 2 -You want to use your own private \s-1DRBG\s0 instances. -Multiple \s-1DRBG\s0 instances which are accessed only by a single thread provide -additional security (because their internal states are independent) and -better scalability in multithreaded applications (because they don't need -to be locked). -.IP "\(bu" 2 -You need to integrate a previously unsupported entropy source. -.IP "\(bu" 2 -You need to change the default settings of the standard OpenSSL \s-1RAND\s0 -implementation to meet specific requirements. -.SH "CHAINING" -.IX Header "CHAINING" -A \s-1DRBG\s0 instance can be used as the entropy source of another \s-1DRBG\s0 instance, -provided it has itself access to a valid entropy source. -The \s-1DRBG\s0 instance which acts as entropy source is called the \fIparent\fR \s-1DRBG,\s0 -the other instance the \fIchild\fR \s-1DRBG.\s0 -.PP -This is called chaining. A chained \s-1DRBG\s0 instance is created by passing -a pointer to the parent \s-1DRBG\s0 as argument to the \fBRAND_DRBG_new()\fR call. -It is possible to create chains of more than two \s-1DRBG\s0 in a row. -.SH "THE THREE SHARED DRBG INSTANCES" -.IX Header "THE THREE SHARED DRBG INSTANCES" -Currently, there are three shared \s-1DRBG\s0 instances, -the <master>, <public>, and <private> \s-1DRBG.\s0 -While the <master> \s-1DRBG\s0 is a single global instance, the <public> and <private> -\&\s-1DRBG\s0 are created per thread and accessed through thread-local storage. -.PP -By default, the functions \fBRAND_bytes\fR\|(3) and \fBRAND_priv_bytes\fR\|(3) use -the thread-local <public> and <private> \s-1DRBG\s0 instance, respectively. -.SS "The <master> \s-1DRBG\s0 instance" -.IX Subsection "The <master> DRBG instance" -The <master> \s-1DRBG\s0 is not used directly by the application, only for reseeding -the two other two \s-1DRBG\s0 instances. It reseeds itself by obtaining randomness -either from os entropy sources or by consuming randomness which was added -previously by \fBRAND_add\fR\|(3). -.SS "The <public> \s-1DRBG\s0 instance" -.IX Subsection "The <public> DRBG instance" -This instance is used per default by \fBRAND_bytes\fR\|(3). -.SS "The <private> \s-1DRBG\s0 instance" -.IX Subsection "The <private> DRBG instance" -This instance is used per default by \fBRAND_priv_bytes\fR\|(3) -.SH "LOCKING" -.IX Header "LOCKING" -The <master> \s-1DRBG\s0 is intended to be accessed concurrently for reseeding -by its child \s-1DRBG\s0 instances. The necessary locking is done internally. -It is \fInot\fR thread-safe to access the <master> \s-1DRBG\s0 directly via the -\&\s-1RAND_DRBG\s0 interface. -The <public> and <private> \s-1DRBG\s0 are thread-local, i.e. there is an -instance of each per thread. So they can safely be accessed without -locking via the \s-1RAND_DRBG\s0 interface. -.PP -Pointers to these \s-1DRBG\s0 instances can be obtained using -\&\fBRAND_DRBG_get0_master()\fR, -\&\fBRAND_DRBG_get0_public()\fR, and -\&\fBRAND_DRBG_get0_private()\fR, respectively. -Note that it is not allowed to store a pointer to one of the thread-local -\&\s-1DRBG\s0 instances in a variable or other memory location where it will be -accessed and used by multiple threads. -.PP -All other \s-1DRBG\s0 instances created by an application don't support locking, -because they are intended to be used by a single thread. -Instead of accessing a single \s-1DRBG\s0 instance concurrently from different -threads, it is recommended to instantiate a separate \s-1DRBG\s0 instance per -thread. Using the <master> \s-1DRBG\s0 as entropy source for multiple \s-1DRBG\s0 -instances on different threads is thread-safe, because the \s-1DRBG\s0 instance -will lock the <master> \s-1DRBG\s0 automatically for obtaining random input. -.SH "THE OVERALL PICTURE" -.IX Header "THE OVERALL PICTURE" -The following picture gives an overview over how the \s-1DRBG\s0 instances work -together and are being used. -.PP -.Vb 10 -\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ -\& | os entropy sources | -\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ -\& | -\& v +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ -\& RAND_add() ==> <master> <\-| shared DRBG (with locking) | -\& / \e +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ -\& / \e +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ -\& <public> <private> <\- | per\-thread DRBG instances | -\& | | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ -\& v v -\& RAND_bytes() RAND_priv_bytes() -\& | ^ -\& | | -\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ -\& | general purpose | | used for secrets like session keys | -\& | random generator | | and private keys for certificates | -\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ -.Ve -.PP -The usual way to obtain random bytes is to call RAND_bytes(...) or -RAND_priv_bytes(...). These calls are roughly equivalent to calling -RAND_DRBG_bytes(<public>, ...) and RAND_DRBG_bytes(<private>, ...), -respectively. The method \fBRAND_DRBG_bytes\fR\|(3) is a convenience method -wrapping the \fBRAND_DRBG_generate\fR\|(3) function, which serves the actual -request for random data. -.SH "RESEEDING" -.IX Header "RESEEDING" -A \s-1DRBG\s0 instance seeds itself automatically, pulling random input from -its entropy source. The entropy source can be either a trusted operating -system entropy source, or another \s-1DRBG\s0 with access to such a source. -.PP -Automatic reseeding occurs after a predefined number of generate requests. -The selection of the trusted entropy sources is configured at build -time using the \-\-with\-rand\-seed option. The following sections explain -the reseeding process in more detail. -.SS "Automatic Reseeding" -.IX Subsection "Automatic Reseeding" -Before satisfying a generate request (\fBRAND_DRBG_generate\fR\|(3)), the \s-1DRBG\s0 -reseeds itself automatically, if one of the following conditions holds: -.PP -\&\- the \s-1DRBG\s0 was not instantiated (=seeded) yet or has been uninstantiated. -.PP -\&\- the number of generate requests since the last reseeding exceeds a -certain threshold, the so called \fIreseed_interval\fR. -This behaviour can be disabled by setting the \fIreseed_interval\fR to 0. -.PP -\&\- the time elapsed since the last reseeding exceeds a certain time -interval, the so called \fIreseed_time_interval\fR. -This can be disabled by setting the \fIreseed_time_interval\fR to 0. -.PP -\&\- the \s-1DRBG\s0 is in an error state. -.PP -\&\fBNote\fR: An error state is entered if the entropy source fails while -the \s-1DRBG\s0 is seeding or reseeding. -The last case ensures that the \s-1DRBG\s0 automatically recovers -from the error as soon as the entropy source is available again. -.SS "Manual Reseeding" -.IX Subsection "Manual Reseeding" -In addition to automatic reseeding, the caller can request an immediate -reseeding of the \s-1DRBG\s0 with fresh entropy by setting the -\&\fIprediction resistance\fR parameter to 1 when calling \fBRAND_DRBG_generate\fR\|(3). -.PP -The document [\s-1NIST SP 800\-90C\s0] describes prediction resistance requests -in detail and imposes strict conditions on the entropy sources that are -approved for providing prediction resistance. -Since the default \s-1DRBG\s0 implementation does not have access to such an approved -entropy source, a request for prediction resistance will currently always fail. -In other words, prediction resistance is currently not supported yet by the \s-1DRBG.\s0 -.PP -For the three shared DRBGs (and only for these) there is another way to -reseed them manually: -If \fBRAND_add\fR\|(3) is called with a positive \fIrandomness\fR argument -(or \fBRAND_seed\fR\|(3)), then this will immediately reseed the <master> \s-1DRBG.\s0 -The <public> and <private> \s-1DRBG\s0 will detect this on their next generate -call and reseed, pulling randomness from <master>. -.PP -The last feature has been added to support the common practice used with -previous OpenSSL versions to call \fBRAND_add()\fR before calling \fBRAND_bytes()\fR. -.SS "Entropy Input vs. Additional Data" -.IX Subsection "Entropy Input vs. Additional Data" -The \s-1DRBG\s0 distinguishes two different types of random input: \fIentropy\fR, -which comes from a trusted source, and \fIadditional input\fR', -which can optionally be added by the user and is considered untrusted. -It is possible to add \fIadditional input\fR not only during reseeding, -but also for every generate request. -This is in fact done automatically by \fBRAND_DRBG_bytes\fR\|(3). -.SS "Configuring the Random Seed Source" -.IX Subsection "Configuring the Random Seed Source" -In most cases OpenSSL will automatically choose a suitable seed source -for automatically seeding and reseeding its <master> \s-1DRBG.\s0 In some cases -however, it will be necessary to explicitly specify a seed source during -configuration, using the \-\-with\-rand\-seed option. For more information, -see the \s-1INSTALL\s0 instructions. There are also operating systems where no -seed source is available and automatic reseeding is disabled by default. -.PP -The following two sections describe the reseeding process of the master -\&\s-1DRBG,\s0 depending on whether automatic reseeding is available or not. -.SS "Reseeding the master \s-1DRBG\s0 with automatic seeding enabled" -.IX Subsection "Reseeding the master DRBG with automatic seeding enabled" -Calling \fBRAND_poll()\fR or \fBRAND_add()\fR is not necessary, because the \s-1DRBG\s0 -pulls the necessary entropy from its source automatically. -However, both calls are permitted, and do reseed the \s-1RNG.\s0 -.PP -\&\fBRAND_add()\fR can be used to add both kinds of random input, depending on the -value of the \fBrandomness\fR argument: -.IP "randomness == 0:" 4 -.IX Item "randomness == 0:" -The random bytes are mixed as additional input into the current state of -the \s-1DRBG.\s0 -Mixing in additional input is not considered a full reseeding, hence the -reseed counter is not reset. -.IP "randomness > 0:" 4 -.IX Item "randomness > 0:" -The random bytes are used as entropy input for a full reseeding -(resp. reinstantiation) if the \s-1DRBG\s0 is instantiated -(resp. uninstantiated or in an error state). -The number of random bits required for reseeding is determined by the -security strength of the \s-1DRBG.\s0 Currently it defaults to 256 bits (32 bytes). -It is possible to provide less randomness than required. -In this case the missing randomness will be obtained by pulling random input -from the trusted entropy sources. -.SS "Reseeding the master \s-1DRBG\s0 with automatic seeding disabled" -.IX Subsection "Reseeding the master DRBG with automatic seeding disabled" -Calling \fBRAND_poll()\fR will always fail. -.PP -\&\fBRAND_add()\fR needs to be called for initial seeding and periodic reseeding. -At least 48 bytes (384 bits) of randomness have to be provided, otherwise -the (re\-)seeding of the \s-1DRBG\s0 will fail. This corresponds to one and a half -times the security strength of the \s-1DRBG.\s0 The extra half is used for the -nonce during instantiation. -.PP -More precisely, the number of bytes needed for seeding depend on the -\&\fIsecurity strength\fR of the \s-1DRBG,\s0 which is set to 256 by default. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -\&\fBRAND_DRBG_bytes\fR\|(3), -\&\fBRAND_DRBG_generate\fR\|(3), -\&\fBRAND_DRBG_reseed\fR\|(3), -\&\fBRAND_DRBG_get0_master\fR\|(3), -\&\fBRAND_DRBG_get0_public\fR\|(3), -\&\fBRAND_DRBG_get0_private\fR\|(3), -\&\fBRAND_DRBG_set_reseed_interval\fR\|(3), -\&\fBRAND_DRBG_set_reseed_time_interval\fR\|(3), -\&\fBRAND_DRBG_set_reseed_defaults\fR\|(3), -\&\s-1\fBRAND\s0\fR\|(7), -.SH "COPYRIGHT" -.IX Header "COPYRIGHT" -Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved. -.PP -Licensed under the OpenSSL license (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>. |