402 lines
18 KiB
Plaintext
402 lines
18 KiB
Plaintext
|
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
|
||
|
|
.\"
|
||
|
|
.\" 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 turned on, 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 "EVP_RAND 7ossl"
|
||
|
|
.TH EVP_RAND 7ossl "2024-01-30" "3.2.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"
|
||
|
|
EVP_RAND \- the random bit generator
|
||
|
|
.SH "SYNOPSIS"
|
||
|
|
.IX Header "SYNOPSIS"
|
||
|
|
.Vb 2
|
||
|
|
\& #include <openssl/evp.h>
|
||
|
|
\& #include <rand.h>
|
||
|
|
.Ve
|
||
|
|
.SH "DESCRIPTION"
|
||
|
|
.IX Header "DESCRIPTION"
|
||
|
|
The default OpenSSL \s-1RAND\s0 method is based on the \s-1EVP_RAND\s0 classes to provide
|
||
|
|
non-deterministic inputs to other cryptographic algorithms.
|
||
|
|
.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-1EVP_RAND API\s0
|
||
|
|
serves as the 'backend', connecting the former with the operating
|
||
|
|
systems's entropy sources and providing access to deterministic random
|
||
|
|
bit generators (\s-1DRBG\s0) and their configuration parameters.
|
||
|
|
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].
|
||
|
|
.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-1EVP_RAND API\s0 directly.
|
||
|
|
The usual way to obtain random bytes is to use \fIRAND_bytes\fR\|(3) or
|
||
|
|
\&\fIRAND_priv_bytes\fR\|(3), see also \s-1\fIRAND\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.
|
||
|
|
Refer to \fIprovider\-rand\fR\|(7) for the implementation details to support adding
|
||
|
|
randomness sources to \s-1EVP_RAND.\s0
|
||
|
|
.IP "\(bu" 2
|
||
|
|
You need to change the default settings of the standard OpenSSL \s-1RAND\s0
|
||
|
|
implementation to meet specific requirements.
|
||
|
|
.SH "EVP_RAND CHAINING"
|
||
|
|
.IX Header "EVP_RAND CHAINING"
|
||
|
|
An \s-1EVP_RAND\s0 instance can be used as the entropy source of another
|
||
|
|
\&\s-1EVP_RAND\s0 instance, provided it has itself access to a valid entropy source.
|
||
|
|
The \s-1EVP_RAND\s0 instance which acts as entropy source is called the \fIparent\fR,
|
||
|
|
the other instance the \fIchild\fR. Typically, the child will be a \s-1DRBG\s0 because
|
||
|
|
it does not make sense for the child to be an entropy source.
|
||
|
|
.PP
|
||
|
|
This is called chaining. A chained \s-1EVP_RAND\s0 instance is created by passing
|
||
|
|
a pointer to the parent \s-1EVP_RAND_CTX\s0 as argument to the \fIEVP_RAND_CTX_new()\fR call.
|
||
|
|
It is possible to create chains of more than two \s-1DRBG\s0 in a row.
|
||
|
|
It is also possible to use any \s-1EVP_RAND_CTX\s0 class as the parent, however, only
|
||
|
|
a live entropy source may ignore and not use its parent.
|
||
|
|
.SH "THE THREE SHARED DRBG INSTANCES"
|
||
|
|
.IX Header "THE THREE SHARED DRBG INSTANCES"
|
||
|
|
Currently, there are three shared \s-1DRBG\s0 instances,
|
||
|
|
the <primary>, <public>, and <private> \s-1DRBG.\s0
|
||
|
|
While the <primary> \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 \fIRAND_bytes\fR\|(3) and \fIRAND_priv_bytes\fR\|(3) use
|
||
|
|
the thread-local <public> and <private> \s-1DRBG\s0 instance, respectively.
|
||
|
|
.SS "The <primary> \s-1DRBG\s0 instance"
|
||
|
|
.IX Subsection "The <primary> DRBG instance"
|
||
|
|
The <primary> \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 \fIRAND_add\fR\|(3).
|
||
|
|
.SS "The <public> \s-1DRBG\s0 instance"
|
||
|
|
.IX Subsection "The <public> DRBG instance"
|
||
|
|
This instance is used per default by \fIRAND_bytes\fR\|(3).
|
||
|
|
.SS "The <private> \s-1DRBG\s0 instance"
|
||
|
|
.IX Subsection "The <private> DRBG instance"
|
||
|
|
This instance is used per default by \fIRAND_priv_bytes\fR\|(3)
|
||
|
|
.SH "LOCKING"
|
||
|
|
.IX Header "LOCKING"
|
||
|
|
The <primary> \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 <primary> \s-1DRBG\s0 directly via the
|
||
|
|
\&\s-1EVP_RAND\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-1EVP_RAND\s0 interface.
|
||
|
|
.PP
|
||
|
|
Pointers to these \s-1DRBG\s0 instances can be obtained using
|
||
|
|
\&\fIRAND_get0_primary()\fR, \fIRAND_get0_public()\fR and \fIRAND_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 <primary> \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 <primary> \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() ==> <primary> <\-| 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
|
||
|
|
EVP_RAND_generate(<public>, ...) and
|
||
|
|
EVP_RAND_generate(<private>, ...),
|
||
|
|
respectively.
|
||
|
|
.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 (\fIEVP_RAND_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
|
||
|
|
\&\fIEVP_RAND_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.
|
||
|
|
A request for prediction resistance can only be satisfied by pulling fresh
|
||
|
|
entropy from a live entropy source (section 5.5.2 of [\s-1NIST SP 800\-90C\s0]).
|
||
|
|
It is up to the user to ensure that a live entropy source is configured
|
||
|
|
and is being used.
|
||
|
|
.PP
|
||
|
|
For the three shared DRBGs (and only for these) there is another way to
|
||
|
|
reseed them manually:
|
||
|
|
If \fIRAND_add\fR\|(3) is called with a positive \fIrandomness\fR argument
|
||
|
|
(or \fIRAND_seed\fR\|(3)), then this will immediately reseed the <primary> \s-1DRBG.\s0
|
||
|
|
The <public> and <private> \s-1DRBG\s0 will detect this on their next generate
|
||
|
|
call and reseed, pulling randomness from <primary>.
|
||
|
|
.PP
|
||
|
|
The last feature has been added to support the common practice used with
|
||
|
|
previous OpenSSL versions to call \fIRAND_add()\fR before calling \fIRAND_bytes()\fR.
|
||
|
|
.SS "Entropy Input and Additional Data"
|
||
|
|
.IX Subsection "Entropy Input and 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.
|
||
|
|
.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 <primary> \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 primary
|
||
|
|
\&\s-1DRBG,\s0 depending on whether automatic reseeding is available or not.
|
||
|
|
.SS "Reseeding the primary \s-1DRBG\s0 with automatic seeding enabled"
|
||
|
|
.IX Subsection "Reseeding the primary DRBG with automatic seeding enabled"
|
||
|
|
Calling \fIRAND_poll()\fR or \fIRAND_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
|
||
|
|
\&\fIRAND_add()\fR can be used to add both kinds of random input, depending on the
|
||
|
|
value of the \fIrandomness\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.
|
||
|
|
.PP
|
||
|
|
\&\s-1NOTE:\s0 Manual reseeding is *not allowed* in \s-1FIPS\s0 mode, because
|
||
|
|
[\s-1NIST\s0 SP\-800\-90Ar1] mandates that entropy *shall not* be provided by
|
||
|
|
the consuming application for instantiation (Section 9.1) or
|
||
|
|
reseeding (Section 9.2). For that reason, the \fIrandomness\fR
|
||
|
|
argument is ignored and the random bytes provided by the \fIRAND_add\fR\|(3) and
|
||
|
|
\&\fIRAND_seed\fR\|(3) calls are treated as additional data.
|
||
|
|
.SS "Reseeding the primary \s-1DRBG\s0 with automatic seeding disabled"
|
||
|
|
.IX Subsection "Reseeding the primary DRBG with automatic seeding disabled"
|
||
|
|
Calling \fIRAND_poll()\fR will always fail.
|
||
|
|
.PP
|
||
|
|
\&\fIRAND_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"
|
||
|
|
\&\s-1\fIRAND\s0\fR\|(7), \s-1\fIEVP_RAND\s0\fR\|(3)
|
||
|
|
.SH "HISTORY"
|
||
|
|
.IX Header "HISTORY"
|
||
|
|
This functionality was added in OpenSSL 3.0.
|
||
|
|
.SH "COPYRIGHT"
|
||
|
|
.IX Header "COPYRIGHT"
|
||
|
|
Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved.
|
||
|
|
.PP
|
||
|
|
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>.
|