|
@@ -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_check(3)>,
|
|
|
+and L<EVP_PKEY_pairwise_check(3)>.
|
|
|
+
|
|
|
+=head4 Deprecated low-level key exchange functions
|
|
|
+
|
|
|
+Many low-level functions have been informally discouraged from use for a long
|
|
|
+time. Applications should instead use L<EVP_PKEY_derive(3)>.
|
|
|
+See L<EVP_KEYEXCH-DH(7)>, L<EVP_KEYEXCH-ECDH(7)> and L<EVP_KEYEXCH-X25519(7)>.
|
|
|
+
|
|
|
+=head4 Deprecated low-level key generation functions
|
|
|
+
|
|
|
+Many low-level functions have been informally discouraged from use for a long
|
|
|
+time. Applications should instead use L<EVP_PKEY_keygen_init(3)> and
|
|
|
+L<EVP_PKEY_generate(3)> as described in L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>,
|
|
|
+L<EVP_PKEY-RSA(7)>, L<EVP_PKEY-EC(7)> and L<EVP_PKEY-X25519(7)>.
|
|
|
+The 'quick' one-shot function L<EVP_PKEY_Q_keygen(3)> and macros for the most
|
|
|
+common cases: <EVP_RSA_gen(3)> and L<EVP_EC_gen(3)> may also be used.
|
|
|
+
|
|
|
+=head4 Deprecated low-level key reading and writing functions
|
|
|
+
|
|
|
+Use of low-level objects (such as DSA) has been informally discouraged from use
|
|
|
+for a long time. Functions to read and write these low-level objects (such as
|
|
|
+PEM_read_DSA_PUBKEY()) should be replaced. Applications should instead use
|
|
|
+L<OSSL_ENCODER_to_bio(3)> and L<OSSL_DECODER_from_bio(3)>.
|
|
|
+
|
|
|
+=head4 Deprecated low-level key printing functions
|
|
|
+
|
|
|
+Use of low-level objects (such as DSA) has been informally discouraged from use
|
|
|
+for a long time. Functions to print these low-level objects such as
|
|
|
+DSA_print() should be replaced with the equivalent EVP_PKEY functions.
|
|
|
+Application should use one of L<EVP_PKEY_print_public(3)>,
|
|
|
+L<EVP_PKEY_print_private(3)>, L<EVP_PKEY_print_params(3)>,
|
|
|
+L<EVP_PKEY_print_public_fp(3)>, L<EVP_PKEY_print_private_fp(3)> or
|
|
|
+L<EVP_PKEY_print_params_fp(3)>. Note that internally these use
|
|
|
+L<OSSL_ENCODER_to_bio(3)> and L<OSSL_DECODER_from_bio(3)>.
|
|
|
+
|
|
|
+=head3 Deprecated function mappings
|
|
|
+
|
|
|
+The following functions have been deprecated in 3.0.
|
|
|
+
|
|
|
+=over 4
|
|
|
+
|
|
|
+=item AES_bi_ige_encrypt and AES_ige_encrypt
|
|
|
+
|
|
|
+There is no replacement for the IGE functions. New code should not use these modes.
|
|
|
+These undocumented functions were never integrated into the EVP layer.
|
|
|
+They implemented the AES Infinite Garble Extension (IGE) mode and AES
|
|
|
+Bi-directional IGE mode. These modes were never formally standardised and
|
|
|
+usage of these functions is believed to be very small. In particular
|
|
|
+AES_bi_ige_encrypt() has a known bug. It accepts 2 AES keys, but only one
|
|
|
+is ever used. The security implications are believed to be minimal, but
|
|
|
+this issue was never fixed for backwards compatibility reasons.
|
|
|
+
|
|
|
+=item AES_encrypt, AES_decrypt, AES_set_encrypt_key, AES_set_decrypt_key,
|
|
|
+AES_cbc_encrypt, AES_cfb128_encrypt, AES_cfb1_encrypt, AES_cfb8_encrypt,
|
|
|
+AES_ecb_encrypt and AES_ofb128_encrypt
|
|
|
+
|
|
|
+=item AES_unwrap_key, AES_wrap_key
|
|
|
+
|
|
|
+See L</Deprecated low-level encryption functions>
|
|
|
+
|
|
|
+=item AES_options
|
|
|
+
|
|
|
+There is no replacement. It returned a string indicating if the AES code was unrolled.
|
|
|
+
|
|
|
+=item ASN1_digest, ASN1_sign and ASN1_verify
|
|
|
+
|
|
|
+There are no replacements. These old functions are not used, and could be
|
|
|
+disabled with the macro NO_ASN1_OLD since OpenSSL 0.9.7.
|
|
|
+
|
|
|
+=item ASN1_STRING_length_set
|
|
|
+
|
|
|
+Use L<ASN1_STRING_set(3)> or L<ASN1_STRING_set0(3)> instead.
|
|
|
+This was a potentially unsafe function that could change the bounds of a
|
|
|
+previously passed in pointer.
|
|
|
+
|
|
|
+=item BF_encrypt, BF_decrypt, BF_set_key, BF_cbc_encrypt, BF_cfb64_encrypt,
|
|
|
+BF_ecb_encrypt and BF_ofb64_encrypt
|
|
|
+
|
|
|
+See L</Deprecated low-level encryption functions>.
|
|
|
+The Blowfish algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
|
|
|
+
|
|
|
+=item BF_options
|
|
|
+
|
|
|
+There is no replacement. This option returned a constant string.
|
|
|
+
|
|
|
+=item BN_is_prime_ex and BN_is_prime_fasttest_ex
|
|
|
+
|
|
|
+Use L<BN_check_prime(3)> which that avoids possible misuse and always uses at least
|
|
|
+64 rounds of the Miller-Rabin primality test.
|
|
|
+
|
|
|
+=item BN_pseudo_rand and BN_pseudo_rand_range
|
|
|
+
|
|
|
+Use L<BN_rand(3)> and L<BN_rand_range(3)>.
|
|
|
+
|
|
|
+=item BN_X931_derive_prime_ex, BN_X931_generate_prime_ex and BN_X931_generate_Xpq
|
|
|
+
|
|
|
+There are no replacements for these low-level functions. They were used internally
|
|
|
+by RSA_X931_derive_ex() and RSA_X931_generate_key_ex() which are also deprecated.
|
|
|
+Use L<EVP_PKEY_keygen(3)> instead.
|
|
|
+
|
|
|
+=item Camellia_encrypt, Camellia_decrypt, Camellia_set_key,
|
|
|
+Camellia_cbc_encrypt, Camellia_cfb128_encrypt, Camellia_cfb1_encrypt,
|
|
|
+Camellia_cfb8_encrypt, Camellia_ctr128_encrypt, Camellia_ecb_encrypt and
|
|
|
+Camellia_ofb128_encrypt.
|
|
|
+
|
|
|
+See L</Deprecated low-level encryption functions>.
|
|
|
+
|
|
|
+=item CAST_encrypt, CAST_decrypt, CAST_set_key, CAST_cbc_encrypt,
|
|
|
+CAST_cfb64_encrypt, CAST_ecb_encrypt and CAST_ofb64_encrypt
|
|
|
+
|
|
|
+See L</Deprecated low-level encryption functions>.
|
|
|
+The CAST algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
|
|
|
+
|
|
|
+=item CMAC_CTX_new, CMAC_CTX_cleanup, CMAC_CTX_copy, CMAC_CTX_free and
|
|
|
+CMAC_CTX_get0_cipher_ctx
|
|
|
+
|
|
|
+See L</Deprecated low-level MAC functions>.
|
|
|
+
|
|
|
+=item CMAC_Init, CMAC_Update, CMAC_Final and CMAC_resume.
|
|
|
+
|
|
|
+See L</Deprecated low-level MAC functions>.
|
|
|
+
|
|
|
+=item CRYPTO_mem_ctrl, CRYPTO_mem_debug_free, CRYPTO_mem_debug_malloc,
|
|
|
+CRYPTO_mem_debug_pop, CRYPTO_mem_debug_push, CRYPTO_mem_debug_realloc,
|
|
|
+CRYPTO_mem_leaks, CRYPTO_mem_leaks_cb, CRYPTO_mem_leaks_fp and
|
|
|
+CRYPTO_set_mem_debug
|
|
|
+
|
|
|
+Memory-leak checking has been deprecated in favor of more modern development
|
|
|
+tools, such as compiler memory and leak sanitizers or Valgrind.
|
|
|
+
|
|
|
+=item d2i_DHparams, d2i_DHxparams, d2i_DSAparams, d2i_DSAPrivateKey,
|
|
|
+d2i_DSAPrivateKey_bio, d2i_DSAPrivateKey_fp, d2i_DSA_PUBKEY, d2i_DSA_PUBKEY_bio,
|
|
|
+d2i_DSA_PUBKEY_fp, d2i_DSAPublicKey,
|
|
|
+d2i_ECParameters, d2i_ECPrivateKey, d2i_ECPrivateKey_bio, d2i_ECPrivateKey_fp,
|
|
|
+d2i_EC_PUBKEY, d2i_EC_PUBKEY_bio, d2i_EC_PUBKEY_fp, o2i_ECPublicKey,
|
|
|
+d2i_RSAPrivateKey, d2i_RSAPrivateKey_bio, d2i_RSAPrivateKey_fp,
|
|
|
+d2i_RSA_PUBKEY, d2i_RSA_PUBKEY_bio, d2i_RSA_PUBKEY_fp, d2i_RSAPublicKey,
|
|
|
+d2i_RSAPublicKey_bio and d2i_RSAPublicKey_fp
|
|
|
+
|
|
|
+See L</Deprecated i2d and d2i functions for low-level key types>
|
|
|
+
|
|
|
+=item DES_crypt, DES_fcrypt, DES_encrypt1, DES_encrypt2, DES_encrypt3,
|
|
|
+DES_decrypt3, DES_ede3_cbc_encrypt, DES_ede3_cfb64_encrypt,
|
|
|
+DES_ede3_cfb_encrypt,DES_ede3_ofb64_encrypt,
|
|
|
+DES_ecb_encrypt, DES_ecb3_encrypt, DES_ofb64_encrypt, DES_ofb_encrypt,
|
|
|
+DES_cfb64_encrypt DES_cfb_encrypt, DES_cbc_encrypt, DES_ncbc_encrypt,
|
|
|
+DES_pcbc_encrypt, DES_xcbc_encrypt, DES_cbc_cksum, DES_quad_cksum,
|
|
|
+DES_check_key_parity, DES_is_weak_key, DES_key_sched, DES_options,
|
|
|
+DES_random_key, DES_set_key, DES_set_key_checked, DES_set_key_unchecked,
|
|
|
+DES_set_odd_parity, DES_string_to_2keys, DES_string_to_key
|
|
|
+
|
|
|
+See L</Deprecated low-level encryption functions>.
|
|
|
+Algorithms for "DESX-CBC", "DES-ECB", "DES-CBC", "DES-OFB", "DES-CFB",
|
|
|
+"DES-CFB1" and "DES-CFB8" have been moved to the L<Legacy Provider|/Legacy Algorithms>.
|
|
|
+
|
|
|
+=item DH_bits, DH_security_bits and DH_size
|
|
|
+
|
|
|
+Use L<EVP_PKEY_bits(3)>, L<EVP_PKEY_security_bits(3)> and L<EVP_PKEY_size(3)>.
|
|
|
+
|
|
|
+=item DH_check, DH_check_ex, DH_check_params, DH_check_params_ex,
|
|
|
+DH_check_pub_key and DH_check_pub_key_ex
|
|
|
+
|
|
|
+See L</Deprecated low-level validation functions>
|
|
|
+
|
|
|
+=item DH_clear_flags, DH_test_flags and DH_set_flags
|
|
|
+
|
|
|
+The DH_FLAG_CACHE_MONT_P flag has been deprecated without replacement.
|
|
|
+The DH_FLAG_TYPE_DH and DH_FLAG_TYPE_DHX have been deprecated.
|
|
|
+Use EVP_PKEY_is_a() to determine the type of a key.
|
|
|
+There is no replacement for setting these flags.
|
|
|
+
|
|
|
+=item DH_compute_key and DH_compute_key_padded
|
|
|
+
|
|
|
+See L</Deprecated low-level key exchange functions>.
|
|
|
+
|
|
|
+=item DH_new, DH_new_by_nid, DH_free, DH_up_ref
|
|
|
+
|
|
|
+See L</Deprecated low-level object creation>
|
|
|
+
|
|
|
+=item DH_generate_key and DH_generate_parameters_ex
|
|
|
+
|
|
|
+See L</Deprecated low-level key generation functions>.
|
|
|
+
|
|
|
+=item DH_get0_pqg, DH_get0_p, DH_get0_q, DH_get0_g, DH_get0_key,
|
|
|
+DH_get0_priv_key, DH_get0_pub_key, DH_get_length and DH_get_nid
|
|
|
+
|
|
|
+See L</Deprecated low-level key parameter getters>
|
|
|
+
|
|
|
+=item DH_get_1024_160, DH_get_2048_224 and DH_get_2048_256
|
|
|
+
|
|
|
+Applications should instead set the B<OSSL_PKEY_PARAM_GROUP_NAME> as specified in
|
|
|
+L<EVP_PKEY-DH(7)/DH parameters>) to one of "dh_1024_160", "dh_2048_224" or
|
|
|
+"dh_2048_256" when generating a DH key.
|
|
|
+
|
|
|
+=item DH_KDF_X9_42
|
|
|
+
|
|
|
+Applications should use L<EVP_PKEY_CTX_set_dh_kdf_type(3)> instead.
|
|
|
+
|
|
|
+=item DH_get_default_method, DH_get0_engine, DH_meth_*, DH_new_method, DH_OpenSSL,
|
|
|
+DH_get_ex_data, DH_set_default_method, DH_set_method and DH_set_ex_data
|
|
|
+
|
|
|
+See L</Providers are a replacement for engines and low-level method overrides>
|
|
|
+
|
|
|
+=item DHparams_print and DHparams_print_fp
|
|
|
+
|
|
|
+See L</Deprecated low-level key printing functions>
|
|
|
+
|
|
|
+=item DH_set0_key, DH_set0_pqg, DH_set_length
|
|
|
+
|
|
|
+See L</Deprecated low-level key parameter setters>
|
|
|
+
|
|
|
+=item DSA_bits, DSA_security_bits and DSA_size
|
|
|
+
|
|
|
+Use L<EVP_PKEY_bits(3)>, L<EVP_PKEY_security_bits(3)> and L<EVP_PKEY_size(3)>.
|
|
|
+
|
|
|
+=item DHparams_dup, DSA_dup_DH
|
|
|
+
|
|
|
+There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)>
|
|
|
+and L<EVP_PKEY_dup(3)> instead.
|
|
|
+
|
|
|
+=item DSA_generate_key and DSA_generate_parameters_ex
|
|
|
+
|
|
|
+See L</Deprecated low-level key generation functions>.
|
|
|
+
|
|
|
+=item DSA_get0_engine, DSA_get_default_method, DSA_get_ex_data, DSA_get_method,
|
|
|
+DSA_meth_*, DSA_new_method, DSA_OpenSSL, DSA_set_default_method, DSA_set_ex_data
|
|
|
+and DSA_set_method
|
|
|
+
|
|
|
+See L</Providers are a replacement for engines and low-level method overrides>.
|
|
|
+
|
|
|
+=item DSA_get0_p, DSA_get0_q, DSA_get0_g, DSA_get0_pqg, DSA_get0_key,
|
|
|
+DSA_get0_priv_key and DSA_get0_pub_key
|
|
|
+
|
|
|
+See L</Deprecated low-level key parameter getters>.
|
|
|
+
|
|
|
+=item DSA_new, DSA_free, DSA_up_ref
|
|
|
+
|
|
|
+See L</Deprecated low-level object creation>
|
|
|
+
|
|
|
+=item DSAparams_dup
|
|
|
+
|
|
|
+There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)>
|
|
|
+and L<EVP_PKEY_dup(3)> instead.
|
|
|
+
|
|
|
+=item DSAparams_print, DSAparams_print_fp, DSA_print and DSA_print_fp
|
|
|
+
|
|
|
+See L</Deprecated low-level key printing functions>
|
|
|
+
|
|
|
+=item DSA_set0_key, DSA_set0_pqg
|
|
|
+
|
|
|
+See L</Deprecated low-level key parameter setters>
|
|
|
+
|
|
|
+=item DSA_set_flags, DSA_clear_flags, DSA_test_flags
|
|
|
+
|
|
|
+The DSA_FLAG_CACHE_MONT_P flag has been deprecated without replacement.
|
|
|
+
|
|
|
+=item DSA_sign, DSA_do_sign, DSA_sign_setup, DSA_verify and DSA_do_verify
|
|
|
+
|
|
|
+See L</Deprecated low-level signing functions>.
|
|
|
+
|
|
|
+=item ECDH_compute_key
|
|
|
+
|
|
|
+See L</Deprecated low-level key exchange functions>.
|
|
|
+
|
|
|
+=item ECDH_KDF_X9_62
|
|
|
+
|
|
|
+Applications may either set this using the helper function
|
|
|
+L<EVP_PKEY_CTX_set_ecdh_kdf_type(3)> or by setting an B<OSSL_PARAM> using the
|
|
|
+"kdf-type" as shown in L<EVP_KEYEXCH-ECDH(7)/EXAMPLES>
|
|
|
+
|
|
|
+=item ECDSA_sign, ECDSA_sign_ex, ECDSA_sign_setup, ECDSA_do_sign, ECDSA_do_sign_ex,
|
|
|
+ECDSA_verify and ECDSA_do_verify
|
|
|
+
|
|
|
+See L</Deprecated low-level signing functions>.
|
|
|
+
|
|
|
+=item ECDSA_size
|
|
|
+
|
|
|
+Applications should use L<EVP_PKEY_size(3)>.
|
|
|
+
|
|
|
+=item EC_GF2m_simple_method, EC_GFp_mont_method, EC_GFp_nist_method,
|
|
|
+EC_GFp_nistp224_method, EC_GFp_nistp256_method, EC_GFp_nistp521_method and
|
|
|
+EC_GFp_simple_method
|
|
|
+
|
|
|
+There are no replacements for these functions. Applications should rely on the
|
|
|
+library automatically assigning a suitable method internally when an EC_GROUP
|
|
|
+is constructed.
|
|
|
+
|
|
|
+=item EC_GROUP_clear_free
|
|
|
+
|
|
|
+Use L<EC_GROUP_free(3)> instead.
|
|
|
+
|
|
|
+=item EC_GROUP_get_curve_GF2m, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m
|
|
|
+and EC_GROUP_set_curve_GFp
|
|
|
+
|
|
|
+Applications should use L<EC_GROUP_get_curve(3)> and L<EC_GROUP_set_curve(3)>.
|
|
|
+
|
|
|
+=item EC_GROUP_have_precompute_mult, EC_GROUP_precompute_mult and EC_KEY_precompute_mult
|
|
|
+
|
|
|
+These functions are not widely used. Applications should instead switch to
|
|
|
+named curves which OpenSSL has hardcoded lookup tables for.
|
|
|
+
|
|
|
+=item EC_GROUP_new, EC_GROUP_method_of, 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.
|
|
|
+
|
|
|
+=item EC_KEY_can_sign
|
|
|
+
|
|
|
+Applications should use L<EVP_PKEY_can_sign(3)> instead.
|
|
|
+
|
|
|
+=item EC_KEY_check_key
|
|
|
+
|
|
|
+See L</Deprecated low-level validation functions>
|
|
|
+
|
|
|
+=item EC_KEY_set_flags, EC_KEY_get_flags and EC_KEY_clear_flags
|
|
|
+
|
|
|
+See L<EVP_PKEY-EC(7)/Common EC parameters> which handles flags as seperate
|
|
|
+parameters for B<OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT>,
|
|
|
+B<OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE>, B<OSSL_PKEY_PARAM_EC_ENCODING>,
|
|
|
+B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH> and
|
|
|
+B<OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC>.
|
|
|
+See also L<EVP_PKEY-EC(7)/EXAMPLES>
|
|
|
+
|
|
|
+=item EC_KEY_dup, EC_KEY_copy
|
|
|
+
|
|
|
+There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)>
|
|
|
+and L<EVP_PKEY_dup(3)> instead.
|
|
|
+
|
|
|
+=item EC_KEY_decoded_from_explicit_params
|
|
|
+
|
|
|
+There is no replacement.
|
|
|
+
|
|
|
+=item EC_KEY_generate_key
|
|
|
+
|
|
|
+See L</Deprecated low-level key generation functions>.
|
|
|
+
|
|
|
+=item EC_KEY_get0_group, EC_KEY_get0_private_key, EC_KEY_get0_public_key,
|
|
|
+EC_KEY_get_conv_form and EC_KEY_get_enc_flags
|
|
|
+
|
|
|
+See L</Deprecated low-level key parameter getters>.
|
|
|
+
|
|
|
+=item EC_KEY_get0_engine, EC_KEY_get_default_method, EC_KEY_get_method,
|
|
|
+EC_KEY_new_method, EC_KEY_get_ex_data, EC_KEY_OpenSSL, EC_KEY_set_ex_data,
|
|
|
+EC_KEY_set_default_method, EC_KEY_METHOD_*, EC_KEY_set_method
|
|
|
+
|
|
|
+See L</Providers are a replacement for engines and low-level method overrides>
|
|
|
+
|
|
|
+=item EC_METHOD_get_field_type
|
|
|
+
|
|
|
+Use L<EC_GROUP_get_field_type(3)> instead.
|
|
|
+See L</Providers are a replacement for engines and low-level method overrides>
|
|
|
+
|
|
|
+=item EC_KEY_key2buf, EC_KEY_oct2key, EC_KEY_oct2priv, EC_KEY_priv2buf and EC_KEY_priv2oct
|
|
|
+
|
|
|
+There are no replacements for these.
|
|
|
+
|
|
|
+=item EC_KEY_new, EC_KEY_new_by_curve_name, EC_KEY_free, EC_KEY_up_ref
|
|
|
+
|
|
|
+See L</Deprecated low-level object creation>
|
|
|
+
|
|
|
+=item EC_KEY_print, EC_KEY_print_fp
|
|
|
+
|
|
|
+See L</Deprecated low-level key printing functions>
|
|
|
+
|
|
|
+=item EC_KEY_set_asn1_flag, EC_KEY_set_conv_form, EC_KEY_set_enc_flags
|
|
|
+
|
|
|
+See L</Deprecated low-level key parameter setters>.
|
|
|
+
|
|
|
+=item EC_KEY_set_group, EC_KEY_set_private_key, EC_KEY_set_public_key, EC_KEY_set_public_key_affine_coordinates
|
|
|
+
|
|
|
+See L</Deprecated low-level key parameter setters>.
|
|
|
+
|
|
|
+=item ECParameters_print, ECParameters_print_fp, ECPKParameters_print and
|
|
|
+ECPKParameters_print_fp
|
|
|
+
|
|
|
+See L</Deprecated low-level key printing functions>
|
|
|
+
|
|
|
+=item EC_POINT_bn2point and EC_POINT_point2bn
|
|
|
+
|
|
|
+These functions were not particularly useful, since EC point serialization
|
|
|
+formats are not individual big-endian integers.
|
|
|
+
|
|
|
+=item EC_POINT_get_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GFp,
|
|
|
+EC_POINT_set_affine_coordinates_GF2m and EC_POINT_set_affine_coordinates_GFp
|
|
|
+
|
|
|
+Applications should use L<EC_POINT_get_affine_coordinates(3)> and
|
|
|
+L<EC_POINT_set_affine_coordinates(3)> instead.
|
|
|
+
|
|
|
+=item EC_POINT_get_Jprojective_coordinates_GFp and EC_POINT_set_Jprojective_coordinates_GFp
|
|
|
+
|
|
|
+These functions are not widely used. Applications should instead use the
|
|
|
+L<EC_POINT_set_affine_coordinates(3)> and L<EC_POINT_get_affine_coordinates(3)>
|
|
|
+functions.
|
|
|
+
|
|
|
+=item EC_POINT_make_affine and EC_POINTs_make_affine
|
|
|
+
|
|
|
+There is no replacement. These functions were not widely used, and OpenSSL
|
|
|
+automatically performs this conversion when needed.
|
|
|
+
|
|
|
+=item EC_POINT_set_compressed_coordinates_GF2m and EC_POINT_set_compressed_coordinates_GFp
|
|
|
+
|
|
|
+Applications should use L<EC_POINT_set_compressed_coordinates(3)> instead.
|
|
|
+
|
|
|
+=item EC_POINTs_mul
|
|
|
+
|
|
|
+This function is not widely used. Applications should instead use the
|
|
|
+L<EC_POINT_mul(3)> function.
|
|
|
+
|
|
|
+=item ENGINE_*
|
|
|
+
|
|
|
+All engine functions are deprecated. An engine should be rewritten as a provider.
|
|
|
+See L</Providers are a replacement for engines and low-level method overrides>.
|
|
|
+
|
|
|
+=item ERR_load_*, ERR_func_error_string, ERR_get_error_line,
|
|
|
+ERR_get_error_line_data and ERR_get_state
|
|
|
+
|
|
|
+OpenSSL now loads error strings automatically so these functions are not needed.
|
|
|
+
|
|
|
+=item ERR_peek_error_line_data and ERR_peek_last_error_line_data
|
|
|
+
|
|
|
+The new functions are L<ERR_peek_error_func(3)>, L<ERR_peek_last_error_func(3)>,
|
|
|
+L<ERR_peek_error_data(3)>, L<ERR_peek_last_error_data(3)>, L<ERR_get_error_all(3)>,
|
|
|
+L<ERR_peek_error_all(3)> and L<ERR_peek_last_error_all(3)>.
|
|
|
+Applications should use L<ERR_get_error_all(3)>, or pick information
|
|
|
+with ERR_peek functions and finish off with getting the error code by using
|
|
|
+L<ERR_get_error(3)>.
|
|
|
+
|
|
|
+=item EVP_CIPHER_CTX_iv, EVP_CIPHER_CTX_iv_noconst and EVP_CIPHER_CTX_original_iv
|
|
|
+
|
|
|
+Applications should instead use L<EVP_CIPHER_CTX_get_updated_iv(3)>,
|
|
|
+L<EVP_CIPHER_CTX_get_updated_iv(3)> and L<EVP_CIPHER_CTX_get_original_iv(3)>
|
|
|
+respectively.
|
|
|
+See L<EVP_CIPHER_CTX_get_original_iv(3)> for further information.
|
|
|
+
|
|
|
+=item EVP_CIPHER_meth_*, EVP_MD_CTX_set_update_fn, EVP_MD_CTX_update_fn, and EVP_MD_meth_*
|
|
|
+
|
|
|
+See L</Providers are a replacement for engines and low-level method overrides>.
|
|
|
+
|
|
|
+=item 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.
|
|
|
+
|
|
|
+These control operations are not invoked by the OpenSSL library anymore and
|
|
|
+are replaced by direct checks of the key operation against the key type
|
|
|
+when the operation is initialized.
|
|
|
+
|
|
|
+=item EVP_PKEY_CTX_get0_dh_kdf_ukm and EVP_PKEY_CTX_get0_ecdh_kdf_ukm
|
|
|
+
|
|
|
+See the "kdf-ukm" item in L<EVP_KEYEXCH-DH(7)/DH key exchange parameters> and
|
|
|
+L<EVP_KEYEXCH-ECDH(7)/ECDH Key Exchange parameters>.
|
|
|
+These functions are obsolete and should not be required.
|
|
|
+
|
|
|
+=item EVP_PKEY_CTX_set_rsa_keygen_pubexp
|
|
|
+
|
|
|
+Applications should use L<EVP_PKEY_CTX_set1_rsa_keygen_pubexp(3)> instead.
|
|
|
+
|
|
|
+=item EVP_PKEY_cmp and EVP_PKEY_cmp_parameters()
|
|
|
+
|
|
|
+Applications should use L<EVP_PKEY_eq(3)> and L<EVP_PKEY_parameters_eq(3)> instead.
|
|
|
+See L<EVP_PKEY_copy_parameters(3)> for further details.
|
|
|
+
|
|
|
+=item EVP_PKEY_encrypt_old, EVP_PKEY_decrypt_old,
|
|
|
+
|
|
|
+Applications should use L<EVP_PKEY_encrypt_init(3)> and L<EVP_PKEY_encrypt(3)> or
|
|
|
+L<EVP_PKEY_decrypt_init(3)> and L<EVP_PKEY_decrypt(3)> instead.
|
|
|
+
|
|
|
+=item EVP_PKEY_get0
|
|
|
+
|
|
|
+This function returns NULL if the key comes from a provider.
|
|
|
+
|
|
|
+=item EVP_PKEY_get0_DH, EVP_PKEY_get0_DSA, EVP_PKEY_get0_EC_KEY, EVP_PKEY_get0_RSA,
|
|
|
+EVP_PKEY_get1_DH, EVP_PKEY_get1_DSA, EVP_PKEY_get1_EC_KEY and EVP_PKEY_get1_RSA,
|
|
|
+EVP_PKEY_get0_hmac, EVP_PKEY_get0_poly1305 and EVP_PKEY_get0_siphash
|
|
|
+
|
|
|
+See L</Functions that return an internal key should be treated as read only>.
|
|
|
+
|
|
|
+=item EVP_PKEY_meth_*
|
|
|
+
|
|
|
+See L</Providers are a replacement for engines and low-level method overrides>.
|
|
|
+
|
|
|
+=item EVP_PKEY_new_CMAC_key
|
|
|
+
|
|
|
+See L</Deprecated low-level MAC functions>.
|
|
|
+
|
|
|
+=item EVP_PKEY_assign, EVP_PKEY_set1_DH, EVP_PKEY_set1_DSA, EVP_PKEY_set1_EC_KEY and EVP_PKEY_set1_RSA
|
|
|
+
|
|
|
+See L</Deprecated low-level key object getters and setters>
|
|
|
+
|
|
|
+=item 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 into/from an EVP_PKEY object. With OpenSSL 3.0 these are replaced by the more
|
|
|
+generic functions L<EVP_PKEY_set1_encoded_public_key(3)> and
|
|
|
+L<EVP_PKEY_get1_encoded_public_key(3)>.
|
|
|
+The old versions have been converted to deprecated macros that just call the
|
|
|
+new functions.
|
|
|
+
|
|
|
+=item EVP_PKEY_set1_engine and EVP_PKEY_get0_engine
|
|
|
+
|
|
|
+See L</Providers are a replacement for engines and low-level method overrides>.
|
|
|
+
|
|
|
+=item EVP_PKEY_set_alias_type
|
|
|
+
|
|
|
+This function has been removed. There is no replacement.
|
|
|
+See L</EVP_PKEY_set_alias_type() method has been removed>
|
|
|
+
|
|
|
+=item HMAC_Init_ex, HMAC_Update, HMAC_Final, HMAC_size
|
|
|
+
|
|
|
+See L</Deprecated low-level MAC functions>.
|
|
|
+
|
|
|
+=item HMAC_CTX_new, HMAC_CTX_free, HMAC_CTX_copy, HMAC_CTX_reset,
|
|
|
+HMAC_CTX_set_flags and HMAC_CTX_get_md
|
|
|
+
|
|
|
+See L</Deprecated low-level MAC functions>.
|
|
|
+
|
|
|
+=item i2d_DHparams, i2d_DHxparams
|
|
|
+
|
|
|
+See L</Deprecated low-level key reading and writing functions>
|
|
|
+and L<d2i_RSAPrivateKey(3)/Migration>
|
|
|
+
|
|
|
+=item i2d_DSAparams, i2d_DSAPrivateKey, i2d_DSAPrivateKey_bio,
|
|
|
+i2d_DSAPrivateKey_fp, i2d_DSA_PUBKEY, i2d_DSA_PUBKEY_bio, i2d_DSA_PUBKEY_fp and
|
|
|
+i2d_DSAPublicKey
|
|
|
+
|
|
|
+See L</Deprecated low-level key reading and writing functions>
|
|
|
+and L<d2i_RSAPrivateKey(3)/Migration>
|
|
|
+
|
|
|
+=item i2d_ECParameters, i2d_ECPrivateKey, i2d_ECPrivateKey_bio,
|
|
|
+i2d_ECPrivateKey_fp, i2d_EC_PUBKEY, i2d_EC_PUBKEY_bio, i2d_EC_PUBKEY_fp and
|
|
|
+i2o_ECPublicKey.
|
|
|
+
|
|
|
+See L</Deprecated low-level key reading and writing functions>
|
|
|
+and L<d2i_RSAPrivateKey(3)/Migration>
|
|
|
+
|
|
|
+=item i2d_RSAPrivateKey, i2d_RSAPrivateKey_bio, i2d_RSAPrivateKey_fp.
|
|
|
+i2d_RSA_PUBKEY, i2d_RSA_PUBKEY_bio, i2d_RSA_PUBKEY_fp, i2d_RSAPublicKey
|
|
|
+i2d_RSAPublicKey_bio and i2d_RSAPublicKey_fp
|
|
|
+
|
|
|
+See L</Deprecated low-level key reading and writing functions>
|
|
|
+and L<d2i_RSAPrivateKey(3)/Migration>
|
|
|
+
|
|
|
+=item IDEA_encrypt, IDEA_set_decrypt_key, IDEA_set_encrypt_key,
|
|
|
+IDEA_cbc_encrypt, IDEA_cfb64_encrypt, IDEA_ecb_encrypt and IDEA_ofb64_encrypt
|
|
|
+
|
|
|
+See L</Deprecated low-level encryption functions>.
|
|
|
+IDEA has been moved to the L<Legacy Provider|/Legacy Algorithms>.
|
|
|
+
|
|
|
+=item IDEA_options
|
|
|
+
|
|
|
+There is no replacement. This function returned a constant string.
|
|
|
+
|
|
|
+=item MD2, MD2_Init, MD2_Update and MD2_Final
|
|
|
+
|
|
|
+See L</Deprecated low-level encryption functions>.
|
|
|
+MD2 has been moved to the L<Legacy Provider|/Legacy Algorithms>.
|
|
|
+
|
|
|
+=item MD2_options
|
|
|
+
|
|
|
+There is no replacement. This function returned a constant string.
|
|
|
+
|
|
|
+=item MD4, MD4_Init, MD4_Update, MD4_Final and MD4_Transform
|
|
|
+
|
|
|
+See L</Deprecated low-level encryption functions>.
|
|
|
+MD4 has been moved to the L<Legacy Provider|/Legacy Algorithms>.
|
|
|
+
|
|
|
+=item MDC2, MDC2_Init, MDC2_Update and MDC2_Final
|
|
|
+
|
|
|
+See L</Deprecated low-level encryption functions>.
|
|
|
+MDC2 has been moved to the L<Legacy Provider|/Legacy Algorithms>.
|
|
|
+
|
|
|
+=item MD5, MD5_Init, MD5_Update, MD5_Final and MD5_Transform
|
|
|
+
|
|
|
+See L</Deprecated low-level encryption functions>.
|
|
|
+
|
|
|
+=item NCONF_WIN32
|
|
|
+
|
|
|
+This undocumented function has no replacement.
|
|
|
+See L<config(5)/HISTORY> for more details.
|
|
|
+
|
|
|
+=item OCSP_parse_url()
|
|
|
+
|
|
|
+Use L<OSSL_HTTP_parse_url(3)> instead.
|
|
|
+
|
|
|
+=item OCSP_REQ_CTX type and OCSP_REQ_CTX_*() methods.
|
|
|
+
|
|
|
+These methods 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_*(). See L<OSSL_HTTP_REQ_CTX(3)> for additional details.
|
|
|
+
|
|
|
+=item OPENSSL_fork_child, OPENSSL_fork_parent and OPENSSL_fork_prepare
|
|
|
+
|
|
|
+There is no replacement for these functions. These pthread fork support methods
|
|
|
+were unused by OpenSSL.
|
|
|
+
|
|
|
+=item OSSL_STORE_ctrl, OSSL_STORE_do_all_loaders, OSSL_STORE_LOADER_get0_engine,
|
|
|
+OSSL_STORE_LOADER_get0_scheme, OSSL_STORE_LOADER_new,
|
|
|
+OSSL_STORE_LOADER_set_attach, OSSL_STORE_LOADER_set_close,
|
|
|
+OSSL_STORE_LOADER_set_ctrl, OSSL_STORE_LOADER_set_eof
|
|
|
+OSSL_STORE_LOADER_set_error, OSSL_STORE_LOADER_set_expect,
|
|
|
+OSSL_STORE_LOADER_set_find, OSSL_STORE_LOADER_set_load,
|
|
|
+OSSL_STORE_LOADER_set_open, OSSL_STORE_LOADER_set_open_ex,
|
|
|
+OSSL_STORE_register_loader, OSSL_STORE_unregister_loader and OSSL_STORE_vctrl
|
|
|
+
|
|
|
+These functions helped applications and engines create loaders for
|
|
|
+schemes they supported. These are all deprecated and discouraged in favour of
|
|
|
+provider implementations, see L<provider-storemgmt(7)>.
|
|
|
+
|
|
|
+=item PEM_read_DHparams, PEM_read_bio_DHparams,
|
|
|
+PEM_read_DSAparams, PEM_read_bio_DSAparams,
|
|
|
+PEM_read_DSAPrivateKey, PEM_read_DSA_PUBKEY,
|
|
|
+PEM_read_bio_DSAPrivateKey and PEM_read_bio_DSA_PUBKEY,
|
|
|
+PEM_read_ECPKParameters, PEM_read_ECPrivateKey, PEM_read_EC_PUBKEY,
|
|
|
+PEM_read_bio_ECPKParameters, PEM_read_bio_ECPrivateKey, PEM_read_bio_EC_PUBKEY,
|
|
|
+PEM_read_RSAPrivateKey, PEM_read_RSA_PUBKEY, PEM_read_RSAPublicKey,
|
|
|
+PEM_read_bio_RSAPrivateKey, PEM_read_bio_RSA_PUBKEY, PEM_read_bio_RSAPublicKey,
|
|
|
+PEM_write_bio_DHparams, PEM_write_bio_DHxparams, PEM_write_DHparams, PEM_write_DHxparams,
|
|
|
+PEM_write_DSAparams, PEM_write_DSAPrivateKey, PEM_write_DSA_PUBKEY,
|
|
|
+PEM_write_bio_DSAparams, PEM_write_bio_DSAPrivateKey, PEM_write_bio_DSA_PUBKEY,
|
|
|
+PEM_write_ECPKParameters, PEM_write_ECPrivateKey, PEM_write_EC_PUBKEY,
|
|
|
+PEM_write_bio_ECPKParameters, PEM_write_bio_ECPrivateKey, PEM_write_bio_EC_PUBKEY,
|
|
|
+PEM_write_RSAPrivateKey, PEM_write_RSA_PUBKEY, PEM_write_RSAPublicKey,
|
|
|
+PEM_write_bio_RSAPrivateKey, PEM_write_bio_RSA_PUBKEY and PEM_write_bio_RSAPublicKey.
|
|
|
+
|
|
|
+See L</Deprecated low-level key reading and writing functions>
|
|
|
+
|
|
|
+=item PKCS1_MGF1
|
|
|
+
|
|
|
+See L</Deprecated low-level encryption functions>.
|
|
|
+
|
|
|
+=item RAND_get_rand_method, RAND_set_rand_method, RAND_OpenSSL and RAND_set_rand_engine
|
|
|
+
|
|
|
+Applications should instead use L<RAND_set_DRBG_type(3)>,
|
|
|
+L<EVP_RAND(3)> and L<EVP_RAND(7)>.
|
|
|
+See L<RAND_set_rand_method(3)> for more details.
|
|
|
+
|
|
|
+=item RC2_encrypt, RC2_decrypt, RC2_set_key, RC2_cbc_encrypt, RC2_cfb64_encrypt,
|
|
|
+RC2_ecb_encrypt, RC2_ofb64_encrypt,
|
|
|
+RC4, RC4_set_key, RC4_options,
|
|
|
+RC5_32_encrypt, RC5_32_set_key, RC5_32_decrypt, RC5_32_cbc_encrypt,
|
|
|
+RC5_32_cfb64_encrypt, RC5_32_ecb_encrypt and RC5_32_ofb64_encrypt
|
|
|
+
|
|
|
+See L</Deprecated low-level encryption functions>.
|
|
|
+The Algorithms "RC2", "RC4" and "RC5" have been moved to the L<Legacy Provider|/Legacy Algorithms>.
|
|
|
+
|
|
|
+=item RIPEMD160, RIPEMD160_Init, RIPEMD160_Update, RIPEMD160_Final and RIPEMD160_Transform
|
|
|
+
|
|
|
+See L</Deprecated low-level digest functions>.
|
|
|
+The RIPE algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
|
|
|
+
|
|
|
+=item RSA_bits, RSA_security_bits and RSA_size
|
|
|
+
|
|
|
+Use L<EVP_PKEY_bits(3)>, L<EVP_PKEY_security_bits(3)> and L<EVP_PKEY_size(3)>.
|
|
|
+
|
|
|
+=item RSA_check_key and RSA_check_key_ex
|
|
|
+
|
|
|
+See L</Deprecated low-level validation functions>
|
|
|
+
|
|
|
+=item RSA_clear_flags, RSA_flags, RSA_set_flags, RSA_test_flags,
|
|
|
+RSA_setup_blinding, RSA_blinding_off and RSA_blinding_on
|
|
|
+
|
|
|
+All of these RSA flags have been deprecated without replacement:
|
|
|
+
|
|
|
+RSA_FLAG_BLINDING, RSA_FLAG_CACHE_PRIVATE, RSA_FLAG_CACHE_PUBLIC,
|
|
|
+RSA_FLAG_EXT_PKEY, RSA_FLAG_NO_BLINDING, RSA_FLAG_THREAD_SAFE and
|
|
|
+RSA_METHOD_FLAG_NO_CHECK.
|
|
|
+
|
|
|
+=item RSA_generate_key_ex, RSA_generate_multi_prime_key
|
|
|
+
|
|
|
+See L</Deprecated low-level key generation functions>.
|
|
|
+
|
|
|
+=item RSA_get0_engine
|
|
|
+
|
|
|
+See L</Providers are a replacement for engines and low-level method overrides>
|
|
|
+
|
|
|
+=item RSA_get0_crt_params, RSA_get0_d, RSA_get0_dmp1, RSA_get0_dmq1,
|
|
|
+RSA_get0_e, RSA_get0_factors, RSA_get0_iqmp, RSA_get0_key,
|
|
|
+RSA_get0_multi_prime_crt_params, RSA_get0_multi_prime_factors, RSA_get0_n,
|
|
|
+RSA_get0_p, RSA_get0_pss_params, RSA_get0_q and RSA_get_multi_prime_extra_count.
|
|
|
+
|
|
|
+See L</Deprecated low-level key parameter getters>
|
|
|
+
|
|
|
+=item RSA_new, RSA_free and RSA_up_ref
|
|
|
+
|
|
|
+See L</Deprecated low-level object creation>.
|
|
|
+
|
|
|
+=item RSA_get_default_method, RSA_get_ex_data and RSA_get_method
|
|
|
+
|
|
|
+See L</Providers are a replacement for engines and low-level method overrides>.
|
|
|
+
|
|
|
+=item RSA_get_version
|
|
|
+
|
|
|
+There is no replacement.
|
|
|
+
|
|
|
+=item RSA_meth_*, RSA_new_method, RSA_null_method and RSA_PKCS1_OpenSSL
|
|
|
+
|
|
|
+See L</Providers are a replacement for engines and low-level method overrides>.
|
|
|
+
|
|
|
+=item RSA_padding_add_* and RSA_padding_check_*
|
|
|
+
|
|
|
+See L</Deprecated low-level signing functions> and
|
|
|
+L</Deprecated low-level encryption functions>.
|
|
|
+
|
|
|
+=item RSA_print and RSA_print_fp
|
|
|
+
|
|
|
+See L</Deprecated low-level key printing functions>
|
|
|
+
|
|
|
+=item RSA_public_encrypt and RSA_private_decrypt
|
|
|
+
|
|
|
+See L</Deprecated low-level encryption functions>
|
|
|
+
|
|
|
+=item RSA_private_encrypt and RSA_public_decrypt
|
|
|
+
|
|
|
+This is equivalent to doing sign and verify operations (with a padding mode
|
|
|
+of none). See L</Deprecated low-level signing functions>.
|
|
|
+
|
|
|
+=item RSAPrivateKey_dup, RSAPublicKey_dup
|
|
|
+
|
|
|
+There is no direct replacement. Applications may use L<EVP_PKEY_dup(3)>.
|
|
|
+
|
|
|
+=item RSAPublicKey_it and RSAPrivateKey_it
|
|
|
+
|
|
|
+See L</Deprecated low-level key reading and writing functions>
|
|
|
+
|
|
|
+=item RSA_set0_crt_params, RSA_set0_factors, RSA_set0_key and RSA_set0_multi_prime_params
|
|
|
+
|
|
|
+See L</Deprecated low-level key parameter setters>.
|
|
|
+
|
|
|
+=item RSA_set_default_method, RSA_set_method, RSA_set_ex_data
|
|
|
+
|
|
|
+See L</Providers are a replacement for engines and low-level method overrides>
|
|
|
+
|
|
|
+=item RSA_sign, RSA_sign_ASN1_OCTET_STRING, RSA_verify, RSA_verify_ASN1_OCTET_STRING,
|
|
|
+RSA_verify_PKCS1_PSS and RSA_verify_PKCS1_PSS_mgf1
|
|
|
+
|
|
|
+See L</Deprecated low-level signing functions>.
|
|
|
+
|
|
|
+=item RSA_X931_derive_ex, RSA_X931_generate_key_ex and RSA_X931_hash_id.
|
|
|
+
|
|
|
+There are no replacements for these functions.
|
|
|
+X931 padding can be set using L<EVP_SIGNATURE-RSA(7)/Signature Parameters>.
|
|
|
+See B<OSSL_SIGNATURE_PARAM_PAD_MODE>.
|
|
|
+
|
|
|
+=item SEED_encrypt, SEED_decrypt, SEED_set_key, SEED_cbc_encrypt,
|
|
|
+SEED_cfb128_encrypt, SEED_ecb_encrypt and SEED_ofb128_encrypt.
|
|
|
+
|
|
|
+See L</Deprecated low-level encryption functions>.
|
|
|
+The SEED algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
|
|
|
+
|
|
|
+=item SHA1_Init, SHA1_Update, SHA1_Final, SHA1_Transform,
|
|
|
+SHA224_Init, SHA224_Update, SHA224_Final,
|
|
|
+SHA256_Init, SHA256_Update, SHA256_Final, SHA256_Transform,
|
|
|
+SHA384_Init, SHA384_Update, SHA384_Final,
|
|
|
+SHA512_Init, SHA512_Update, SHA512_Final and SHA512_Transform
|
|
|
+
|
|
|
+See L</Deprecated low-level digest functions>.
|
|
|
+
|
|
|
+=item SRP_Calc_A, SRP_Calc_B, SRP_Calc_client_key, SRP_Calc_server_key,
|
|
|
+SRP_Calc_u, SRP_Calc_x, SRP_check_known_gN_param, SRP_create_verifier,
|
|
|
+SRP_create_verifier_BN, SRP_get_default_gN, SRP_user_pwd_free, SRP_user_pwd_new,
|
|
|
+SRP_user_pwd_set0_sv, SRP_user_pwd_set1_ids, SRP_user_pwd_set_gN,
|
|
|
+SRP_VBASE_add0_user, SRP_VBASE_free, SRP_VBASE_get1_by_user, SRP_VBASE_init,
|
|
|
+SRP_VBASE_new, SRP_Verify_A_mod_N, SRP_Verify_B_mod_N
|
|
|
+
|
|
|
+There are no replacements for the SRP functions.
|
|
|
+
|
|
|
+=item SSL_CTX_set_tmp_dh_callback, SSL_set_tmp_dh_callback,
|
|
|
+SSL_CTX_set_tmp_dh and SSL_set_tmp_dh.
|
|
|
+
|
|
|
+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 L<SSL_CTX_set_dh_auto(3)>
|
|
|
+or L<SSL_set_dh_auto(3)>. If custom parameters are necessary then applications can
|
|
|
+use the alternative functions L<SSL_CTX_set0_tmp_dh_pkey(3)> and
|
|
|
+L<SSL_set0_tmp_dh_pkey(3)>. 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.
|
|
|
+
|
|
|
+=item SSL_CTX_set_tlsext_ticket_key_cb.
|
|
|
+
|
|
|
+Use the new L<SSL_CTX_set_tlsext_ticket_key_evp_cb(3)> function instead.
|
|
|
+
|
|
|
+=item WHIRLPOOL, WHIRLPOOL_Init, WHIRLPOOL_Update, WHIRLPOOL_Final and WHIRLPOOL_BitUpdate
|
|
|
+
|
|
|
+See L</Deprecated low-level digest functions>.
|
|
|
+The Whirlpool algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
|
|
|
+
|
|
|
+=item X509_certificate_type
|
|
|
+
|
|
|
+This was an undocumented function. Applications can use L<X509_get0_pubkey(3)>
|
|
|
+and L<X509_get0_signature(3)> instead.
|
|
|
+
|
|
|
+=item X509_http_nbio and X509_CRL_http_nbio
|
|
|
+
|
|
|
+Use L<X509_load_http(3)> and L<X509_CRL_load_http(3)> instead.
|
|
|
+
|
|
|
+=back
|
|
|
+
|
|
|
+=head2 Using the FIPS Module in applications
|
|
|
+
|
|
|
+See L<fips_module(7)> and L<OSSL_PROVIDER-FIPS(7)> for details.
|
|
|
+
|
|
|
+=head2 OpenSSL command line application changes
|
|
|
+
|
|
|
+=head3 New applications
|
|
|
+
|
|
|
+L<'kdf'|openssl-kdf(1)> uses the new L<EVP_KDF(3)> API.
|
|
|
+L<'mac'|openssl-mac(1)> uses the new L<EVP_MAC(3)> API.
|
|
|
+
|
|
|
+=head3 Added options
|
|
|
+
|
|
|
+'-provider_path' and '-provider' are available to all apps and can be used
|
|
|
+multiple times to load any providers, such as the 'legacy' provider or
|
|
|
+third party providers. If used then the 'default' provider would also need to be
|
|
|
+specified if required. The '-provider_path' must be specified before the
|
|
|
+'-provider' option.
|
|
|
+
|
|
|
+The 'list' app has many new options. See L<openssl-list(1)> for more information.
|
|
|
+
|
|
|
+`-crl_lastupdate` and `-crl_nextupdate` used by 'ca' allows explicit setting of
|
|
|
+fields in the generated CRL.
|
|
|
+
|
|
|
+=head3 Removed options
|
|
|
+
|
|
|
+Interactive mode is not longer available.
|
|
|
+
|
|
|
+The `-crypt` option used by `passwd`.
|
|
|
+The '-c' option used by `x509`, `dhparam`, `dsaparam`, and `ecparam`.
|
|
|
+
|
|
|
+=head3 Other Changes
|
|
|
+
|
|
|
+The output of Command line applications may have minor changes.
|
|
|
+These are primarily changes in capitalisation and white space. However, in some
|
|
|
+cases, there are additional differences.
|
|
|
+For example, the DH parameters output from `dhparam` now lists 'P', 'Q', 'G' and
|
|
|
+'pcounter' instead of 'prime', 'generator', 'subgroup order' and 'counter'
|
|
|
+respectively.
|
|
|
+
|
|
|
+The openssl commands that read keys, certificates, and CRLs now
|
|
|
+automatically detect the PEM or DER format of the input files so it is not
|
|
|
+necessary to explicitly specify the input format anymore. However if the
|
|
|
+input format option is used the specified format will be required.
|
|
|
+
|
|
|
+`speed` no longer uses low-level API calls.
|
|
|
+This implies some of the performance numbers might not be comparable with the
|
|
|
+previous releases due to higher overhead. This applies particularly to
|
|
|
+measuring performance on smaller data chunks.
|
|
|
+
|
|
|
+'dhparam', 'dsa', 'gendsa', 'dsaparam', 'genrsa' and 'rsa' have been
|
|
|
+modified to use PKEY APIs.
|
|
|
+'genrsa' and 'rsa' now write PKCS #8 keys by default.
|
|
|
+
|
|
|
+=head3 Default settings
|
|
|
+
|
|
|
+"SHA256" is now the default digest for TS query used by `ts`.
|
|
|
+
|
|
|
+=head3 Deprecated apps
|
|
|
+
|
|
|
+'rsautl' has been deprecated, use 'pkeyutl' instead.
|
|
|
+'dhparam', 'dsa', 'gendsa', 'dsaparam', 'genrsa', 'rsa', 'genrsa' and 'rsa' are
|
|
|
+now in maintenance mode and no new features will be added to them.
|
|
|
+
|
|
|
+=head2 TLS Changes
|
|
|
+
|
|
|
+=over 4
|
|
|
+
|
|
|
+=item TLS 1.3 FFDHE key exchange support added
|
|
|
+
|
|
|
+This uses DH safe prime named groups.
|
|
|
+
|
|
|
+=item 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.
|
|
|
+
|
|
|
+=item SSL and SSL_CTX options are now 64 bit instead of 32 bit.
|
|
|
+
|
|
|
+The signatures of the functions to get and set options on SSL and
|
|
|
+SSL_CTX objects changed from "unsigned long" to "uint64_t" type.
|
|
|
+
|
|
|
+This may require source code changes.
|
|
|
+
|
|
|
+See L<SSL_CTX_get_options(3)>, L<SSL_CTX_set_options(3)>,
|
|
|
+L<SSL_get_options(3)> and L<SSL_set_options(3)>.
|
|
|
+
|
|
|
+=item SSL_set1_host() and SSL_add1_host() Changes
|
|
|
+
|
|
|
+These functions now take IP literal addresses as well as actual hostnames.
|
|
|
+
|
|
|
+=item Added SSL option SSL_OP_CLEANSE_PLAINTEXT
|
|
|
+
|
|
|
+If the option is set, openssl cleanses (zeroizes) plaintext bytes from
|
|
|
+internal buffers after delivering them to the application. Note,
|
|
|
+the application is still responsible for cleansing other copies
|
|
|
+(e.g.: data received by L<SSL_read(3)>).
|
|
|
+
|
|
|
+=item Client-initiated renegotiation is disabled by default.
|
|
|
+
|
|
|
+To allow it, use the '-client_renegotiation' option,
|
|
|
+the B<SSL_OP_ALLOW_CLIENT_RENEGOTIATION> flag, or the "ClientRenegotiation"
|
|
|
+config parameter as appropriate.
|
|
|
+
|
|
|
+=item Secure renegotiation is now required by default for TLS connections
|
|
|
+
|
|
|
+Support for RFC 5746 secure renegotiation is now required by default for
|
|
|
+SSL or TLS connections to succeed. Applications that require the ability
|
|
|
+to connect to legacy peers will need to explicitly set
|
|
|
+SSL_OP_LEGACY_SERVER_CONNECT. Accordingly, SSL_OP_LEGACY_SERVER_CONNECT
|
|
|
+is no longer set as part of SSL_OP_ALL.
|
|
|
+
|
|
|
+=item Combining the Configure options no-ec and no-dh no longer disables TLSv1.3
|
|
|
+
|
|
|
+Typically if OpenSSL has no EC or DH algorithms then it cannot support
|
|
|
+connections with TLSv1.3. However OpenSSL now supports "pluggable" groups
|
|
|
+through providers. Therefore third party providers may supply group
|
|
|
+implementations even where there are no built-in ones. Attempting to create
|
|
|
+TLS connections in such a build without also disabling TLSv1.3 at run time or
|
|
|
+using third party provider groups may result in handshake failures. TLSv1.3
|
|
|
+can be disabled at compile time using the "no-tls1_3" Configure option.
|
|
|
+
|
|
|
+=item SSL_CTX_set_ciphersuites() and SSL_set_ciphersuites() changes.
|
|
|
+
|
|
|
+The methods now ignore unknown ciphers.
|
|
|
+
|
|
|
+=item Security callback change.
|
|
|
+
|
|
|
+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.
|
|
|
+
|
|
|
+=item New SSL option SSL_OP_IGNORE_UNEXPECTED_EOF
|
|
|
+
|
|
|
+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.
|
|
|
+
|
|
|
+=item 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 L<SSL_CTX_set_security_level(3)>. This also means
|
|
|
+that where the signature algorithms extension is missing from a ClientHello
|
|
|
+then the handshake will fail in TLS 1.2 at security level 1. This is because,
|
|
|
+although this extension is optional, failing to provide one means that
|
|
|
+OpenSSL will fallback to a default set of signature algorithms. This default
|
|
|
+set requires the availability of SHA1.
|
|
|
+
|
|
|
+=item 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 L<SSL_CTX_set_security_level(3)>. If the
|
|
|
+leaf certificate is signed with SHA-1, a call to L<SSL_CTX_use_certificate(3)>
|
|
|
+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 L<X509_VERIFY_PARAM_set_auth_level(3)> or using the `-auth_level`
|
|
|
+options of the commands.
|
|
|
+
|
|
|
+=back
|
|
|
+
|
|
|
+=head1 SEE ALSO
|
|
|
+
|
|
|
+L<fips_module(7)>
|
|
|
+
|
|
|
+=head1 COPYRIGHT
|
|
|
+
|
|
|
+Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
|
|
|
+
|
|
|
+Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
|
+this file except in compliance with the License. You can obtain a copy
|
|
|
+in the file LICENSE in the source distribution or at
|
|
|
+L<https://www.openssl.org/source/license.html>.
|
|
|
+
|
|
|
+=cut
|