5 migration_guide - OpenSSL migration guide
9 See the individual manual pages for details.
13 This guide details the changes required to migrate to new versions of OpenSSL.
14 Currently this covers OpenSSL 3.0. For earlier versions refer to
15 L<https://github.com/openssl/openssl/blob/master/CHANGES.md>.
16 For an overview of some of the key concepts introduced in OpenSSL 3.0 see
21 =head2 Main Changes from OpenSSL 1.1.1
25 OpenSSL 3.0 is a major release and consequently any application that currently
26 uses an older version of OpenSSL will at the very least need to be recompiled in
27 order to work with the new version. It is the intention that the large majority
28 of applications will work unchanged with OpenSSL 3.0 if those applications
29 previously worked with OpenSSL 1.1.1. However this is not guaranteed and some
30 changes may be required in some cases. Changes may also be required if
31 applications need to take advantage of some of the new features available in
32 OpenSSL 3.0 such as the availability of the FIPS module.
36 In previous versions, OpenSSL was licensed under the L<dual OpenSSL and SSLeay
37 licenses|https://www.openssl.org/source/license-openssl-ssleay.txt>
38 (both licenses apply). From OpenSSL 3.0 this is replaced by the
39 L<Apache License v2|https://www.openssl.org/source/apache-license-2.0.txt>.
41 =head3 Providers and FIPS support
43 One of the key changes from OpenSSL 1.1.1 is the introduction of the Provider
44 concept. Providers collect together and make available algorithm implementations.
45 With OpenSSL 3.0 it is possible to specify, either programmatically or via a
46 config file, which providers you want to use for any given application.
47 OpenSSL 3.0 comes with 5 different providers as standard. Over time third
48 parties may distribute additional providers that can be plugged into OpenSSL.
49 All algorithm implementations available via providers are accessed through the
50 "high level" APIs (for example those functions prefixed with C<EVP>). They cannot
51 be accessed using the L</Low Level APIs>.
53 One of the standard providers available is the FIPS provider. This makes
54 available FIPS validated cryptographic algorithms.
55 The FIPS provider is disabled by default and needs to be enabled explicitly
56 at configuration time using the C<enable-fips> option. If it is enabled,
57 the FIPS provider gets built and installed in addition to the other standard
58 providers. No separate installation procedure is necessary.
59 There is however a dedicated C<install_fips> make target, which serves the
60 special purpose of installing only the FIPS provider into an existing
63 See also L</Legacy Algorithms> for information on the legacy provider.
65 See also L</Completing the installation of the FIPS Module> and
66 L</Using the FIPS Module in applications>.
70 OpenSSL has historically provided two sets of APIs for invoking cryptographic
71 algorithms: the "high level" APIs (such as the C<EVP> APIs) and the "low level"
72 APIs. The high level APIs are typically designed to work across all algorithm
73 types. The "low level" APIs are targeted at a specific algorithm implementation.
74 For example, the EVP APIs provide the functions L<EVP_EncryptInit_ex(3)>,
75 L<EVP_EncryptUpdate(3)> and L<EVP_EncryptFinal(3)> to perform symmetric
76 encryption. Those functions can be used with the algorithms AES, CHACHA, 3DES etc.
77 On the other hand, to do AES encryption using the low level APIs you would have
78 to call AES specific functions such as L<AES_set_encrypt_key(3)>,
79 L<AES_encrypt(3)>, and so on. The functions for 3DES are different.
80 Use of the low level APIs has been informally discouraged by the OpenSSL
81 development team for a long time. However in OpenSSL 3.0 this is made more
82 formal. All such low level APIs have been deprecated. You may still use them in
83 your applications, but you may start to see deprecation warnings during
84 compilation (dependent on compiler support for this). Deprecated APIs may be
85 removed from future versions of OpenSSL so you are strongly encouraged to update
86 your code to use the high level APIs instead.
88 This is described in more detail in L</Deprecation of Low Level Functions>
90 =head3 Legacy Algorithms
92 Some cryptographic algorithms such as B<MD2> and B<DES> that were available via
93 the EVP APIs are now considered legacy and their use is strongly discouraged.
94 These legacy EVP algorithms are still available in OpenSSL 3.0 but not by
95 default. If you want to use them then you must load the legacy provider.
96 This can be as simple as a config file change, or can be done programmatically.
97 See L<OSSL_PROVIDER-legacy(7)> for a complete list of algorithms.
98 Applications using the EVP APIs to access these algorithms should instead use
99 more modern algorithms. If that is not possible then these applications
100 should ensure that the legacy provider has been loaded. This can be achieved
101 either programmatically or via configuration. See L<crypto(7)> man page for
102 more information about providers.
104 =head3 Engines and "METHOD" APIs
106 The refactoring to support Providers conflicts internally with the APIs used to
107 support engines, including the ENGINE API and any function that creates or
108 modifies custom "METHODS" (for example L<EVP_MD_meth_new(3)>,
109 L<EVP_CIPHER_meth_new(3)>, L<EVP_PKEY_meth_new(3)>, L<RSA_meth_new(3)>,
110 L<EC_KEY_METHOD_new(3)>, etc.). These functions are being deprecated in
111 OpenSSL 3.0, and users of these APIs should know that their use can likely
112 bypass provider selection and configuration, with unintended consequences.
113 This is particularly relevant for applications written to use the OpenSSL 3.0
114 FIPS module, as detailed below. Authors and maintainers of external engines are
115 strongly encouraged to refactor their code transforming engines into providers
116 using the new Provider API and avoiding deprecated methods.
118 =head3 Versioning Scheme
120 The OpenSSL versioning scheme has changed with the OpenSSL 3.0 release. The new
121 versioning scheme has this format:
125 For OpenSSL 1.1.1 and below, different patch levels were indicated by a letter
126 at the end of the release version number. This will no longer be used and
127 instead the patch level is indicated by the final number in the version. A
128 change in the second (MINOR) number indicates that new features may have been
129 added. OpenSSL versions with the same major number are API and ABI compatible.
130 If the major number changes then API and ABI compatibility is not guaranteed.
132 For more information, see L<OpenSSL_version(3)>.
134 =head3 Other major new features
136 =head4 Certificate Management Protocol (CMP, RFC 4210)
138 This also covers CRMF (RFC 4211) and HTTP transfer (RFC 6712)
139 See L<openssl-cmp(1)> and L<OSSL_CMP_exec_certreq(3)> as starting points.
141 =head4 HTTP(S) client
143 A proper HTTP(S) client that supports GET and POST, redirection, plain and
144 ASN.1-encoded contents, proxies, and timeouts.
146 =head4 Key Derivation Function API (EVP_KDF)
148 This simplifies the process of adding new KDF and PRF implementations.
150 Previously KDF algorithms had been shoe-horned into using the EVP_PKEY object
151 which was not a logical mapping.
152 Existing applications that use KDF algorithms using EVP_PKEY
153 (scrypt, TLS1 PRF and HKDF) may be slower as they use an EVP_KDF bridge
155 All new applications should use the new L<EVP_KDF(3)> interface.
156 See also L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)> and
157 L<OSSL_PROVIDER-FIPS(7)/Key Derivation Function (KDF)>.
159 =head4 Message Authentication Code API (EVP_MAC)
161 This simplifies the process of adding MAC implementations.
163 This includes a generic EVP_PKEY to EVP_MAC bridge, to facilitate the continued
164 use of MACs through raw private keys in functionality such as
165 L<EVP_DigestSign(3)> and L<EVP_DigestVerify(3)>.
167 All new applications should use the new L<EVP_MAC(3)> interface.
168 See also L<OSSL_PROVIDER-default(7)/Message Authentication Code (MAC)>
169 and L<OSSL_PROVIDER-FIPS(7)/Message Authentication Code (MAC)>.
171 =head4 Support for Linux Kernel TLS
173 In order to use KTLS, support for it must be compiled in using the
174 C<enable-ktls> configuration option. It must also be enabled at run time using
175 the B<SSL_OP_ENABLE_KTLS> option.
177 =head4 New Algorithms
183 KDF algorithms "SINGLE STEP" and "SSH"
185 See L<EVP_KDF-SS(7)> and L<EVP_KDF-SSHKDF(7)>
189 MAC Algorithms "GMAC" and "KMAC"
191 See L<EVP_MAC-GMAC(7)> and L<EVP_MAC-KMAC(7)>.
195 KEM Algorithm "RSASVE"
197 See L<EVP_KEM-RSA(7)>.
201 Cipher Algorithm "AES-SIV"
203 See L<EVP_EncryptInit(3)/SIV Mode>.
207 AES Key Wrap inverse ciphers supported by EVP layer.
209 The inverse ciphers use AES decryption for wrapping, and AES encryption for
210 unwrapping. The algorithms are: "AES-128-WRAP-INV", "AES-192-WRAP-INV",
211 "AES-256-WRAP-INV", "AES-128-WRAP-PAD-INV", "AES-192-WRAP-PAD-INV" and
212 "AES-256-WRAP-PAD-INV".
214 =item AES CTS cipher added to EVP layer.
216 The algorithms are "AES-128-CBC-CTS", "AES-192-CBC-CTS" and "AES-256-CBC-CTS".
217 CS1, CS2 and CS3 variants are supported.
221 =head4 CMS and PKCS#7 updates
227 Added CAdES-BES signature verification support.
231 Added CAdES-BES signature scheme and attributes support (RFC 5126) to CMS API.
235 Added AuthEnvelopedData content type structure (RFC 5083) using AES_GCM
237 This uses the AES-GCM parameter (RFC 5084) for the Cryptographic Message Syntax.
238 Its purpose is to support encryption and decryption of a digital envelope that
239 is both authenticated and encrypted using AES GCM mode.
243 L<PKCS7_get_octet_string(3)> and L<PKCS7_type_is_other(3)> were made public.
247 =head4 PKCS#12 API updates
249 The default algorithms for pkcs12 creation with the PKCS12_create() function
250 were changed to more modern PBKDF2 and AES based algorithms. The default
251 MAC iteration count was changed to PKCS12_DEFAULT_ITER to make it equal
252 with the password-based encryption iteration count. The default digest
253 algorithm for the MAC computation was changed to SHA-256. The pkcs12
254 application now supports -legacy option that restores the previous
255 default algorithms to support interoperability with legacy systems.
257 Added enhanced PKCS#12 APIs which accept a library context B<OSSL_LIB_CTX>
258 and (where relevant) a property query. Other APIs which handle PKCS#7 and
259 PKCS#8 objects have also been enhanced where required. This includes:
261 L<PKCS12_add_key_ex(3)>, L<PKCS12_add_safe_ex(3)>, L<PKCS12_add_safes_ex(3)>,
262 L<PKCS12_create_ex(3)>, L<PKCS12_decrypt_skey_ex(3)>, L<PKCS12_init_ex(3)>,
263 L<PKCS12_item_decrypt_d2i_ex(3)>, L<PKCS12_item_i2d_encrypt_ex(3)>,
264 L<PKCS12_key_gen_asc_ex(3)>, L<PKCS12_key_gen_uni_ex(3)>, L<PKCS12_key_gen_utf8_ex(3)>,
265 L<PKCS12_pack_p7encdata_ex(3)>, L<PKCS12_pbe_crypt_ex(3)>, L<PKCS12_PBE_keyivgen_ex(3)>,
266 L<PKCS12_SAFEBAG_create_pkcs8_encrypt_ex(3)>, L<PKCS5_pbe2_set_iv_ex(3)>,
267 L<PKCS5_pbe_set0_algor_ex(3)>, L<PKCS5_pbe_set_ex(3)>, L<PKCS5_pbkdf2_set_ex(3)>,
268 L<PKCS5_v2_PBE_keyivgen_ex(3)>, L<PKCS5_v2_scrypt_keyivgen_ex(3)>,
269 L<PKCS8_decrypt_ex(3)>, L<PKCS8_encrypt_ex(3)>, L<PKCS8_set0_pbe_ex(3)>.
271 As part of this change the EVP_PBE_xxx APIs can also accept a library
272 context and property query and will call an extended version of the key/IV
273 derivation function which supports these parameters. This includes
274 L<EVP_PBE_CipherInit_ex(3)>, L<EVP_PBE_find_ex(3)> and L<EVP_PBE_scrypt_ex(3)>.
276 =head4 Windows thread synchronization changes
278 Windows thread synchronization uses read/write primitives (SRWLock) when
279 supported by the OS, otherwise CriticalSection continues to be used.
283 A new generic trace API has been added which provides support for enabling
284 instrumentation through trace output. This feature is mainly intended as an aid
285 for developers and is disabled by default. To utilize it, OpenSSL needs to be
286 configured with the C<enable-trace> option.
288 If the tracing API is enabled, the application can activate trace output by
289 registering BIOs as trace channels for a number of tracing and debugging
290 categories. See L<OSSL_trace_enabled(3)>.
292 =head4 Key validation updates
294 L<EVP_PKEY_public_check(3)> and L<EVP_PKEY_param_check(3)> now work for
295 more key types. This includes RSA, DSA, ED25519, X25519, ED448 and X448.
296 Previously (in 1.1.1) they would return -2. For key types that do not have
297 parameters then L<EVP_PKEY_param_check(3)> will always return 1.
299 =head3 Other notable deprecations and changes
301 =head4 The function code part of an OpenSSL error code is no longer relevant
303 This code is now always set to zero. Related functions are deprecated.
305 =head4 STACK and HASH macros have been cleaned up
307 The type-safe wrappers are declared everywhere and implemented once.
308 See L<DEFINE_STACK_OF(3)> and L<DECLARE_LHASH_OF(3)>.
310 =head4 The RAND_DRBG subsystem has been removed
312 The new L<EVP_RAND(3)> is a partial replacement: the DRBG callback framework is
313 absent. The RAND_DRBG API did not fit well into the new provider concept as
314 implemented by EVP_RAND and EVP_RAND_CTX.
316 =head4 Removed FIPS_mode() and FIPS_mode_set()
318 These functions are legacy APIs that are not applicable to the new provider
319 model. Applications should instead use
320 L<EVP_default_properties_is_fips_enabled(3)> and
321 L<EVP_default_properties_enable_fips(3)>.
323 =head4 Key generation is slower
325 The Miller-Rabin test now uses 64 rounds, which is used for all prime generation,
326 including RSA key generation. This affects the time for larger keys sizes.
328 The default key generation method for the regular 2-prime RSA keys was changed
329 to the FIPS 186-4 B.3.6 method (Generation of Probable Primes with Conditions
330 Based on Auxiliary Probable Primes). This method is slower than the original
333 =head4 Change PBKDF2 to conform to SP800-132 instead of the older PKCS5 RFC2898
335 This checks that the salt length is at least 128 bits, the derived key length is
336 at least 112 bits, and that the iteration count is at least 1000.
337 For backwards compatibility these checks are disabled by default in the
338 default provider, but are enabled by default in the fips provider.
340 To enable or disable the checks see B<OSSL_KDF_PARAM_PKCS5> in
341 L<EVP_KDF-PBKDF2(7)>. The parameter can be set using L<EVP_KDF_derive(3)>.
343 =head4 Enforce a minimum DH modulus size of 512 bits
345 Smaller sizes now result in an error.
347 =head4 SM2 key changes
349 EC EVP_PKEYs with the SM2 curve have been reworked to automatically become
350 EVP_PKEY_SM2 rather than EVP_PKEY_EC.
352 Unlike in previous OpenSSL versions, this means that applications cannot
353 call C<EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2)> to get SM2 computations.
355 Parameter and key generation is also reworked to make it possible
356 to generate EVP_PKEY_SM2 parameters and keys. Applications must now generate
357 SM2 keys directly and must not create an EVP_PKEY_EC key first.
359 Validation of SM2 keys has been separated from the validation of regular EC
360 keys, allowing to improve the SM2 validation process to reject loaded private
361 keys that are not conforming to the SM2 ISO standard.
362 In particular, a private scalar `k` outside the range `1 <= k < n-1` is now
365 =head4 EVP_PKEY_set_alias_type() method has been removed
367 This function made a B<EVP_PKEY> object mutable after it had been set up. In
368 OpenSSL 3.0 it was decided that a provided key should not be able to change its
369 type, so this function has been removed.
371 =head4 Functions that return an internal key should be treated as read only
373 Functions such as L<EVP_PKEY_get0_RSA(3)> behave slightly differently in
374 OpenSSL 3.0. Previously they returned a pointer to the low-level key used
375 internally by libcrypto. From OpenSSL 3.0 this key may now be held in a
376 provider. Calling these functions will only return a handle on the internal key
377 where the EVP_PKEY was constructed using this key in the first place, for
378 example using a function or macro such as L<EVP_PKEY_assign_RSA(3)>,
379 L<EVP_PKEY_set1_RSA(3)>, etc.
380 Where the EVP_PKEY holds a provider managed key, then these functions now return
381 a cached copy of the key. Changes to the internal provider key that take place
382 after the first time the cached key is accessed will not be reflected back in
383 the cached copy. Similarly any changes made to the cached copy by application
384 code will not be reflected back in the internal provider key.
386 For the above reasons the keys returned from these functions should typically be
387 treated as read-only. To emphasise this the value returned from
388 L<EVP_PKEY_get0_RSA(3)>, L<EVP_PKEY_get0_DSA(3)>, L<EVP_PKEY_get0_EC_KEY(3)> and
389 L<EVP_PKEY_get0_DH(3)> have been made const. This may break some existing code.
390 Applications broken by this change should be modified. The preferred solution is
391 to refactor the code to avoid the use of these deprecated functions. Failing
392 this the code should be modified to use a const pointer instead.
393 The L<EVP_PKEY_get1_RSA(3)>, L<EVP_PKEY_get1_DSA(3)>, L<EVP_PKEY_get1_EC_KEY(3)>
394 and L<EVP_PKEY_get1_DH(3)> functions continue to return a non-const pointer to
395 enable them to be "freed". However they should also be treated as read-only.
397 =head4 The public key check has moved from EVP_PKEY_derive() to EVP_PKEY_derive_set_peer()
399 This may mean result in an error in L<EVP_PKEY_derive_set_peer(3)> rather than
400 during L<EVP_PKEY_derive(3)>.
401 To disable this check use EVP_PKEY_derive_set_peer_ex(dh, peer, 0).
403 =head4 The print format has cosmetic changes for some functions
405 The output from numerous "printing" functions such as L<X509_signature_print(3)>,
406 L<X509_print_ex(3)>, L<X509_CRL_print_ex(3)>, and other similar functions has been
407 amended such that there may be cosmetic differences between the output
408 observed in 1.1.1 and 3.0. This also applies to the B<-text> output from the
409 B<openssl x509> and B<openssl crl> applications.
411 =head4 Interactive mode from the B<openssl> program has been removed
413 From now on, running it without arguments is equivalent to B<openssl help>.
415 =head4 The error return values from some control calls (ctrl) have changed
417 One significant change is that controls which used to return -2 for
418 invalid inputs, now return -1 indicating a generic error condition instead.
420 =head4 DH and DHX key types have different settable parameters
422 Previously (in 1.1.1) these conflicting parameters were allowed, but will now
423 result in errors. See L<EVP_PKEY-DH(7)> for further details. This affects the
424 behaviour of L<openssl-genpkey(1)> for DH parameter generation.
426 =head2 Installation and Compilation
428 Please refer to the INSTALL.md file in the top of the distribution for
429 instructions on how to build and install OpenSSL 3.0. Please also refer to the
430 various platform specific NOTES files for your specific platform.
432 =head2 Upgrading from OpenSSL 1.1.1
434 Upgrading to OpenSSL 3.0 from OpenSSL 1.1.1 should be relatively straight
435 forward in most cases. The most likely area where you will encounter problems
436 is if you have used low level APIs in your code (as discussed above). In that
437 case you are likely to start seeing deprecation warnings when compiling your
438 application. If this happens you have 3 options:
444 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.
448 Suppress the warnings. Refer to your compiler documentation on how to do this.
452 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
456 =head2 Upgrading from OpenSSL 1.0.2
458 Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 is likely to be significantly more
459 difficult. In addition to the issues discussed above in the section about
460 L</Upgrading from OpenSSL 1.1.1>, the main things to be aware of are:
466 The build and installation procedure has changed significantly.
468 Check the file INSTALL.md in the top of the installation for instructions on how
469 to build and install OpenSSL for your platform. Also read the various NOTES
470 files in the same directory, as applicable for your platform.
474 Many structures have been made opaque in OpenSSL 3.0.
476 The structure definitions have been removed from the public header files and
477 moved to internal header files. In practice this means that you can no longer
478 stack allocate some structures. Instead they must be heap allocated through some
479 function call (typically those function names have a C<_new> suffix to them).
480 Additionally you must use "setter" or "getter" functions to access the fields
481 within those structures.
483 For example code that previously looked like this:
487 /* This line will now generate compiler errors */
488 EVP_MD_CTX_init(&md_ctx);
490 The code needs to be amended to look like this:
493 md_ctx = EVP_MD_CTX_new();
496 EVP_MD_CTX_free(md_ctx);
500 Support for TLSv1.3 has been added.
502 This has a number of implications for SSL/TLS applications. See the
503 L<TLS1.3 page|https://wiki.openssl.org/index.php/TLS1.3> for further details.
507 More details about the breaking changes between OpenSSL versions 1.0.2 and 1.1.0
509 L<OpenSSL 1.1.0 Changes page|https://wiki.openssl.org/index.php/OpenSSL_1.1.0_Changes>.
511 =head3 Upgrading from the OpenSSL 2.0 FIPS Object Module
513 The OpenSSL 2.0 FIPS Object Module was a separate download that had to be built
514 separately and then integrated into your main OpenSSL 1.0.2 build.
515 In OpenSSL 3.0 the FIPS support is fully integrated into the mainline version of
516 OpenSSL and is no longer a separate download. For further information see
517 L</Completing the installation of the FIPS Module>.
519 The function calls FIPS_mode() and FIPS_mode_set() have been removed
520 from OpenSSL 3.0. You should rewrite your application to not use them.
521 See L<fips_module(7)> and L<OSSL_PROVIDER-FIPS(7)> for details.
523 =head2 Completing the installation of the FIPS Module
525 The FIPS Module will be built and installed automatically if FIPS support has
526 been configured. The current documentation can be found in the
527 L<README-FIPS|https://github.com/openssl/openssl/blob/master/README-FIPS.md> file.
531 Applications written to work with OpenSSL 1.1.1 will mostly just work with
532 OpenSSL 3.0. However changes will be required if you want to take advantage of
533 some of the new features that OpenSSL 3.0 makes available. In order to do that
534 you need to understand some new concepts introduced in OpenSSL 3.0.
535 Read L<crypto(7)/Library contexts> for further information.
537 =head3 Library Context
539 A library context allows different components of a complex application to each
540 use a different library context and have different providers loaded with
541 different configuration settings.
542 See L<crypto(7)/Library contexts> for further info.
544 If the user creates an B<OSSL_LIB_CTX> via L<OSSL_LIB_CTX_new(3)> then many
545 functions may need to be changed to pass additional parameters to handle the
548 =head4 Using a Library Context - Old functions that should be changed
550 If a library context is needed then all EVP_* digest functions that return a
551 B<const EVP_MD *> such as EVP_sha256() should be replaced with a call to
552 L<EVP_MD_fetch(3)>. See L<crypto(7)/ALGORITHM FETCHING>.
554 If a library context is needed then all EVP_* cipher functions that return a
555 B<const EVP_CIPHER *> such as EVP_aes_128_cbc() should be replaced vith a call to
556 L<EVP_CIPHER_fetch(3)>. See L<crypto(7)/ALGORITHM FETCHING>.
558 Some functions can be passed an object that has already been set up with a library
559 context such as L<d2i_X509(3)>, L<d2i_X509_CRL(3)> and L<d2i_X509_REQ(3)>.
560 If NULL is passed instead then the created object will be set up with the
561 default library context. Use L<X509_new_ex(3)>, L<X509_CRL_new_ex(3)> and
562 L<X509_REQ_new_ex(3)> if a library context is required.
564 All functions listed below with a I<NAME> have a replacment function I<NAME_ex>
565 that takes B<OSSL_LIB_CTX> as an additional argument. Functions that have other
566 mappings are listed along with the respective name.
572 L<ASN1_item_sign(3)> and L<ASN1_item_verify(3)>
576 L<BN_CTX_new(3)> and L<BN_CTX_secure_new(3)>
580 L<CMS_AuthEnvelopedData_create(3)>, L<CMS_ContentInfo_new(3)>, L<CMS_data_create(3)>,
581 L<CMS_digest_create(3)>, L<CMS_EncryptedData_encrypt(3)>, L<CMS_encrypt(3)>,
582 L<CMS_EnvelopedData_create(3)>, L<CMS_ReceiptRequest_create0(3)> and L<CMS_sign(3)>
586 L<CONF_modules_load_file(3)>
590 L<CTLOG_new(3)>, L<CTLOG_new_from_base64(3)> and L<CTLOG_STORE_new(3)>
594 L<CT_POLICY_EVAL_CTX_new(3)>
598 L<d2i_AutoPrivateKey(3)>, L<d2i_PrivateKey(3)> and L<d2i_PUBKEY(3)>
602 L<d2i_PrivateKey_bio(3)> and L<d2i_PrivateKey_fp(3)>
604 Use L<d2i_PrivateKey_ex_bio(3)> and L<d2i_PrivateKey_ex_fp(3)>
610 Use L<EC_GROUP_new_by_curve_name_ex(3)> or L<EC_GROUP_new_from_params(3)>.
614 L<EVP_DigestSignInit(3)> and L<EVP_DigestVerifyInit(3)>
618 L<EVP_PBE_CipherInit(3)>, L<EVP_PBE_find(3)> and L<EVP_PBE_scrypt(3)>
626 L<EVP_PKEY_CTX_new_id(3)>
628 Use L<EVP_PKEY_CTX_new_from_name(3)>
632 L<EVP_PKEY_derive_set_peer(3)>, L<EVP_PKEY_new_raw_private_key(3)>
633 and L<EVP_PKEY_new_raw_public_key(3)>
637 L<EVP_SignFinal(3)> and L<EVP_VerifyFinal(3)>
645 L<OCSP_RESPID_match(3)> and L<OCSP_RESPID_set_by_key(3)>
649 L<OPENSSL_thread_stop(3)>
653 L<OSSL_STORE_open(3)>
657 L<PEM_read_bio_Parameters(3)>, L<PEM_read_bio_PrivateKey(3)>, L<PEM_read_bio_PUBKEY(3)>,
658 L<PEM_read_PrivateKey(3)> and L<PEM_read_PUBKEY(3)>
662 L<PEM_write_bio_PrivateKey(3)>, L<PEM_write_bio_PUBKEY(3)>, L<PEM_write_PrivateKey(3)>
663 and L<PEM_write_PUBKEY(3)>
667 L<PEM_X509_INFO_read_bio(3)> and L<PEM_X509_INFO_read(3)>
671 L<PKCS12_add_key(3)>, L<PKCS12_add_safe(3)>, L<PKCS12_add_safes(3)>,
672 L<PKCS12_create(3)>, L<PKCS12_decrypt_skey(3)>, L<PKCS12_init(3)>, L<PKCS12_item_decrypt_d2i(3)>,
673 L<PKCS12_item_i2d_encrypt(3)>, L<PKCS12_key_gen_asc(3)>, L<PKCS12_key_gen_uni(3)>,
674 L<PKCS12_key_gen_utf8(3)>, L<PKCS12_pack_p7encdata(3)>, L<PKCS12_pbe_crypt(3)>,
675 L<PKCS12_PBE_keyivgen(3)>, L<PKCS12_SAFEBAG_create_pkcs8_encrypt(3)>
679 L<PKCS5_pbe_set0_algor(3)>, L<PKCS5_pbe_set(3)>, L<PKCS5_pbe2_set_iv(3)>,
680 L<PKCS5_pbkdf2_set(3)> and L<PKCS5_v2_scrypt_keyivgen(3)>
684 L<PKCS7_encrypt(3)>, L<PKCS7_new(3)> and L<PKCS7_sign(3)>
688 L<PKCS8_decrypt(3)>, L<PKCS8_encrypt(3)> and L<PKCS8_set0_pbe(3)>
692 L<RAND_bytes(3)> and L<RAND_priv_bytes(3)>
696 L<SMIME_write_ASN1(3)>
700 L<TS_RESP_CTX_new(3)>
708 L<X509_load_cert_crl_file(3)> and L<X509_load_cert_file(3)>
712 L<X509_LOOKUP_by_subject(3)> and L<X509_LOOKUP_ctrl(3)>
724 L<X509_REQ_new(3)> and L<X509_REQ_verify(3)>
728 L<X509_STORE_CTX_new(3)>, L<X509_STORE_set_default_paths(3)>, L<X509_STORE_load_file(3)>,
729 L<X509_STORE_load_locations(3)> and L<X509_STORE_load_store(3)>
733 =head4 New functions that use a Library context
735 The following functions can be passed a library context if required.
736 Passing NULL will use the default library context.
742 L<EVP_ASYM_CIPHER_fetch(3)> and L<EVP_ASYM_CIPHER_do_all_provided(3)>
746 L<EVP_CIPHER_fetch(3)> and L<EVP_CIPHER_do_all_provided(3)>
750 L<EVP_default_properties_enable_fips(3)> and
751 L<EVP_default_properties_is_fips_enabled(3)>
755 L<EVP_KDF_fetch(3)> and L<EVP_KDF_do_all_provided(3)>
759 L<EVP_KEM_fetch(3)> and L<EVP_KEM_do_all_provided(3)>
763 L<EVP_KEYEXCH_fetch(3)> and L<EVP_KEYEXCH_do_all_provided(3)>
767 L<EVP_KEYMGMT_fetch(3)> and L<EVP_KEYMGMT_do_all_provided(3)>
771 L<EVP_MAC_fetch(3)> and L<EVP_MAC_do_all_provided(3)>
775 L<EVP_MD_fetch(3)> and L<EVP_MD_do_all_provided(3)>
779 L<EVP_PKEY_CTX_new_from_pkey(3)>
783 L<EVP_PKEY_Q_keygen(3)>
787 L<EVP_Q_mac(3)> and L<EVP_Q_digest(3)>
791 L<EVP_RAND(3)> and L<EVP_RAND_do_all_provided(3)>
795 L<EVP_set_default_properties(3)>
799 L<EVP_SIGNATURE_fetch(3)> and L<EVP_SIGNATURE_do_all_provided(3)>
803 L<OSSL_CMP_CTX_new(3)> and L<OSSL_CMP_SRV_CTX_new(3)>
807 L<OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert(3)>
811 L<OSSL_CRMF_MSG_create_popo(3)> and L<OSSL_CRMF_MSGS_verify_popo(3)>
815 L<OSSL_CRMF_pbm_new(3)> and L<OSSL_CRMF_pbmp_new(3)>
819 L<OSSL_DECODER_CTX_add_extra(3)> and L<OSSL_DECODER_CTX_new_for_pkey(3)>
823 L<OSSL_DECODER_fetch(3)> and L<OSSL_DECODER_do_all_provided(3)>
827 L<OSSL_ENCODER_CTX_add_extra(3)>
831 L<OSSL_ENCODER_fetch(3)> and L<OSSL_ENCODER_do_all_provided(3)>
835 L<OSSL_LIB_CTX_free(3)>, L<OSSL_LIB_CTX_load_config(3)> and L<OSSL_LIB_CTX_set0_default(3)>
839 L<OSSL_PROVIDER_add_builtin(3)>, L<OSSL_PROVIDER_available(3)>,
840 L<OSSL_PROVIDER_do_all(3)>, L<OSSL_PROVIDER_load(3)>,
841 L<OSSL_PROVIDER_set_default_search_path(3)> and L<OSSL_PROVIDER_try_load(3)>
845 L<OSSL_SELF_TEST_get_callback(3)> and L<OSSL_SELF_TEST_set_callback(3)>
849 L<OSSL_STORE_attach(3)>
853 L<OSSL_STORE_LOADER_fetch(3)> and L<OSSL_STORE_LOADER_do_all_provided(3)>
857 L<RAND_get0_primary(3)>, L<RAND_get0_private(3)>, L<RAND_get0_public(3)>,
858 L<RAND_set_DRBG_type(3)> and L<RAND_set_seed_source_type(3)>
864 Providers are described in detail here L<crypto(7)/Providers>.
865 See also L<crypto(7)/OPENSSL PROVIDERS>.
867 =head3 Fetching algorithms and property queries
869 Implicit and Explicit Fetching is described in detail here
870 L<crypto(7)/ALGORITHM FETCHING>.
872 =head3 Deprecation of Low Level Functions
874 A significant number of APIs have been deprecated in OpenSSL 3.0.
875 This section describes some common categories of deprecations.
876 See L</Deprecated function mappings> for the list of deprecated functions
877 that refer to these categories.
879 =head4 Providers are a replacement for engines and low-level method overrides
881 Any accessor that uses an ENGINE is deprecated (such as EVP_PKEY_set1_engine()).
882 Applications using engines should instead use providers.
884 Before providers were added algorithms were overriden by changing the methods
885 used by algorithms. All these methods such as RSA_new_method() and RSA_meth_new()
886 are now deprecated and can be replaced by using providers instead.
888 =head4 Deprecated i2d and d2i functions for low-level key types
890 Any i2d and d2i functions such as d2i_DHparams() that take a low-level key type
891 have been deprecated. Applications should instead use the L<OSSL_DECODER(3)> and
892 L<OSSL_ENCODER(3)> APIs to read and write files.
893 See L<d2i_RSAPrivateKey(3)/Migration> for further details.
895 =head4 Deprecated low-level key object getters and setters
897 Applications that set or get low-level key objects (such as EVP_PKEY_set1_DH()
898 or EVP_PKEY_get0()) should instead use the OSSL_ENCODER
899 (See L<OSSL_ENCODER_to_bio(3)>) or OSSL_DECODER (See L<OSSL_DECODER_from_bio(3)>)
900 APIs, or alternatively use L<EVP_PKEY_fromdata(3)> or L<EVP_PKEY_todata(3)>.
902 =head4 Deprecated low-level key parameter getters
904 Functions that access low-level objects directly such as L<RSA_get0_n(3)> are now
905 deprecated. Applications should use one of L<EVP_PKEY_get_bn_param(3)>,
906 L<EVP_PKEY_get_int_param(3)>, l<EVP_PKEY_get_size_t_param(3)>,
907 L<EVP_PKEY_get_utf8_string_param(3)>, L<EVP_PKEY_get_octet_string_param(3)> or
908 L<EVP_PKEY_get_params(3)> to access fields from an EVP_PKEY.
909 Gettable parameters are listed in L<EVP_PKEY-RSA(7)/Common RSA parameters>,
910 L<EVP_PKEY-DH(7)/DH parameters>, L<EVP_PKEY-DSA(7)/DSA parameters>,
911 L<EVP_PKEY-FFC(7)/FFC parameters>, L<EVP_PKEY-EC(7)/Common EC parameters> and
912 L<EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>.
913 Applications may also use L<EVP_PKEY_todata(3)> to return all fields.
915 =head4 Deprecated low-level key parameter setters
917 Functions that access low-level objects directly such as L<RSA_set0_crt_params(3)>
918 are now deprecated. Applications should use L<EVP_PKEY_fromdata(3)> to create
919 new keys from user provided key data. Keys should be immutable once they are
920 created, so if required the user may use L<EVP_PKEY_todata(3)>, L<OSSL_PARAM_merge(3)>,
921 and L<EVP_PKEY_fromdata(3)> to create a modified key.
922 See L<EVP_PKEY-DH(7)/Examples> for more information.
923 See L</Deprecated low-level key generation functions> for information on
924 generating a key using parameters.
926 =head4 Deprecated low-level object creation
928 Low-level objects were created using methods such as L<RSA_new(3)>,
929 L<RSA_up_ref(3)> and L<RSA_free(3)>. Applications should instead use the
930 high-level EVP_PKEY APIs, e.g. L<EVP_PKEY_new(3)>, L<EVP_PKEY_up_ref(3)> and
932 See also L<EVP_PKEY_CTX_new_from_name(3)> and L<EVP_PKEY_CTX_new_from_pkey(3)>.
934 EVP_PKEYs may be created in a variety of ways:
935 See also L</Deprecated low-level key generation functions>,
936 L</Deprecated low-level key reading and writing functions> and
937 L</Deprecated low-level key parameter setters>.
939 =head4 Deprecated low-level encryption functions
941 Low-level encryption functions such as L<AES_encrypt(3)> and L<AES_decrypt(3)>
942 have been informally discouraged from use for a long time. Applications should
943 instead use the high level EVP APIs L<EVP_EncryptInit_ex(3)>,
944 L<EVP_EncryptUpdate(3)>, and L<EVP_EncryptFinal_ex(3)> or
945 L<EVP_DecryptInit_ex(3)>, L<EVP_DecryptUpdate(3)> and L<EVP_DecryptFinal_ex(3)>.
947 =head4 Deprecated low-level digest functions
949 Use of low-level digest functions such as L<SHA1_Init(3)> have been
950 informally discouraged from use for a long time. Applications should instead
951 use the the high level EVP APIs L<EVP_DigestInit_ex(3)>, L<EVP_DigestUpdate(3)>
952 and L<EVP_DigestFinal_ex(3)>, or the quick one-shot L<EVP_Q_digest(3)>.
954 Note that the functions L<SHA1(3)>, L<SHA224(3)>, L<SHA256(3)>, L<SHA384(3)>
955 and L<SHA512(3)> have changed to macros that use L<EVP_Q_digest(3)>.
957 =head4 Deprecated low-level signing functions
959 Use of low-level signing functions such as L<DSA_sign(3)> have been
960 informally discouraged for a long time. Instead applications should use
961 L<EVP_DigestSign(3)> and L<EVP_DigestVerify(3)>.
962 See also L<EVP_SIGNATURE-RSA(7)>, L<EVP_SIGNATURE-DSA(7)>,
963 L<EVP_SIGNATURE-ECDSA(7)> and L<EVP_SIGNATURE-ED25519(7)>.
965 =head4 Deprecated low-level MAC functions
967 Low-level mac functions such as L<CMAC_Init(3)> are deprecated.
968 Applications should instead use the new L<EVP_MAC(3)> interface, using
969 L<EVP_MAC_CTX_new(3)>, L<EVP_MAC_CTX_free(3)>, L<EVP_MAC_init(3)>,
970 L<EVP_MAC_update(3)> and L<EVP_MAC_final(3)> or the single-shot MAC function
972 See L<EVP_MAC(3)>, L<EVP_MAC-HMAC(7)>, L<EVP_MAC-CMAC(7)>, L<EVP_MAC-GMAC(7)>,
973 L<EVP_MAC-KMAC(7)>, L<EVP_MAC-BLAKE2(7)>, L<EVP_MAC-Poly1305(7)> and
974 L<EVP_MAC-Siphash(7)> for additional information.
976 Note that the one-shot method HMAC() is still available for compatability purposes.
978 =head4 Deprecated low-level validation functions
980 Low-level validation functions such as L<DH_check(3)> have been informally
981 discouraged from use for a long time. Applications should instead use the high-level
982 EVP_PKEY APIs such as L<EVP_PKEY_check(3)>, L<EVP_PKEY_param_check(3)>,
983 L<EVP_PKEY_param_check_quick(3)>, L<EVP_PKEY_public_check(3)>,
984 L<EVP_PKEY_public_check_quick(3)>, L<EVP_PKEY_private_check(3)>,
985 and L<EVP_PKEY_pairwise_check(3)>.
987 =head4 Deprecated low-level key exchange functions
989 Many low-level functions have been informally discouraged from use for a long
990 time. Applications should instead use L<EVP_PKEY_derive(3)>.
991 See L<EVP_KEYEXCH-DH(7)>, L<EVP_KEYEXCH-ECDH(7)> and L<EVP_KEYEXCH-X25519(7)>.
993 =head4 Deprecated low-level key generation functions
995 Many low-level functions have been informally discouraged from use for a long
996 time. Applications should instead use L<EVP_PKEY_keygen_init(3)> and
997 L<EVP_PKEY_generate(3)> as described in L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>,
998 L<EVP_PKEY-RSA(7)>, L<EVP_PKEY-EC(7)> and L<EVP_PKEY-X25519(7)>.
999 The 'quick' one-shot function L<EVP_PKEY_Q_keygen(3)> and macros for the most
1000 common cases: <EVP_RSA_gen(3)> and L<EVP_EC_gen(3)> may also be used.
1002 =head4 Deprecated low-level key reading and writing functions
1004 Use of low-level objects (such as DSA) has been informally discouraged from use
1005 for a long time. Functions to read and write these low-level objects (such as
1006 PEM_read_DSA_PUBKEY()) should be replaced. Applications should instead use
1007 L<OSSL_ENCODER_to_bio(3)> and L<OSSL_DECODER_from_bio(3)>.
1009 =head4 Deprecated low-level key printing functions
1011 Use of low-level objects (such as DSA) has been informally discouraged from use
1012 for a long time. Functions to print these low-level objects such as
1013 DSA_print() should be replaced with the equivalent EVP_PKEY functions.
1014 Application should use one of L<EVP_PKEY_print_public(3)>,
1015 L<EVP_PKEY_print_private(3)>, L<EVP_PKEY_print_params(3)>,
1016 L<EVP_PKEY_print_public_fp(3)>, L<EVP_PKEY_print_private_fp(3)> or
1017 L<EVP_PKEY_print_params_fp(3)>. Note that internally these use
1018 L<OSSL_ENCODER_to_bio(3)> and L<OSSL_DECODER_from_bio(3)>.
1020 =head3 Deprecated function mappings
1022 The following functions have been deprecated in 3.0.
1028 AES_bi_ige_encrypt() and AES_ige_encrypt()
1030 There is no replacement for the IGE functions. New code should not use these modes.
1031 These undocumented functions were never integrated into the EVP layer.
1032 They implemented the AES Infinite Garble Extension (IGE) mode and AES
1033 Bi-directional IGE mode. These modes were never formally standardised and
1034 usage of these functions is believed to be very small. In particular
1035 AES_bi_ige_encrypt() has a known bug. It accepts 2 AES keys, but only one
1036 is ever used. The security implications are believed to be minimal, but
1037 this issue was never fixed for backwards compatibility reasons.
1041 AES_encrypt(), AES_decrypt(), AES_set_encrypt_key(), AES_set_decrypt_key(),
1042 AES_cbc_encrypt(), AES_cfb128_encrypt(), AES_cfb1_encrypt(), AES_cfb8_encrypt(),
1043 AES_ecb_encrypt(), AES_ofb128_encrypt()
1047 AES_unwrap_key(), AES_wrap_key()
1049 See L</Deprecated low-level encryption functions>
1055 There is no replacement. It returned a string indicating if the AES code was unrolled.
1059 ASN1_digest(), ASN1_sign(), ASN1_verify()
1061 There are no replacements. These old functions are not used, and could be
1062 disabled with the macro NO_ASN1_OLD since OpenSSL 0.9.7.
1066 ASN1_STRING_length_set()
1068 Use L<ASN1_STRING_set(3)> or L<ASN1_STRING_set0(3)> instead.
1069 This was a potentially unsafe function that could change the bounds of a
1070 previously passed in pointer.
1074 BF_encrypt(), BF_decrypt(), BF_set_key(), BF_cbc_encrypt(), BF_cfb64_encrypt(),
1075 BF_ecb_encrypt(), BF_ofb64_encrypt()
1077 See L</Deprecated low-level encryption functions>.
1078 The Blowfish algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1084 There is no replacement. This option returned a constant string.
1088 BN_is_prime_ex(), BN_is_prime_fasttest_ex()
1090 Use L<BN_check_prime(3)> which that avoids possible misuse and always uses at least
1091 64 rounds of the Miller-Rabin primality test.
1095 BN_pseudo_rand(), BN_pseudo_rand_range()
1097 Use L<BN_rand(3)> and L<BN_rand_range(3)>.
1101 BN_X931_derive_prime_ex(), BN_X931_generate_prime_ex(), BN_X931_generate_Xpq()
1103 There are no replacements for these low-level functions. They were used internally
1104 by RSA_X931_derive_ex() and RSA_X931_generate_key_ex() which are also deprecated.
1105 Use L<EVP_PKEY_keygen(3)> instead.
1109 Camellia_encrypt(), Camellia_decrypt(), Camellia_set_key(),
1110 Camellia_cbc_encrypt(), Camellia_cfb128_encrypt(), Camellia_cfb1_encrypt(),
1111 Camellia_cfb8_encrypt(), Camellia_ctr128_encrypt(), Camellia_ecb_encrypt(),
1112 Camellia_ofb128_encrypt()
1114 See L</Deprecated low-level encryption functions>.
1118 CAST_encrypt(), CAST_decrypt(), CAST_set_key(), CAST_cbc_encrypt(),
1119 CAST_cfb64_encrypt(), CAST_ecb_encrypt(), CAST_ofb64_encrypt()
1121 See L</Deprecated low-level encryption functions>.
1122 The CAST algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1126 CMAC_CTX_new(), CMAC_CTX_cleanup(), CMAC_CTX_copy(), CMAC_CTX_free(),
1127 CMAC_CTX_get0_cipher_ctx()
1129 See L</Deprecated low-level MAC functions>.
1133 CMAC_Init(), CMAC_Update(), CMAC_Final(), CMAC_resume()
1135 See L</Deprecated low-level MAC functions>.
1139 CRYPTO_mem_ctrl(), CRYPTO_mem_debug_free(), CRYPTO_mem_debug_malloc(),
1140 CRYPTO_mem_debug_pop(), CRYPTO_mem_debug_push(), CRYPTO_mem_debug_realloc(),
1141 CRYPTO_mem_leaks(), CRYPTO_mem_leaks_cb(), CRYPTO_mem_leaks_fp(),
1142 CRYPTO_set_mem_debug()
1144 Memory-leak checking has been deprecated in favor of more modern development
1145 tools, such as compiler memory and leak sanitizers or Valgrind.
1149 d2i_DHparams(), d2i_DHxparams(), d2i_DSAparams(), d2i_DSAPrivateKey(),
1150 d2i_DSAPrivateKey_bio(), d2i_DSAPrivateKey_fp(), d2i_DSA_PUBKEY(),
1151 d2i_DSA_PUBKEY_bio(), d2i_DSA_PUBKEY_fp(), d2i_DSAPublicKey(),
1152 d2i_ECParameters(), d2i_ECPrivateKey(), d2i_ECPrivateKey_bio(),
1153 d2i_ECPrivateKey_fp(), d2i_EC_PUBKEY(), d2i_EC_PUBKEY_bio(),
1154 d2i_EC_PUBKEY_fp(), o2i_ECPublicKey(), d2i_RSAPrivateKey(),
1155 d2i_RSAPrivateKey_bio(), d2i_RSAPrivateKey_fp(), d2i_RSA_PUBKEY(),
1156 d2i_RSA_PUBKEY_bio(), d2i_RSA_PUBKEY_fp(), d2i_RSAPublicKey(),
1157 d2i_RSAPublicKey_bio(), d2i_RSAPublicKey_fp()
1159 See L</Deprecated i2d and d2i functions for low-level key types>
1163 DES_crypt(), DES_fcrypt(), DES_encrypt1(), DES_encrypt2(), DES_encrypt3(),
1164 DES_decrypt3(), DES_ede3_cbc_encrypt(), DES_ede3_cfb64_encrypt(),
1165 DES_ede3_cfb_encrypt(),DES_ede3_ofb64_encrypt(),
1166 DES_ecb_encrypt(), DES_ecb3_encrypt(), DES_ofb64_encrypt(), DES_ofb_encrypt(),
1167 DES_cfb64_encrypt DES_cfb_encrypt(), DES_cbc_encrypt(), DES_ncbc_encrypt(),
1168 DES_pcbc_encrypt(), DES_xcbc_encrypt(), DES_cbc_cksum(), DES_quad_cksum(),
1169 DES_check_key_parity(), DES_is_weak_key(), DES_key_sched(), DES_options(),
1170 DES_random_key(), DES_set_key(), DES_set_key_checked(), DES_set_key_unchecked(),
1171 DES_set_odd_parity(), DES_string_to_2keys(), DES_string_to_key()
1173 See L</Deprecated low-level encryption functions>.
1174 Algorithms for "DESX-CBC", "DES-ECB", "DES-CBC", "DES-OFB", "DES-CFB",
1175 "DES-CFB1" and "DES-CFB8" have been moved to the L<Legacy Provider|/Legacy Algorithms>.
1179 DH_bits(), DH_security_bits(), DH_size()
1181 Use L<EVP_PKEY_bits(3)>, L<EVP_PKEY_security_bits(3)> and L<EVP_PKEY_size(3)>.
1185 DH_check(), DH_check_ex(), DH_check_params(), DH_check_params_ex(),
1186 DH_check_pub_key(), DH_check_pub_key_ex()
1188 See L</Deprecated low-level validation functions>
1192 DH_clear_flags(), DH_test_flags(), DH_set_flags()
1194 The B<DH_FLAG_CACHE_MONT_P> flag has been deprecated without replacement.
1195 The B<DH_FLAG_TYPE_DH> and B<DH_FLAG_TYPE_DHX> have been deprecated.
1196 Use EVP_PKEY_is_a() to determine the type of a key.
1197 There is no replacement for setting these flags.
1201 DH_compute_key() DH_compute_key_padded()
1203 See L</Deprecated low-level key exchange functions>.
1207 DH_new(), DH_new_by_nid(), DH_free(), DH_up_ref()
1209 See L</Deprecated low-level object creation>
1213 DH_generate_key(), DH_generate_parameters_ex()
1215 See L</Deprecated low-level key generation functions>.
1219 DH_get0_pqg(), DH_get0_p(), DH_get0_q(), DH_get0_g(), DH_get0_key(),
1220 DH_get0_priv_key(), DH_get0_pub_key(), DH_get_length(), DH_get_nid()
1222 See L</Deprecated low-level key parameter getters>
1226 DH_get_1024_160(), DH_get_2048_224(), DH_get_2048_256()
1228 Applications should instead set the B<OSSL_PKEY_PARAM_GROUP_NAME> as specified in
1229 L<EVP_PKEY-DH(7)/DH parameters>) to one of "dh_1024_160", "dh_2048_224" or
1230 "dh_2048_256" when generating a DH key.
1236 Applications should use L<EVP_PKEY_CTX_set_dh_kdf_type(3)> instead.
1240 DH_get_default_method(), DH_get0_engine(), DH_meth_*(), DH_new_method(),
1241 DH_OpenSSL(), DH_get_ex_data(), DH_set_default_method(), DH_set_method(),
1244 See L</Providers are a replacement for engines and low-level method overrides>
1248 DHparams_print(), DHparams_print_fp()
1250 See L</Deprecated low-level key printing functions>
1254 DH_set0_key(), DH_set0_pqg(), DH_set_length()
1256 See L</Deprecated low-level key parameter setters>
1260 DSA_bits(), DSA_security_bits(), DSA_size()
1262 Use L<EVP_PKEY_bits(3)>, L<EVP_PKEY_security_bits(3)> and L<EVP_PKEY_size(3)>.
1266 DHparams_dup(), DSA_dup_DH()
1268 There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)>
1269 and L<EVP_PKEY_dup(3)> instead.
1273 DSA_generate_key(), DSA_generate_parameters_ex()
1275 See L</Deprecated low-level key generation functions>.
1279 DSA_get0_engine(), DSA_get_default_method(), DSA_get_ex_data(),
1280 DSA_get_method(), DSA_meth_*(), DSA_new_method(), DSA_OpenSSL(),
1281 DSA_set_default_method(), DSA_set_ex_data(), DSA_set_method()
1283 See L</Providers are a replacement for engines and low-level method overrides>.
1287 DSA_get0_p(), DSA_get0_q(), DSA_get0_g(), DSA_get0_pqg(), DSA_get0_key(),
1288 DSA_get0_priv_key(), DSA_get0_pub_key()
1290 See L</Deprecated low-level key parameter getters>.
1294 DSA_new(), DSA_free(), DSA_up_ref()
1296 See L</Deprecated low-level object creation>
1302 There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)>
1303 and L<EVP_PKEY_dup(3)> instead.
1307 DSAparams_print(), DSAparams_print_fp(), DSA_print(), DSA_print_fp()
1309 See L</Deprecated low-level key printing functions>
1313 DSA_set0_key(), DSA_set0_pqg()
1315 See L</Deprecated low-level key parameter setters>
1319 DSA_set_flags(), DSA_clear_flags(), DSA_test_flags()
1321 The B<DSA_FLAG_CACHE_MONT_P> flag has been deprecated without replacement.
1325 DSA_sign(), DSA_do_sign(), DSA_sign_setup(), DSA_verify(), DSA_do_verify()
1327 See L</Deprecated low-level signing functions>.
1333 See L</Deprecated low-level key exchange functions>.
1339 Applications may either set this using the helper function
1340 L<EVP_PKEY_CTX_set_ecdh_kdf_type(3)> or by setting an B<OSSL_PARAM> using the
1341 "kdf-type" as shown in L<EVP_KEYEXCH-ECDH(7)/EXAMPLES>
1345 ECDSA_sign(), ECDSA_sign_ex(), ECDSA_sign_setup(), ECDSA_do_sign(),
1346 ECDSA_do_sign_ex(), ECDSA_verify(), ECDSA_do_verify()
1348 See L</Deprecated low-level signing functions>.
1354 Applications should use L<EVP_PKEY_size(3)>.
1358 EC_GF2m_simple_method(), EC_GFp_mont_method(), EC_GFp_nist_method(),
1359 EC_GFp_nistp224_method(), EC_GFp_nistp256_method(), EC_GFp_nistp521_method(),
1360 EC_GFp_simple_method()
1362 There are no replacements for these functions. Applications should rely on the
1363 library automatically assigning a suitable method internally when an EC_GROUP
1368 EC_GROUP_clear_free()
1370 Use L<EC_GROUP_free(3)> instead.
1374 EC_GROUP_get_curve_GF2m(), EC_GROUP_get_curve_GFp(), EC_GROUP_set_curve_GF2m(),
1375 EC_GROUP_set_curve_GFp()
1377 Applications should use L<EC_GROUP_get_curve(3)> and L<EC_GROUP_set_curve(3)>.
1381 EC_GROUP_have_precompute_mult(), EC_GROUP_precompute_mult(),
1382 EC_KEY_precompute_mult()
1384 These functions are not widely used. Applications should instead switch to
1385 named curves which OpenSSL has hardcoded lookup tables for.
1389 EC_GROUP_new(), EC_GROUP_method_of(), EC_POINT_method_of()
1391 EC_METHOD is now an internal-only concept and a suitable EC_METHOD is assigned
1392 internally without application intervention.
1393 Users of EC_GROUP_new() should switch to a different suitable constructor.
1399 Applications should use L<EVP_PKEY_can_sign(3)> instead.
1405 See L</Deprecated low-level validation functions>
1409 EC_KEY_set_flags(), EC_KEY_get_flags(), EC_KEY_clear_flags()
1411 See L<EVP_PKEY-EC(7)/Common EC parameters> which handles flags as seperate
1412 parameters for B<OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT>,
1413 B<OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE>, B<OSSL_PKEY_PARAM_EC_ENCODING>,
1414 B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH> and
1415 B<OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC>.
1416 See also L<EVP_PKEY-EC(7)/EXAMPLES>
1420 EC_KEY_dup(), EC_KEY_copy()
1422 There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)>
1423 and L<EVP_PKEY_dup(3)> instead.
1427 EC_KEY_decoded_from_explicit_params()
1429 There is no replacement.
1433 EC_KEY_generate_key()
1435 See L</Deprecated low-level key generation functions>.
1439 EC_KEY_get0_group(), EC_KEY_get0_private_key(), EC_KEY_get0_public_key(),
1440 EC_KEY_get_conv_form(), EC_KEY_get_enc_flags()
1442 See L</Deprecated low-level key parameter getters>.
1446 EC_KEY_get0_engine(), EC_KEY_get_default_method(), EC_KEY_get_method(),
1447 EC_KEY_new_method(), EC_KEY_get_ex_data(), EC_KEY_OpenSSL(),
1448 EC_KEY_set_ex_data(), EC_KEY_set_default_method(), EC_KEY_METHOD_*(),
1451 See L</Providers are a replacement for engines and low-level method overrides>
1455 EC_METHOD_get_field_type()
1457 Use L<EC_GROUP_get_field_type(3)> instead.
1458 See L</Providers are a replacement for engines and low-level method overrides>
1462 EC_KEY_key2buf(), EC_KEY_oct2key(), EC_KEY_oct2priv(), EC_KEY_priv2buf(),
1465 There are no replacements for these.
1469 EC_KEY_new(), EC_KEY_new_by_curve_name(), EC_KEY_free(), EC_KEY_up_ref()
1471 See L</Deprecated low-level object creation>
1475 EC_KEY_print(), EC_KEY_print_fp()
1477 See L</Deprecated low-level key printing functions>
1481 EC_KEY_set_asn1_flag(), EC_KEY_set_conv_form(), EC_KEY_set_enc_flags()
1483 See L</Deprecated low-level key parameter setters>.
1487 EC_KEY_set_group(), EC_KEY_set_private_key(), EC_KEY_set_public_key(),
1488 EC_KEY_set_public_key_affine_coordinates()
1490 See L</Deprecated low-level key parameter setters>.
1494 ECParameters_print(), ECParameters_print_fp(), ECPKParameters_print(),
1495 ECPKParameters_print_fp()
1497 See L</Deprecated low-level key printing functions>
1501 EC_POINT_bn2point(), EC_POINT_point2bn()
1503 These functions were not particularly useful, since EC point serialization
1504 formats are not individual big-endian integers.
1508 EC_POINT_get_affine_coordinates_GF2m(), EC_POINT_get_affine_coordinates_GFp(),
1509 EC_POINT_set_affine_coordinates_GF2m(), EC_POINT_set_affine_coordinates_GFp()
1511 Applications should use L<EC_POINT_get_affine_coordinates(3)> and
1512 L<EC_POINT_set_affine_coordinates(3)> instead.
1516 EC_POINT_get_Jprojective_coordinates_GFp(), EC_POINT_set_Jprojective_coordinates_GFp()
1518 These functions are not widely used. Applications should instead use the
1519 L<EC_POINT_set_affine_coordinates(3)> and L<EC_POINT_get_affine_coordinates(3)>
1524 EC_POINT_make_affine(), EC_POINTs_make_affine()
1526 There is no replacement. These functions were not widely used, and OpenSSL
1527 automatically performs this conversion when needed.
1531 EC_POINT_set_compressed_coordinates_GF2m(), EC_POINT_set_compressed_coordinates_GFp()
1533 Applications should use L<EC_POINT_set_compressed_coordinates(3)> instead.
1539 This function is not widely used. Applications should instead use the
1540 L<EC_POINT_mul(3)> function.
1546 All engine functions are deprecated. An engine should be rewritten as a provider.
1547 See L</Providers are a replacement for engines and low-level method overrides>.
1551 B<ERR_load_*()>, ERR_func_error_string(), ERR_get_error_line(),
1552 ERR_get_error_line_data(), ERR_get_state()
1554 OpenSSL now loads error strings automatically so these functions are not needed.
1558 ERR_peek_error_line_data(), ERR_peek_last_error_line_data()
1560 The new functions are L<ERR_peek_error_func(3)>, L<ERR_peek_last_error_func(3)>,
1561 L<ERR_peek_error_data(3)>, L<ERR_peek_last_error_data(3)>, L<ERR_get_error_all(3)>,
1562 L<ERR_peek_error_all(3)> and L<ERR_peek_last_error_all(3)>.
1563 Applications should use L<ERR_get_error_all(3)>, or pick information
1564 with ERR_peek functions and finish off with getting the error code by using
1565 L<ERR_get_error(3)>.
1569 EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_iv_noconst(), EVP_CIPHER_CTX_original_iv()
1571 Applications should instead use L<EVP_CIPHER_CTX_get_updated_iv(3)>,
1572 L<EVP_CIPHER_CTX_get_updated_iv(3)> and L<EVP_CIPHER_CTX_get_original_iv(3)>
1574 See L<EVP_CIPHER_CTX_get_original_iv(3)> for further information.
1578 B<EVP_CIPHER_meth_*()>, EVP_MD_CTX_set_update_fn(), EVP_MD_CTX_update_fn(),
1581 See L</Providers are a replacement for engines and low-level method overrides>.
1585 EVP_PKEY_CTRL_PKCS7_ENCRYPT(), EVP_PKEY_CTRL_PKCS7_DECRYPT(),
1586 EVP_PKEY_CTRL_PKCS7_SIGN(), EVP_PKEY_CTRL_CMS_ENCRYPT(),
1587 EVP_PKEY_CTRL_CMS_DECRYPT(), and EVP_PKEY_CTRL_CMS_SIGN()
1589 These control operations are not invoked by the OpenSSL library anymore and
1590 are replaced by direct checks of the key operation against the key type
1591 when the operation is initialized.
1595 EVP_PKEY_CTX_get0_dh_kdf_ukm(), EVP_PKEY_CTX_get0_ecdh_kdf_ukm()
1597 See the "kdf-ukm" item in L<EVP_KEYEXCH-DH(7)/DH key exchange parameters> and
1598 L<EVP_KEYEXCH-ECDH(7)/ECDH Key Exchange parameters>.
1599 These functions are obsolete and should not be required.
1603 EVP_PKEY_CTX_set_rsa_keygen_pubexp()
1605 Applications should use L<EVP_PKEY_CTX_set1_rsa_keygen_pubexp(3)> instead.
1609 EVP_PKEY_cmp(), EVP_PKEY_cmp_parameters()
1611 Applications should use L<EVP_PKEY_eq(3)> and L<EVP_PKEY_parameters_eq(3)> instead.
1612 See L<EVP_PKEY_copy_parameters(3)> for further details.
1616 EVP_PKEY_encrypt_old(), EVP_PKEY_decrypt_old(),
1618 Applications should use L<EVP_PKEY_encrypt_init(3)> and L<EVP_PKEY_encrypt(3)> or
1619 L<EVP_PKEY_decrypt_init(3)> and L<EVP_PKEY_decrypt(3)> instead.
1625 This function returns NULL if the key comes from a provider.
1629 EVP_PKEY_get0_DH(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_EC_KEY(), EVP_PKEY_get0_RSA(),
1630 EVP_PKEY_get1_DH(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_EC_KEY and EVP_PKEY_get1_RSA(),
1631 EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash()
1633 See L</Functions that return an internal key should be treated as read only>.
1637 B<EVP_PKEY_meth_*()>
1639 See L</Providers are a replacement for engines and low-level method overrides>.
1643 EVP_PKEY_new_CMAC_key()
1645 See L</Deprecated low-level MAC functions>.
1649 EVP_PKEY_assign(), EVP_PKEY_set1_DH(), EVP_PKEY_set1_DSA(),
1650 EVP_PKEY_set1_EC_KEY(), EVP_PKEY_set1_RSA()
1652 See L</Deprecated low-level key object getters and setters>
1656 EVP_PKEY_set1_tls_encodedpoint() EVP_PKEY_get1_tls_encodedpoint()
1658 These functions were previously used by libssl to set or get an encoded public
1659 key into/from an EVP_PKEY object. With OpenSSL 3.0 these are replaced by the more
1660 generic functions L<EVP_PKEY_set1_encoded_public_key(3)> and
1661 L<EVP_PKEY_get1_encoded_public_key(3)>.
1662 The old versions have been converted to deprecated macros that just call the
1667 EVP_PKEY_set1_engine(), EVP_PKEY_get0_engine()
1669 See L</Providers are a replacement for engines and low-level method overrides>.
1673 EVP_PKEY_set_alias_type()
1675 This function has been removed. There is no replacement.
1676 See L</EVP_PKEY_set_alias_type() method has been removed>
1680 HMAC_Init_ex(), HMAC_Update(), HMAC_Final(), HMAC_size()
1682 See L</Deprecated low-level MAC functions>.
1686 HMAC_CTX_new(), HMAC_CTX_free(), HMAC_CTX_copy(), HMAC_CTX_reset(),
1687 HMAC_CTX_set_flags(), HMAC_CTX_get_md()
1689 See L</Deprecated low-level MAC functions>.
1693 i2d_DHparams(), i2d_DHxparams()
1695 See L</Deprecated low-level key reading and writing functions>
1696 and L<d2i_RSAPrivateKey(3)/Migration>
1700 i2d_DSAparams(), i2d_DSAPrivateKey(), i2d_DSAPrivateKey_bio(),
1701 i2d_DSAPrivateKey_fp(), i2d_DSA_PUBKEY(), i2d_DSA_PUBKEY_bio(),
1702 i2d_DSA_PUBKEY_fp(), i2d_DSAPublicKey()
1704 See L</Deprecated low-level key reading and writing functions>
1705 and L<d2i_RSAPrivateKey(3)/Migration>
1709 i2d_ECParameters(), i2d_ECPrivateKey(), i2d_ECPrivateKey_bio(),
1710 i2d_ECPrivateKey_fp(), i2d_EC_PUBKEY(), i2d_EC_PUBKEY_bio(),
1711 i2d_EC_PUBKEY_fp(), i2o_ECPublicKey()
1713 See L</Deprecated low-level key reading and writing functions>
1714 and L<d2i_RSAPrivateKey(3)/Migration>
1718 i2d_RSAPrivateKey(), i2d_RSAPrivateKey_bio(), i2d_RSAPrivateKey_fp(),
1719 i2d_RSA_PUBKEY(), i2d_RSA_PUBKEY_bio(), i2d_RSA_PUBKEY_fp(),
1720 i2d_RSAPublicKey(), i2d_RSAPublicKey_bio(), i2d_RSAPublicKey_fp()
1722 See L</Deprecated low-level key reading and writing functions>
1723 and L<d2i_RSAPrivateKey(3)/Migration>
1727 IDEA_encrypt(), IDEA_set_decrypt_key(), IDEA_set_encrypt_key(),
1728 IDEA_cbc_encrypt(), IDEA_cfb64_encrypt(), IDEA_ecb_encrypt(),
1729 IDEA_ofb64_encrypt()
1731 See L</Deprecated low-level encryption functions>.
1732 IDEA has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1738 There is no replacement. This function returned a constant string.
1742 MD2(), MD2_Init(), MD2_Update(), MD2_Final()
1744 See L</Deprecated low-level encryption functions>.
1745 MD2 has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1751 There is no replacement. This function returned a constant string.
1755 MD4(), MD4_Init(), MD4_Update(), MD4_Final(), MD4_Transform()
1757 See L</Deprecated low-level encryption functions>.
1758 MD4 has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1762 MDC2(), MDC2_Init(), MDC2_Update(), MDC2_Final()
1764 See L</Deprecated low-level encryption functions>.
1765 MDC2 has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1769 MD5(), MD5_Init(), MD5_Update(), MD5_Final(), MD5_Transform()
1771 See L</Deprecated low-level encryption functions>.
1777 This undocumented function has no replacement.
1778 See L<config(5)/HISTORY> for more details.
1784 Use L<OSSL_HTTP_parse_url(3)> instead.
1788 B<OCSP_REQ_CTX> type and B<OCSP_REQ_CTX_*()> functions
1790 These methods were used to collect all necessary data to form a HTTP request,
1791 and to perform the HTTP transfer with that request. With OpenSSL 3.0, the
1792 type is B<OSSL_HTTP_REQ_CTX>, and the deprecated functions are replaced
1793 with B<OSSL_HTTP_REQ_CTX_*()>. See L<OSSL_HTTP_REQ_CTX(3)> for additional
1798 OPENSSL_fork_child(), OPENSSL_fork_parent(), OPENSSL_fork_prepare()
1800 There is no replacement for these functions. These pthread fork support methods
1801 were unused by OpenSSL.
1805 OSSL_STORE_ctrl(), OSSL_STORE_do_all_loaders(), OSSL_STORE_LOADER_get0_engine(),
1806 OSSL_STORE_LOADER_get0_scheme(), OSSL_STORE_LOADER_new(),
1807 OSSL_STORE_LOADER_set_attach(), OSSL_STORE_LOADER_set_close(),
1808 OSSL_STORE_LOADER_set_ctrl(), OSSL_STORE_LOADER_set_eof(),
1809 OSSL_STORE_LOADER_set_error(), OSSL_STORE_LOADER_set_expect(),
1810 OSSL_STORE_LOADER_set_find(), OSSL_STORE_LOADER_set_load(),
1811 OSSL_STORE_LOADER_set_open(), OSSL_STORE_LOADER_set_open_ex(),
1812 OSSL_STORE_register_loader(), OSSL_STORE_unregister_loader(),
1815 These functions helped applications and engines create loaders for
1816 schemes they supported. These are all deprecated and discouraged in favour of
1817 provider implementations, see L<provider-storemgmt(7)>.
1821 PEM_read_DHparams(), PEM_read_bio_DHparams(),
1822 PEM_read_DSAparams(), PEM_read_bio_DSAparams(),
1823 PEM_read_DSAPrivateKey(), PEM_read_DSA_PUBKEY(),
1824 PEM_read_bio_DSAPrivateKey and PEM_read_bio_DSA_PUBKEY(),
1825 PEM_read_ECPKParameters(), PEM_read_ECPrivateKey(), PEM_read_EC_PUBKEY(),
1826 PEM_read_bio_ECPKParameters(), PEM_read_bio_ECPrivateKey(), PEM_read_bio_EC_PUBKEY(),
1827 PEM_read_RSAPrivateKey(), PEM_read_RSA_PUBKEY(), PEM_read_RSAPublicKey(),
1828 PEM_read_bio_RSAPrivateKey(), PEM_read_bio_RSA_PUBKEY(), PEM_read_bio_RSAPublicKey(),
1829 PEM_write_bio_DHparams(), PEM_write_bio_DHxparams(), PEM_write_DHparams(), PEM_write_DHxparams(),
1830 PEM_write_DSAparams(), PEM_write_DSAPrivateKey(), PEM_write_DSA_PUBKEY(),
1831 PEM_write_bio_DSAparams(), PEM_write_bio_DSAPrivateKey(), PEM_write_bio_DSA_PUBKEY(),
1832 PEM_write_ECPKParameters(), PEM_write_ECPrivateKey(), PEM_write_EC_PUBKEY(),
1833 PEM_write_bio_ECPKParameters(), PEM_write_bio_ECPrivateKey(), PEM_write_bio_EC_PUBKEY(),
1834 PEM_write_RSAPrivateKey(), PEM_write_RSA_PUBKEY(), PEM_write_RSAPublicKey(),
1835 PEM_write_bio_RSAPrivateKey(), PEM_write_bio_RSA_PUBKEY(),
1836 PEM_write_bio_RSAPublicKey(),
1838 See L</Deprecated low-level key reading and writing functions>
1844 See L</Deprecated low-level encryption functions>.
1848 RAND_get_rand_method(), RAND_set_rand_method(), RAND_OpenSSL(),
1849 RAND_set_rand_engine()
1851 Applications should instead use L<RAND_set_DRBG_type(3)>,
1852 L<EVP_RAND(3)> and L<EVP_RAND(7)>.
1853 See L<RAND_set_rand_method(3)> for more details.
1857 RC2_encrypt(), RC2_decrypt(), RC2_set_key(), RC2_cbc_encrypt(), RC2_cfb64_encrypt(),
1858 RC2_ecb_encrypt(), RC2_ofb64_encrypt(),
1859 RC4(), RC4_set_key(), RC4_options(),
1860 RC5_32_encrypt(), RC5_32_set_key(), RC5_32_decrypt(), RC5_32_cbc_encrypt(),
1861 RC5_32_cfb64_encrypt(), RC5_32_ecb_encrypt(), RC5_32_ofb64_encrypt()
1863 See L</Deprecated low-level encryption functions>.
1864 The Algorithms "RC2", "RC4" and "RC5" have been moved to the L<Legacy Provider|/Legacy Algorithms>.
1868 RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update(), RIPEMD160_Final(),
1869 RIPEMD160_Transform()
1871 See L</Deprecated low-level digest functions>.
1872 The RIPE algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1876 RSA_bits(), RSA_security_bits(), RSA_size()
1878 Use L<EVP_PKEY_bits(3)>, L<EVP_PKEY_security_bits(3)> and L<EVP_PKEY_size(3)>.
1882 RSA_check_key(), RSA_check_key_ex()
1884 See L</Deprecated low-level validation functions>
1888 RSA_clear_flags(), RSA_flags(), RSA_set_flags(), RSA_test_flags(),
1889 RSA_setup_blinding(), RSA_blinding_off(), RSA_blinding_on()
1891 All of these RSA flags have been deprecated without replacement:
1893 B<RSA_FLAG_BLINDING>, B<RSA_FLAG_CACHE_PRIVATE>, B<RSA_FLAG_CACHE_PUBLIC>,
1894 B<RSA_FLAG_EXT_PKEY>, B<RSA_FLAG_NO_BLINDING>, B<RSA_FLAG_THREAD_SAFE>
1895 B<RSA_METHOD_FLAG_NO_CHECK>
1899 RSA_generate_key_ex(), RSA_generate_multi_prime_key()
1901 See L</Deprecated low-level key generation functions>.
1907 See L</Providers are a replacement for engines and low-level method overrides>
1911 RSA_get0_crt_params(), RSA_get0_d(), RSA_get0_dmp1(), RSA_get0_dmq1(),
1912 RSA_get0_e(), RSA_get0_factors(), RSA_get0_iqmp(), RSA_get0_key(),
1913 RSA_get0_multi_prime_crt_params(), RSA_get0_multi_prime_factors(), RSA_get0_n(),
1914 RSA_get0_p(), RSA_get0_pss_params(), RSA_get0_q(),
1915 RSA_get_multi_prime_extra_count()
1917 See L</Deprecated low-level key parameter getters>
1921 RSA_new(), RSA_free(), RSA_up_ref()
1923 See L</Deprecated low-level object creation>.
1927 RSA_get_default_method(), RSA_get_ex_data and RSA_get_method()
1929 See L</Providers are a replacement for engines and low-level method overrides>.
1935 There is no replacement.
1939 B<RSA_meth_*()>, RSA_new_method(), RSA_null_method and RSA_PKCS1_OpenSSL()
1941 See L</Providers are a replacement for engines and low-level method overrides>.
1945 B<RSA_padding_add_*()>, B<RSA_padding_check_*()>
1947 See L</Deprecated low-level signing functions> and
1948 L</Deprecated low-level encryption functions>.
1952 RSA_print(), RSA_print_fp()
1954 See L</Deprecated low-level key printing functions>
1958 RSA_public_encrypt(), RSA_private_decrypt()
1960 See L</Deprecated low-level encryption functions>
1964 RSA_private_encrypt(), RSA_public_decrypt()
1966 This is equivalent to doing sign and verify operations (with a padding mode
1967 of none). See L</Deprecated low-level signing functions>.
1971 RSAPrivateKey_dup(), RSAPublicKey_dup()
1973 There is no direct replacement. Applications may use L<EVP_PKEY_dup(3)>.
1977 RSAPublicKey_it(), RSAPrivateKey_it()
1979 See L</Deprecated low-level key reading and writing functions>
1983 RSA_set0_crt_params(), RSA_set0_factors(), RSA_set0_key(),
1984 RSA_set0_multi_prime_params()
1986 See L</Deprecated low-level key parameter setters>.
1990 RSA_set_default_method(), RSA_set_method(), RSA_set_ex_data()
1992 See L</Providers are a replacement for engines and low-level method overrides>
1996 RSA_sign(), RSA_sign_ASN1_OCTET_STRING(), RSA_verify(),
1997 RSA_verify_ASN1_OCTET_STRING(), RSA_verify_PKCS1_PSS(),
1998 RSA_verify_PKCS1_PSS_mgf1()
2000 See L</Deprecated low-level signing functions>.
2004 RSA_X931_derive_ex(), RSA_X931_generate_key_ex(), RSA_X931_hash_id()
2006 There are no replacements for these functions.
2007 X931 padding can be set using L<EVP_SIGNATURE-RSA(7)/Signature Parameters>.
2008 See B<OSSL_SIGNATURE_PARAM_PAD_MODE>.
2012 SEED_encrypt(), SEED_decrypt(), SEED_set_key(), SEED_cbc_encrypt(),
2013 SEED_cfb128_encrypt(), SEED_ecb_encrypt(), SEED_ofb128_encrypt()
2015 See L</Deprecated low-level encryption functions>.
2016 The SEED algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
2020 SHA1_Init(), SHA1_Update(), SHA1_Final(), SHA1_Transform(),
2021 SHA224_Init(), SHA224_Update(), SHA224_Final(),
2022 SHA256_Init(), SHA256_Update(), SHA256_Final(), SHA256_Transform(),
2023 SHA384_Init(), SHA384_Update(), SHA384_Final(),
2024 SHA512_Init(), SHA512_Update(), SHA512_Final(), SHA512_Transform()
2026 See L</Deprecated low-level digest functions>.
2030 SRP_Calc_A(), SRP_Calc_B(), SRP_Calc_client_key(), SRP_Calc_server_key(),
2031 SRP_Calc_u(), SRP_Calc_x(), SRP_check_known_gN_param(), SRP_create_verifier(),
2032 SRP_create_verifier_BN(), SRP_get_default_gN(), SRP_user_pwd_free(), SRP_user_pwd_new(),
2033 SRP_user_pwd_set0_sv(), SRP_user_pwd_set1_ids(), SRP_user_pwd_set_gN(),
2034 SRP_VBASE_add0_user(), SRP_VBASE_free(), SRP_VBASE_get1_by_user(), SRP_VBASE_init(),
2035 SRP_VBASE_new(), SRP_Verify_A_mod_N(), SRP_Verify_B_mod_N()
2037 There are no replacements for the SRP functions.
2041 SSL_CTX_set_tmp_dh_callback(), SSL_set_tmp_dh_callback(),
2042 SSL_CTX_set_tmp_dh(), SSL_set_tmp_dh()
2044 These are used to set the Diffie-Hellman (DH) parameters that are to be used by
2045 servers requiring ephemeral DH keys. Instead applications should consider using
2046 the built-in DH parameters that are available by calling L<SSL_CTX_set_dh_auto(3)>
2047 or L<SSL_set_dh_auto(3)>. If custom parameters are necessary then applications can
2048 use the alternative functions L<SSL_CTX_set0_tmp_dh_pkey(3)> and
2049 L<SSL_set0_tmp_dh_pkey(3)>. There is no direct replacement for the "callback"
2050 functions. The callback was originally useful in order to have different
2051 parameters for export and non-export ciphersuites. Export ciphersuites are no
2052 longer supported by OpenSSL. Use of the callback functions should be replaced
2053 by one of the other methods described above.
2057 SSL_CTX_set_tlsext_ticket_key_cb()
2059 Use the new L<SSL_CTX_set_tlsext_ticket_key_evp_cb(3)> function instead.
2063 WHIRLPOOL(), WHIRLPOOL_Init(), WHIRLPOOL_Update(), WHIRLPOOL_Final(),
2064 WHIRLPOOL_BitUpdate()
2066 See L</Deprecated low-level digest functions>.
2067 The Whirlpool algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
2071 X509_certificate_type()
2073 This was an undocumented function. Applications can use L<X509_get0_pubkey(3)>
2074 and L<X509_get0_signature(3)> instead.
2078 X509_http_nbio(), X509_CRL_http_nbio()
2080 Use L<X509_load_http(3)> and L<X509_CRL_load_http(3)> instead.
2084 =head2 Using the FIPS Module in applications
2086 See L<fips_module(7)> and L<OSSL_PROVIDER-FIPS(7)> for details.
2088 =head2 OpenSSL command line application changes
2090 =head3 New applications
2092 L<B<openssl kdf>|openssl-kdf(1)> uses the new L<EVP_KDF(3)> API.
2093 L<B<openssl kdf>|openssl-mac(1)> uses the new L<EVP_MAC(3)> API.
2095 =head3 Added options
2097 B<-provider_path> and B<-provider> are available to all apps and can be used
2098 multiple times to load any providers, such as the 'legacy' provider or third
2099 party providers. If used then the 'default' provider would also need to be
2100 specified if required. The B<-provider_path> must be specified before the
2101 B<-provider> option.
2103 The B<list> app has many new options. See L<openssl-list(1)> for more
2106 B<-crl_lastupdate> and B<-crl_nextupdate> used by B<openssl ca> allows
2107 explicit setting of fields in the generated CRL.
2109 =head3 Removed options
2111 Interactive mode is not longer available.
2113 The B<-crypt> option used by B<openssl passwd>.
2114 The B<-c> option used by B<openssl x509>, B<openssl dhparam>,
2115 B<openssl dsaparam>, and B<openssl ecparam>.
2117 =head3 Other Changes
2119 The output of Command line applications may have minor changes.
2120 These are primarily changes in capitalisation and white space. However, in some
2121 cases, there are additional differences.
2122 For example, the DH parameters output from B<openssl dhparam> now lists 'P',
2123 'Q', 'G' and 'pcounter' instead of 'prime', 'generator', 'subgroup order' and
2124 'counter' respectively.
2126 The B<openssl> commands that read keys, certificates, and CRLs now
2127 automatically detect the PEM or DER format of the input files so it is not
2128 necessary to explicitly specify the input format anymore. However if the
2129 input format option is used the specified format will be required.
2131 B<openssl speed> no longer uses low-level API calls.
2132 This implies some of the performance numbers might not be comparable with the
2133 previous releases due to higher overhead. This applies particularly to
2134 measuring performance on smaller data chunks.
2136 b<openssl dhparam>, B<openssl dsa>, B<openssl gendsa>, B<openssl dsaparam>,
2137 B<openssl genrsa> and B<openssl rsa> have been modified to use PKEY APIs.
2138 B<openssl genrsa> and B<openssl rsa> now write PKCS #8 keys by default.
2140 =head3 Default settings
2142 "SHA256" is now the default digest for TS query used by B<openssl ts>.
2144 =head3 Deprecated apps
2146 B<openssl rsautl> is deprecated, use B<openssl pkeyutl> instead.
2147 B<openssl dhparam>, B<openssl dsa>, B<openssl gendsa>, B<openssl dsaparam>,
2148 B<openssl genrsa>, B<openssl rsa>, B<openssl genrsa> and B<openssl rsa> are
2149 now in maintenance mode and no new features will be added to them.
2157 TLS 1.3 FFDHE key exchange support added
2159 This uses DH safe prime named groups.
2163 Support for fully "pluggable" TLSv1.3 groups.
2165 This means that providers may supply their own group implementations (using
2166 either the "key exchange" or the "key encapsulation" methods) which will
2167 automatically be detected and used by libssl.
2171 SSL and SSL_CTX options are now 64 bit instead of 32 bit.
2173 The signatures of the functions to get and set options on SSL and
2174 SSL_CTX objects changed from "unsigned long" to "uint64_t" type.
2176 This may require source code changes.
2178 See L<SSL_CTX_get_options(3)>, L<SSL_CTX_set_options(3)>,
2179 L<SSL_get_options(3)> and L<SSL_set_options(3)>.
2183 SSL_set1_host() and SSL_add1_host() Changes
2185 These functions now take IP literal addresses as well as actual hostnames.
2189 Added SSL option SSL_OP_CLEANSE_PLAINTEXT
2191 If the option is set, openssl cleanses (zeroizes) plaintext bytes from
2192 internal buffers after delivering them to the application. Note,
2193 the application is still responsible for cleansing other copies
2194 (e.g.: data received by L<SSL_read(3)>).
2198 Client-initiated renegotiation is disabled by default.
2200 To allow it, use the B<-client_renegotiation> option,
2201 the B<SSL_OP_ALLOW_CLIENT_RENEGOTIATION> flag, or the C<ClientRenegotiation>
2202 config parameter as appropriate.
2206 Secure renegotiation is now required by default for TLS connections
2208 Support for RFC 5746 secure renegotiation is now required by default for
2209 SSL or TLS connections to succeed. Applications that require the ability
2210 to connect to legacy peers will need to explicitly set
2211 SSL_OP_LEGACY_SERVER_CONNECT. Accordingly, SSL_OP_LEGACY_SERVER_CONNECT
2212 is no longer set as part of SSL_OP_ALL.
2216 Combining the Configure options no-ec and no-dh no longer disables TLSv1.3
2218 Typically if OpenSSL has no EC or DH algorithms then it cannot support
2219 connections with TLSv1.3. However OpenSSL now supports "pluggable" groups
2220 through providers. Therefore third party providers may supply group
2221 implementations even where there are no built-in ones. Attempting to create
2222 TLS connections in such a build without also disabling TLSv1.3 at run time or
2223 using third party provider groups may result in handshake failures. TLSv1.3
2224 can be disabled at compile time using the "no-tls1_3" Configure option.
2228 SSL_CTX_set_ciphersuites() and SSL_set_ciphersuites() changes.
2230 The methods now ignore unknown ciphers.
2234 Security callback change.
2236 The security callback, which can be customised by application code, supports
2237 the security operation SSL_SECOP_TMP_DH. This is defined to take an EVP_PKEY
2238 in the "other" parameter. In most places this is what is passed. All these
2239 places occur server side. However there was one client side call of this
2240 security operation and it passed a DH object instead. This is incorrect
2241 according to the definition of SSL_SECOP_TMP_DH, and is inconsistent with all
2242 of the other locations. Therefore this client side call has been changed to
2243 pass an EVP_PKEY instead.
2247 New SSL option SSL_OP_IGNORE_UNEXPECTED_EOF
2249 The SSL option SSL_OP_IGNORE_UNEXPECTED_EOF is introduced. If that option
2250 is set, an unexpected EOF is ignored, it pretends a close notify was received
2251 instead and so the returned error becomes SSL_ERROR_ZERO_RETURN.
2255 The security strength of SHA1 and MD5 based signatures in TLS has been reduced.
2257 This results in SSL 3, TLS 1.0, TLS 1.1 and DTLS 1.0 no longer
2258 working at the default security level of 1 and instead requires security
2259 level 0. The security level can be changed either using the cipher string
2260 with `C<@SECLEVEL>, or calling L<SSL_CTX_set_security_level(3)>. This also means
2261 that where the signature algorithms extension is missing from a ClientHello
2262 then the handshake will fail in TLS 1.2 at security level 1. This is because,
2263 although this extension is optional, failing to provide one means that
2264 OpenSSL will fallback to a default set of signature algorithms. This default
2265 set requires the availability of SHA1.
2269 X509 certificates signed using SHA1 are no longer allowed at security level 1 and above.
2271 In TLS/SSL the default security level is 1. It can be set either using the cipher
2272 string with C<@SECLEVEL>, or calling L<SSL_CTX_set_security_level(3)>. If the
2273 leaf certificate is signed with SHA-1, a call to L<SSL_CTX_use_certificate(3)>
2274 will fail if the security level is not lowered first.
2275 Outside TLS/SSL, the default security level is -1 (effectively 0). It can
2276 be set using L<X509_VERIFY_PARAM_set_auth_level(3)> or using the B<-auth_level>
2277 options of the commands.
2287 Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
2289 Licensed under the Apache License 2.0 (the "License"). You may not use
2290 this file except in compliance with the License. You can obtain a copy
2291 in the file LICENSE in the source distribution or at
2292 L<https://www.openssl.org/source/license.html>.