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

For OpenSSL 3.0 a [Migration guide][] has been added, so the CHANGES entries
listed here are only a brief description.
The migration guide contains more detailed information related to new features,
breaking changes, and mappings for the large list of deprecated functions.

[Migration guide]: https://github.com/openssl/openssl/tree/master/doc/man7/migration_guide.pod

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

 * The signatures of the functions to get and set options on SSL and
   SSL_CTX objects changed from "unsigned long" to "uint64_t" type.
   Some source code changes may be required.

   * Rich Salz *

 * Client-initiated renegotiation is disabled by default. To allow it, use
   the -client_renegotiation option, the SSL_OP_ALLOW_CLIENT_RENEGOTIATION
   flag, or the "ClientRenegotiation" config parameter as appropriate.

   * Rich Salz *

 * Add "abspath" and "includedir" pragma's to config files, to prevent,
   or modify relative pathname inclusion.

   * Rich Salz *

 * OpenSSL includes a cryptographic module that is intended to be FIPS 140-2
   validated. Please consult the README-FIPS and
   README-PROVIDERS files, as well as the migration guide.

   *OpenSSL team members and many third party contributors*

 * For the key types DH and DHX the allowed settable parameters are now different.

   *Shane Lontis*

 * The openssl commands that read keys, certificates, and CRLs now
   automatically detect the PEM or DER format of the input files.

   *David von Oheimb, Richard Levitte, and Tomáš Mráz*

 * Added enhanced PKCS#12 APIs which accept a library context.

   *Jon Spillett*

 * The default manual page suffix ($MANSUFFIX) has been changed to "ossl"

   *Matt Caswell*

 * Added support for Kernel TLS (KTLS).

   *Boris Pismenny, John Baldwin and Andrew Gallatin*

 * Support for RFC 5746 secure renegotiation is now required by default for
   SSL or TLS connections to succeed.

   *Benjamin Kaduk*

 * The signature of the `copy` functional parameter of the
   EVP_PKEY_meth_set_copy() function has changed so its `src` argument is
   now `const EVP_PKEY_CTX *` instead of `EVP_PKEY_CTX *`. Similarly
   the signature of the `pub_decode` functional parameter of the
   EVP_PKEY_asn1_set_public() function has changed so its `pub` argument is
   now `const X509_PUBKEY *` instead of `X509_PUBKEY *`.

   *David von Oheimb*

 * The error return values from some control calls (ctrl) have changed.

   *Paul Dale*

 * A public key check is now performed during EVP_PKEY_derive_set_peer().

   *Shane Lontis*

 * The EVP_PKEY_CTRL_PKCS7_ENCRYPT, EVP_PKEY_CTRL_PKCS7_DECRYPT,
   EVP_PKEY_CTRL_PKCS7_SIGN, EVP_PKEY_CTRL_CMS_ENCRYPT,
   EVP_PKEY_CTRL_CMS_DECRYPT, and EVP_PKEY_CTRL_CMS_SIGN control operations
   are deprecated.

   *Tomáš Mráz*

 * The EVP_PKEY_public_check() and EVP_PKEY_param_check() functions now work for
   more key types.

 * The output from the command line applications may have minor
   changes.

   *Paul Dale*

 * The output from numerous "printing" may have minor changes.

   *David von Oheimb*

 * Windows thread synchronization uses read/write primitives (SRWLock) when
   supported by the OS, otherwise CriticalSection continues to be used.

   *Vincent Drake*

 * Add filter BIO BIO_f_readbuffer() that allows BIO_tell() and BIO_seek() to
   work on read only BIO source/sinks that do not support these functions.
   This allows piping or redirection of a file BIO using stdin to be buffered
   into memory. This is used internally in OSSL_DECODER_from_bio().

   *Shane Lontis*

 * OSSL_STORE_INFO_get_type() may now return an additional value. In 1.1.1
   this function would return one of the values OSSL_STORE_INFO_NAME,
   OSSL_STORE_INFO_PKEY, OSSL_STORE_INFO_PARAMS, OSSL_STORE_INFO_CERT or
   OSSL_STORE_INFO_CRL. Decoded public keys would previously have been reported
   as type OSSL_STORE_INFO_PKEY in 1.1.1. In 3.0 decoded public keys are now
   reported as having the new type OSSL_STORE_INFO_PUBKEY. Applications
   using this function should be amended to handle the changed return value.

   *Richard Levitte*

 * Improved adherence to Enhanced Security Services (ESS, RFC 2634 and RFC 5035)
   for the TSP and CMS Advanced Electronic Signatures (CAdES) implementations.
   As required by RFC 5035 check both ESSCertID and ESSCertIDv2 if both present.
   Correct the semantics of checking the validation chain in case ESSCertID{,v2}
   contains more than one certificate identifier: This means that all
   certificates referenced there MUST be part of the validation chain.

   *David von Oheimb*

 * The implementation of older EVP ciphers related to CAST, IDEA, SEED, RC2, RC4,
   RC5, DESX and DES have been moved to the legacy provider.

   *Matt Caswell*

 * The implementation of the EVP digests MD2, MD4, MDC2, WHIRLPOOL and
   RIPEMD-160 have been moved to the legacy provider.

   *Matt Caswell*

 * The deprecated function EVP_PKEY_get0() now returns NULL being called for a
   provided key.

   *Dmitry Belyavskiy*

 * The deprecated functions EVP_PKEY_get0_RSA(),
   EVP_PKEY_get0_DSA(), EVP_PKEY_get0_EC_KEY(), EVP_PKEY_get0_DH(),
   EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305() and EVP_PKEY_get0_siphash() as
   well as the similarly named "get1" functions behave differently in
   OpenSSL 3.0.

   *Matt Caswell*

 * A number of functions handling low-level keys or engines were deprecated
   including EVP_PKEY_set1_engine(), EVP_PKEY_get0_engine(), EVP_PKEY_assign(),
   EVP_PKEY_get0(), EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305() and
   EVP_PKEY_get0_siphash().

   *Matt Caswell*

 * Deprecated obsolete EVP_PKEY_CTX_get0_dh_kdf_ukm() and
   EVP_PKEY_CTX_get0_ecdh_kdf_ukm() functions.

   *Tomáš Mráz*

 * The RAND_METHOD APIs have been deprecated.

   *Paul Dale*

 * The SRP APIs have been deprecated.

   *Matt Caswell*

 * Add a compile time option to prevent the caching of provider fetched
   algorithms.  This is enabled by including the no-cached-fetch option
   at configuration time.

   *Paul Dale*

 * pkcs12 now uses defaults of PBKDF2, AES and SHA-256, with a MAC iteration
   count of PKCS12_DEFAULT_ITER.

   *Tomáš Mráz and Sahana Prasad*

 * The openssl speed command does not use low-level API calls anymore.

   *Tomáš Mráz*

 * Parallel dual-prime 1024-bit modular exponentiation for AVX512_IFMA
   capable processors.

   *Ilya Albrekht, Sergey Kirillov, Andrey Matyukov (Intel Corp)*

 * Combining the Configure options no-ec and no-dh no longer disables TLSv1.3.

   *Matt Caswell*

 * Implemented support for fully "pluggable" TLSv1.3 groups. This means that
   providers may supply their own group implementations (using either the "key
   exchange" or the "key encapsulation" methods) which will automatically be
   detected and used by libssl.

   *Matt Caswell, Nicola Tuveri*

 * The undocumented function X509_certificate_type() has been deprecated;

   *Rich Salz*

 * Deprecated the obsolete BN_pseudo_rand() and BN_pseudo_rand_range().

   *Tomáš Mráz*

 * Removed RSA padding mode for SSLv23 (which was only used for
   SSLv2). This includes the functions RSA_padding_check_SSLv23() and
   RSA_padding_add_SSLv23() and the `-ssl` option in the deprecated
   `rsautl` command.

   *Rich Salz*

 * Deprecated the obsolete X9.31 RSA key generation related functions.

   *Tomáš Mráz*

 * The default key generation method for the regular 2-prime RSA keys was
   changed to the FIPS 186-4 B.3.6 method.

   *Shane Lontis*

 * Deprecated the BN_is_prime_ex() and BN_is_prime_fasttest_ex() functions.

   *Kurt Roeckx*

 * Deprecated EVP_MD_CTX_set_update_fn() and EVP_MD_CTX_update_fn().

   *Rich Salz*

 * Deprecated the type OCSP_REQ_CTX and the functions OCSP_REQ_CTX_*() and
   replaced with OSSL_HTTP_REQ_CTX and the functions OSSL_HTTP_REQ_CTX_*().

   *Rich Salz, Richard Levitte, and David von Oheimb*

 * Deprecated `X509_http_nbio()` and `X509_CRL_http_nbio()`.

   *David von Oheimb*

 * Deprecated `OCSP_parse_url()`.

   *David von Oheimb*

 * Validation of SM2 keys has been separated from the validation of regular EC
   keys.

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

 * Added convenience functions for generating asymmetric key pairs:
   The 'quick' one-shot (yet somewhat limited) function L<EVP_PKEY_Q_keygen(3)>
   and macros for the most common cases: <EVP_RSA_gen(3)> and L<EVP_EC_gen(3)>.

   *David von Oheimb*

 * All of the low level EC_KEY functions have been deprecated.

   *Shane Lontis, Paul Dale, Richard Levitte, and Tomáš Mráz*

 * Deprecated all the libcrypto and libssl error string loading
   functions.

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

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

   *Shane Lontis*

 * Deprecated EVP_PKEY_set1_tls_encodedpoint() and
   EVP_PKEY_get1_tls_encodedpoint().

   *Matt Caswell*

 * The security callback, which can be customised by application code, supports
   the security operation SSL_SECOP_TMP_DH. One location of the "other" parameter
   was incorrectly passing a DH object. It now passed an EVP_PKEY in all cases.

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

 * Removed EVP_PKEY_set_alias_type().

   *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

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

   *Richard Levitte*

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

   *Tomáš Mráz*

 * Dropped interactive mode from the `openssl` program.

   *Richard Levitte*

 * Deprecated `EVP_PKEY_cmp()` and `EVP_PKEY_cmp_parameters()`.

   *David von Oheimb and Shane Lontis*

 * Deprecated `EC_METHOD_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().

   *Billy Bob Brumley*

 * Deprecated EC_GROUP_new(), EC_GROUP_method_of(), and EC_POINT_method_of().

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

 * Added the AuthEnvelopedData content type structure (RFC 5083) with AES-GCM
   parameter (RFC 5084) for the Cryptographic Message Syntax (CMS).

   *Jakub Zelenka*

 * Deprecated EC_POINT_make_affine() and EC_POINTs_make_affine().

   *Billy Bob Brumley*

 * Deprecated EC_GROUP_precompute_mult(), EC_GROUP_have_precompute_mult(), and
   EC_KEY_precompute_mult().

   *Billy Bob Brumley*

 * Deprecated EC_POINTs_mul().

   *Billy Bob Brumley*

 * Removed FIPS_mode() and FIPS_mode_set().

   *Shane Lontis*

 * The SSL option SSL_OP_IGNORE_UNEXPECTED_EOF is introduced.

   *Dmitry Belyavskiy*

 * Deprecated EC_POINT_set_Jprojective_coordinates_GFp() and
   EC_POINT_get_Jprojective_coordinates_GFp().

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

   *Kurt Roeckx*

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

   *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/`.
   It supports arbitrary request and response content types, GET redirection,
   TLS, connections via HTTP(S) proxies, connections and exchange via
   user-defined BIOs (allowing implicit connections), persistent connections,
   and timeout checks.  See L<OSSL_HTTP_transfer(3)> etc. for details.
   The legacy OCSP-focused (and only partly documented) API
   is retained for backward compatibility, while most of it is deprecated.

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

   *Paul Dale*

 * X509 certificates signed using SHA1 are no longer allowed at security
   level 1 and above.

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

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

   *Paul Dale and Matt Caswell*

 * All of the low level DSA functions have been deprecated.

   *Paul Dale*

 * Reworked the treatment of EC EVP_PKEYs with the SM2 curve to
   automatically become EVP_PKEY_SM2 rather than EVP_PKEY_EC.

   *Richard Levitte*

 * Deprecated low level ECDH and ECDSA functions.

   *Paul Dale*

 * Deprecated EVP_PKEY_decrypt_old() and EVP_PKEY_encrypt_old().

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

   *Paul Dale*

 * All of the low level HMAC functions have been deprecated.

   *Paul Dale and David von Oheimb*

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

   *Paul Dale*

 * The low-level MD2, MD4, MD5, MDC2, RIPEMD160, SHA1, SHA224, SHA256,
   SHA384, SHA512 and Whirlpool digest functions have been deprecated.

   *Paul Dale and David von Oheimb*

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

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