openssl/CHANGES.md

OpenSSL CHANGES
===============

This is a high-level summary of the most important changes.
For a full list of changes, see the [git commit log][log] and
pick the appropriate release branch.

  [log]: https://github.com/openssl/openssl/commits/

OpenSSL Releases
----------------

 - [OpenSSL 3.0](#openssl-30)
 - [OpenSSL 1.1.1](#openssl-111)
 - [OpenSSL 1.1.0](#openssl-110)
 - [OpenSSL 1.0.2](#openssl-102)
 - [OpenSSL 1.0.1](#openssl-101)
 - [OpenSSL 1.0.0](#openssl-100)
 - [OpenSSL 0.9.x](#openssl-09x)

OpenSSL 3.0
-----------

### Changes between 1.1.1 and 3.0 [xx XXX xxxx]

 * Deprecated the obsolete X9.31 RSA key generation related functions
   BN_X931_generate_Xpq(), BN_X931_derive_prime_ex(), and
   BN_X931_generate_prime_ex().

   *Tomas Mraz*

 * Deprecated the type OCSP_REQ_CTX and the functions OCSP_REQ_CTX_new(),
   OCSP_REQ_CTX_free(), OCSP_REQ_CTX_http(), OCSP_REQ_CTX_add1_header(),
   OCSP_REQ_CTX_i2d(), OCSP_REQ_CTX_nbio(), OCSP_REQ_CTX_nbio_d2i(),
   OCSP_REQ_CTX_get0_mem_bio() and OCSP_set_max_response_length().  These
   were used to collect all necessary data to form a HTTP request, and to
   perform the HTTP transfer with that request.  With OpenSSL 3.0, the
   type is OSSL_HTTP_REQ_CTX, and the deprecated functions are replaced
   with OSSL_HTTP_REQ_CTX_new(), OSSL_HTTP_REQ_CTX_free(),
   OSSL_HTTP_REQ_CTX_set_request_line(), OSSL_HTTP_REQ_CTX_add1_header(),
   OSSL_HTTP_REQ_CTX_i2d(), OSSL_HTTP_REQ_CTX_nbio(),
   OSSL_HTTP_REQ_CTX_sendreq_d2i(), OSSL_HTTP_REQ_CTX_get0_mem_bio() and
   OSSL_HTTP_REQ_CTX_set_max_response_length().

   *Rich Salz and Richard Levitte*

 * 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.

   *Nicola Tuveri*

 * Behavior of the `pkey` app is changed, when using the `-check` or `-pubcheck`
   switches: a validation failure triggers an early exit, returning a failure
   exit status to the parent process.

   *Nicola Tuveri*

 * Changed behavior of SSL_CTX_set_ciphersuites() and SSL_set_ciphersuites()
   to ignore unknown ciphers.

   *Otto Hollmann*

 * The `-cipher-commands` and `-digest-commands` options
   of the command line utility `list` have been deprecated.
   Instead use the `-cipher-algorithms` and `-digest-algorithms` options.

   *Dmitry Belyavskiy*

 * Deprecated all the libcrypto and libssl error string loading
   functions: ERR_load_ASN1_strings(), ERR_load_ASYNC_strings(),
   ERR_load_BIO_strings(), ERR_load_BN_strings(), ERR_load_BUF_strings(),
   ERR_load_CMS_strings(), ERR_load_COMP_strings(), ERR_load_CONF_strings(),
   ERR_load_CRYPTO_strings(), ERR_load_CT_strings(), ERR_load_DH_strings(),
   ERR_load_DSA_strings(), ERR_load_EC_strings(), ERR_load_ENGINE_strings(),
   ERR_load_ERR_strings(), ERR_load_EVP_strings(), ERR_load_KDF_strings(),
   ERR_load_OBJ_strings(), ERR_load_OCSP_strings(), ERR_load_PEM_strings(),
   ERR_load_PKCS12_strings(), ERR_load_PKCS7_strings(), ERR_load_RAND_strings(),
   ERR_load_RSA_strings(), ERR_load_OSSL_STORE_strings(), ERR_load_TS_strings(),
   ERR_load_UI_strings(), ERR_load_X509_strings(), ERR_load_X509V3_strings().

   Calling these functions is not necessary since OpenSSL 1.1.0, as OpenSSL
   now loads error strings automatically.

   *Richard Levitte*

 * The functions SSL_CTX_set_tmp_dh_callback and SSL_set_tmp_dh_callback, as
   well as the macros SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() have been
   deprecated. These are used to set the Diffie-Hellman (DH) parameters that
   are to be used by servers requiring ephemeral DH keys. Instead applications
   should consider using the built-in DH parameters that are available by
   calling SSL_CTX_set_dh_auto() or SSL_set_dh_auto(). If custom parameters are
   necessary then applications can use the alternative functions
   SSL_CTX_set0_tmp_dh_pkey() and SSL_set0_tmp_dh_pkey(). There is no direct
   replacement for the "callback" functions. The callback was originally useful
   in order to have different parameters for export and non-export ciphersuites.
   Export ciphersuites are no longer supported by OpenSSL. Use of the callback
   functions should be replaced by one of the other methods described above.

   *Matt Caswell*

 * The `-crypt` option to the `passwd` command line tool has been removed.

   *Paul Dale*

 * The -C option to the `x509`, `dhparam`, `dsaparam`, and `ecparam` commands
   were removed.

   *Rich Salz*

 * Add support for AES Key Wrap inverse ciphers to the EVP layer.
   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".
   The inverse ciphers use AES decryption for wrapping, and
   AES encryption for unwrapping.

   *Shane Lontis*

 * Deprecated EVP_PKEY_set1_tls_encodedpoint() and
   EVP_PKEY_get1_tls_encodedpoint(). These functions were previously used by
   libssl to set or get an encoded public key in/from an EVP_PKEY object. With
   OpenSSL 3.0 these are replaced by the more generic functions
   EVP_PKEY_set1_encoded_public_key() and EVP_PKEY_get1_encoded_public_key().
   The old versions have been converted to deprecated macros that just call the
   new functions.

   *Matt Caswell*

 * The security callback, which can be customised by application code, supports
   the security operation SSL_SECOP_TMP_DH. This is defined to take an EVP_PKEY
   in the "other" parameter. In most places this is what is passed. All these
   places occur server side. However there was one client side call of this
   security operation and it passed a DH object instead. This is incorrect
   according to the definition of SSL_SECOP_TMP_DH, and is inconsistent with all
   of the other locations. Therefore this client side call has been changed to
   pass an EVP_PKEY instead.

   *Matt Caswell*

 * Add PKCS7_get_octet_string() and PKCS7_type_is_other() to the public
   interface. Their functionality remains unchanged.

   *Jordan Montgomery*

 * Added new option for 'openssl list', '-providers', which will display the
   list of loaded providers, their names, version and status.  It optionally
   displays their gettable parameters.

   *Paul Dale*

 * Deprecated EVP_PKEY_set_alias_type().  This function was previously
   needed as a workaround to recognise SM2 keys.  With OpenSSL 3.0, this key
   type is internally recognised so the workaround is no longer needed.

   Functionality is still retained as it is, but will only work with
   EVP_PKEYs with a legacy internal key.

   *Richard Levitte*

 * Deprecated `EVP_PKEY_CTX_set_rsa_keygen_pubexp()` and introduced
   `EVP_PKEY_CTX_set1_rsa_keygen_pubexp()`, which is now preferred.

   *Jeremy Walch*

 * Changed all "STACK" functions to be macros instead of inline functions. Macro
   parameters are still checked for type safety at compile time via helper
   inline functions.

   *Matt Caswell*

 * Remove the RAND_DRBG API

   The RAND_DRBG API did not fit well into the new provider concept as
   implemented by EVP_RAND and EVP_RAND_CTX. The main reason is that the
   RAND_DRBG API is a mixture of 'front end' and 'back end' API calls
   and some of its API calls are rather low-level. This holds in particular
   for the callback mechanism (`RAND_DRBG_set_callbacks()`).

   Adding a compatibility layer to continue supporting the RAND_DRBG API as
   a legacy API for a regular deprecation period turned out to come at the
   price of complicating the new provider API unnecessarily. Since the
   RAND_DRBG API exists only since version 1.1.1, it was decided by the OMC
   to drop it entirely.

   *Paul Dale and Matthias St. Pierre*

 * Allow `SSL_set1_host()` and `SSL_add1_host()` to take IP literal addresses
   as well as actual hostnames.

   *David Woodhouse*

 * The 'MinProtocol' and 'MaxProtocol' configuration commands now silently
   ignore TLS protocol version bounds when configuring DTLS-based contexts, and
   conversely, silently ignore DTLS protocol version bounds when configuring
   TLS-based contexts.  The commands can be repeated to set bounds of both
   types.  The same applies with the corresponding "min_protocol" and
   "max_protocol" command-line switches, in case some application uses both TLS
   and DTLS.

   SSL_CTX instances that are created for a fixed protocol version (e.g.
   `TLSv1_server_method()`) also silently ignore version bounds.  Previously
   attempts to apply bounds to these protocol versions would result in an
   error.  Now only the "version-flexible" SSL_CTX instances are subject to
   limits in configuration files in command-line options.

   *Viktor Dukhovni*

 * Deprecated the `ENGINE` API.  Engines should be replaced with providers
   going forward.

   *Paul Dale*

 * Reworked the recorded ERR codes to make better space for system errors.
   To distinguish them, the macro `ERR_SYSTEM_ERROR()` indicates if the
   given code is a system error (true) or an OpenSSL error (false).

   *Richard Levitte*

 * Reworked the test perl framework to better allow parallel testing.

   *Nicola Tuveri and David von Oheimb*

 * Added ciphertext stealing algorithms AES-128-CBC-CTS, AES-192-CBC-CTS and
   AES-256-CBC-CTS to the providers. CS1, CS2 and CS3 variants are supported.

   *Shane Lontis*

 * 'Configure' has been changed to figure out the configuration target if
   none is given on the command line.  Consequently, the 'config' script is
   now only a mere wrapper.  All documentation is changed to only mention
   'Configure'.

   *Rich Salz and Richard Levitte*

 * Added a library context `OSSL_LIB_CTX` that applications as well as
   other libraries can use to form a separate context within which
   libcrypto operations are performed.

   There are two ways this can be used:

   - Directly, by passing a library context to functions that take
     such an argument, such as `EVP_CIPHER_fetch` and similar algorithm
     fetching functions.
   - Indirectly, by creating a new library context and then assigning
     it as the new default, with `OSSL_LIB_CTX_set0_default`.

   All public OpenSSL functions that take an `OSSL_LIB_CTX` pointer,
   apart from the functions directly related to `OSSL_LIB_CTX`, accept
   NULL to indicate that the default library context should be used.

   Library code that changes the default library context using
   `OSSL_LIB_CTX_set0_default` should take care to restore it with a
   second call before returning to the caller.

   _(Note: the library context was initially called `OPENSSL_CTX` and
   renamed to `OSSL_LIB_CTX` in version 3.0.0 alpha7.)_

   *Richard Levitte*

 * Handshake now fails if Extended Master Secret extension is dropped
   on renegotiation.

   *Tomas Mraz*

 * Dropped interactive mode from the `openssl` program.  From now on,
   running it without arguments is equivalent to `openssl help`.

   *Richard Levitte*

 * Renamed `EVP_PKEY_cmp()` to `EVP_PKEY_eq()` and
   `EVP_PKEY_cmp_parameters()` to `EVP_PKEY_parameters_eq()`.
   While the old function names have been retained for backward compatibility
   they should not be used in new developments
   because their return values are confusing: Unlike other `_cmp()` functions
   they do not return 0 in case their arguments are equal.

   *David von Oheimb*

 * Deprecated `EC_METHOD_get_field_type()`. Applications should switch to
   `EC_GROUP_get_field_type()`.

   *Billy Bob Brumley*

 * Deprecated EC_GFp_simple_method(), EC_GFp_mont_method(),
   EC_GF2m_simple_method(), EC_GFp_nist_method(), EC_GFp_nistp224_method()
   EC_GFp_nistp256_method(), and EC_GFp_nistp521_method().
   Applications should rely on the library automatically assigning a suitable
   EC_METHOD internally upon EC_GROUP construction.

   *Billy Bob Brumley*

 * Deprecated EC_GROUP_new(), EC_GROUP_method_of(), and EC_POINT_method_of().
   EC_METHOD is now an internal-only concept and a suitable EC_METHOD is
   assigned internally without application intervention.
   Users of EC_GROUP_new() should switch to a different suitable constructor.

   *Billy Bob Brumley*

 * Add CAdES-BES signature verification support, mostly derived
   from ESSCertIDv2 TS (RFC 5816) contribution by Marek Klein.

   *Filipe Raimundo da Silva*

 * Add CAdES-BES signature scheme and attributes support (RFC 5126) to CMS API.

   *Antonio Iacono*

 * Deprecated EC_POINT_make_affine() and EC_POINTs_make_affine(). These
   functions are not widely used and now OpenSSL automatically perform this
   conversion when needed.

   *Billy Bob Brumley*

 * Deprecated EC_GROUP_precompute_mult(), EC_GROUP_have_precompute_mult(), and
   EC_KEY_precompute_mult(). These functions are not widely used and
   applications should instead switch to named curves which OpenSSL has
   hardcoded lookup tables for.

   *Billy Bob Brumley*

 * Deprecated EC_POINTs_mul(). This function is not widely used and applications
   should instead use the L<EC_POINT_mul(3)> function.

   *Billy Bob Brumley*

 * Removed FIPS_mode() and FIPS_mode_set(). These functions are legacy API's
   that are not applicable to the new provider model. Applications should
   instead use EVP_default_properties_is_fips_enabled() and
   EVP_default_properties_enable_fips().

   *Shane Lontis*

 * The SSL option SSL_OP_IGNORE_UNEXPECTED_EOF is introduced. If that option
   is set, an unexpected EOF is ignored, it pretends a close notify was received
   instead and so the returned error becomes SSL_ERROR_ZERO_RETURN.

   *Dmitry Belyavskiy*

 * Deprecated EC_POINT_set_Jprojective_coordinates_GFp() and
   EC_POINT_get_Jprojective_coordinates_GFp(). These functions are not widely
   used and applications should instead use the
   L<EC_POINT_set_affine_coordinates(3)> and
   L<EC_POINT_get_affine_coordinates(3)> functions.

   *Billy Bob Brumley*

 * Added OSSL_PARAM_BLD to the public interface.  This allows OSSL_PARAM
   arrays to be more easily constructed via a series of utility functions.
   Create a parameter builder using OSSL_PARAM_BLD_new(), add parameters using
   the various push functions and finally convert to a passable OSSL_PARAM
   array using OSSL_PARAM_BLD_to_param().

   *Paul Dale*

 * The security strength of SHA1 and MD5 based signatures in TLS has been
   reduced. This results in SSL 3, TLS 1.0, TLS 1.1 and DTLS 1.0 no longer
   working at the default security level of 1 and instead requires security
   level 0. The security level can be changed either using the cipher string
   with `@SECLEVEL`, or calling `SSL_CTX_set_security_level()`.

   *Kurt Roeckx*

 * EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_DH(), and
   EVP_PKEY_get0_EC_KEY() can now handle EVP_PKEYs with provider side
   internal keys, if they correspond to one of those built in types.

   *Richard Levitte*

 * Added EVP_PKEY_set_type_by_keymgmt(), to initialise an EVP_PKEY to
   contain a provider side internal key.

   *Richard Levitte*

 * ASN1_verify(), ASN1_digest() and ASN1_sign() have been deprecated.
   They are old functions that we don't use, and that you could disable with
   the macro NO_ASN1_OLD.  This goes all the way back to OpenSSL 0.9.7.

   *Richard Levitte*

 * Project text documents not yet having a proper file name extension
   (`HACKING`, `LICENSE`, `NOTES*`, `README*`, `VERSION`) have been renamed to
   `*.md` as far as reasonable, else `*.txt`, for better use with file managers.

   *David von Oheimb*

 * The main project documents (README, NEWS, CHANGES, INSTALL, SUPPORT)
   have been converted to Markdown with the goal to produce documents
   which not only look pretty when viewed online in the browser, but
   remain well readable inside a plain text editor.

   To achieve this goal, a 'minimalistic' Markdown style has been applied
   which avoids formatting elements that interfere too much with the
   reading flow in the text file. For example, it

   * avoids [ATX headings][] and uses [setext headings][] instead
     (which works for `<h1>` and `<h2>` headings only).
   * avoids [inline links][] and uses [reference links][] instead.
   * avoids [fenced code blocks][] and uses [indented code blocks][] instead.

     [ATX headings]:         https://github.github.com/gfm/#atx-headings
     [setext headings]:      https://github.github.com/gfm/#setext-headings
     [inline links]:         https://github.github.com/gfm/#inline-link
     [reference links]:      https://github.github.com/gfm/#reference-link
     [fenced code blocks]:   https://github.github.com/gfm/#fenced-code-blocks
     [indented code blocks]: https://github.github.com/gfm/#indented-code-blocks

   *Matthias St. Pierre*

 * The test suite is changed to preserve results of each test recipe.
   A new directory test-runs/ with subdirectories named like the
   test recipes are created in the build tree for this purpose.

   *Richard Levitte*

 * Added an implementation of CMP and CRMF (RFC 4210, RFC 4211 RFC 6712).
   This adds `crypto/cmp/`, `crpyto/crmf/`, `apps/cmp.c`, and `test/cmp_*`.
   See L<openssl-cmp(1)> and L<OSSL_CMP_exec_IR_ses(3)> as starting points.

   *David von Oheimb, Martin Peylo*

 * Generalized the HTTP client code from `crypto/ocsp/` into `crpyto/http/`.
   The legacy OCSP-focused and only partly documented API is retained for
   backward compatibility. See L<OSSL_CMP_MSG_http_perform(3)> etc. for details.

   *David von Oheimb*

 * Added `util/check-format.pl`, a tool for checking adherence to the
   OpenSSL coding style <https://www.openssl.org/policies/codingstyle.html>.
   The checks performed are incomplete and yield some false positives.
   Still the tool should be useful for detecting most typical glitches.

   *David von Oheimb*

 * `BIO_do_connect()` and `BIO_do_handshake()` have been extended:
   If domain name resolution yields multiple IP addresses all of them are tried
   after `connect()` failures.

   *David von Oheimb*

 * All of the low level RSA functions have been deprecated including:

   RSA_new_method, RSA_size, RSA_security_bits, RSA_get0_pss_params,
   RSA_get_version, RSA_get0_engine, RSA_generate_key_ex,
   RSA_generate_multi_prime_key, RSA_X931_derive_ex, RSA_X931_generate_key_ex,
   RSA_check_key, RSA_check_key_ex, RSA_public_encrypt, RSA_private_encrypt,
   RSA_public_decrypt, RSA_private_decrypt, RSA_set_default_method,
   RSA_get_default_method, RSA_null_method, RSA_get_method, RSA_set_method,
   RSA_PKCS1_OpenSSL, RSA_print_fp, RSA_print, RSA_sign, RSA_verify,
   RSA_sign_ASN1_OCTET_STRING, RSA_verify_ASN1_OCTET_STRING, RSA_blinding_on,
   RSA_blinding_off, RSA_setup_blinding, RSA_padding_add_PKCS1_type_1,
   RSA_padding_check_PKCS1_type_1, RSA_padding_add_PKCS1_type_2,
   RSA_padding_check_PKCS1_type_2, PKCS1_MGF1, RSA_padding_add_PKCS1_OAEP,
   RSA_padding_check_PKCS1_OAEP, RSA_padding_add_PKCS1_OAEP_mgf1,
   RSA_padding_check_PKCS1_OAEP_mgf1, RSA_padding_add_SSLv23,
   RSA_padding_check_SSLv23, RSA_padding_add_none, RSA_padding_check_none,
   RSA_padding_add_X931, RSA_padding_check_X931, RSA_X931_hash_id,
   RSA_verify_PKCS1_PSS, RSA_padding_add_PKCS1_PSS, RSA_verify_PKCS1_PSS_mgf1,
   RSA_padding_add_PKCS1_PSS_mgf1, RSA_set_ex_data, RSA_get_ex_data,
   RSA_meth_new, RSA_meth_free, RSA_meth_dup, RSA_meth_get0_name,
   RSA_meth_set1_name, RSA_meth_get_flags, RSA_meth_set_flags,
   RSA_meth_get0_app_data, RSA_meth_set0_app_data, RSA_meth_get_pub_enc,
   RSA_meth_set_pub_enc, RSA_meth_get_pub_dec, RSA_meth_set_pub_dec,
   RSA_meth_get_priv_enc, RSA_meth_set_priv_enc, RSA_meth_get_priv_dec,
   RSA_meth_set_priv_dec, RSA_meth_get_mod_exp, RSA_meth_set_mod_exp,
   RSA_meth_get_bn_mod_exp, RSA_meth_set_bn_mod_exp, RSA_meth_get_init,
   RSA_meth_set_init, RSA_meth_get_finish, RSA_meth_set_finish,
   RSA_meth_get_sign, RSA_meth_set_sign, RSA_meth_get_verify,
   RSA_meth_set_verify, RSA_meth_get_keygen, RSA_meth_set_keygen,
   RSA_meth_get_multi_prime_keygen and RSA_meth_set_multi_prime_keygen.

   Use of these low level functions has been informally discouraged for a long
   time.  Instead applications should use L<EVP_PKEY_encrypt_init(3)>,
   L<EVP_PKEY_encrypt(3)>, L<EVP_PKEY_decrypt_init(3)> and
   L<EVP_PKEY_decrypt(3)>.

   *Paul Dale*

 * X509 certificates signed using SHA1 are no longer allowed at security
   level 1 and above.
   In TLS/SSL the default security level is 1. It can be set either
   using the cipher string with `@SECLEVEL`, or calling
   `SSL_CTX_set_security_level()`. If the leaf certificate is signed with SHA-1,
   a call to `SSL_CTX_use_certificate()` will fail if the security level is not
   lowered first.
   Outside TLS/SSL, the default security level is -1 (effectively 0). It can
   be set using `X509_VERIFY_PARAM_set_auth_level()` or using the `-auth_level`
   options of the commands.

   *Kurt Roeckx*

 * The command line utilities dhparam, dsa, gendsa and dsaparam have been
   modified to use PKEY APIs.  These commands are now in maintenance mode
   and no new features will be added to them.

   *Paul Dale*

 * The command line utility rsautl has been deprecated.
   Instead use the pkeyutl program.

   *Paul Dale*

 * The command line utilities genrsa and rsa have been modified to use PKEY
   APIs. They now write PKCS#8 keys by default. These commands are now in
   maintenance mode and no new features will be added to them.

   *Paul Dale*

 * All of the low level DH functions have been deprecated including:

   DH_OpenSSL, DH_set_default_method, DH_get_default_method, DH_set_method,
   DH_new_method, DH_new, DH_free, DH_up_ref, DH_bits, DH_set0_pqg, DH_size,
   DH_security_bits, DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data,
   DH_generate_parameters_ex, DH_check_params_ex, DH_check_ex, DH_check_pub_key_ex,
   DH_check, DH_check_pub_key, DH_generate_key, DH_compute_key,
   DH_compute_key_padded, DHparams_print_fp, DHparams_print, DH_get_nid,
   DH_KDF_X9_42, DH_get0_engine, DH_meth_new, DH_meth_free, DH_meth_dup,
   DH_meth_get0_name, DH_meth_set1_name, DH_meth_get_flags, DH_meth_set_flags,
   DH_meth_get0_app_data, DH_meth_set0_app_data, DH_meth_get_generate_key,
   DH_meth_set_generate_key, DH_meth_get_compute_key, DH_meth_set_compute_key,
   DH_meth_get_bn_mod_exp, DH_meth_set_bn_mod_exp, DH_meth_get_init,
   DH_meth_set_init, DH_meth_get_finish, DH_meth_set_finish,
   DH_meth_get_generate_params and DH_meth_set_generate_params.

   Use of these low level functions has been informally discouraged for a long
   time.  Instead applications should use L<EVP_PKEY_derive_init(3)>
   and L<EVP_PKEY_derive(3)>.

   Additionally functions that read and write DH objects such as d2i_DHparams,
   i2d_DHparams, PEM_read_DHparam, PEM_write_DHparams and other similar
   functions have also been deprecated. Applications should instead use the
   OSSL_DECODER and OSSL_ENCODER APIs to read and write DH files.

   Finaly functions that assign or obtain DH objects from an EVP_PKEY such as
   `EVP_PKEY_assign_DH()`, `EVP_PKEY_get0_DH()`, `EVP_PKEY_get1_DH()`, and
   `EVP_PKEY_set1_DH()` are also deprecated.
   Applications should instead either read or write an
   EVP_PKEY directly using the OSSL_DECODER and OSSL_ENCODER APIs.
   Or load an    EVP_PKEY directly from DH data using `EVP_PKEY_fromdata()`.

   *Paul Dale and Matt Caswell*

 * All of the low level DSA functions have been deprecated including:

   DSA_new, DSA_free, DSA_up_ref, DSA_bits, DSA_get0_pqg, DSA_set0_pqg,
   DSA_get0_key, DSA_set0_key, DSA_get0_p, DSA_get0_q, DSA_get0_g,
   DSA_get0_pub_key, DSA_get0_priv_key, DSA_clear_flags, DSA_test_flags,
   DSA_set_flags, DSA_do_sign, DSA_do_verify, DSA_OpenSSL,
   DSA_set_default_method, DSA_get_default_method, DSA_set_method,
   DSA_get_method, DSA_new_method, DSA_size, DSA_security_bits,
   DSA_sign_setup, DSA_sign, DSA_verify, DSA_get_ex_new_index,
   DSA_set_ex_data, DSA_get_ex_data, DSA_generate_parameters_ex,
   DSA_generate_key, DSA_meth_new, DSA_get0_engine, DSA_meth_free,
   DSA_meth_dup, DSA_meth_get0_name, DSA_meth_set1_name, DSA_meth_get_flags,
   DSA_meth_set_flags, DSA_meth_get0_app_data, DSA_meth_set0_app_data,
   DSA_meth_get_sign, DSA_meth_set_sign, DSA_meth_get_sign_setup,
   DSA_meth_set_sign_setup, DSA_meth_get_verify, DSA_meth_set_verify,
   DSA_meth_get_mod_exp, DSA_meth_set_mod_exp, DSA_meth_get_bn_mod_exp,
   DSA_meth_set_bn_mod_exp, DSA_meth_get_init, DSA_meth_set_init,
   DSA_meth_get_finish, DSA_meth_set_finish, DSA_meth_get_paramgen,
   DSA_meth_set_paramgen, DSA_meth_get_keygen and DSA_meth_set_keygen.

   Use of these low level functions has been informally discouraged for a long
   time.  Instead applications should use L<EVP_DigestSignInit_ex(3)>,
   L<EVP_DigestSignUpdate(3)> and L<EVP_DigestSignFinal(3)>.

   *Paul Dale*

 * Reworked the treatment of EC EVP_PKEYs with the SM2 curve to
   automatically become EVP_PKEY_SM2 rather than EVP_PKEY_EC.
   This means that applications don't have to look at the curve NID and
   `EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2)` to get SM2 computations.
   However, they still can, that `EVP_PKEY_set_alias_type()` call acts as
   a no-op when the EVP_PKEY is already of the given type.

   Parameter and key generation is also reworked to make it possible
   to generate EVP_PKEY_SM2 parameters and keys without having to go
   through EVP_PKEY_EC generation and then change the EVP_PKEY type.
   However, code that does the latter will still work as before.

   *Richard Levitte*

 * Deprecated low level ECDH and ECDSA functions.  These include:

   ECDH_compute_key, ECDSA_do_sign, ECDSA_do_sign_ex, ECDSA_do_verify,
   ECDSA_sign_setup, ECDSA_sign, ECDSA_sign_ex, ECDSA_verify and
   ECDSA_size.

   Use of these low level functions has been informally discouraged for a long
   time.  Instead applications should use the EVP_PKEY_derive(3),
   EVP_DigestSign(3) and EVP_DigestVerify(3) functions.

   *Paul Dale*

 * Deprecated the EC_KEY_METHOD functions.  These include:

   EC_KEY_METHOD_new, EC_KEY_METHOD_free, EC_KEY_METHOD_set_init,
   EC_KEY_METHOD_set_keygen, EC_KEY_METHOD_set_compute_key,
   EC_KEY_METHOD_set_sign, EC_KEY_METHOD_set_verify,
   EC_KEY_METHOD_get_init, EC_KEY_METHOD_get_keygen,
   EC_KEY_METHOD_get_compute_key, EC_KEY_METHOD_get_sign and
   EC_KEY_METHOD_get_verify.

   Instead applications and extension writers should use the OSSL_PROVIDER APIs.

   *Paul Dale*

 * Deprecated EVP_PKEY_decrypt_old(), please use EVP_PKEY_decrypt_init()
   and EVP_PKEY_decrypt() instead.
   Deprecated EVP_PKEY_encrypt_old(), please use EVP_PKEY_encrypt_init()
   and EVP_PKEY_encrypt() instead.

   *Richard Levitte*

 * Enhanced the documentation of EVP_PKEY_size(), EVP_PKEY_bits()
   and EVP_PKEY_security_bits().  Especially EVP_PKEY_size() needed
   a new formulation to include all the things it can be used for,
   as well as words of caution.

   *Richard Levitte*

 * The SSL_CTX_set_tlsext_ticket_key_cb(3) function has been deprecated.
   Instead used the new SSL_CTX_set_tlsext_ticket_key_evp_cb(3) function.

   *Paul Dale*

 * All of the low level HMAC functions have been deprecated including:

   HMAC, HMAC_size, HMAC_CTX_new, HMAC_CTX_reset, HMAC_CTX_free,
   HMAC_Init_ex, HMAC_Update, HMAC_Final, HMAC_CTX_copy, HMAC_CTX_set_flags
   and HMAC_CTX_get_md.

   Use of these low level functions has been informally discouraged for a long
   time.  Instead applications should use 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)>.

   *Paul Dale*

 * Over two thousand fixes were made to the documentation, including:
   - Common options (such as -rand/-writerand, TLS version control, etc)
     were refactored and point to newly-enhanced descriptions in openssl.pod.
   - Added style conformance for all options (with help from Richard Levitte),
     documented all reported missing options, added a CI build to check
     that all options are documented and that no unimplemented options
     are documented.
   - Documented some internals, such as all use of environment variables.
   - Addressed all internal broken L<> references.

   *Rich Salz*

 * All of the low level CMAC functions have been deprecated including:

   CMAC_CTX_new, CMAC_CTX_cleanup, CMAC_CTX_free, CMAC_CTX_get0_cipher_ctx,
   CMAC_CTX_copy, CMAC_Init, CMAC_Update, CMAC_Final and CMAC_resume.

   Use of these low level functions has been informally discouraged for a long
   time.  Instead applications should use 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)>.

   *Paul Dale*

 * All of the low level MD2, MD4, MD5, MDC2, RIPEMD160, SHA1, SHA224, SHA256,
   SHA384, SHA512 and Whirlpool digest functions have been deprecated.
   These include:

   MD2, MD2_options, MD2_Init, MD2_Update, MD2_Final, MD4, MD4_Init,
   MD4_Update, MD4_Final, MD4_Transform, MD5, MD5_Init, MD5_Update,
   MD5_Final, MD5_Transform, MDC2, MDC2_Init, MDC2_Update, MDC2_Final,
   RIPEMD160, RIPEMD160_Init, RIPEMD160_Update, RIPEMD160_Final,
   RIPEMD160_Transform, SHA1_Init, SHA1_Update, SHA1_Final, SHA1_Transform,
   SHA224_Init, SHA224_Update, SHA224_Final, SHA224_Transform, SHA256_Init,
   SHA256_Update, SHA256_Final, SHA256_Transform, SHA384, SHA384_Init,
   SHA384_Update, SHA384_Final, SHA512, SHA512_Init, SHA512_Update,
   SHA512_Final, SHA512_Transform, WHIRLPOOL, WHIRLPOOL_Init,
   WHIRLPOOL_Update, WHIRLPOOL_BitUpdate and WHIRLPOOL_Final.

   Use of these low level functions has been informally discouraged
   for a long time.  Applications should use the EVP_DigestInit_ex(3),
   EVP_DigestUpdate(3) and EVP_DigestFinal_ex(3) functions instead.

   *Paul Dale*

 * Corrected the documentation of the return values from the `EVP_DigestSign*`
   set of functions.  The documentation mentioned negative values for some
   errors, but this was never the case, so the mention of negative values
   was removed.

   Code that followed the documentation and thereby check with something
   like `EVP_DigestSignInit(...) <= 0` will continue to work undisturbed.

   *Richard Levitte*

 * All of the low level cipher functions have been deprecated including:

   AES_options, AES_set_encrypt_key, AES_set_decrypt_key, AES_encrypt,
   AES_decrypt, AES_ecb_encrypt, AES_cbc_encrypt, AES_cfb128_encrypt,
   AES_cfb1_encrypt, AES_cfb8_encrypt, AES_ofb128_encrypt,
   AES_wrap_key, AES_unwrap_key, BF_set_key, BF_encrypt, BF_decrypt,
   BF_ecb_encrypt, BF_cbc_encrypt, BF_cfb64_encrypt, BF_ofb64_encrypt,
   BF_options, Camellia_set_key, Camellia_encrypt, Camellia_decrypt,
   Camellia_ecb_encrypt, Camellia_cbc_encrypt, Camellia_cfb128_encrypt,
   Camellia_cfb1_encrypt, Camellia_cfb8_encrypt, Camellia_ofb128_encrypt,
   Camellia_ctr128_encrypt, CAST_set_key, CAST_encrypt, CAST_decrypt,
   CAST_ecb_encrypt, CAST_cbc_encrypt, CAST_cfb64_encrypt,
   CAST_ofb64_encrypt, DES_options, DES_encrypt1, DES_encrypt2,
   DES_encrypt3, DES_decrypt3, DES_cbc_encrypt, DES_ncbc_encrypt,
   DES_pcbc_encrypt, DES_xcbc_encrypt, DES_cfb_encrypt, DES_cfb64_encrypt,
   DES_ecb_encrypt, DES_ofb_encrypt, DES_ofb64_encrypt, DES_random_key,
   DES_set_odd_parity, DES_check_key_parity, DES_is_weak_key, DES_set_key,
   DES_key_sched, DES_set_key_checked, DES_set_key_unchecked,
   DES_string_to_key, DES_string_to_2keys, DES_fixup_key_parity,
   DES_ecb2_encrypt, DES_ede2_cbc_encrypt, DES_ede2_cfb64_encrypt,
   DES_ede2_ofb64_encrypt, DES_ecb3_encrypt, DES_ede3_cbc_encrypt,
   DES_ede3_cfb64_encrypt, DES_ede3_cfb_encrypt, DES_ede3_ofb64_encrypt,
   DES_cbc_cksum, DES_quad_cksum, IDEA_encrypt, IDEA_options,
   IDEA_ecb_encrypt, IDEA_set_encrypt_key, IDEA_set_decrypt_key,
   IDEA_cbc_encrypt, IDEA_cfb64_encrypt, IDEA_ofb64_encrypt, RC2_set_key,
   RC2_encrypt, RC2_decrypt, RC2_ecb_encrypt, RC2_cbc_encrypt,
   RC2_cfb64_encrypt, RC2_ofb64_encrypt, RC4, RC4_options, RC4_set_key,
   RC5_32_set_key, RC5_32_encrypt, RC5_32_decrypt, RC5_32_ecb_encrypt,
   RC5_32_cbc_encrypt, RC5_32_cfb64_encrypt, RC5_32_ofb64_encrypt,
   SEED_set_key, SEED_encrypt, SEED_decrypt, SEED_ecb_encrypt,
   SEED_cbc_encrypt, SEED_cfb128_encrypt and SEED_ofb128_encrypt.

   Use of these low level functions has been informally discouraged for
   a long time. Applications should use the high level EVP APIs, e.g.
   EVP_EncryptInit_ex, EVP_EncryptUpdate, EVP_EncryptFinal_ex, and the
   equivalently named decrypt functions instead.

   *Matt Caswell and Paul Dale*

 * Removed include/openssl/opensslconf.h.in and replaced it with
   include/openssl/configuration.h.in, which differs in not including
   <openssl/macros.h>.  A short header include/openssl/opensslconf.h
   was added to include both.

   This allows internal hacks where one might need to modify the set
   of configured macros, for example this if deprecated symbols are
   still supposed to be available internally:

       #include <openssl/configuration.h>

       #undef OPENSSL_NO_DEPRECATED
       #define OPENSSL_SUPPRESS_DEPRECATED

       #include <openssl/macros.h>

   This should not be used by applications that use the exported
   symbols, as that will lead to linking errors.

   *Richard Levitte*

 * Fixed an overflow bug in the x64_64 Montgomery squaring procedure
   used in exponentiation with 512-bit moduli. No EC algorithms are
   affected. Analysis suggests that attacks against 2-prime RSA1024,
   3-prime RSA1536, and DSA1024 as a result of this defect would be very
   difficult to perform and are not believed likely. Attacks against DH512
   are considered just feasible. However, for an attack the target would
   have to re-use the DH512 private key, which is not recommended anyway.
   Also applications directly using the low level API BN_mod_exp may be
   affected if they use BN_FLG_CONSTTIME.
   ([CVE-2019-1551])

   *Andy Polyakov*

 * Most memory-debug features have been deprecated, and the functionality
   replaced with no-ops.

   *Rich Salz*

 * Added documentation for the STACK API.

   *Rich Salz*

 * Introduced a new method type and API, OSSL_ENCODER, to
   represent generic encoders.  An implementation is expected to
   be able to encode an object associated with a given name (such
   as an algorithm name for an asymmetric key) into forms given by
   implementation properties.

   Encoders are primarily used from inside libcrypto, through
   calls to functions like EVP_PKEY_print_private(),
   PEM_write_bio_PrivateKey() and similar.

   Encoders are specified in such a way that they can be made to
   directly handle the provider side portion of an object, if this
   provider side part comes from the same provider as the encoder
   itself, but can also be made to handle objects in parametrized
   form (as an OSSL_PARAM array of data).  This allows a provider to
   offer generic encoders as a service for any other provider.

   *Richard Levitte*

 * Added a .pragma directive to the syntax of configuration files, to
   allow varying behavior in a supported and predictable manner.
   Currently added pragma:

           .pragma dollarid:on

   This allows dollar signs to be a keyword character unless it's
   followed by a opening brace or parenthesis.  This is useful for
   platforms where dollar signs are commonly used in names, such as
   volume names and system directory names on VMS.

   *Richard Levitte*

 * Added functionality to create an EVP_PKEY from user data.  This
   is effectively the same as creating a RSA, DH or DSA object and
   then assigning them to an EVP_PKEY, but directly using algorithm
   agnostic EVP functions.  A benefit is that this should be future
   proof for public key algorithms to come.

   *Richard Levitte*

 * Change the interpretation of the '--api' configuration option to
   mean that this is a desired API compatibility level with no
   further meaning.  The previous interpretation, that this would
   also mean to remove all deprecated symbols up to and including
   the given version, no requires that 'no-deprecated' is also used
   in the configuration.

   When building applications, the desired API compatibility level
   can be set with the OPENSSL_API_COMPAT macro like before.  For
   API compatibility version below 3.0, the old style numerical
   value is valid as before, such as -DOPENSSL_API_COMPAT=0x10100000L.
   For version 3.0 and on, the value is expected to be the decimal
   value calculated from the major and minor version like this:

           MAJOR * 10000 + MINOR * 100

   Examples:

           -DOPENSSL_API_COMPAT=30000             For 3.0
           -DOPENSSL_API_COMPAT=30200             For 3.2