Adding upstream version 4.23.0.upstream/4.23.0

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

1 files changed, 443 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man7/ossl-guide-libcrypto-introduction.7ssl b/upstream/debian-unstable/man7/ossl-guide-libcrypto-introduction.7ssl
new file mode 100644
index 00000000..e39a2102
--- /dev/null
+++ b/upstream/debian-unstable/man7/ossl-guide-libcrypto-introduction.7ssl
@@ -0,0 +1,443 @@
+.\" -*- 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 "OSSL-GUIDE-LIBCRYPTO-INTRODUCTION 7SSL"
+.TH OSSL-GUIDE-LIBCRYPTO-INTRODUCTION 7SSL 2024-04-04 3.2.2-dev 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
+ossl\-guide\-libcrypto\-introduction, crypto
+\&\- OpenSSL Guide: An introduction to libcrypto
+.SH INTRODUCTION
+.IX Header "INTRODUCTION"
+The OpenSSL cryptography library (\f(CW\*(C`libcrypto\*(C'\fR) enables access to a wide range
+of cryptographic algorithms used in various Internet standards. The services
+provided by this library are used by the OpenSSL implementations of TLS and
+CMS, and they have also been used to implement many other third party products
+and protocols.
+.PP
+The functionality includes symmetric encryption, public key cryptography, key
+agreement, certificate handling, cryptographic hash functions, cryptographic
+pseudo-random number generators, message authentication codes (MACs), key
+derivation functions (KDFs), and various utilities.
+.SS Algorithms
+.IX Subsection "Algorithms"
+Cryptographic primitives such as the SHA256 digest, or AES encryption are
+referred to in OpenSSL as "algorithms". Each algorithm may have multiple
+implementations available for use. For example the RSA algorithm is available as
+a "default" implementation suitable for general use, and a "fips" implementation
+which has been validated to FIPS 140 standards for situations where that is
+important. It is also possible that a third party could add additional
+implementations such as in a hardware security module (HSM).
+.PP
+Algorithms are implemented in providers. See
+\&\fBossl\-guide\-libraries\-introduction\fR\|(7) for information about providers.
+.SS Operations
+.IX Subsection "Operations"
+Different algorithms can be grouped together by their purpose. For example there
+are algorithms for encryption, and different algorithms for digesting data.
+These different groups are known as "operations" in OpenSSL. Each operation
+has a different set of functions associated with it. For example to perform an
+encryption operation using AES (or any other encryption algorithm) you would use
+the encryption functions detailed on the \fBEVP_EncryptInit\fR\|(3) page. Or to
+perform a digest operation using SHA256 then you would use the digesting
+functions on the \fBEVP_DigestInit\fR\|(3) page.
+.SH "ALGORITHM FETCHING"
+.IX Header "ALGORITHM FETCHING"
+In order to use an algorithm an implementation for it must first be "fetched".
+Fetching is the process of looking through the available implementations,
+applying selection criteria (via a property query string), and finally choosing
+the implementation that will be used.
+.PP
+Two types of fetching are supported by OpenSSL \- "Explicit fetching" and
+"Implicit fetching".
+.SS "Explicit fetching"
+.IX Subsection "Explicit fetching"
+Explicit fetching involves directly calling a specific API to fetch an algorithm
+implementation from a provider. This fetched object can then be passed to other
+APIs. These explicit fetching functions usually have the name \f(CW\*(C`APINAME_fetch\*(C'\fR,
+where \f(CW\*(C`APINAME\*(C'\fR is the name of the operation. For example \fBEVP_MD_fetch\fR\|(3)
+can be used to explicitly fetch a digest algorithm implementation. The user is
+responsible for freeing the object returned from the \f(CW\*(C`APINAME_fetch\*(C'\fR function
+using \f(CW\*(C`APINAME_free\*(C'\fR when it is no longer needed.
+.PP
+These fetching functions follow a fairly common pattern, where three
+arguments are passed:
+.IP "The library context" 4
+.IX Item "The library context"
+See \fBOSSL_LIB_CTX\fR\|(3) for a more detailed description.
+This may be NULL to signify the default (global) library context, or a
+context created by the user. Only providers loaded in this library context (see
+\&\fBOSSL_PROVIDER_load\fR\|(3)) will be considered by the fetching function. In case
+no provider has been loaded in this library context then the default provider
+will be loaded as a fallback (see \fBOSSL_PROVIDER\-default\fR\|(7)).
+.IP "An identifier" 4
+.IX Item "An identifier"
+For all currently implemented fetching functions this is the algorithm name.
+Each provider supports a list of algorithm implementations. See the provider
+specific documentation for information on the algorithm implementations
+available in each provider:
+"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-default\fR\|(7),
+"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-FIPS\fR\|(7),
+"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-legacy\fR\|(7) and
+"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-base\fR\|(7).
+.Sp
+Note, while providers may register algorithms against a list of names using a
+string with a colon separated list of names, fetching algorithms using that
+format is currently unsupported.
+.IP "A property query string" 4
+.IX Item "A property query string"
+The property query string used to guide selection of the algorithm
+implementation. See
+"PROPERTY QUERY STRINGS" in \fBossl\-guide\-libraries\-introduction\fR\|(7).
+.PP
+The algorithm implementation that is fetched can then be used with other diverse
+functions that use them. For example the \fBEVP_DigestInit_ex\fR\|(3) function takes
+as a parameter an \fBEVP_MD\fR object which may have been returned from an earlier
+call to \fBEVP_MD_fetch\fR\|(3).
+.SS "Implicit fetching"
+.IX Subsection "Implicit fetching"
+OpenSSL has a number of functions that return an algorithm object with no
+associated implementation, such as \fBEVP_sha256\fR\|(3), \fBEVP_aes_128_cbc\fR\|(3),
+\&\fBEVP_get_cipherbyname\fR\|(3) or \fBEVP_get_digestbyname\fR\|(3). These are present for
+compatibility with OpenSSL before version 3.0 where explicit fetching was not
+available.
+.PP
+When they are used with functions like \fBEVP_DigestInit_ex\fR\|(3) or
+\&\fBEVP_CipherInit_ex\fR\|(3), the actual implementation to be used is
+fetched implicitly using default search criteria (which uses NULL for the
+library context and property query string).
+.PP
+In some cases implicit fetching can also occur when a NULL algorithm parameter
+is supplied. In this case an algorithm implementation is implicitly fetched
+using default search criteria and an algorithm name that is consistent with
+the context in which it is being used.
+.PP
+Functions that use an \fBEVP_PKEY_CTX\fR or an \fBEVP_PKEY\fR\|(3), such as
+\&\fBEVP_DigestSignInit\fR\|(3), all fetch the implementations implicitly. Usually the
+algorithm to fetch is determined based on the type of key that is being used and
+the function that has been called.
+.SS Performance
+.IX Subsection "Performance"
+If you perform the same operation many times with the same algorithm then it is
+recommended to use a single explicit fetch of the algorithm and then reuse the
+explicitly fetched algorithm each subsequent time. This will typically be
+faster than implicitly fetching the algorithm every time you use it. See an
+example of Explicit fetching in "USING ALGORITHMS IN APPLICATIONS".
+.PP
+Prior to OpenSSL 3.0, functions such as \fBEVP_sha256()\fR which return a "const"
+object were used directly to indicate the algorithm to use in various function
+calls. If you pass the return value of one of these convenience functions to an
+operation then you are using implicit fetching. If you are converting an
+application that worked with an OpenSSL version prior to OpenSSL 3.0 then
+consider changing instances of implicit fetching to explicit fetching instead.
+.PP
+If an explicitly fetched object is not passed to an operation, then any implicit
+fetch will use an internally cached prefetched object, but it will
+still be slower than passing the explicitly fetched object directly.
+.PP
+The following functions can be used for explicit fetching:
+.IP \fBEVP_MD_fetch\fR\|(3) 4
+.IX Item "EVP_MD_fetch"
+Fetch a message digest/hashing algorithm implementation.
+.IP \fBEVP_CIPHER_fetch\fR\|(3) 4
+.IX Item "EVP_CIPHER_fetch"
+Fetch a symmetric cipher algorithm implementation.
+.IP \fBEVP_KDF_fetch\fR\|(3) 4
+.IX Item "EVP_KDF_fetch"
+Fetch a Key Derivation Function (KDF) algorithm implementation.
+.IP \fBEVP_MAC_fetch\fR\|(3) 4
+.IX Item "EVP_MAC_fetch"
+Fetch a Message Authentication Code (MAC) algorithm implementation.
+.IP \fBEVP_KEM_fetch\fR\|(3) 4
+.IX Item "EVP_KEM_fetch"
+Fetch a Key Encapsulation Mechanism (KEM) algorithm implementation
+.IP \fBOSSL_ENCODER_fetch\fR\|(3) 4
+.IX Item "OSSL_ENCODER_fetch"
+Fetch an encoder algorithm implementation (e.g. to encode keys to a specified
+format).
+.IP \fBOSSL_DECODER_fetch\fR\|(3) 4
+.IX Item "OSSL_DECODER_fetch"
+Fetch a decoder algorithm implementation (e.g. to decode keys from a specified
+format).
+.IP \fBEVP_RAND_fetch\fR\|(3) 4
+.IX Item "EVP_RAND_fetch"
+Fetch a Pseudo Random Number Generator (PRNG) algorithm implementation.
+.PP
+See "OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-default\fR\|(7),
+"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-FIPS\fR\|(7),
+"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-legacy\fR\|(7) and
+"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-base\fR\|(7) for a list of algorithm names
+that can be fetched.
+.SH "FETCHING EXAMPLES"
+.IX Header "FETCHING EXAMPLES"
+The following section provides a series of examples of fetching algorithm
+implementations.
+.PP
+Fetch any available implementation of SHA2\-256 in the default context. Note
+that some algorithms have aliases. So "SHA256" and "SHA2\-256" are synonymous:
+.PP
+.Vb 3
+\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", NULL);
+\& ...
+\& EVP_MD_free(md);
+.Ve
+.PP
+Fetch any available implementation of AES\-128\-CBC in the default context:
+.PP
+.Vb 3
+\& EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES\-128\-CBC", NULL);
+\& ...
+\& EVP_CIPHER_free(cipher);
+.Ve
+.PP
+Fetch an implementation of SHA2\-256 from the default provider in the default
+context:
+.PP
+.Vb 3
+\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider=default");
+\& ...
+\& EVP_MD_free(md);
+.Ve
+.PP
+Fetch an implementation of SHA2\-256 that is not from the default provider in the
+default context:
+.PP
+.Vb 3
+\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider!=default");
+\& ...
+\& EVP_MD_free(md);
+.Ve
+.PP
+Fetch an implementation of SHA2\-256 that is preferably from the FIPS provider in
+the default context:
+.PP
+.Vb 3
+\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider=?fips");
+\& ...
+\& EVP_MD_free(md);
+.Ve
+.PP
+Fetch an implementation of SHA2\-256 from the default provider in the specified
+library context:
+.PP
+.Vb 3
+\& EVP_MD *md = EVP_MD_fetch(libctx, "SHA2\-256", "provider=default");
+\& ...
+\& EVP_MD_free(md);
+.Ve
+.PP
+Load the legacy provider into the default context and then fetch an
+implementation of WHIRLPOOL from it:
+.PP
+.Vb 2
+\& /* This only needs to be done once \- usually at application start up */
+\& OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
+\&
+\& EVP_MD *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "provider=legacy");
+\& ...
+\& EVP_MD_free(md);
+.Ve
+.PP
+Note that in the above example the property string "provider=legacy" is optional
+since, assuming no other providers have been loaded, the only implementation of
+the "whirlpool" algorithm is in the "legacy" provider. Also note that the
+default provider should be explicitly loaded if it is required in addition to
+other providers:
+.PP
+.Vb 3
+\& /* This only needs to be done once \- usually at application start up */
+\& OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
+\& OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default");
+\&
+\& EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL);
+\& EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA2\-256", NULL);
+\& ...
+\& EVP_MD_free(md_whirlpool);
+\& EVP_MD_free(md_sha256);
+.Ve
+.SH "USING ALGORITHMS IN APPLICATIONS"
+.IX Header "USING ALGORITHMS IN APPLICATIONS"
+Cryptographic algorithms are made available to applications through use of the
+"EVP" APIs. Each of the various operations such as encryption, digesting,
+message authentication codes, etc., have a set of EVP function calls that can
+be invoked to use them. See the \fBevp\fR\|(7) page for further details.
+.PP
+Most of these follow a common pattern. A "context" object is first created. For
+example for a digest operation you would use an \fBEVP_MD_CTX\fR, and for an
+encryption/decryption operation you would use an \fBEVP_CIPHER_CTX\fR. The
+operation is then initialised ready for use via an "init" function \- optionally
+passing in a set of parameters (using the \fBOSSL_PARAM\fR\|(3) type) to configure how
+the operation should behave. Next data is fed into the operation in a series of
+"update" calls. The operation is finalised using a "final" call which will
+typically provide some kind of output. Finally the context is cleaned up and
+freed.
+.PP
+The following shows a complete example for doing this process for digesting
+data using SHA256. The process is similar for other operations such as
+encryption/decryption, signatures, message authentication codes, etc. Additional
+examples can be found in the OpenSSL demos (see
+"DEMO APPLICATIONS" in \fBossl\-guide\-libraries\-introduction\fR\|(7)).
+.PP
+.Vb 4
+\& #include <stdio.h>
+\& #include <openssl/evp.h>
+\& #include <openssl/bio.h>
+\& #include <openssl/err.h>
+\&
+\& int main(void)
+\& {
+\&     EVP_MD_CTX *ctx = NULL;
+\&     EVP_MD *sha256 = NULL;
+\&     const unsigned char msg[] = {
+\&         0x00, 0x01, 0x02, 0x03
+\&     };
+\&     unsigned int len = 0;
+\&     unsigned char *outdigest = NULL;
+\&     int ret = 1;
+\&
+\&     /* Create a context for the digest operation */
+\&     ctx = EVP_MD_CTX_new();
+\&     if (ctx == NULL)
+\&         goto err;
+\&
+\&     /*
+\&      * Fetch the SHA256 algorithm implementation for doing the digest. We\*(Aqre
+\&      * using the "default" library context here (first NULL parameter), and
+\&      * we\*(Aqre not supplying any particular search criteria for our SHA256
+\&      * implementation (second NULL parameter). Any SHA256 implementation will
+\&      * do.
+\&      * In a larger application this fetch would just be done once, and could
+\&      * be used for multiple calls to other operations such as EVP_DigestInit_ex().
+\&      */
+\&     sha256 = EVP_MD_fetch(NULL, "SHA256", NULL);
+\&     if (sha256 == NULL)
+\&         goto err;
+\&
+\&    /* Initialise the digest operation */
+\&    if (!EVP_DigestInit_ex(ctx, sha256, NULL))
+\&        goto err;
+\&
+\&     /*
+\&      * Pass the message to be digested. This can be passed in over multiple
+\&      * EVP_DigestUpdate calls if necessary
+\&      */
+\&     if (!EVP_DigestUpdate(ctx, msg, sizeof(msg)))
+\&         goto err;
+\&
+\&     /* Allocate the output buffer */
+\&     outdigest = OPENSSL_malloc(EVP_MD_get_size(sha256));
+\&     if (outdigest == NULL)
+\&         goto err;
+\&
+\&     /* Now calculate the digest itself */
+\&     if (!EVP_DigestFinal_ex(ctx, outdigest, &len))
+\&         goto err;
+\&
+\&     /* Print out the digest result */
+\&     BIO_dump_fp(stdout, outdigest, len);
+\&
+\&     ret = 0;
+\&
+\&  err:
+\&     /* Clean up all the resources we allocated */
+\&     OPENSSL_free(outdigest);
+\&     EVP_MD_free(sha256);
+\&     EVP_MD_CTX_free(ctx);
+\&     if (ret != 0)
+\&        ERR_print_errors_fp(stderr);
+\&     return ret;
+\& }
+.Ve
+.SH "ENCODING AND DECODING KEYS"
+.IX Header "ENCODING AND DECODING KEYS"
+Many algorithms require the use of a key. Keys can be generated dynamically
+using the EVP APIs (for example see \fBEVP_PKEY_Q_keygen\fR\|(3)). However it is often
+necessary to save or load keys (or their associated parameters) to or from some
+external format such as PEM or DER (see \fBopenssl\-glossary\fR\|(7)). OpenSSL uses
+encoders and decoders to perform this task.
+.PP
+Encoders and decoders are just algorithm implementations in the same way as
+any other algorithm implementation in OpenSSL. They are implemented by
+providers. The OpenSSL encoders and decoders are available in the default
+provider. They are also duplicated in the base provider.
+.PP
+For information about encoders see \fBOSSL_ENCODER_CTX_new_for_pkey\fR\|(3). For
+information about decoders see \fBOSSL_DECODER_CTX_new_for_pkey\fR\|(3).
+.PP
+As well as using encoders/decoders directly there are also some helper functions
+that can be used for certain well known and commonly used formats. For example
+see \fBPEM_read_PrivateKey\fR\|(3) and \fBPEM_write_PrivateKey\fR\|(3) for information
+about reading and writing key data from PEM encoded files.
+.SH "FURTHER READING"
+.IX Header "FURTHER READING"
+See \fBossl\-guide\-libssl\-introduction\fR\|(7) for an introduction to using \f(CW\*(C`libssl\*(C'\fR.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBopenssl\fR\|(1), \fBssl\fR\|(7), \fBevp\fR\|(7), \fBOSSL_LIB_CTX\fR\|(3), \fBopenssl\-threads\fR\|(7),
+\&\fBproperty\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7), \fBOSSL_PROVIDER\-base\fR\|(7),
+\&\fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7), \fBOSSL_PROVIDER\-null\fR\|(7),
+\&\fBopenssl\-glossary\fR\|(7), \fBprovider\fR\|(7)
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright 2000\-2024 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>.