Add migration guide for 3.0

Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14710)

1 files changed, 1804 insertions, 0 deletions

diff --git a/doc/man7/migration_guide.pod b/doc/man7/migration_guide.pod
new file mode 100644
index 0000000000..58260860de
--- /dev/null
+++ b/doc/man7/migration_guide.pod
@@ -0,0 +1,1804 @@
+=pod
+
+=head1 NAME
+
+migration_guide - OpenSSL migration guide
+
+=head1 SYNOPSIS
+
+See the individual manual pages for details.
+
+=head1 DESCRIPTION
+
+This guide details the changes required to migrate to new versions of OpenSSL.
+Currently this covers OpenSSL 3.0. For earlier versions refer to
+L<https://github.com/openssl/openssl/blob/master/CHANGES.md>.
+For an overview of some of the key concepts introduced in OpenSSL 3.0 see
+L<crypto(7)>.
+
+=head1 OPENSSL 3_0
+
+=head2 Main Changes from OpenSSL 1.1.1
+
+=head3 Major Release
+
+OpenSSL 3.0 is a major release and consequently any application that currently
+uses an older version of OpenSSL will at the very least need to be recompiled in
+order to work with the new version. It is the intention that the large majority
+of applications will work unchanged with OpenSSL 3.0 if those applications
+previously worked with OpenSSL 1.1.1. However this is not guaranteed and some
+changes may be required in some cases. Changes may also be required if
+applications need to take advantage of some of the new features available in
+OpenSSL 3.0 such as the availability of the FIPS module.
+
+=head3 License Change
+
+In previous versions, OpenSSL was licensed under the L<dual OpenSSL and SSLeay
+licenses|https://www.openssl.org/source/license-openssl-ssleay.txt>
+(both licenses apply). From OpenSSL 3.0 this is replaced by the
+L<Apache License v2|https://www.openssl.org/source/apache-license-2.0.txt>.
+
+=head3 Providers and FIPS support
+
+One of the key changes from OpenSSL 1.1.1 is the introduction of the Provider
+concept. Providers collect together and make available algorithm implementations.
+With OpenSSL 3.0 it is possible to specify, either programmatically or via a
+config file, which providers you want to use for any given application.
+OpenSSL 3.0 comes with 5 different providers as standard. Over time third
+parties may distribute additional providers that can be plugged into OpenSSL.
+All algorithm implementations available via providers are accessed through the
+"high level" APIs (for example those functions prefixed with "EVP"). They cannot
+be accessed using the L</Low Level APIs>.
+One of the standard providers available is the FIPS provider. This makes
+available FIPS validated cryptographic algorithms.
+The FIPS provider is disabled by default and needs to be enabled explicitly
+at configuration time using the `enable-fips` option. If it is enabled,
+the FIPS provider gets built and installed in addition to the other standard
+providers. No separate installation procedure is necessary.
+There is however a dedicated `install_fips` make target, which serves the
+special purpose of installing only the FIPS provider into an existing
+OpenSSL installation.
+
+See also L</Legacy Algorithms> for information on the legacy provider.
+
+See also L</Completing the installation of the FIPS Module> and
+L</Using the FIPS Module in applications>.
+
+=head3 Low Level APIs
+
+OpenSSL has historically provided two sets of APIs for invoking cryptographic
+algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level"
+APIs. The high level APIs are typically designed to work across all algorithm
+types. The "low level" APIs are targeted at a specific algorithm implementation.
+For example, the EVP APIs provide the functions L<EVP_EncryptInit_ex(3)>,
+L<EVP_EncryptUpdate(3)> and L<EVP_EncryptFinal(3)> to perform symmetric
+encryption. Those functions can be used with the algorithms AES, CHACHA, 3DES etc.
+On the other hand, to do AES encryption using the low level APIs you would have
+to call AES specific functions such as L<AES_set_encrypt_key(3)>,
+L<AES_encrypt(3)>, and so on. The functions for 3DES are different.
+Use of the low level APIs has been informally discouraged by the OpenSSL
+development team for a long time. However in OpenSSL 3.0 this is made more
+formal. All such low level APIs have been deprecated. You may still use them in
+your applications, but you may start to see deprecation warnings during
+compilation (dependent on compiler support for this). Deprecated APIs may be
+removed from future versions of OpenSSL so you are strongly encouraged to update
+your code to use the high level APIs instead.
+
+This is described in more detail in L</Deprecation of Low Level Functions>
+
+=head3 Legacy Algorithms
+
+Some cryptographic algorithms such as B<MD2> and B<DES> that were available via
+the EVP APIs are now considered legacy and their use is strongly discouraged.
+These legacy EVP algorithms are still available in OpenSSL 3.0 but not by
+default. If you want to use them then you must load the legacy provider.
+This can be as simple as a config file change, or can be done programmatically.
+See L<OSSL_PROVIDER-legacy(7)> for a complete list of algorithms.
+Applications using the EVP APIs to access these algorithms should instead use
+more modern algorithms. If that is not possible then these applications
+should ensure that the legacy provider has been loaded. This can be achieved
+either programmatically or via configuration. See L<crypto(7)> man page for
+more information about providers.
+
+=head3 Engines and "METHOD" APIs
+
+The refactoring to support Providers conflicts internally with the APIs used to
+support engines, including the ENGINE API and any function that creates or
+modifies custom "METHODS" (for example L<EVP_MD_meth_new(3)>,
+L<EVP_CIPHER_meth_new(3)>, L<EVP_PKEY_meth_new(3)>, L<RSA_meth_new(3)>,
+L<EC_KEY_METHOD_new(3)>, etc.). These functions are being deprecated in
+OpenSSL 3.0, and users of these APIs should know that their use can likely
+bypass provider selection and configuration, with unintended consequences.
+This is particularly relevant for applications written to use the OpenSSL 3.0
+FIPS module, as detailed below. Authors and maintainers of external engines are
+strongly encouraged to refactor their code transforming engines into providers
+using the new Provider API and avoiding deprecated methods. 
+
+=head3 Versioning Scheme
+
+The OpenSSL versioning scheme has changed with the OpenSSL 3.0 release. The new
+versioning scheme has this format:
+
+MAJOR.MINOR.PATCH
+
+For OpenSSL 1.1.1 and below, different patch levels were indicated by a letter
+at the end of the release version number. This will no longer be used and
+instead the patch level is indicated by the final number in the version. A
+change in the second (MINOR) number indicates that new features may have been
+added. OpenSSL versions with the same major number are API and ABI compatible.
+If the major number changes then API and ABI compatibility is not guaranteed. 
+
+=head3 Other major new features
+
+=head4 Certificate Management Protocol (CMP, RFC 4210)
+
+This also covers CRMF (RFC 4211) and HTTP transfer (RFC 6712)
+See L<openssl-cmp(1)> and L<OSSL_CMP_exec_certreq(3)> as starting points.
+
+=head4 HTTP(S) client
+
+A proper HTTP(S) client that supports GET and POST, redirection, plain and
+ASN.1-encoded contents, proxies, and timeouts.
+
+=head4 Key Derivation Function API (EVP_KDF)
+
+This simplifies the process of adding new KDF and PRF implementations.
+
+Previously KDF algorithms had been shoe-horned into using the EVP_PKEY object
+which was not a logical mapping.
+Existing applications that use KDF algorithms using EVP_PKEY
+(scrypt, TLS1 PRF and HKDF) may be slower as they use an EVP_KDF bridge
+internally.
+All new applications should use the new L<EVP_KDF(3)> interface.
+See also L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)> and
+L<OSSL_PROVIDER-FIPS(7)/Key Derivation Function (KDF)>.
+
+=head4 Message Authentication Code API (EVP_MAC)
+
+This simplifies the process of adding MAC implementations.
+
+This includes a generic EVP_PKEY to EVP_MAC bridge, to facilitate the continued
+use of MACs through raw private keys in functionality such as
+L<EVP_DigestSign(3)> and L<EVP_DigestVerify(3)>.
+
+All new applications should use the new L<EVP_MAC(3)> interface.
+See also L<OSSL_PROVIDER-default(7)/Message Authentication Code (MAC)>
+and L<OSSL_PROVIDER-FIPS(7)/Message Authentication Code (MAC)>.
+
+=head4 Support for Linux Kernel TLS
+
+In order to use KTLS, support for it must be compiled in using the 'enable-ktls'
+compile time option. It must also be enabled at run time using the
+B<SSL_OP_ENABLE_KTLS> option.
+
+=head4 New Algorithms
+
+=over 4
+
+=item KDF algorithms "SINGLE STEP" and "SSH"
+
+See L<EVP_KDF-SS(7)> and L<EVP_KDF-SSHKDF(7)>
+
+=item MAC Algorithms "GMAC" and "KMAC"
+
+See L<EVP_MAC-GMAC(7)> and L<EVP_MAC-KMAC(7)>.
+
+=item KEM Algorithm "RSASVE"
+
+See L<EVP_KEM-RSA(7)>.
+
+=item Cipher Algorithm "AES-SIV"
+
+See L<EVP_EncryptInit(3)/SIV Mode>.
+
+=item AES Key Wrap inverse ciphers supported by EVP layer.
+
+The inverse ciphers use AES decryption for wrapping, and AES encryption for
+unwrapping. The algorithms are: "AES-128-WRAP-INV", "AES-192-WRAP-INV",
+"AES-256-WRAP-INV", "AES-128-WRAP-PAD-INV", "AES-192-WRAP-PAD-INV" and
+"AES-256-WRAP-PAD-INV".
+
+=item AES CTS cipher added to EVP layer.
+
+The algorithms are "AES-128-CBC-CTS", "AES-192-CBC-CTS" and "AES-256-CBC-CTS".
+CS1, CS2 and CS3 variants are supported.
+
+=back
+
+=head4 CMS and PKCS#7 updates
+
+=over 4
+
+=item Added CAdES-BES signature verification support.
+
+=item Added CAdES-BES signature scheme and attributes support (RFC 5126) to CMS API.
+
+=item Added AuthEnvelopedData content type structure (RFC 5083) using AES_GCM
+
+This uses the AES-GCM parameter (RFC 5084) for the Cryptographic Message Syntax.
+Its purpose is to support encryption and decryption of a digital envelope that
+is both authenticated and encrypted using AES GCM mode.
+
+=item L<PKCS7_get_octet_string(3)> and L<PKCS7_type_is_other(3)> were made public.
+
+=back
+
+=head4 PKCS#12 API updates
+
+The default algorithms for pkcs12 creation with the PKCS12_create() function
+were changed to more modern PBKDF2 and AES based algorithms. The default
+MAC iteration count was changed to PKCS12_DEFAULT_ITER to make it equal
+with the password-based encryption iteration count. The default digest
+algorithm for the MAC computation was changed to SHA-256. The pkcs12
+application now supports -legacy option that restores the previous
+default algorithms to support interoperability with legacy systems.
+
+Added enhanced PKCS#12 APIs which accept a library context `OSSL_LIB_CTX`
+and (where relevant) a property query. Other APIs which handle PKCS#7 and
+PKCS#8 objects have also been enhanced where required. This includes:
+
+L<PKCS12_add_key_ex(3)>, L<PKCS12_add_safe_ex(3)>, L<PKCS12_add_safes_ex(3)>,
+L<PKCS12_create_ex(3)>, L<PKCS12_decrypt_skey_ex(3)>, L<PKCS12_init_ex(3)>,
+L<PKCS12_item_decrypt_d2i_ex(3)>, L<PKCS12_item_i2d_encrypt_ex(3)>,
+L<PKCS12_key_gen_asc_ex(3)>, L<PKCS12_key_gen_uni_ex(3)>, L<PKCS12_key_gen_utf8_ex(3)>,
+L<PKCS12_pack_p7encdata_ex(3)>, L<PKCS12_pbe_crypt_ex(3)>, L<PKCS12_PBE_keyivgen_ex(3)>,
+L<PKCS12_SAFEBAG_create_pkcs8_encrypt_ex(3)>, L<PKCS5_pbe2_set_iv_ex(3)>,
+L<PKCS5_pbe_set0_algor_ex(3)>, L<PKCS5_pbe_set_ex(3)>, L<PKCS5_pbkdf2_set_ex(3)>,
+L<PKCS5_v2_PBE_keyivgen_ex(3)>, L<PKCS5_v2_scrypt_keyivgen_ex(3)>,
+L<PKCS8_decrypt_ex(3)>, L<PKCS8_encrypt_ex(3)>, L<PKCS8_set0_pbe_ex(3)>.
+
+As part of this change the EVP_PBE_xxx APIs can also accept a library
+context and property query and will call an extended version of the key/IV
+derivation function which supports these parameters. This includes
+L<EVP_PBE_CipherInit_ex(3)>, L<EVP_PBE_find_ex(3)> and L<EVP_PBE_scrypt_ex(3)>.
+
+=head4 Windows thread synchronization changes
+
+Windows thread synchronization uses read/write primitives (SRWLock) when
+supported by the OS, otherwise CriticalSection continues to be used.
+
+=head4 Trace API
+
+A new generic trace API has been added which provides support for enabling
+instrumentation through trace output. This feature is mainly intended as an aid
+for developers and is disabled by default. To utilize it, OpenSSL needs to be
+configured with the `enable-trace` option.
+
+If the tracing API is enabled, the application can activate trace output by
+registering BIOs as trace channels for a number of tracing and debugging
+categories. See L<OSSL_trace_enabled(3)>.
+
+=head4 Key validation updates
+
+L<EVP_PKEY_public_check(3)> and L<EVP_PKEY_param_check(3)> now work for
+more key types. This includes RSA, DSA, ED25519, X25519, ED448 and X448.
+Previously (in 1.1.1) they would return -2. For key types that do not have
+parameters then L<EVP_PKEY_param_check(3)> will always return 1.
+
+=head3 Other notable deprecations and changes
+
+=head4 The function code part of an OpenSSL error code is no longer relevant
+
+This code is now always set to zero. Related functions are deprecated.
+
+=head4 STACK and HASH macro's have been cleaned up
+
+The type-safe wrappers are declared everywhere and implemented once.
+See L<DEFINE_STACK_OF(3)> and L<DECLARE_LHASH_OF(3)>.
+
+=head4 The RAND_DRBG subsystem has been removed
+
+The new L<EVP_RAND(3)> is a partial replacement: the DRBG callback framework is
+absent. The RAND_DRBG API did not fit well into the new provider concept as
+implemented by EVP_RAND and EVP_RAND_CTX.
+
+=head4 Removed FIPS_mode() and FIPS_mode_set()
+
+These functions are legacy APIs that are not applicable to the new provider
+model. Applications should instead use
+L<EVP_default_properties_is_fips_enabled(3)> and
+L<EVP_default_properties_enable_fips(3)>.
+
+=head4 Key generation is slower
+
+The Miller-Rabin test now uses 64 rounds, which is used for all prime generation,
+including RSA key generation. This affects the time for larger keys sizes.
+
+The default key generation method for the regular 2-prime RSA keys was changed
+to the FIPS 186-4 B.3.6 method (Generation of Probable Primes with Conditions
+Based on Auxiliary Probable Primes). This method is slower than the original
+method.
+
+=head4 Change PBKDF2 to conform to SP800-132 instead of the older PKCS5 RFC2898
+
+This checks that the salt length is at least 128 bits, the derived key length is
+at least 112 bits, and that the iteration count is at least 1000.
+For backwards compatibility these checks are disabled by default in the
+default provider, but are enabled by default in the fips provider.
+
+To enable or disable the checks see B<OSSL_KDF_PARAM_PKCS5> in
+L<EVP_KDF-PBKDF2(7)>. The parameter can be set using L<EVP_KDF_derive(3)>.
+
+=head4 Enforce a minimum DH modulus size of 512 bits
+
+Smaller sizes now result in an error.
+
+=head4 SM2 key changes
+
+EC EVP_PKEYs with the SM2 curve have been reworked to automatically become
+EVP_PKEY_SM2 rather than EVP_PKEY_EC.
+
+Unlike in previous OpenSSL versions, this means that applications cannot
+call `EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2)` to get SM2 computations.
+
+Parameter and key generation is also reworked to make it possible
+to generate EVP_PKEY_SM2 parameters and keys. Applications must now generate
+SM2 keys directly and must not create an EVP_PKEY_EC key first.
+
+Validation of SM2 keys has been separated from the validation of regular EC
+keys, allowing to improve the SM2 validation process to reject loaded private
+keys that are not conforming to the SM2 ISO standard.
+In particular, a private scalar `k` outside the range `1 <= k < n-1` is now
+correctly rejected.
+
+=head4 EVP_PKEY_set_alias_type() method has been removed
+
+This function made a B<EVP_PKEY> object mutable after it had been set up. In
+OpenSSL 3.0 it was decided that a provided key should not be able to change its
+type, so this function has been removed.
+
+=head4 Functions that return an internal key should be treated as read only
+
+Functions such as L<EVP_PKEY_get0_RSA(3)> behave slightly differently in
+OpenSSL 3.0. Previously they returned a pointer to the low-level key used
+internally by libcrypto. From OpenSSL 3.0 this key may now be held in a
+provider. Calling these functions will only return a handle on the internal key
+where the EVP_PKEY was constructed using this key in the first place, for
+example using a function or macro such as L<EVP_PKEY_assign_RSA(3)>,
+L<EVP_PKEY_set1_RSA(3)>, etc.
+Where the EVP_PKEY holds a provider managed key, then these functions now return
+a cached copy of the key. Changes to the internal provider key that take place
+after the first time the cached key is accessed will not be reflected back in
+the cached copy. Similarly any changes made to the cached copy by application
+code will not be reflected back in the internal provider key.
+
+For the above reasons the keys returned from these functions should typically be
+treated as read-only. To emphasise this the value returned from
+L<EVP_PKEY_get0_RSA(3)>, L<EVP_PKEY_get0_DSA(3)>, L<EVP_PKEY_get0_EC_KEY(3)> and
+L<EVP_PKEY_get0_DH(3)> have been made const. This may break some existing code.
+Applications broken by this change should be modified. The preferred solution is
+to refactor the code to avoid the use of these deprecated functions. Failing
+this the code should be modified to use a const pointer instead.
+The L<EVP_PKEY_get1_RSA(3)>, L<EVP_PKEY_get1_DSA(3)>, L<EVP_PKEY_get1_EC_KEY(3)>
+and L<EVP_PKEY_get1_DH(3)> functions continue to return a non-const pointer to
+enable them to be "freed". However they should also be treated as read-only.
+
+=head4 The public key check has moved from EVP_PKEY_derive() to EVP_PKEY_derive_set_peer()
+
+This may mean result in an error in L<EVP_PKEY_derive_set_peer(3)> rather than
+during L<EVP_PKEY_derive(3)>.
+To disable this check use EVP_PKEY_derive_set_peer_ex(dh, peer, 0). 
+
+=head4 The print format has cosmetic changes for some functions
+
+The output from numerous "printing" functions such as L<X509_signature_print(3)>,
+L<X509_print_ex(3)>, L<X509_CRL_print_ex(3)>, and other similar functions has been
+amended such that there may be cosmetic differences between the output
+observed in 1.1.1 and 3.0. This also applies to the "-text" output from the
+x509 and crl applications.
+
+=head4 Interactive mode from the `openssl` program has been removed
+
+From now on, running it without arguments is equivalent to `openssl help`.
+
+=head4 The error return values from some control calls (ctrl) have changed
+
+One significant change is that controls which used to return -2 for
+invalid inputs, now return -1 indicating a generic error condition instead.
+
+=head4 DH and DHX key types have different settable parameters
+
+Previously (in 1.1.1) these conflicting parameters were allowed, but will now
+result in errors. See L<EVP_PKEY-DH(7)> for further details. This affects the
+behaviour of L<openssl-genpkey(1)> for DH parameter generation.
+
+=head2 Installation and Compilation
+
+Please refer to the INSTALL.md file in the top of the distribution for
+instructions on how to build and install OpenSSL 3.0. Please also refer to the
+various platform specific NOTES files for your specific platform.
+
+=head2 Upgrading from OpenSSL 1.1.1
+
+Upgrading to OpenSSL 3.0 from OpenSSL 1.1.1 should be relatively straight
+forward in most cases. The most likely area where you will encounter problems
+is if you have used low level APIs in your code (as discussed above). In that
+case you are likely to start seeing deprecation warnings when compiling your
+application. If this happens you have 3 options:
+
+=over 4
+
+=item 1) Ignore the warnings. They are just warnings. The deprecated functions are still present and you may still use them. However be aware that they may be removed from a future version of OpenSSL.
+
+=item 2) Suppress the warnings. Refer to your compiler documentation on how to do this.
+
+=item 3) Remove your usage of the low level APIs. In this case you will need to rewrite your code to use the high level APIs instead
+
+=back
+
+=head2 Upgrading from OpenSSL 1.0.2
+
+Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 is likely to be significantly more
+difficult. In addition to the issues discussed above in the section about
+L</Upgrading from OpenSSL 1.1.1>, the main things to be aware of are:
+
+=over 4
+
+=item 1) The build and installation procedure has changed significantly.
+
+Check the file INSTALL.md in the top of the installation for instructions on how
+to build and install OpenSSL for your platform. Also read the various NOTES
+files in the same directory, as applicable for your platform.
+
+=item 2) Many structures have been made opaque in OpenSSL 3.0.
+
+The structure definitions have been removed from the public header files and
+moved to internal header files. In practice this means that you can no longer
+stack allocate some structures. Instead they must be heap allocated through some
+function call (typically those function names have a `_new` suffix to them).
+Additionally you must use "setter" or "getter" functions to access the fields
+within those structures.
+
+For example code that previously looked like this:
+
+ EVP_MD_CTX md_ctx;
+
+ /* This line will now generate compiler errors */
+ EVP_MD_CTX_init(&md_ctx);
+
+ The code needs to be amended to look like this:
+ EVP_MD_CTX *md_ctx;
+
+ md_ctx = EVP_MD_CTX_new();
+ ...
+ ...
+ EVP_MD_CTX_free(md_ctx);
+
+=item 3) Support for TLSv1.3 has been added.
+
+This has a number of implications for SSL/TLS applications. See the 
+L<TLS1.3 page|https://wiki.openssl.org/index.php/TLS1.3> for further details.
+
+=back
+
+More details about the breaking changes between OpenSSL versions 1.0.2 and 1.1.0
+can be found on the
+L<OpenSSL 1.1.0 Changes page|https://wiki.openssl.org/index.php/OpenSSL_1.1.0_Changes>. 
+
+=head3 Upgrading from the OpenSSL 2.0 FIPS Object Module
+
+The OpenSSL 2.0 FIPS Object Module was a separate download that had to be built
+separately and then integrated into your main OpenSSL 1.0.2 build.
+In OpenSSL 3.0 the FIPS support is fully integrated into the mainline version of
+OpenSSL and is no longer a separate download. For further information see
+L</Completing the installation of the FIPS Module>.
+
+The function calls 'FIPS_mode()' and 'FIPS_mode_set()' have been removed
+from OpenSSL 3.0. You should rewrite your application to not use them.
+See L<fips_module(7)> and L<OSSL_PROVIDER-FIPS(7)> for details.
+
+=head2 Completing the installation of the FIPS Module
+
+The FIPS Module will be built and installed automatically if FIPS support has
+been configured. The current documentation can be found in the
+L<README-FIPS|https://github.com/openssl/openssl/blob/master/README-FIPS.md> file.
+
+=head2 Programming
+
+Applications written to work with OpenSSL 1.1.1 will mostly just work with
+OpenSSL 3.0. However changes will be required if you want to take advantage of
+some of the new features that OpenSSL 3.0 makes available. In order to do that
+you need to understand some new concepts introduced in OpenSSL 3.0.
+Read L<crypto(7)/Library contexts> for further information.
+
+=head3 Library Context
+
+A library context allows different components of a complex application to each
+use a different library context and have different providers loaded with
+different configuration settings.
+See L<crypto(7)/Library contexts> for further info.
+
+If the user creates an B<OSSL_LIB_CTX> via L<OSSL_LIB_CTX_new(3)> then many
+functions may need to be changed to pass additional parameters to handle the
+library context.
+
+=head4 Using a Library Context - Old functions that should be changed
+
+If a library context is needed then all EVP_* digest functions that return a
+B<const EVP_MD *> such as EVP_sha256() should be replaced with a call to
+L<EVP_MD_fetch(3)>. See L<crypto(7)/ALGORITHM FETCHING>.
+
+If a library context is needed then all EVP_* cipher functions that return a
+B<const EVP_CIPHER *> such as EVP_aes_128_cbc() should be replaced vith a call to
+L<EVP_CIPHER_fetch(3)>. See L<crypto(7)/ALGORITHM FETCHING>.
+
+Some functions can be passed an object that has already been set up with a library
+context such as L<d2i_X509(3)>, L<d2i_X509_CRL(3)> and L<d2i_X509_REQ(3)>.
+If NULL is passed instead then the created object will be set up with the
+default library context. Use L<X509_new_ex(3)>, L<X509_CRL_new_ex(3)> and
+L<X509_REQ_new_ex(3)> if a library context is required.
+
+All functions listed below with a I<NAME> have a replacment function I<NAME_ex>
+that takes B<OSSL_LIB_CTX> as an additional argument. Functions that have other
+mappings are listed along with the respective name.
+
+=over 4
+
+=item L<ASN1_item_sign(3)> and L<ASN1_item_verify(3)>
+
+=item L<BN_CTX_new(3)> and L<BN_CTX_secure_new(3)>
+
+=item L<CMS_AuthEnvelopedData_create(3)>, L<CMS_ContentInfo_new(3)>, L<CMS_data_create(3)>,
+L<CMS_digest_create(3)>, L<CMS_EncryptedData_encrypt(3)>, L<CMS_encrypt(3)>,
+L<CMS_EnvelopedData_create(3)>, L<CMS_ReceiptRequest_create0(3)> and L<CMS_sign(3)>
+
+=item L<CONF_modules_load_file(3)>
+
+=item L<CTLOG_new(3)>, L<CTLOG_new_from_base64(3)> and L<CTLOG_STORE_new(3)>
+
+=item L<CT_POLICY_EVAL_CTX_new(3)>
+
+=item L<d2i_AutoPrivateKey(3)>, L<d2i_PrivateKey(3)> and L<d2i_PUBKEY(3)>
+
+=item L<d2i_PrivateKey_bio(3)> and L<d2i_PrivateKey_fp(3)>
+
+Use L<d2i_PrivateKey_ex_bio(3)> and L<d2i_PrivateKey_ex_fp(3)>
+
+=item L<EC_GROUP_new(3)>
+
+Use L<EC_GROUP_new_by_curve_name_ex(3)> or L<EC_GROUP_new_from_params(3)>.
+
+=item L<EVP_DigestSignInit(3)> and L<EVP_DigestVerifyInit(3)>
+
+=item L<EVP_PBE_CipherInit(3)>, L<EVP_PBE_find(3)> and L<EVP_PBE_scrypt(3)>
+
+=item L<EVP_PKCS82PKEY(3)>
+
+=item L<EVP_PKEY_CTX_new_id(3)>
+
+Use L<EVP_PKEY_CTX_new_from_name(3)>
+
+=item L<EVP_PKEY_derive_set_peer(3)>, L<EVP_PKEY_new_raw_private_key(3)>
+and L<EVP_PKEY_new_raw_public_key(3)>
+
+=item L<EVP_SignFinal(3)> and L<EVP_VerifyFinal(3)>
+
+=item L<NCONF_new(3)>
+
+=item L<OCSP_RESPID_match(3)> and L<OCSP_RESPID_set_by_key(3)>
+
+=item L<OPENSSL_thread_stop(3)>
+
+=item L<OSSL_STORE_open(3)>
+
+=item L<PEM_read_bio_Parameters(3)>, L<PEM_read_bio_PrivateKey(3)>, L<PEM_read_bio_PUBKEY(3)>,
+L<PEM_read_PrivateKey(3)> and L<PEM_read_PUBKEY(3)>
+
+=item L<PEM_write_bio_PrivateKey(3)>, L<PEM_write_bio_PUBKEY(3)>, L<PEM_write_PrivateKey(3)>
+and L<PEM_write_PUBKEY(3)>
+
+=item L<PEM_X509_INFO_read_bio(3)> and L<PEM_X509_INFO_read(3)>
+
+=item L<PKCS12_add_key(3)>, L<PKCS12_add_safe(3)>, L<PKCS12_add_safes(3)>,
+L<PKCS12_create(3)>, L<PKCS12_decrypt_skey(3)>, L<PKCS12_init(3)>, L<PKCS12_item_decrypt_d2i(3)>,
+L<PKCS12_item_i2d_encrypt(3)>, L<PKCS12_key_gen_asc(3)>, L<PKCS12_key_gen_uni(3)>,
+L<PKCS12_key_gen_utf8(3)>, L<PKCS12_pack_p7encdata(3)>, L<PKCS12_pbe_crypt(3)>,
+L<PKCS12_PBE_keyivgen(3)>, L<PKCS12_SAFEBAG_create_pkcs8_encrypt(3)>
+
+=item L<PKCS5_pbe_set0_algor(3)>, L<PKCS5_pbe_set(3)>, L<PKCS5_pbe2_set_iv(3)>,
+L<PKCS5_pbkdf2_set(3)> and L<PKCS5_v2_scrypt_keyivgen(3)>
+
+=item L<PKCS7_encrypt(3)>, L<PKCS7_new(3)> and L<PKCS7_sign(3)>
+
+=item L<PKCS8_decrypt(3)>, L<PKCS8_encrypt(3)> and L<PKCS8_set0_pbe(3)>
+
+=item L<RAND_bytes(3)> and L<RAND_priv_bytes(3)>
+
+=item L<SMIME_write_ASN1(3)>
+
+=item L<TS_RESP_CTX_new(3)>
+
+=item L<X509_CRL_new(3)>
+
+=item L<X509_load_cert_crl_file(3)> and L<X509_load_cert_file(3)>
+
+=item L<X509_LOOKUP_by_subject(3)> and L<X509_LOOKUP_ctrl(3)>
+
+=item L<X509_NAME_hash(3)>
+
+=item L<X509_new(3)>
+
+=item L<X509_REQ_new(3)> and L<X509_REQ_verify(3)>
+
+=item L<X509_STORE_CTX_new(3)>, L<X509_STORE_set_default_paths(3)>, L<X509_STORE_load_file(3)>,
+L<X509_STORE_load_locations(3)> and L<X509_STORE_load_store(3)>
+
+=back
+
+=head4 New functions that use a Library context
+
+The following functions can be passed a library context if required.
+Passing NULL will use the default library context.
+
+=over 4
+
+=item L<EVP_ASYM_CIPHER_fetch(3)> and L<EVP_ASYM_CIPHER_do_all_provided(3)>
+
+=item L<EVP_CIPHER_fetch(3)> and L<EVP_CIPHER_do_all_provided(3)>
+
+=item L<EVP_default_properties_enable_fips(3)> and
+L<EVP_default_properties_is_fips_enabled(3)>
+
+=item L<EVP_KDF_fetch(3)> and L<EVP_KDF_do_all_provided(3)>
+
+=item L<EVP_KEM_fetch(3)> and L<EVP_KEM_do_all_provided(3)>
+
+=item L<EVP_KEYEXCH_fetch(3)> and L<EVP_KEYEXCH_do_all_provided(3)>
+
+=item L<EVP_KEYMGMT_fetch(3)> and L<EVP_KEYMGMT_do_all_provided(3)>
+
+=item L<EVP_MAC_fetch(3)> and L<EVP_MAC_do_all_provided(3)>
+
+=item L<EVP_MD_fetch(3)> and L<EVP_MD_do_all_provided(3)>
+
+=item L<EVP_PKEY_CTX_new_from_pkey(3)>
+
+=item L<EVP_PKEY_Q_keygen(3)>
+
+=item L<EVP_Q_mac(3)> and L<EVP_Q_digest(3)>
+
+=item L<EVP_RAND(3)> and L<EVP_RAND_do_all_provided(3)>
+
+=item L<EVP_set_default_properties(3)>
+
+=item L<EVP_SIGNATURE_fetch(3)> and L<EVP_SIGNATURE_do_all_provided(3)>
+
+=item L<OSSL_CMP_CTX_new(3)> and L<OSSL_CMP_SRV_CTX_new(3)>
+
+=item L<OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert(3)>
+
+=item L<OSSL_CRMF_MSG_create_popo(3)> and L<OSSL_CRMF_MSGS_verify_popo(3)>
+
+=item L<OSSL_CRMF_pbm_new(3)> and L<OSSL_CRMF_pbmp_new(3)>
+
+=item L<OSSL_DECODER_CTX_add_extra(3)> and L<OSSL_DECODER_CTX_new_for_pkey(3)>
+
+=item L<OSSL_DECODER_fetch(3)> and L<OSSL_DECODER_do_all_provided(3)>
+
+=item L<OSSL_ENCODER_CTX_add_extra(3)>
+
+=item L<OSSL_ENCODER_fetch(3)> and L<OSSL_ENCODER_do_all_provided(3)>
+
+=item L<OSSL_LIB_CTX_free(3)>, L<OSSL_LIB_CTX_load_config(3)> and L<OSSL_LIB_CTX_set0_default(3)>
+
+=item L<OSSL_PROVIDER_add_builtin(3)>, L<OSSL_PROVIDER_available(3)>,
+L<OSSL_PROVIDER_do_all(3)>, L<OSSL_PROVIDER_load(3)>,
+L<OSSL_PROVIDER_set_default_search_path(3)> and L<OSSL_PROVIDER_try_load(3)>
+
+=item L<OSSL_SELF_TEST_get_callback(3)> and L<OSSL_SELF_TEST_set_callback(3)>
+
+=item L<OSSL_STORE_attach(3)>
+
+=item L<OSSL_STORE_LOADER_fetch(3)> and L<OSSL_STORE_LOADER_do_all_provided(3)>
+
+=item L<RAND_get0_primary(3)>, L<RAND_get0_private(3)>, L<RAND_get0_public(3)>,
+L<RAND_set_DRBG_type(3)> and L<RAND_set_seed_source_type(3)>
+
+=back
+
+=head3 Providers
+
+Providers are described in detail here L<crypto(7)/Providers>.
+See also L<crypto(7)/OPENSSL PROVIDERS>.
+
+=head3 Fetching algorithms and property queries
+
+Implicit and Explicit Fetching is described in detail here
+L<crypto(7)/ALGORITHM FETCHING>.
+
+=head3 Deprecation of Low Level Functions
+
+A significant number of APIs have been deprecated in OpenSSL 3.0.
+This section describes some common categories of deprecations.
+See L</Deprecated function mappings> for the list of deprecated functions
+that refer to these categories.
+
+=head4 Providers are a replacement for engines and low-level method overrides
+
+Any accessor that uses an ENGINE is deprecated (such as EVP_PKEY_set1_engine()).
+Applications using engines should instead use providers.
+
+Before providers were added algorithms were overriden by changing the methods
+used by algorithms. All these methods such as RSA_new_method() and RSA_meth_new()
+are now deprecated and can be replaced by using providers instead.
+
+=head4 Deprecated i2d and d2i functions for low-level key types
+
+Any i2d and d2i functions such as d2i_DHparams() that take a low-level key type
+have been deprecated. Applications should instead use the L<OSSL_DECODER(3)> and
+L<OSSL_ENCODER(3)> APIs to read and write files.
+See L<d2i_RSAPrivateKey(3)/Migration> for further details.
+
+=head4 Deprecated low-level key object getters and setters
+
+Applications that set or get low-level key objects (such as EVP_PKEY_set1_DH()
+or EVP_PKEY_get0()) should instead use the OSSL_ENCODER
+(See L<OSSL_ENCODER_to_bio(3)>) or OSSL_DECODER (See L<OSSL_DECODER_from_bio(3)>)
+APIs, or alternatively use L<EVP_PKEY_fromdata(3)> or L<EVP_PKEY_todata(3)>.
+
+=head4 Deprecated low-level key parameter getters
+
+Functions that access low-level objects directly such as L<RSA_get0_n(3)> are now
+deprecated. Applications should use one of L<EVP_PKEY_get_bn_param(3)>,
+L<EVP_PKEY_get_int_param(3)>, l<EVP_PKEY_get_size_t_param(3)>,
+L<EVP_PKEY_get_utf8_string_param(3)>, L<EVP_PKEY_get_octet_string_param(3)> or 
+L<EVP_PKEY_get_params(3)> to access fields from an EVP_PKEY.
+Gettable parameters are listed in L<EVP_PKEY-RSA(7)/Common RSA parameters>,
+L<EVP_PKEY-DH(7)/DH parameters>, L<EVP_PKEY-DSA(7)/DSA parameters>,
+L<EVP_PKEY-FFC(7)/FFC parameters>, L<EVP_PKEY-EC(7)/Common EC parameters> and
+L<EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>.
+Applications may also use L<EVP_PKEY_todata(3)> to return all fields.
+
+=head4 Deprecated low-level key parameter setters
+
+Functions that access low-level objects directly such as L<RSA_set0_crt_params(3)>
+are now deprecated. Applications should use L<EVP_PKEY_fromdata(3)> to create
+new keys from user provided key data. Keys should be immutable once they are
+created, so if required the user may use L<EVP_PKEY_todata(3)>, L<OSSL_PARAM_merge(3)>,
+and L<EVP_PKEY_fromdata(3)> to create a modified key.
+See L<EVP_PKEY-DH(7)/Examples> for more information.
+See L</Deprecated low-level key generation functions> for information on
+generating a key using parameters.
+
+=head4 Deprecated low-level object creation
+
+Low-level objects were created using methods such as L<RSA_new(3)>,
+L<RSA_up_ref(3)> and L<RSA_free(3)>. Applications should instead use the
+high-level EVP_PKEY APIs, e.g. L<EVP_PKEY_new(3)>, L<EVP_PKEY_up_ref(3)> and
+L<EVP_PKEY_free(3)>.
+See also L<EVP_PKEY_CTX_new_from_name(3)> and L<EVP_PKEY_CTX_new_from_pkey(3)>.
+
+EVP_PKEY's may be created in a variety of ways:
+See also L</Deprecated low-level key generation functions>,
+L</Deprecated low-level key reading and writing functions> and
+L</Deprecated low-level key parameter setters>.
+
+=head4 Deprecated low-level encryption functions
+
+Low-level encryption functions such as L<AES_encrypt(3)> and L<AES_decrypt(3)>
+have been informally discouraged from use for a long time. Applications should
+instead use the high level EVP APIs L<EVP_EncryptInit_ex(3)>,
+L<EVP_EncryptUpdate(3)>, and L<EVP_EncryptFinal_ex(3)> or
+L<EVP_DecryptInit_ex(3)>, L<EVP_DecryptUpdate(3)> and L<EVP_DecryptFinal_ex(3)>.
+
+=head4 Deprecated low-level digest functions
+
+Use of low-level digest functions such as L<SHA1_Init(3)> have been
+informally discouraged from use for a long time.  Applications should instead
+use the the high level EVP APIs L<EVP_DigestInit_ex(3)>, L<EVP_DigestUpdate(3)>
+and L<EVP_DigestFinal_ex(3)>, or the quick one-shot L<EVP_Q_digest(3)>.
+
+Note that the functions L<SHA1(3)>, L<SHA224(3)>, L<SHA256(3)>, L<SHA384(3)>
+and L<SHA512(3)> have changed to macros that use L<EVP_Q_digest(3)>.
+
+=head4 Deprecated low-level signing functions
+
+Use of low-level signing functions such as L<DSA_sign(3)> have been
+informally discouraged for a long time. Instead applications should use
+L<EVP_DigestSign(3)> and L<EVP_DigestVerify(3)>.
+See also L<EVP_SIGNATURE-RSA(7)>, L<EVP_SIGNATURE-DSA(7)>,
+L<EVP_SIGNATURE-ECDSA(7)> and L<EVP_SIGNATURE-ED25519(7)>.
+
+=head4 Deprecated low-level MAC functions
+
+Low-level mac functions such as L<CMAC_Init(3)> are deprecated.
+Applications should instead use the new L<EVP_MAC(3)> interface, using
+L<EVP_MAC_CTX_new(3)>, L<EVP_MAC_CTX_free(3)>, L<EVP_MAC_init(3)>,
+L<EVP_MAC_update(3)> and L<EVP_MAC_final(3)> or the single-shot MAC function
+L<EVP_Q_mac(3)>.
+See L<EVP_MAC(3)>, L<EVP_MAC-HMAC(7)>, L<EVP_MAC-CMAC(7)>, L<EVP_MAC-GMAC(7)>,
+L<EVP_MAC-KMAC(7)>, L<EVP_MAC-BLAKE2(7)>, L<EVP_MAC-Poly1305(7)> and
+L<EVP_MAC-Siphash(7)> for additional information.
+
+Note that the one-shot method HMAC() is still available for compatability purposes.
+
+=head4 Deprecated low-level validation functions
+
+Low-level validation functions such as L<DH_check(3)> have been informally
+discouraged from use for a long time. Applications should instead use the high-level
+EVP_PKEY APIs such as L<EVP_PKEY_check(3)>, L<EVP_PKEY_param_check(3)>,
+L<EVP_PKEY_param_check_quick(3)>, L<EVP_PKEY_public_check(3)>,
+L<EVP_PKEY_public_check_quick(3)>, L<EVP_PKEY_private_c