Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 234 insertions, 0 deletions

diff --git a/upstream/archlinux/man7/EVP_KDF-ARGON2.7ssl b/upstream/archlinux/man7/EVP_KDF-ARGON2.7ssl
new file mode 100644
index 00000000..15da3599
--- /dev/null
+++ b/upstream/archlinux/man7/EVP_KDF-ARGON2.7ssl
@@ -0,0 +1,234 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (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
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    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
+.\" ========================================================================
+.\"
+.IX Title "EVP_KDF-ARGON2 7ssl"
+.TH EVP_KDF-ARGON2 7ssl 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_KDF\-ARGON2 \- The Argon2 EVP KDF implementation
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Support for computing the \fBargon2\fR password-based KDF through the \fBEVP_KDF\fR
+API.
+.PP
+The EVP_KDF\-ARGON2 algorithm implements the Argon2 password-based key
+derivation function, as described in IETF RFC 9106.  It is memory-hard in
+the sense that it deliberately requires a significant amount of RAM for efficient
+computation. The intention of this is to render brute forcing of passwords on
+systems that lack large amounts of main memory (such as GPUs or ASICs)
+computationally infeasible.
+.PP
+Argon2d (Argon2i) uses data-dependent (data-independent) memory access and
+primary seek to address trade-off (side-channel) attacks.
+.PP
+Argon2id is a hybrid construction which, in the first two slices of the first
+pass, generates reference addresses data-independently as in Argon2i, whereas
+in later slices and next passes it generates them data-dependently as in
+Argon2d.
+.PP
+Sbox-hardened version Argon2ds is not supported.
+.PP
+For more information, please refer to RFC 9106.
+.SS "Supported parameters"
+.IX Subsection "Supported parameters"
+The supported parameters are:
+.IP """pass"" (\fBOSSL_KDF_PARAM_PASSWORD\fR) <octet string>" 4
+.IX Item """pass"" (OSSL_KDF_PARAM_PASSWORD) <octet string>"
+.PD 0
+.IP """salt"" (\fBOSSL_KDF_PARAM_SALT\fR) <octet string>" 4
+.IX Item """salt"" (OSSL_KDF_PARAM_SALT) <octet string>"
+.IP """secret"" (\fBOSSL_KDF_PARAM_SECRET\fR) <octet string>" 4
+.IX Item """secret"" (OSSL_KDF_PARAM_SECRET) <octet string>"
+.IP """iter"" (\fBOSSL_KDF_PARAM_ITER\fR) <unsigned integer>" 4
+.IX Item """iter"" (OSSL_KDF_PARAM_ITER) <unsigned integer>"
+.IP """size"" (\fBOSSL_KDF_PARAM_SIZE\fR) <unsigned integer>" 4
+.IX Item """size"" (OSSL_KDF_PARAM_SIZE) <unsigned integer>"
+.PD
+These parameters work as described in "PARAMETERS" in \fBEVP_KDF\fR\|(3).
+.Sp
+Note that RFC 9106 recommends 128 bits salt for most applications, or 64 bits
+salt in the case of space constraints. At least 128 bits output length is
+recommended.
+.Sp
+Note that secret (or pepper) is an optional secret data used along the
+password.
+.IP """threads"" (\fBOSSL_KDF_PARAM_THREADS\fR) <unsigned integer>" 4
+.IX Item """threads"" (OSSL_KDF_PARAM_THREADS) <unsigned integer>"
+The number of threads, bounded above by the number of lanes.
+.Sp
+This can only be used with built-in thread support. Threading must be
+explicitly enabled. See EXAMPLES section for more information.
+.IP """ad"" (\fBOSSL_KDF_PARAM_ARGON2_AD\fR) <octet string>" 4
+.IX Item """ad"" (OSSL_KDF_PARAM_ARGON2_AD) <octet string>"
+Optional associated data, may be used to "tag" a group of keys, or tie them
+to a particular public key, without having to modify salt.
+.IP """lanes"" (\fBOSSL_KDF_PARAM_ARGON2_LANES\fR) <unsigned integer>" 4
+.IX Item """lanes"" (OSSL_KDF_PARAM_ARGON2_LANES) <unsigned integer>"
+Argon2 splits the requested memory size into lanes, each of which is designed
+to be processed in parallel. For example, on a system with p cores, it's
+recommended to use p lanes.
+.Sp
+The number of lanes is used to derive the key. It is possible to specify
+more lanes than the number of available computational threads. This is
+especially encouraged if multi-threading is disabled.
+.IP """memcost"" (\fBOSSL_KDF_PARAM_ARGON2_MEMCOST\fR) <unsigned integer>" 4
+.IX Item """memcost"" (OSSL_KDF_PARAM_ARGON2_MEMCOST) <unsigned integer>"
+Memory cost parameter (the number of 1k memory blocks used).
+.IP """version"" (\fBOSSL_KDF_PARAM_ARGON2_VERSION\fR) <unsigned integer>" 4
+.IX Item """version"" (OSSL_KDF_PARAM_ARGON2_VERSION) <unsigned integer>"
+Argon2 version. Supported values: 0x10, 0x13 (default).
+.IP """early_clean"" (\fBOSSL_KDF_PARAM_EARLY_CLEAN\fR) <unsigned integer>" 4
+.IX Item """early_clean"" (OSSL_KDF_PARAM_EARLY_CLEAN) <unsigned integer>"
+If set (nonzero), password and secret stored in Argon2 context are zeroed
+early during initial hash computation, as soon as they are not needed.
+Otherwise, they are zeroed along the rest of Argon2 context data on clear,
+free, reset.
+.Sp
+This can be useful if, for example, multiple keys with different ad value
+are to be generated from a single password and secret.
+.SH EXAMPLES
+.IX Header "EXAMPLES"
+This example uses Argon2d with password "1234567890", salt "saltsalt",
+using 2 lanes, 2 threads, and memory cost of 65536:
+.PP
+.Vb 5
+\& #include <string.h>                 /* strlen               */
+\& #include <openssl/core_names.h>     /* OSSL_KDF_*           */
+\& #include <openssl/params.h>         /* OSSL_PARAM_*         */
+\& #include <openssl/thread.h>         /* OSSL_set_max_threads */
+\& #include <openssl/kdf.h>            /* EVP_KDF_*            */
+\&
+\& int main(void)
+\& {
+\&     int retval = 1;
+\&
+\&     EVP_KDF *kdf = NULL;
+\&     EVP_KDF_CTX *kctx = NULL;
+\&     OSSL_PARAM params[6], *p = params;
+\&
+\&     /* argon2 params, please refer to RFC9106 for recommended defaults */
+\&     uint32_t lanes = 2, threads = 2, memcost = 65536;
+\&     char pwd[] = "1234567890", salt[] = "saltsalt";
+\&
+\&     /* derive result */
+\&     size_t outlen = 128;
+\&     unsigned char result[outlen];
+\&
+\&     /* required if threads > 1 */
+\&     if (OSSL_set_max_threads(NULL, threads) != 1)
+\&         goto fail;
+\&
+\&     p = params;
+\&     *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_THREADS, &threads);
+\&     *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_ARGON2_LANES,
+\&                                        &lanes);
+\&     *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_ARGON2_MEMCOST,
+\&                                        &memcost);
+\&     *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
+\&                                              salt,
+\&                                              strlen((const char *)salt));
+\&     *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_PASSWORD,
+\&                                              pwd,
+\&                                              strlen((const char *)pwd));
+\&     *p++ = OSSL_PARAM_construct_end();
+\&
+\&     if ((kdf = EVP_KDF_fetch(NULL, "ARGON2D", NULL)) == NULL)
+\&         goto fail;
+\&     if ((kctx = EVP_KDF_CTX_new(kdf)) == NULL)
+\&         goto fail;
+\&     if (EVP_KDF_derive(kctx, &result[0], outlen, params) != 1)
+\&         goto fail;
+\&
+\&     printf("Output = %s\en", OPENSSL_buf2hexstr(result, outlen));
+\&     retval = 0;
+\&
+\& fail:
+\&     EVP_KDF_free(kdf);
+\&     EVP_KDF_CTX_free(kctx);
+\&     OSSL_set_max_threads(NULL, 0);
+\&
+\&     return retval;
+\& }
+.Ve
+.SH NOTES
+.IX Header "NOTES"
+"ARGON2I", "ARGON2D", and "ARGON2ID" are the names for this implementation; it
+can be used with the \fBEVP_KDF_fetch()\fR function.
+.SH "CONFORMING TO"
+.IX Header "CONFORMING TO"
+RFC 9106 Argon2, see <https://www.rfc\-editor.org/rfc/rfc9106.txt>.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBEVP_KDF\fR\|(3),
+\&\fBEVP_KDF_CTX_new\fR\|(3),
+\&\fBEVP_KDF_CTX_free\fR\|(3),
+\&\fBEVP_KDF_CTX_set_params\fR\|(3),
+\&\fBEVP_KDF_derive\fR\|(3),
+"PARAMETERS" in \fBEVP_KDF\fR\|(3)
+.SH HISTORY
+.IX Header "HISTORY"
+This functionality was added to OpenSSL 3.2.
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright 2022\-2023 The OpenSSL Project Authors. All Rights Reserved.
+.PP
+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 LICENSE in the source distribution or at
+<https://www.openssl.org/source/license.html>.