Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 401 insertions, 0 deletions

diff --git a/upstream/debian-bookworm/man7/EVP_RAND.7ssl b/upstream/debian-bookworm/man7/EVP_RAND.7ssl
new file mode 100644
index 00000000..70e0c599
--- /dev/null
+++ b/upstream/debian-bookworm/man7/EVP_RAND.7ssl
@@ -0,0 +1,401 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\"
+.\" 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 "EVP_RAND 7SSL"
+.TH EVP_RAND 7SSL "2023-10-23" "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>.