path: root/secure/lib/libcrypto/man/man7/EVP_RAND.7

.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
.\" 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 "2023-09-19" "3.0.11" "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 \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.
Refer to \fBprovider\-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 \fBEVP_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 \fBRAND_bytes\fR\|(3) and \fBRAND_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 \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 <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
\&\fBRAND_get0_primary()\fR, \fBRAND_get0_public()\fR and \fBRAND_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 (\fBEVP_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
\&\fBEVP_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 \fBRAND_add\fR\|(3) is called with a positive \fIrandomness\fR argument
(or \fBRAND_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 \fBRAND_add()\fR before calling \fBRAND_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 \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 \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 \fBRAND_add\fR\|(3) and
\&\fBRAND_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 \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"
\&\s-1\fBRAND\s0\fR\|(7), \s-1\fBEVP_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>.