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 Not all algorithms may be available for the application at a particular moment.
64 If the application code uses any digest or cipher algorithm via the EVP interface,
65 the application should verify the result of the L<EVP_EncryptInit(3)>,
66 L<EVP_EncryptInit_ex(3)>, and L<EVP_DigestInit(3)> functions. In case when
67 the requested algorithm is not available, these functions will fail.
69 See also L</Legacy Algorithms> for information on the legacy provider.
71 See also L</Completing the installation of the FIPS Module> and
72 L</Using the FIPS Module in applications>.
76 OpenSSL has historically provided two sets of APIs for invoking cryptographic
77 algorithms: the "high level" APIs (such as the C<EVP> APIs) and the "low level"
78 APIs. The high level APIs are typically designed to work across all algorithm
79 types. The "low level" APIs are targeted at a specific algorithm implementation.
80 For example, the EVP APIs provide the functions L<EVP_EncryptInit_ex(3)>,
81 L<EVP_EncryptUpdate(3)> and L<EVP_EncryptFinal(3)> to perform symmetric
82 encryption. Those functions can be used with the algorithms AES, CHACHA, 3DES etc.
83 On the other hand, to do AES encryption using the low level APIs you would have
84 to call AES specific functions such as L<AES_set_encrypt_key(3)>,
85 L<AES_encrypt(3)>, and so on. The functions for 3DES are different.
86 Use of the low level APIs has been informally discouraged by the OpenSSL
87 development team for a long time. However in OpenSSL 3.0 this is made more
88 formal. All such low level APIs have been deprecated. You may still use them in
89 your applications, but you may start to see deprecation warnings during
90 compilation (dependent on compiler support for this). Deprecated APIs may be
91 removed from future versions of OpenSSL so you are strongly encouraged to update
92 your code to use the high level APIs instead.
94 This is described in more detail in L</Deprecation of Low Level Functions>
96 =head3 Legacy Algorithms
98 Some cryptographic algorithms such as B<MD2> and B<DES> that were available via
99 the EVP APIs are now considered legacy and their use is strongly discouraged.
100 These legacy EVP algorithms are still available in OpenSSL 3.0 but not by
101 default. If you want to use them then you must load the legacy provider.
102 This can be as simple as a config file change, or can be done programmatically.
103 See L<OSSL_PROVIDER-legacy(7)> for a complete list of algorithms.
104 Applications using the EVP APIs to access these algorithms should instead use
105 more modern algorithms. If that is not possible then these applications
106 should ensure that the legacy provider has been loaded. This can be achieved
107 either programmatically or via configuration. See L<crypto(7)> man page for
108 more information about providers.
110 =head3 Engines and "METHOD" APIs
112 The refactoring to support Providers conflicts internally with the APIs used to
113 support engines, including the ENGINE API and any function that creates or
114 modifies custom "METHODS" (for example L<EVP_MD_meth_new(3)>,
115 L<EVP_CIPHER_meth_new(3)>, L<EVP_PKEY_meth_new(3)>, L<RSA_meth_new(3)>,
116 L<EC_KEY_METHOD_new(3)>, etc.). These functions are being deprecated in
117 OpenSSL 3.0, and users of these APIs should know that their use can likely
118 bypass provider selection and configuration, with unintended consequences.
119 This is particularly relevant for applications written to use the OpenSSL 3.0
120 FIPS module, as detailed below. Authors and maintainers of external engines are
121 strongly encouraged to refactor their code transforming engines into providers
122 using the new Provider API and avoiding deprecated methods.
124 =head3 Versioning Scheme
126 The OpenSSL versioning scheme has changed with the OpenSSL 3.0 release. The new
127 versioning scheme has this format:
131 For OpenSSL 1.1.1 and below, different patch levels were indicated by a letter
132 at the end of the release version number. This will no longer be used and
133 instead the patch level is indicated by the final number in the version. A
134 change in the second (MINOR) number indicates that new features may have been
135 added. OpenSSL versions with the same major number are API and ABI compatible.
136 If the major number changes then API and ABI compatibility is not guaranteed.
138 For more information, see L<OpenSSL_version(3)>.
140 =head3 Other major new features
142 =head4 Certificate Management Protocol (CMP, RFC 4210)
144 This also covers CRMF (RFC 4211) and HTTP transfer (RFC 6712)
145 See L<openssl-cmp(1)> and L<OSSL_CMP_exec_certreq(3)> as starting points.
147 =head4 HTTP(S) client
149 A proper HTTP(S) client that supports GET and POST, redirection, plain and
150 ASN.1-encoded contents, proxies, and timeouts.
152 =head4 Key Derivation Function API (EVP_KDF)
154 This simplifies the process of adding new KDF and PRF implementations.
156 Previously KDF algorithms had been shoe-horned into using the EVP_PKEY object
157 which was not a logical mapping.
158 Existing applications that use KDF algorithms using EVP_PKEY
159 (scrypt, TLS1 PRF and HKDF) may be slower as they use an EVP_KDF bridge
161 All new applications should use the new L<EVP_KDF(3)> interface.
162 See also L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)> and
163 L<OSSL_PROVIDER-FIPS(7)/Key Derivation Function (KDF)>.
165 =head4 Message Authentication Code API (EVP_MAC)
167 This simplifies the process of adding MAC implementations.
169 This includes a generic EVP_PKEY to EVP_MAC bridge, to facilitate the continued
170 use of MACs through raw private keys in functionality such as
171 L<EVP_DigestSign(3)> and L<EVP_DigestVerify(3)>.
173 All new applications should use the new L<EVP_MAC(3)> interface.
174 See also L<OSSL_PROVIDER-default(7)/Message Authentication Code (MAC)>
175 and L<OSSL_PROVIDER-FIPS(7)/Message Authentication Code (MAC)>.
177 =head4 Support for Linux Kernel TLS
179 In order to use KTLS, support for it must be compiled in using the
180 C<enable-ktls> configuration option. It must also be enabled at run time using
181 the B<SSL_OP_ENABLE_KTLS> option.
183 =head4 New Algorithms
189 KDF algorithms "SINGLE STEP" and "SSH"
191 See L<EVP_KDF-SS(7)> and L<EVP_KDF-SSHKDF(7)>
195 MAC Algorithms "GMAC" and "KMAC"
197 See L<EVP_MAC-GMAC(7)> and L<EVP_MAC-KMAC(7)>.
201 KEM Algorithm "RSASVE"
203 See L<EVP_KEM-RSA(7)>.
207 Cipher Algorithm "AES-SIV"
209 See L<EVP_EncryptInit(3)/SIV Mode>.
213 AES Key Wrap inverse ciphers supported by EVP layer.
215 The inverse ciphers use AES decryption for wrapping, and AES encryption for
216 unwrapping. The algorithms are: "AES-128-WRAP-INV", "AES-192-WRAP-INV",
217 "AES-256-WRAP-INV", "AES-128-WRAP-PAD-INV", "AES-192-WRAP-PAD-INV" and
218 "AES-256-WRAP-PAD-INV".
222 AES CTS cipher added to EVP layer.
224 The algorithms are "AES-128-CBC-CTS", "AES-192-CBC-CTS" and "AES-256-CBC-CTS".
225 CS1, CS2 and CS3 variants are supported.
229 =head4 CMS and PKCS#7 updates
235 Added CAdES-BES signature verification support.
239 Added CAdES-BES signature scheme and attributes support (RFC 5126) to CMS API.
243 Added AuthEnvelopedData content type structure (RFC 5083) using AES_GCM
245 This uses the AES-GCM parameter (RFC 5084) for the Cryptographic Message Syntax.
246 Its purpose is to support encryption and decryption of a digital envelope that
247 is both authenticated and encrypted using AES GCM mode.
251 L<PKCS7_get_octet_string(3)> and L<PKCS7_type_is_other(3)> were made public.
255 =head4 PKCS#12 API updates
257 The default algorithms for pkcs12 creation with the PKCS12_create() function
258 were changed to more modern PBKDF2 and AES based algorithms. The default
259 MAC iteration count was changed to PKCS12_DEFAULT_ITER to make it equal
260 with the password-based encryption iteration count. The default digest
261 algorithm for the MAC computation was changed to SHA-256. The pkcs12
262 application now supports -legacy option that restores the previous
263 default algorithms to support interoperability with legacy systems.
265 Added enhanced PKCS#12 APIs which accept a library context B<OSSL_LIB_CTX>
266 and (where relevant) a property query. Other APIs which handle PKCS#7 and
267 PKCS#8 objects have also been enhanced where required. This includes:
269 L<PKCS12_add_key_ex(3)>, L<PKCS12_add_safe_ex(3)>, L<PKCS12_add_safes_ex(3)>,
270 L<PKCS12_create_ex(3)>, L<PKCS12_decrypt_skey_ex(3)>, L<PKCS12_init_ex(3)>,
271 L<PKCS12_item_decrypt_d2i_ex(3)>, L<PKCS12_item_i2d_encrypt_ex(3)>,
272 L<PKCS12_key_gen_asc_ex(3)>, L<PKCS12_key_gen_uni_ex(3)>, L<PKCS12_key_gen_utf8_ex(3)>,
273 L<PKCS12_pack_p7encdata_ex(3)>, L<PKCS12_pbe_crypt_ex(3)>, L<PKCS12_PBE_keyivgen_ex(3)>,
274 L<PKCS12_SAFEBAG_create_pkcs8_encrypt_ex(3)>, L<PKCS5_pbe2_set_iv_ex(3)>,
275 L<PKCS5_pbe_set0_algor_ex(3)>, L<PKCS5_pbe_set_ex(3)>, L<PKCS5_pbkdf2_set_ex(3)>,
276 L<PKCS5_v2_PBE_keyivgen_ex(3)>, L<PKCS5_v2_scrypt_keyivgen_ex(3)>,
277 L<PKCS8_decrypt_ex(3)>, L<PKCS8_encrypt_ex(3)>, L<PKCS8_set0_pbe_ex(3)>.
279 As part of this change the EVP_PBE_xxx APIs can also accept a library
280 context and property query and will call an extended version of the key/IV
281 derivation function which supports these parameters. This includes
282 L<EVP_PBE_CipherInit_ex(3)>, L<EVP_PBE_find_ex(3)> and L<EVP_PBE_scrypt_ex(3)>.
284 =head4 Windows thread synchronization changes
286 Windows thread synchronization uses read/write primitives (SRWLock) when
287 supported by the OS, otherwise CriticalSection continues to be used.
291 A new generic trace API has been added which provides support for enabling
292 instrumentation through trace output. This feature is mainly intended as an aid
293 for developers and is disabled by default. To utilize it, OpenSSL needs to be
294 configured with the C<enable-trace> option.
296 If the tracing API is enabled, the application can activate trace output by
297 registering BIOs as trace channels for a number of tracing and debugging
298 categories. See L<OSSL_trace_enabled(3)>.
300 =head4 Key validation updates
302 L<EVP_PKEY_public_check(3)> and L<EVP_PKEY_param_check(3)> now work for
303 more key types. This includes RSA, DSA, ED25519, X25519, ED448 and X448.
304 Previously (in 1.1.1) they would return -2. For key types that do not have
305 parameters then L<EVP_PKEY_param_check(3)> will always return 1.
307 =head3 Other notable deprecations and changes
309 =head4 The function code part of an OpenSSL error code is no longer relevant
311 This code is now always set to zero. Related functions are deprecated.
313 =head4 STACK and HASH macros have been cleaned up
315 The type-safe wrappers are declared everywhere and implemented once.
316 See L<DEFINE_STACK_OF(3)> and L<DECLARE_LHASH_OF(3)>.
318 =head4 The RAND_DRBG subsystem has been removed
320 The new L<EVP_RAND(3)> is a partial replacement: the DRBG callback framework is
321 absent. The RAND_DRBG API did not fit well into the new provider concept as
322 implemented by EVP_RAND and EVP_RAND_CTX.
324 =head4 Removed FIPS_mode() and FIPS_mode_set()
326 These functions are legacy APIs that are not applicable to the new provider
327 model. Applications should instead use
328 L<EVP_default_properties_is_fips_enabled(3)> and
329 L<EVP_default_properties_enable_fips(3)>.
331 =head4 Key generation is slower
333 The Miller-Rabin test now uses 64 rounds, which is used for all prime generation,
334 including RSA key generation. This affects the time for larger keys sizes.
336 The default key generation method for the regular 2-prime RSA keys was changed
337 to the FIPS 186-4 B.3.6 method (Generation of Probable Primes with Conditions
338 Based on Auxiliary Probable Primes). This method is slower than the original
341 =head4 Change PBKDF2 to conform to SP800-132 instead of the older PKCS5 RFC2898
343 This checks that the salt length is at least 128 bits, the derived key length is
344 at least 112 bits, and that the iteration count is at least 1000.
345 For backwards compatibility these checks are disabled by default in the
346 default provider, but are enabled by default in the fips provider.
348 To enable or disable the checks see B<OSSL_KDF_PARAM_PKCS5> in
349 L<EVP_KDF-PBKDF2(7)>. The parameter can be set using L<EVP_KDF_derive(3)>.
351 =head4 Enforce a minimum DH modulus size of 512 bits
353 Smaller sizes now result in an error.
355 =head4 SM2 key changes
357 EC EVP_PKEYs with the SM2 curve have been reworked to automatically become
358 EVP_PKEY_SM2 rather than EVP_PKEY_EC.
360 Unlike in previous OpenSSL versions, this means that applications cannot
361 call C<EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2)> to get SM2 computations.
363 Parameter and key generation is also reworked to make it possible
364 to generate EVP_PKEY_SM2 parameters and keys. Applications must now generate
365 SM2 keys directly and must not create an EVP_PKEY_EC key first. It is no longer
366 possible to import an SM2 key with domain parameters other than the SM2 elliptic
369 Validation of SM2 keys has been separated from the validation of regular EC
370 keys, allowing to improve the SM2 validation process to reject loaded private
371 keys that are not conforming to the SM2 ISO standard.
372 In particular, a private scalar I<k> outside the range I<< 1 <= k < n-1 >> is
373 now correctly rejected.
375 =head4 EVP_PKEY_set_alias_type() method has been removed
377 This function made a B<EVP_PKEY> object mutable after it had been set up. In
378 OpenSSL 3.0 it was decided that a provided key should not be able to change its
379 type, so this function has been removed.
381 =head4 Functions that return an internal key should be treated as read only
383 Functions such as L<EVP_PKEY_get0_RSA(3)> behave slightly differently in
384 OpenSSL 3.0. Previously they returned a pointer to the low-level key used
385 internally by libcrypto. From OpenSSL 3.0 this key may now be held in a
386 provider. Calling these functions will only return a handle on the internal key
387 where the EVP_PKEY was constructed using this key in the first place, for
388 example using a function or macro such as L<EVP_PKEY_assign_RSA(3)>,
389 L<EVP_PKEY_set1_RSA(3)>, etc.
390 Where the EVP_PKEY holds a provider managed key, then these functions now return
391 a cached copy of the key. Changes to the internal provider key that take place
392 after the first time the cached key is accessed will not be reflected back in
393 the cached copy. Similarly any changes made to the cached copy by application
394 code will not be reflected back in the internal provider key.
396 For the above reasons the keys returned from these functions should typically be
397 treated as read-only. To emphasise this the value returned from
398 L<EVP_PKEY_get0_RSA(3)>, L<EVP_PKEY_get0_DSA(3)>, L<EVP_PKEY_get0_EC_KEY(3)> and
399 L<EVP_PKEY_get0_DH(3)> have been made const. This may break some existing code.
400 Applications broken by this change should be modified. The preferred solution is
401 to refactor the code to avoid the use of these deprecated functions. Failing
402 this the code should be modified to use a const pointer instead.
403 The L<EVP_PKEY_get1_RSA(3)>, L<EVP_PKEY_get1_DSA(3)>, L<EVP_PKEY_get1_EC_KEY(3)>
404 and L<EVP_PKEY_get1_DH(3)> functions continue to return a non-const pointer to
405 enable them to be "freed". However they should also be treated as read-only.
407 =head4 The public key check has moved from EVP_PKEY_derive() to EVP_PKEY_derive_set_peer()
409 This may mean result in an error in L<EVP_PKEY_derive_set_peer(3)> rather than
410 during L<EVP_PKEY_derive(3)>.
411 To disable this check use EVP_PKEY_derive_set_peer_ex(dh, peer, 0).
413 =head4 The print format has cosmetic changes for some functions
415 The output from numerous "printing" functions such as L<X509_signature_print(3)>,
416 L<X509_print_ex(3)>, L<X509_CRL_print_ex(3)>, and other similar functions has been
417 amended such that there may be cosmetic differences between the output
418 observed in 1.1.1 and 3.0. This also applies to the B<-text> output from the
419 B<openssl x509> and B<openssl crl> applications.
421 =head4 Interactive mode from the B<openssl> program has been removed
423 From now on, running it without arguments is equivalent to B<openssl help>.
425 =head4 The error return values from some control calls (ctrl) have changed
427 One significant change is that controls which used to return -2 for
428 invalid inputs, now return -1 indicating a generic error condition instead.
430 =head4 DH and DHX key types have different settable parameters
432 Previously (in 1.1.1) these conflicting parameters were allowed, but will now
433 result in errors. See L<EVP_PKEY-DH(7)> for further details. This affects the
434 behaviour of L<openssl-genpkey(1)> for DH parameter generation.
436 =head4 EVP_CIPHER_CTX_set_flags() ordering change
438 If using a cipher from a provider the B<EVP_CIPH_FLAG_LENGTH_BITS> flag can only
439 be set B<after> the cipher has been assigned to the cipher context.
440 See L<EVP_EncryptInit(3)/FLAGS> for more information.
442 =head2 Installation and Compilation
444 Please refer to the INSTALL.md file in the top of the distribution for
445 instructions on how to build and install OpenSSL 3.0. Please also refer to the
446 various platform specific NOTES files for your specific platform.
448 =head2 Upgrading from OpenSSL 1.1.1
450 Upgrading to OpenSSL 3.0 from OpenSSL 1.1.1 should be relatively straight
451 forward in most cases. The most likely area where you will encounter problems
452 is if you have used low level APIs in your code (as discussed above). In that
453 case you are likely to start seeing deprecation warnings when compiling your
454 application. If this happens you have 3 options:
460 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.
464 Suppress the warnings. Refer to your compiler documentation on how to do this.
468 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
472 =head3 Error code changes
474 As OpenSSL 3.0 provides a brand new Encoder/Decoder mechanism for working with
475 widely used file formats, application code that checks for particular error
476 reason codes on key loading failures might need an update.
478 Password-protected keys may deserve special attention. If only some errors
479 are treated as an indicator that the user should be asked about the password again,
480 it's worth testing these scenarios and processing the newly relevant codes.
482 There may be more cases to treat specially, depending on the calling application code.
484 =head2 Upgrading from OpenSSL 1.0.2
486 Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 is likely to be significantly more
487 difficult. In addition to the issues discussed above in the section about
488 L</Upgrading from OpenSSL 1.1.1>, the main things to be aware of are:
494 The build and installation procedure has changed significantly.
496 Check the file INSTALL.md in the top of the installation for instructions on how
497 to build and install OpenSSL for your platform. Also read the various NOTES
498 files in the same directory, as applicable for your platform.
502 Many structures have been made opaque in OpenSSL 3.0.
504 The structure definitions have been removed from the public header files and
505 moved to internal header files. In practice this means that you can no longer
506 stack allocate some structures. Instead they must be heap allocated through some
507 function call (typically those function names have a C<_new> suffix to them).
508 Additionally you must use "setter" or "getter" functions to access the fields
509 within those structures.
511 For example code that previously looked like this:
515 /* This line will now generate compiler errors */
516 EVP_MD_CTX_init(&md_ctx);
518 The code needs to be amended to look like this:
522 md_ctx = EVP_MD_CTX_new();
525 EVP_MD_CTX_free(md_ctx);
529 Support for TLSv1.3 has been added.
531 This has a number of implications for SSL/TLS applications. See the
532 L<TLS1.3 page|https://wiki.openssl.org/index.php/TLS1.3> for further details.
536 More details about the breaking changes between OpenSSL versions 1.0.2 and 1.1.0
538 L<OpenSSL 1.1.0 Changes page|https://wiki.openssl.org/index.php/OpenSSL_1.1.0_Changes>.
540 =head3 Upgrading from the OpenSSL 2.0 FIPS Object Module
542 The OpenSSL 2.0 FIPS Object Module was a separate download that had to be built
543 separately and then integrated into your main OpenSSL 1.0.2 build.
544 In OpenSSL 3.0 the FIPS support is fully integrated into the mainline version of
545 OpenSSL and is no longer a separate download. For further information see
546 L</Completing the installation of the FIPS Module>.
548 The function calls FIPS_mode() and FIPS_mode_set() have been removed
549 from OpenSSL 3.0. You should rewrite your application to not use them.
550 See L<fips_module(7)> and L<OSSL_PROVIDER-FIPS(7)> for details.
552 =head2 Completing the installation of the FIPS Module
554 The FIPS Module will be built and installed automatically if FIPS support has
555 been configured. The current documentation can be found in the
556 L<README-FIPS|https://github.com/openssl/openssl/blob/master/README-FIPS.md> file.
560 Applications written to work with OpenSSL 1.1.1 will mostly just work with
561 OpenSSL 3.0. However changes will be required if you want to take advantage of
562 some of the new features that OpenSSL 3.0 makes available. In order to do that
563 you need to understand some new concepts introduced in OpenSSL 3.0.
564 Read L<crypto(7)/Library contexts> for further information.
566 =head3 Library Context
568 A library context allows different components of a complex application to each
569 use a different library context and have different providers loaded with
570 different configuration settings.
571 See L<crypto(7)/Library contexts> for further info.
573 If the user creates an B<OSSL_LIB_CTX> via L<OSSL_LIB_CTX_new(3)> then many
574 functions may need to be changed to pass additional parameters to handle the
577 =head4 Using a Library Context - Old functions that should be changed
579 If a library context is needed then all EVP_* digest functions that return a
580 B<const EVP_MD *> such as EVP_sha256() should be replaced with a call to
581 L<EVP_MD_fetch(3)>. See L<crypto(7)/ALGORITHM FETCHING>.
583 If a library context is needed then all EVP_* cipher functions that return a
584 B<const EVP_CIPHER *> such as EVP_aes_128_cbc() should be replaced vith a call to
585 L<EVP_CIPHER_fetch(3)>. See L<crypto(7)/ALGORITHM FETCHING>.
587 Some functions can be passed an object that has already been set up with a library
588 context such as L<d2i_X509(3)>, L<d2i_X509_CRL(3)>, L<d2i_X509_REQ(3)> and
589 L<d2i_X509_PUBKEY(3)>. If NULL is passed instead then the created object will be
590 set up with the default library context. Use L<X509_new_ex(3)>,
591 L<X509_CRL_new_ex(3)>, L<X509_REQ_new_ex(3)> and L<X509_PUBKEY_new_ex(3)> if a
592 library context is required.
594 All functions listed below with a I<NAME> have a replacment function I<NAME_ex>
595 that takes B<OSSL_LIB_CTX> as an additional argument. Functions that have other
596 mappings are listed along with the respective name.
602 L<ASN1_item_new(3)>, L<ASN1_item_d2i(3)>, L<ASN1_item_d2i_fp(3)>,
603 L<ASN1_item_d2i_bio(3)>, L<ASN1_item_sign(3)> and L<ASN1_item_verify(3)>
611 b2i_RSA_PVK_bio() and i2b_PVK_bio()
615 L<BN_CTX_new(3)> and L<BN_CTX_secure_new(3)>
619 L<CMS_AuthEnvelopedData_create(3)>, L<CMS_ContentInfo_new(3)>, L<CMS_data_create(3)>,
620 L<CMS_digest_create(3)>, L<CMS_EncryptedData_encrypt(3)>, L<CMS_encrypt(3)>,
621 L<CMS_EnvelopedData_create(3)>, L<CMS_ReceiptRequest_create0(3)> and L<CMS_sign(3)>
625 L<CONF_modules_load_file(3)>
629 L<CTLOG_new(3)>, L<CTLOG_new_from_base64(3)> and L<CTLOG_STORE_new(3)>
633 L<CT_POLICY_EVAL_CTX_new(3)>
637 L<d2i_AutoPrivateKey(3)>, L<d2i_PrivateKey(3)> and L<d2i_PUBKEY(3)>
641 L<d2i_PrivateKey_bio(3)> and L<d2i_PrivateKey_fp(3)>
643 Use L<d2i_PrivateKey_ex_bio(3)> and L<d2i_PrivateKey_ex_fp(3)>
649 Use L<EC_GROUP_new_by_curve_name_ex(3)> or L<EC_GROUP_new_from_params(3)>.
653 L<EVP_DigestSignInit(3)> and L<EVP_DigestVerifyInit(3)>
657 L<EVP_PBE_CipherInit(3)>, L<EVP_PBE_find(3)> and L<EVP_PBE_scrypt(3)>
661 L<PKCS5_PBE_keyivgen(3)>
669 L<EVP_PKEY_CTX_new_id(3)>
671 Use L<EVP_PKEY_CTX_new_from_name(3)>
675 L<EVP_PKEY_derive_set_peer(3)>, L<EVP_PKEY_new_raw_private_key(3)>
676 and L<EVP_PKEY_new_raw_public_key(3)>
680 L<EVP_SignFinal(3)> and L<EVP_VerifyFinal(3)>
688 L<OCSP_RESPID_match(3)> and L<OCSP_RESPID_set_by_key(3)>
692 L<OPENSSL_thread_stop(3)>
696 L<OSSL_STORE_open(3)>
700 L<PEM_read_bio_Parameters(3)>, L<PEM_read_bio_PrivateKey(3)>, L<PEM_read_bio_PUBKEY(3)>,
701 L<PEM_read_PrivateKey(3)> and L<PEM_read_PUBKEY(3)>
705 L<PEM_write_bio_PrivateKey(3)>, L<PEM_write_bio_PUBKEY(3)>, L<PEM_write_PrivateKey(3)>
706 and L<PEM_write_PUBKEY(3)>
710 L<PEM_X509_INFO_read_bio(3)> and L<PEM_X509_INFO_read(3)>
714 L<PKCS12_add_key(3)>, L<PKCS12_add_safe(3)>, L<PKCS12_add_safes(3)>,
715 L<PKCS12_create(3)>, L<PKCS12_decrypt_skey(3)>, L<PKCS12_init(3)>, L<PKCS12_item_decrypt_d2i(3)>,
716 L<PKCS12_item_i2d_encrypt(3)>, L<PKCS12_key_gen_asc(3)>, L<PKCS12_key_gen_uni(3)>,
717 L<PKCS12_key_gen_utf8(3)>, L<PKCS12_pack_p7encdata(3)>, L<PKCS12_pbe_crypt(3)>,
718 L<PKCS12_PBE_keyivgen(3)>, L<PKCS12_SAFEBAG_create_pkcs8_encrypt(3)>
722 L<PKCS5_pbe_set0_algor(3)>, L<PKCS5_pbe_set(3)>, L<PKCS5_pbe2_set_iv(3)>,
723 L<PKCS5_pbkdf2_set(3)> and L<PKCS5_v2_scrypt_keyivgen(3)>
727 L<PKCS7_encrypt(3)>, L<PKCS7_new(3)> and L<PKCS7_sign(3)>
731 L<PKCS8_decrypt(3)>, L<PKCS8_encrypt(3)> and L<PKCS8_set0_pbe(3)>
735 L<RAND_bytes(3)> and L<RAND_priv_bytes(3)>
739 L<SMIME_write_ASN1(3)>
743 L<SSL_load_client_CA_file(3)>
751 L<TS_RESP_CTX_new(3)>
759 L<X509_load_cert_crl_file(3)> and L<X509_load_cert_file(3)>
763 L<X509_LOOKUP_by_subject(3)> and L<X509_LOOKUP_ctrl(3)>
775 L<X509_REQ_new(3)> and L<X509_REQ_verify(3)>
779 L<X509_STORE_CTX_new(3)>, L<X509_STORE_set_default_paths(3)>, L<X509_STORE_load_file(3)>,
780 L<X509_STORE_load_locations(3)> and L<X509_STORE_load_store(3)>
784 =head4 New functions that use a Library context
786 The following functions can be passed a library context if required.
787 Passing NULL will use the default library context.
793 L<BIO_new_from_core_bio(3)>
797 L<EVP_ASYM_CIPHER_fetch(3)> and L<EVP_ASYM_CIPHER_do_all_provided(3)>
801 L<EVP_CIPHER_fetch(3)> and L<EVP_CIPHER_do_all_provided(3)>
805 L<EVP_default_properties_enable_fips(3)> and
806 L<EVP_default_properties_is_fips_enabled(3)>
810 L<EVP_KDF_fetch(3)> and L<EVP_KDF_do_all_provided(3)>
814 L<EVP_KEM_fetch(3)> and L<EVP_KEM_do_all_provided(3)>
818 L<EVP_KEYEXCH_fetch(3)> and L<EVP_KEYEXCH_do_all_provided(3)>
822 L<EVP_KEYMGMT_fetch(3)> and L<EVP_KEYMGMT_do_all_provided(3)>
826 L<EVP_MAC_fetch(3)> and L<EVP_MAC_do_all_provided(3)>
830 L<EVP_MD_fetch(3)> and L<EVP_MD_do_all_provided(3)>
834 L<EVP_PKEY_CTX_new_from_pkey(3)>
838 L<EVP_PKEY_Q_keygen(3)>
842 L<EVP_Q_mac(3)> and L<EVP_Q_digest(3)>
846 L<EVP_RAND(3)> and L<EVP_RAND_do_all_provided(3)>
850 L<EVP_set_default_properties(3)>
854 L<EVP_SIGNATURE_fetch(3)> and L<EVP_SIGNATURE_do_all_provided(3)>
858 L<OSSL_CMP_CTX_new(3)> and L<OSSL_CMP_SRV_CTX_new(3)>
862 L<OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert(3)>
866 L<OSSL_CRMF_MSG_create_popo(3)> and L<OSSL_CRMF_MSGS_verify_popo(3)>
870 L<OSSL_CRMF_pbm_new(3)> and L<OSSL_CRMF_pbmp_new(3)>
874 L<OSSL_DECODER_CTX_add_extra(3)> and L<OSSL_DECODER_CTX_new_for_pkey(3)>
878 L<OSSL_DECODER_fetch(3)> and L<OSSL_DECODER_do_all_provided(3)>
882 L<OSSL_ENCODER_CTX_add_extra(3)>
886 L<OSSL_ENCODER_fetch(3)> and L<OSSL_ENCODER_do_all_provided(3)>
890 L<OSSL_LIB_CTX_free(3)>, L<OSSL_LIB_CTX_load_config(3)> and L<OSSL_LIB_CTX_set0_default(3)>
894 L<OSSL_PROVIDER_add_builtin(3)>, L<OSSL_PROVIDER_available(3)>,
895 L<OSSL_PROVIDER_do_all(3)>, L<OSSL_PROVIDER_load(3)>,
896 L<OSSL_PROVIDER_set_default_search_path(3)> and L<OSSL_PROVIDER_try_load(3)>
900 L<OSSL_SELF_TEST_get_callback(3)> and L<OSSL_SELF_TEST_set_callback(3)>
904 L<OSSL_STORE_attach(3)>
908 L<OSSL_STORE_LOADER_fetch(3)> and L<OSSL_STORE_LOADER_do_all_provided(3)>
912 L<RAND_get0_primary(3)>, L<RAND_get0_private(3)>, L<RAND_get0_public(3)>,
913 L<RAND_set_DRBG_type(3)> and L<RAND_set_seed_source_type(3)>
919 Providers are described in detail here L<crypto(7)/Providers>.
920 See also L<crypto(7)/OPENSSL PROVIDERS>.
922 =head3 Fetching algorithms and property queries
924 Implicit and Explicit Fetching is described in detail here
925 L<crypto(7)/ALGORITHM FETCHING>.
927 =head3 Mapping EVP controls and flags to provider B<OSSL_PARAM> parameters
929 The existing functions for controls (such as L<EVP_CIPHER_CTX_ctrl(3)>) and
930 manipulating flags (such as L<EVP_MD_CTX_set_flags(3)>)internally use
931 B<OSSL_PARAMS> to pass information to/from provider objects.
932 See L<OSSL_PARAM(3)> for additional information related to parameters.
934 For ciphers see L<EVP_EncryptInit(3)/CONTROLS>, L<EVP_EncryptInit(3)/FLAGS> and
935 L<EVP_EncryptInit(3)/PARAMETERS>.
937 For digests see L<EVP_DigestInit(3)/CONTROLS>, L<EVP_DigestInit(3)/FLAGS> and
938 L<EVP_DigestInit(3)/PARAMETERS>.
940 =head3 Deprecation of Low Level Functions
942 A significant number of APIs have been deprecated in OpenSSL 3.0.
943 This section describes some common categories of deprecations.
944 See L</Deprecated function mappings> for the list of deprecated functions
945 that refer to these categories.
947 =head4 Providers are a replacement for engines and low-level method overrides
949 Any accessor that uses an ENGINE is deprecated (such as EVP_PKEY_set1_engine()).
950 Applications using engines should instead use providers.
952 Before providers were added algorithms were overriden by changing the methods
953 used by algorithms. All these methods such as RSA_new_method() and RSA_meth_new()
954 are now deprecated and can be replaced by using providers instead.
956 =head4 Deprecated i2d and d2i functions for low-level key types
958 Any i2d and d2i functions such as d2i_DHparams() that take a low-level key type
959 have been deprecated. Applications should instead use the L<OSSL_DECODER(3)> and
960 L<OSSL_ENCODER(3)> APIs to read and write files.
961 See L<d2i_RSAPrivateKey(3)/Migration> for further details.
963 =head4 Deprecated low-level key object getters and setters
965 Applications that set or get low-level key objects (such as EVP_PKEY_set1_DH()
966 or EVP_PKEY_get0()) should instead use the OSSL_ENCODER
967 (See L<OSSL_ENCODER_to_bio(3)>) or OSSL_DECODER (See L<OSSL_DECODER_from_bio(3)>)
968 APIs, or alternatively use L<EVP_PKEY_fromdata(3)> or L<EVP_PKEY_todata(3)>.
970 =head4 Deprecated low-level key parameter getters
972 Functions that access low-level objects directly such as L<RSA_get0_n(3)> are now
973 deprecated. Applications should use one of L<EVP_PKEY_get_bn_param(3)>,
974 L<EVP_PKEY_get_int_param(3)>, l<EVP_PKEY_get_size_t_param(3)>,
975 L<EVP_PKEY_get_utf8_string_param(3)>, L<EVP_PKEY_get_octet_string_param(3)> or
976 L<EVP_PKEY_get_params(3)> to access fields from an EVP_PKEY.
977 Gettable parameters are listed in L<EVP_PKEY-RSA(7)/Common RSA parameters>,
978 L<EVP_PKEY-DH(7)/DH parameters>, L<EVP_PKEY-DSA(7)/DSA parameters>,
979 L<EVP_PKEY-FFC(7)/FFC parameters>, L<EVP_PKEY-EC(7)/Common EC parameters> and
980 L<EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>.
981 Applications may also use L<EVP_PKEY_todata(3)> to return all fields.
983 =head4 Deprecated low-level key parameter setters
985 Functions that access low-level objects directly such as L<RSA_set0_crt_params(3)>
986 are now deprecated. Applications should use L<EVP_PKEY_fromdata(3)> to create
987 new keys from user provided key data. Keys should be immutable once they are
988 created, so if required the user may use L<EVP_PKEY_todata(3)>, L<OSSL_PARAM_merge(3)>,
989 and L<EVP_PKEY_fromdata(3)> to create a modified key.
990 See L<EVP_PKEY-DH(7)/Examples> for more information.
991 See L</Deprecated low-level key generation functions> for information on
992 generating a key using parameters.
994 =head4 Deprecated low-level object creation
996 Low-level objects were created using methods such as L<RSA_new(3)>,
997 L<RSA_up_ref(3)> and L<RSA_free(3)>. Applications should instead use the
998 high-level EVP_PKEY APIs, e.g. L<EVP_PKEY_new(3)>, L<EVP_PKEY_up_ref(3)> and
1000 See also L<EVP_PKEY_CTX_new_from_name(3)> and L<EVP_PKEY_CTX_new_from_pkey(3)>.
1002 EVP_PKEYs may be created in a variety of ways:
1003 See also L</Deprecated low-level key generation functions>,
1004 L</Deprecated low-level key reading and writing functions> and
1005 L</Deprecated low-level key parameter setters>.
1007 =head4 Deprecated low-level encryption functions
1009 Low-level encryption functions such as L<AES_encrypt(3)> and L<AES_decrypt(3)>
1010 have been informally discouraged from use for a long time. Applications should
1011 instead use the high level EVP APIs L<EVP_EncryptInit_ex(3)>,
1012 L<EVP_EncryptUpdate(3)>, and L<EVP_EncryptFinal_ex(3)> or
1013 L<EVP_DecryptInit_ex(3)>, L<EVP_DecryptUpdate(3)> and L<EVP_DecryptFinal_ex(3)>.
1015 =head4 Deprecated low-level digest functions
1017 Use of low-level digest functions such as L<SHA1_Init(3)> have been
1018 informally discouraged from use for a long time. Applications should instead
1019 use the the high level EVP APIs L<EVP_DigestInit_ex(3)>, L<EVP_DigestUpdate(3)>
1020 and L<EVP_DigestFinal_ex(3)>, or the quick one-shot L<EVP_Q_digest(3)>.
1022 Note that the functions L<SHA1(3)>, L<SHA224(3)>, L<SHA256(3)>, L<SHA384(3)>
1023 and L<SHA512(3)> have changed to macros that use L<EVP_Q_digest(3)>.
1025 =head4 Deprecated low-level signing functions
1027 Use of low-level signing functions such as L<DSA_sign(3)> have been
1028 informally discouraged for a long time. Instead applications should use
1029 L<EVP_DigestSign(3)> and L<EVP_DigestVerify(3)>.
1030 See also L<EVP_SIGNATURE-RSA(7)>, L<EVP_SIGNATURE-DSA(7)>,
1031 L<EVP_SIGNATURE-ECDSA(7)> and L<EVP_SIGNATURE-ED25519(7)>.
1033 =head4 Deprecated low-level MAC functions
1035 Low-level mac functions such as L<CMAC_Init(3)> are deprecated.
1036 Applications should instead use the new L<EVP_MAC(3)> interface, using
1037 L<EVP_MAC_CTX_new(3)>, L<EVP_MAC_CTX_free(3)>, L<EVP_MAC_init(3)>,
1038 L<EVP_MAC_update(3)> and L<EVP_MAC_final(3)> or the single-shot MAC function
1040 See L<EVP_MAC(3)>, L<EVP_MAC-HMAC(7)>, L<EVP_MAC-CMAC(7)>, L<EVP_MAC-GMAC(7)>,
1041 L<EVP_MAC-KMAC(7)>, L<EVP_MAC-BLAKE2(7)>, L<EVP_MAC-Poly1305(7)> and
1042 L<EVP_MAC-Siphash(7)> for additional information.
1044 Note that the one-shot method HMAC() is still available for compatability purposes.
1046 =head4 Deprecated low-level validation functions
1048 Low-level validation functions such as L<DH_check(3)> have been informally
1049 discouraged from use for a long time. Applications should instead use the high-level
1050 EVP_PKEY APIs such as L<EVP_PKEY_check(3)>, L<EVP_PKEY_param_check(3)>,
1051 L<EVP_PKEY_param_check_quick(3)>, L<EVP_PKEY_public_check(3)>,
1052 L<EVP_PKEY_public_check_quick(3)>, L<EVP_PKEY_private_check(3)>,
1053 and L<EVP_PKEY_pairwise_check(3)>.
1055 =head4 Deprecated low-level key exchange functions
1057 Many low-level functions have been informally discouraged from use for a long
1058 time. Applications should instead use L<EVP_PKEY_derive(3)>.
1059 See L<EVP_KEYEXCH-DH(7)>, L<EVP_KEYEXCH-ECDH(7)> and L<EVP_KEYEXCH-X25519(7)>.
1061 =head4 Deprecated low-level key generation functions
1063 Many low-level functions have been informally discouraged from use for a long
1064 time. Applications should instead use L<EVP_PKEY_keygen_init(3)> and
1065 L<EVP_PKEY_generate(3)> as described in L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>,
1066 L<EVP_PKEY-RSA(7)>, L<EVP_PKEY-EC(7)> and L<EVP_PKEY-X25519(7)>.
1067 The 'quick' one-shot function L<EVP_PKEY_Q_keygen(3)> and macros for the most
1068 common cases: <EVP_RSA_gen(3)> and L<EVP_EC_gen(3)> may also be used.
1070 =head4 Deprecated low-level key reading and writing functions
1072 Use of low-level objects (such as DSA) has been informally discouraged from use
1073 for a long time. Functions to read and write these low-level objects (such as
1074 PEM_read_DSA_PUBKEY()) should be replaced. Applications should instead use
1075 L<OSSL_ENCODER_to_bio(3)> and L<OSSL_DECODER_from_bio(3)>.
1077 =head4 Deprecated low-level key printing functions
1079 Use of low-level objects (such as DSA) has been informally discouraged from use
1080 for a long time. Functions to print these low-level objects such as
1081 DSA_print() should be replaced with the equivalent EVP_PKEY functions.
1082 Application should use one of L<EVP_PKEY_print_public(3)>,
1083 L<EVP_PKEY_print_private(3)>, L<EVP_PKEY_print_params(3)>,
1084 L<EVP_PKEY_print_public_fp(3)>, L<EVP_PKEY_print_private_fp(3)> or
1085 L<EVP_PKEY_print_params_fp(3)>. Note that internally these use
1086 L<OSSL_ENCODER_to_bio(3)> and L<OSSL_DECODER_from_bio(3)>.
1088 =head3 Deprecated function mappings
1090 The following functions have been deprecated in 3.0.
1096 AES_bi_ige_encrypt() and AES_ige_encrypt()
1098 There is no replacement for the IGE functions. New code should not use these modes.
1099 These undocumented functions were never integrated into the EVP layer.
1100 They implemented the AES Infinite Garble Extension (IGE) mode and AES
1101 Bi-directional IGE mode. These modes were never formally standardised and
1102 usage of these functions is believed to be very small. In particular
1103 AES_bi_ige_encrypt() has a known bug. It accepts 2 AES keys, but only one
1104 is ever used. The security implications are believed to be minimal, but
1105 this issue was never fixed for backwards compatibility reasons.
1109 AES_encrypt(), AES_decrypt(), AES_set_encrypt_key(), AES_set_decrypt_key(),
1110 AES_cbc_encrypt(), AES_cfb128_encrypt(), AES_cfb1_encrypt(), AES_cfb8_encrypt(),
1111 AES_ecb_encrypt(), AES_ofb128_encrypt()
1115 AES_unwrap_key(), AES_wrap_key()
1117 See L</Deprecated low-level encryption functions>
1123 There is no replacement. It returned a string indicating if the AES code was unrolled.
1127 ASN1_digest(), ASN1_sign(), ASN1_verify()
1129 There are no replacements. These old functions are not used, and could be
1130 disabled with the macro NO_ASN1_OLD since OpenSSL 0.9.7.
1134 ASN1_STRING_length_set()
1136 Use L<ASN1_STRING_set(3)> or L<ASN1_STRING_set0(3)> instead.
1137 This was a potentially unsafe function that could change the bounds of a
1138 previously passed in pointer.
1142 BF_encrypt(), BF_decrypt(), BF_set_key(), BF_cbc_encrypt(), BF_cfb64_encrypt(),
1143 BF_ecb_encrypt(), BF_ofb64_encrypt()
1145 See L</Deprecated low-level encryption functions>.
1146 The Blowfish algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1152 There is no replacement. This option returned a constant string.
1156 BIO_get_callback(), BIO_set_callback(), BIO_debug_callback()
1158 Use the respective non-deprecated _ex() functions.
1162 BN_is_prime_ex(), BN_is_prime_fasttest_ex()
1164 Use L<BN_check_prime(3)> which that avoids possible misuse and always uses at least
1165 64 rounds of the Miller-Rabin primality test.
1169 BN_pseudo_rand(), BN_pseudo_rand_range()
1171 Use L<BN_rand(3)> and L<BN_rand_range(3)>.
1175 BN_X931_derive_prime_ex(), BN_X931_generate_prime_ex(), BN_X931_generate_Xpq()
1177 There are no replacements for these low-level functions. They were used internally
1178 by RSA_X931_derive_ex() and RSA_X931_generate_key_ex() which are also deprecated.
1179 Use L<EVP_PKEY_keygen(3)> instead.
1183 Camellia_encrypt(), Camellia_decrypt(), Camellia_set_key(),
1184 Camellia_cbc_encrypt(), Camellia_cfb128_encrypt(), Camellia_cfb1_encrypt(),
1185 Camellia_cfb8_encrypt(), Camellia_ctr128_encrypt(), Camellia_ecb_encrypt(),
1186 Camellia_ofb128_encrypt()
1188 See L</Deprecated low-level encryption functions>.
1192 CAST_encrypt(), CAST_decrypt(), CAST_set_key(), CAST_cbc_encrypt(),
1193 CAST_cfb64_encrypt(), CAST_ecb_encrypt(), CAST_ofb64_encrypt()
1195 See L</Deprecated low-level encryption functions>.
1196 The CAST algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1200 CMAC_CTX_new(), CMAC_CTX_cleanup(), CMAC_CTX_copy(), CMAC_CTX_free(),
1201 CMAC_CTX_get0_cipher_ctx()
1203 See L</Deprecated low-level MAC functions>.
1207 CMAC_Init(), CMAC_Update(), CMAC_Final(), CMAC_resume()
1209 See L</Deprecated low-level MAC functions>.
1213 CRYPTO_mem_ctrl(), CRYPTO_mem_debug_free(), CRYPTO_mem_debug_malloc(),
1214 CRYPTO_mem_debug_pop(), CRYPTO_mem_debug_push(), CRYPTO_mem_debug_realloc(),
1215 CRYPTO_mem_leaks(), CRYPTO_mem_leaks_cb(), CRYPTO_mem_leaks_fp(),
1216 CRYPTO_set_mem_debug()
1218 Memory-leak checking has been deprecated in favor of more modern development
1219 tools, such as compiler memory and leak sanitizers or Valgrind.
1223 d2i_DHparams(), d2i_DHxparams(), d2i_DSAparams(), d2i_DSAPrivateKey(),
1224 d2i_DSAPrivateKey_bio(), d2i_DSAPrivateKey_fp(), d2i_DSA_PUBKEY(),
1225 d2i_DSA_PUBKEY_bio(), d2i_DSA_PUBKEY_fp(), d2i_DSAPublicKey(),
1226 d2i_ECParameters(), d2i_ECPrivateKey(), d2i_ECPrivateKey_bio(),
1227 d2i_ECPrivateKey_fp(), d2i_EC_PUBKEY(), d2i_EC_PUBKEY_bio(),
1228 d2i_EC_PUBKEY_fp(), o2i_ECPublicKey(), d2i_RSAPrivateKey(),
1229 d2i_RSAPrivateKey_bio(), d2i_RSAPrivateKey_fp(), d2i_RSA_PUBKEY(),
1230 d2i_RSA_PUBKEY_bio(), d2i_RSA_PUBKEY_fp(), d2i_RSAPublicKey(),
1231 d2i_RSAPublicKey_bio(), d2i_RSAPublicKey_fp()
1233 See L</Deprecated i2d and d2i functions for low-level key types>
1237 DES_crypt(), DES_fcrypt(), DES_encrypt1(), DES_encrypt2(), DES_encrypt3(),
1238 DES_decrypt3(), DES_ede3_cbc_encrypt(), DES_ede3_cfb64_encrypt(),
1239 DES_ede3_cfb_encrypt(),DES_ede3_ofb64_encrypt(),
1240 DES_ecb_encrypt(), DES_ecb3_encrypt(), DES_ofb64_encrypt(), DES_ofb_encrypt(),
1241 DES_cfb64_encrypt DES_cfb_encrypt(), DES_cbc_encrypt(), DES_ncbc_encrypt(),
1242 DES_pcbc_encrypt(), DES_xcbc_encrypt(), DES_cbc_cksum(), DES_quad_cksum(),
1243 DES_check_key_parity(), DES_is_weak_key(), DES_key_sched(), DES_options(),
1244 DES_random_key(), DES_set_key(), DES_set_key_checked(), DES_set_key_unchecked(),
1245 DES_set_odd_parity(), DES_string_to_2keys(), DES_string_to_key()
1247 See L</Deprecated low-level encryption functions>.
1248 Algorithms for "DESX-CBC", "DES-ECB", "DES-CBC", "DES-OFB", "DES-CFB",
1249 "DES-CFB1" and "DES-CFB8" have been moved to the L<Legacy Provider|/Legacy Algorithms>.
1253 DH_bits(), DH_security_bits(), DH_size()
1255 Use L<EVP_PKEY_get_bits(3)>, L<EVP_PKEY_get_security_bits(3)> and
1256 L<EVP_PKEY_get_size(3)>.
1260 DH_check(), DH_check_ex(), DH_check_params(), DH_check_params_ex(),
1261 DH_check_pub_key(), DH_check_pub_key_ex()
1263 See L</Deprecated low-level validation functions>
1267 DH_clear_flags(), DH_test_flags(), DH_set_flags()
1269 The B<DH_FLAG_CACHE_MONT_P> flag has been deprecated without replacement.
1270 The B<DH_FLAG_TYPE_DH> and B<DH_FLAG_TYPE_DHX> have been deprecated.
1271 Use EVP_PKEY_is_a() to determine the type of a key.
1272 There is no replacement for setting these flags.
1276 DH_compute_key() DH_compute_key_padded()
1278 See L</Deprecated low-level key exchange functions>.
1282 DH_new(), DH_new_by_nid(), DH_free(), DH_up_ref()
1284 See L</Deprecated low-level object creation>
1288 DH_generate_key(), DH_generate_parameters_ex()
1290 See L</Deprecated low-level key generation functions>.
1294 DH_get0_pqg(), DH_get0_p(), DH_get0_q(), DH_get0_g(), DH_get0_key(),
1295 DH_get0_priv_key(), DH_get0_pub_key(), DH_get_length(), DH_get_nid()
1297 See L</Deprecated low-level key parameter getters>
1301 DH_get_1024_160(), DH_get_2048_224(), DH_get_2048_256()
1303 Applications should instead set the B<OSSL_PKEY_PARAM_GROUP_NAME> as specified in
1304 L<EVP_PKEY-DH(7)/DH parameters>) to one of "dh_1024_160", "dh_2048_224" or
1305 "dh_2048_256" when generating a DH key.
1311 Applications should use L<EVP_PKEY_CTX_set_dh_kdf_type(3)> instead.
1315 DH_get_default_method(), DH_get0_engine(), DH_meth_*(), DH_new_method(),
1316 DH_OpenSSL(), DH_get_ex_data(), DH_set_default_method(), DH_set_method(),
1319 See L</Providers are a replacement for engines and low-level method overrides>
1323 DHparams_print(), DHparams_print_fp()
1325 See L</Deprecated low-level key printing functions>
1329 DH_set0_key(), DH_set0_pqg(), DH_set_length()
1331 See L</Deprecated low-level key parameter setters>
1335 DSA_bits(), DSA_security_bits(), DSA_size()
1337 Use L<EVP_PKEY_get_bits(3)>, L<EVP_PKEY_get_security_bits(3)> and
1338 L<EVP_PKEY_get_size(3)>.
1342 DHparams_dup(), DSA_dup_DH()
1344 There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)>
1345 and L<EVP_PKEY_dup(3)> instead.
1349 DSA_generate_key(), DSA_generate_parameters_ex()
1351 See L</Deprecated low-level key generation functions>.
1355 DSA_get0_engine(), DSA_get_default_method(), DSA_get_ex_data(),
1356 DSA_get_method(), DSA_meth_*(), DSA_new_method(), DSA_OpenSSL(),
1357 DSA_set_default_method(), DSA_set_ex_data(), DSA_set_method()
1359 See L</Providers are a replacement for engines and low-level method overrides>.
1363 DSA_get0_p(), DSA_get0_q(), DSA_get0_g(), DSA_get0_pqg(), DSA_get0_key(),
1364 DSA_get0_priv_key(), DSA_get0_pub_key()
1366 See L</Deprecated low-level key parameter getters>.
1370 DSA_new(), DSA_free(), DSA_up_ref()
1372 See L</Deprecated low-level object creation>
1378 There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)>
1379 and L<EVP_PKEY_dup(3)> instead.
1383 DSAparams_print(), DSAparams_print_fp(), DSA_print(), DSA_print_fp()
1385 See L</Deprecated low-level key printing functions>
1389 DSA_set0_key(), DSA_set0_pqg()
1391 See L</Deprecated low-level key parameter setters>
1395 DSA_set_flags(), DSA_clear_flags(), DSA_test_flags()
1397 The B<DSA_FLAG_CACHE_MONT_P> flag has been deprecated without replacement.
1401 DSA_sign(), DSA_do_sign(), DSA_sign_setup(), DSA_verify(), DSA_do_verify()
1403 See L</Deprecated low-level signing functions>.
1409 See L</Deprecated low-level key exchange functions>.
1415 Applications may either set this using the helper function
1416 L<EVP_PKEY_CTX_set_ecdh_kdf_type(3)> or by setting an B<OSSL_PARAM> using the
1417 "kdf-type" as shown in L<EVP_KEYEXCH-ECDH(7)/EXAMPLES>
1421 ECDSA_sign(), ECDSA_sign_ex(), ECDSA_sign_setup(), ECDSA_do_sign(),
1422 ECDSA_do_sign_ex(), ECDSA_verify(), ECDSA_do_verify()
1424 See L</Deprecated low-level signing functions>.
1430 Applications should use L<EVP_PKEY_get_size(3)>.
1434 EC_GF2m_simple_method(), EC_GFp_mont_method(), EC_GFp_nist_method(),
1435 EC_GFp_nistp224_method(), EC_GFp_nistp256_method(), EC_GFp_nistp521_method(),
1436 EC_GFp_simple_method()
1438 There are no replacements for these functions. Applications should rely on the
1439 library automatically assigning a suitable method internally when an EC_GROUP
1444 EC_GROUP_clear_free()
1446 Use L<EC_GROUP_free(3)> instead.
1450 EC_GROUP_get_curve_GF2m(), EC_GROUP_get_curve_GFp(), EC_GROUP_set_curve_GF2m(),
1451 EC_GROUP_set_curve_GFp()
1453 Applications should use L<EC_GROUP_get_curve(3)> and L<EC_GROUP_set_curve(3)>.
1457 EC_GROUP_have_precompute_mult(), EC_GROUP_precompute_mult(),
1458 EC_KEY_precompute_mult()
1460 These functions are not widely used. Applications should instead switch to
1461 named curves which OpenSSL has hardcoded lookup tables for.
1465 EC_GROUP_new(), EC_GROUP_method_of(), EC_POINT_method_of()
1467 EC_METHOD is now an internal-only concept and a suitable EC_METHOD is assigned
1468 internally without application intervention.
1469 Users of EC_GROUP_new() should switch to a different suitable constructor.
1475 Applications should use L<EVP_PKEY_can_sign(3)> instead.
1481 See L</Deprecated low-level validation functions>
1485 EC_KEY_set_flags(), EC_KEY_get_flags(), EC_KEY_clear_flags()
1487 See L<EVP_PKEY-EC(7)/Common EC parameters> which handles flags as seperate
1488 parameters for B<OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT>,
1489 B<OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE>, B<OSSL_PKEY_PARAM_EC_ENCODING>,
1490 B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH> and
1491 B<OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC>.
1492 See also L<EVP_PKEY-EC(7)/EXAMPLES>
1496 EC_KEY_dup(), EC_KEY_copy()
1498 There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)>
1499 and L<EVP_PKEY_dup(3)> instead.
1503 EC_KEY_decoded_from_explicit_params()
1505 There is no replacement.
1509 EC_KEY_generate_key()
1511 See L</Deprecated low-level key generation functions>.
1515 EC_KEY_get0_group(), EC_KEY_get0_private_key(), EC_KEY_get0_public_key(),
1516 EC_KEY_get_conv_form(), EC_KEY_get_enc_flags()
1518 See L</Deprecated low-level key parameter getters>.
1522 EC_KEY_get0_engine(), EC_KEY_get_default_method(), EC_KEY_get_method(),
1523 EC_KEY_new_method(), EC_KEY_get_ex_data(), EC_KEY_OpenSSL(),
1524 EC_KEY_set_ex_data(), EC_KEY_set_default_method(), EC_KEY_METHOD_*(),
1527 See L</Providers are a replacement for engines and low-level method overrides>
1531 EC_METHOD_get_field_type()
1533 Use L<EC_GROUP_get_field_type(3)> instead.
1534 See L</Providers are a replacement for engines and low-level method overrides>
1538 EC_KEY_key2buf(), EC_KEY_oct2key(), EC_KEY_oct2priv(), EC_KEY_priv2buf(),
1541 There are no replacements for these.
1545 EC_KEY_new(), EC_KEY_new_by_curve_name(), EC_KEY_free(), EC_KEY_up_ref()
1547 See L</Deprecated low-level object creation>
1551 EC_KEY_print(), EC_KEY_print_fp()
1553 See L</Deprecated low-level key printing functions>
1557 EC_KEY_set_asn1_flag(), EC_KEY_set_conv_form(), EC_KEY_set_enc_flags()
1559 See L</Deprecated low-level key parameter setters>.
1563 EC_KEY_set_group(), EC_KEY_set_private_key(), EC_KEY_set_public_key(),
1564 EC_KEY_set_public_key_affine_coordinates()
1566 See L</Deprecated low-level key parameter setters>.
1570 ECParameters_print(), ECParameters_print_fp(), ECPKParameters_print(),
1571 ECPKParameters_print_fp()
1573 See L</Deprecated low-level key printing functions>
1577 EC_POINT_bn2point(), EC_POINT_point2bn()
1579 These functions were not particularly useful, since EC point serialization
1580 formats are not individual big-endian integers.
1584 EC_POINT_get_affine_coordinates_GF2m(), EC_POINT_get_affine_coordinates_GFp(),
1585 EC_POINT_set_affine_coordinates_GF2m(), EC_POINT_set_affine_coordinates_GFp()
1587 Applications should use L<EC_POINT_get_affine_coordinates(3)> and
1588 L<EC_POINT_set_affine_coordinates(3)> instead.
1592 EC_POINT_get_Jprojective_coordinates_GFp(), EC_POINT_set_Jprojective_coordinates_GFp()
1594 These functions are not widely used. Applications should instead use the
1595 L<EC_POINT_set_affine_coordinates(3)> and L<EC_POINT_get_affine_coordinates(3)>
1600 EC_POINT_make_affine(), EC_POINTs_make_affine()
1602 There is no replacement. These functions were not widely used, and OpenSSL
1603 automatically performs this conversion when needed.
1607 EC_POINT_set_compressed_coordinates_GF2m(), EC_POINT_set_compressed_coordinates_GFp()
1609 Applications should use L<EC_POINT_set_compressed_coordinates(3)> instead.
1615 This function is not widely used. Applications should instead use the
1616 L<EC_POINT_mul(3)> function.
1622 All engine functions are deprecated. An engine should be rewritten as a provider.
1623 See L</Providers are a replacement for engines and low-level method overrides>.
1627 B<ERR_load_*()>, ERR_func_error_string(), ERR_get_error_line(),
1628 ERR_get_error_line_data(), ERR_get_state()
1630 OpenSSL now loads error strings automatically so these functions are not needed.
1634 ERR_peek_error_line_data(), ERR_peek_last_error_line_data()
1636 The new functions are L<ERR_peek_error_func(3)>, L<ERR_peek_last_error_func(3)>,
1637 L<ERR_peek_error_data(3)>, L<ERR_peek_last_error_data(3)>, L<ERR_get_error_all(3)>,
1638 L<ERR_peek_error_all(3)> and L<ERR_peek_last_error_all(3)>.
1639 Applications should use L<ERR_get_error_all(3)>, or pick information
1640 with ERR_peek functions and finish off with getting the error code by using
1641 L<ERR_get_error(3)>.
1645 EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_iv_noconst(), EVP_CIPHER_CTX_original_iv()
1647 Applications should instead use L<EVP_CIPHER_CTX_get_updated_iv(3)>,
1648 L<EVP_CIPHER_CTX_get_updated_iv(3)> and L<EVP_CIPHER_CTX_get_original_iv(3)>
1650 See L<EVP_CIPHER_CTX_get_original_iv(3)> for further information.
1654 B<EVP_CIPHER_meth_*()>, EVP_MD_CTX_set_update_fn(), EVP_MD_CTX_update_fn(),
1657 See L</Providers are a replacement for engines and low-level method overrides>.
1661 EVP_PKEY_CTRL_PKCS7_ENCRYPT(), EVP_PKEY_CTRL_PKCS7_DECRYPT(),
1662 EVP_PKEY_CTRL_PKCS7_SIGN(), EVP_PKEY_CTRL_CMS_ENCRYPT(),
1663 EVP_PKEY_CTRL_CMS_DECRYPT(), and EVP_PKEY_CTRL_CMS_SIGN()
1665 These control operations are not invoked by the OpenSSL library anymore and
1666 are replaced by direct checks of the key operation against the key type
1667 when the operation is initialized.
1671 EVP_PKEY_CTX_get0_dh_kdf_ukm(), EVP_PKEY_CTX_get0_ecdh_kdf_ukm()
1673 See the "kdf-ukm" item in L<EVP_KEYEXCH-DH(7)/DH key exchange parameters> and
1674 L<EVP_KEYEXCH-ECDH(7)/ECDH Key Exchange parameters>.
1675 These functions are obsolete and should not be required.
1679 EVP_PKEY_CTX_set_rsa_keygen_pubexp()
1681 Applications should use L<EVP_PKEY_CTX_set1_rsa_keygen_pubexp(3)> instead.
1685 EVP_PKEY_cmp(), EVP_PKEY_cmp_parameters()
1687 Applications should use L<EVP_PKEY_eq(3)> and L<EVP_PKEY_parameters_eq(3)> instead.
1688 See L<EVP_PKEY_copy_parameters(3)> for further details.
1692 EVP_PKEY_encrypt_old(), EVP_PKEY_decrypt_old(),
1694 Applications should use L<EVP_PKEY_encrypt_init(3)> and L<EVP_PKEY_encrypt(3)> or
1695 L<EVP_PKEY_decrypt_init(3)> and L<EVP_PKEY_decrypt(3)> instead.
1701 This function returns NULL if the key comes from a provider.
1705 EVP_PKEY_get0_DH(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_EC_KEY(), EVP_PKEY_get0_RSA(),
1706 EVP_PKEY_get1_DH(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_EC_KEY and EVP_PKEY_get1_RSA(),
1707 EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash()
1709 See L</Functions that return an internal key should be treated as read only>.
1713 B<EVP_PKEY_meth_*()>
1715 See L</Providers are a replacement for engines and low-level method overrides>.
1719 EVP_PKEY_new_CMAC_key()
1721 See L</Deprecated low-level MAC functions>.
1725 EVP_PKEY_assign(), EVP_PKEY_set1_DH(), EVP_PKEY_set1_DSA(),
1726 EVP_PKEY_set1_EC_KEY(), EVP_PKEY_set1_RSA()
1728 See L</Deprecated low-level key object getters and setters>
1732 EVP_PKEY_set1_tls_encodedpoint() EVP_PKEY_get1_tls_encodedpoint()
1734 These functions were previously used by libssl to set or get an encoded public
1735 key into/from an EVP_PKEY object. With OpenSSL 3.0 these are replaced by the more
1736 generic functions L<EVP_PKEY_set1_encoded_public_key(3)> and
1737 L<EVP_PKEY_get1_encoded_public_key(3)>.
1738 The old versions have been converted to deprecated macros that just call the
1743 EVP_PKEY_set1_engine(), EVP_PKEY_get0_engine()
1745 See L</Providers are a replacement for engines and low-level method overrides>.
1749 EVP_PKEY_set_alias_type()
1751 This function has been removed. There is no replacement.
1752 See L</EVP_PKEY_set_alias_type() method has been removed>
1756 HMAC_Init_ex(), HMAC_Update(), HMAC_Final(), HMAC_size()
1758 See L</Deprecated low-level MAC functions>.
1762 HMAC_CTX_new(), HMAC_CTX_free(), HMAC_CTX_copy(), HMAC_CTX_reset(),
1763 HMAC_CTX_set_flags(), HMAC_CTX_get_md()
1765 See L</Deprecated low-level MAC functions>.
1769 i2d_DHparams(), i2d_DHxparams()
1771 See L</Deprecated low-level key reading and writing functions>
1772 and L<d2i_RSAPrivateKey(3)/Migration>
1776 i2d_DSAparams(), i2d_DSAPrivateKey(), i2d_DSAPrivateKey_bio(),
1777 i2d_DSAPrivateKey_fp(), i2d_DSA_PUBKEY(), i2d_DSA_PUBKEY_bio(),
1778 i2d_DSA_PUBKEY_fp(), i2d_DSAPublicKey()
1780 See L</Deprecated low-level key reading and writing functions>
1781 and L<d2i_RSAPrivateKey(3)/Migration>
1785 i2d_ECParameters(), i2d_ECPrivateKey(), i2d_ECPrivateKey_bio(),
1786 i2d_ECPrivateKey_fp(), i2d_EC_PUBKEY(), i2d_EC_PUBKEY_bio(),
1787 i2d_EC_PUBKEY_fp(), i2o_ECPublicKey()
1789 See L</Deprecated low-level key reading and writing functions>
1790 and L<d2i_RSAPrivateKey(3)/Migration>
1794 i2d_RSAPrivateKey(), i2d_RSAPrivateKey_bio(), i2d_RSAPrivateKey_fp(),
1795 i2d_RSA_PUBKEY(), i2d_RSA_PUBKEY_bio(), i2d_RSA_PUBKEY_fp(),
1796 i2d_RSAPublicKey(), i2d_RSAPublicKey_bio(), i2d_RSAPublicKey_fp()
1798 See L</Deprecated low-level key reading and writing functions>
1799 and L<d2i_RSAPrivateKey(3)/Migration>
1803 IDEA_encrypt(), IDEA_set_decrypt_key(), IDEA_set_encrypt_key(),
1804 IDEA_cbc_encrypt(), IDEA_cfb64_encrypt(), IDEA_ecb_encrypt(),
1805 IDEA_ofb64_encrypt()
1807 See L</Deprecated low-level encryption functions>.
1808 IDEA has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1814 There is no replacement. This function returned a constant string.
1818 MD2(), MD2_Init(), MD2_Update(), MD2_Final()
1820 See L</Deprecated low-level encryption functions>.
1821 MD2 has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1827 There is no replacement. This function returned a constant string.
1831 MD4(), MD4_Init(), MD4_Update(), MD4_Final(), MD4_Transform()
1833 See L</Deprecated low-level encryption functions>.
1834 MD4 has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1838 MDC2(), MDC2_Init(), MDC2_Update(), MDC2_Final()
1840 See L</Deprecated low-level encryption functions>.
1841 MDC2 has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1845 MD5(), MD5_Init(), MD5_Update(), MD5_Final(), MD5_Transform()
1847 See L</Deprecated low-level encryption functions>.
1853 This undocumented function has no replacement.
1854 See L<config(5)/HISTORY> for more details.
1860 Use L<OSSL_HTTP_parse_url(3)> instead.
1864 B<OCSP_REQ_CTX> type and B<OCSP_REQ_CTX_*()> functions
1866 These methods were used to collect all necessary data to form a HTTP request,
1867 and to perform the HTTP transfer with that request. With OpenSSL 3.0, the
1868 type is B<OSSL_HTTP_REQ_CTX>, and the deprecated functions are replaced
1869 with B<OSSL_HTTP_REQ_CTX_*()>. See L<OSSL_HTTP_REQ_CTX(3)> for additional
1874 OPENSSL_fork_child(), OPENSSL_fork_parent(), OPENSSL_fork_prepare()
1876 There is no replacement for these functions. These pthread fork support methods
1877 were unused by OpenSSL.
1881 OSSL_STORE_ctrl(), OSSL_STORE_do_all_loaders(), OSSL_STORE_LOADER_get0_engine(),
1882 OSSL_STORE_LOADER_get0_scheme(), OSSL_STORE_LOADER_new(),
1883 OSSL_STORE_LOADER_set_attach(), OSSL_STORE_LOADER_set_close(),
1884 OSSL_STORE_LOADER_set_ctrl(), OSSL_STORE_LOADER_set_eof(),
1885 OSSL_STORE_LOADER_set_error(), OSSL_STORE_LOADER_set_expect(),
1886 OSSL_STORE_LOADER_set_find(), OSSL_STORE_LOADER_set_load(),
1887 OSSL_STORE_LOADER_set_open(), OSSL_STORE_LOADER_set_open_ex(),
1888 OSSL_STORE_register_loader(), OSSL_STORE_unregister_loader(),
1891 These functions helped applications and engines create loaders for
1892 schemes they supported. These are all deprecated and discouraged in favour of
1893 provider implementations, see L<provider-storemgmt(7)>.
1897 PEM_read_DHparams(), PEM_read_bio_DHparams(),
1898 PEM_read_DSAparams(), PEM_read_bio_DSAparams(),
1899 PEM_read_DSAPrivateKey(), PEM_read_DSA_PUBKEY(),
1900 PEM_read_bio_DSAPrivateKey and PEM_read_bio_DSA_PUBKEY(),
1901 PEM_read_ECPKParameters(), PEM_read_ECPrivateKey(), PEM_read_EC_PUBKEY(),
1902 PEM_read_bio_ECPKParameters(), PEM_read_bio_ECPrivateKey(), PEM_read_bio_EC_PUBKEY(),
1903 PEM_read_RSAPrivateKey(), PEM_read_RSA_PUBKEY(), PEM_read_RSAPublicKey(),
1904 PEM_read_bio_RSAPrivateKey(), PEM_read_bio_RSA_PUBKEY(), PEM_read_bio_RSAPublicKey(),
1905 PEM_write_bio_DHparams(), PEM_write_bio_DHxparams(), PEM_write_DHparams(), PEM_write_DHxparams(),
1906 PEM_write_DSAparams(), PEM_write_DSAPrivateKey(), PEM_write_DSA_PUBKEY(),
1907 PEM_write_bio_DSAparams(), PEM_write_bio_DSAPrivateKey(), PEM_write_bio_DSA_PUBKEY(),
1908 PEM_write_ECPKParameters(), PEM_write_ECPrivateKey(), PEM_write_EC_PUBKEY(),
1909 PEM_write_bio_ECPKParameters(), PEM_write_bio_ECPrivateKey(), PEM_write_bio_EC_PUBKEY(),
1910 PEM_write_RSAPrivateKey(), PEM_write_RSA_PUBKEY(), PEM_write_RSAPublicKey(),
1911 PEM_write_bio_RSAPrivateKey(), PEM_write_bio_RSA_PUBKEY(),
1912 PEM_write_bio_RSAPublicKey(),
1914 See L</Deprecated low-level key reading and writing functions>
1920 See L</Deprecated low-level encryption functions>.
1924 RAND_get_rand_method(), RAND_set_rand_method(), RAND_OpenSSL(),
1925 RAND_set_rand_engine()
1927 Applications should instead use L<RAND_set_DRBG_type(3)>,
1928 L<EVP_RAND(3)> and L<EVP_RAND(7)>.
1929 See L<RAND_set_rand_method(3)> for more details.
1933 RC2_encrypt(), RC2_decrypt(), RC2_set_key(), RC2_cbc_encrypt(), RC2_cfb64_encrypt(),
1934 RC2_ecb_encrypt(), RC2_ofb64_encrypt(),
1935 RC4(), RC4_set_key(), RC4_options(),
1936 RC5_32_encrypt(), RC5_32_set_key(), RC5_32_decrypt(), RC5_32_cbc_encrypt(),
1937 RC5_32_cfb64_encrypt(), RC5_32_ecb_encrypt(), RC5_32_ofb64_encrypt()
1939 See L</Deprecated low-level encryption functions>.
1940 The Algorithms "RC2", "RC4" and "RC5" have been moved to the L<Legacy Provider|/Legacy Algorithms>.
1944 RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update(), RIPEMD160_Final(),
1945 RIPEMD160_Transform()
1947 See L</Deprecated low-level digest functions>.
1948 The RIPE algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1952 RSA_bits(), RSA_security_bits(), RSA_size()
1954 Use L<EVP_PKEY_get_bits(3)>, L<EVP_PKEY_get_security_bits(3)> and
1955 L<EVP_PKEY_get_size(3)>.
1959 RSA_check_key(), RSA_check_key_ex()
1961 See L</Deprecated low-level validation functions>
1965 RSA_clear_flags(), RSA_flags(), RSA_set_flags(), RSA_test_flags(),
1966 RSA_setup_blinding(), RSA_blinding_off(), RSA_blinding_on()
1968 All of these RSA flags have been deprecated without replacement:
1970 B<RSA_FLAG_BLINDING>, B<RSA_FLAG_CACHE_PRIVATE>, B<RSA_FLAG_CACHE_PUBLIC>,
1971 B<RSA_FLAG_EXT_PKEY>, B<RSA_FLAG_NO_BLINDING>, B<RSA_FLAG_THREAD_SAFE>
1972 B<RSA_METHOD_FLAG_NO_CHECK>
1976 RSA_generate_key_ex(), RSA_generate_multi_prime_key()
1978 See L</Deprecated low-level key generation functions>.
1984 See L</Providers are a replacement for engines and low-level method overrides>
1988 RSA_get0_crt_params(), RSA_get0_d(), RSA_get0_dmp1(), RSA_get0_dmq1(),
1989 RSA_get0_e(), RSA_get0_factors(), RSA_get0_iqmp(), RSA_get0_key(),
1990 RSA_get0_multi_prime_crt_params(), RSA_get0_multi_prime_factors(), RSA_get0_n(),
1991 RSA_get0_p(), RSA_get0_pss_params(), RSA_get0_q(),
1992 RSA_get_multi_prime_extra_count()
1994 See L</Deprecated low-level key parameter getters>
1998 RSA_new(), RSA_free(), RSA_up_ref()
2000 See L</Deprecated low-level object creation>.
2004 RSA_get_default_method(), RSA_get_ex_data and RSA_get_method()
2006 See L</Providers are a replacement for engines and low-level method overrides>.
2012 There is no replacement.
2016 B<RSA_meth_*()>, RSA_new_method(), RSA_null_method and RSA_PKCS1_OpenSSL()
2018 See L</Providers are a replacement for engines and low-level method overrides>.
2022 B<RSA_padding_add_*()>, B<RSA_padding_check_*()>
2024 See L</Deprecated low-level signing functions> and
2025 L</Deprecated low-level encryption functions>.
2029 RSA_print(), RSA_print_fp()
2031 See L</Deprecated low-level key printing functions>
2035 RSA_public_encrypt(), RSA_private_decrypt()
2037 See L</Deprecated low-level encryption functions>
2041 RSA_private_encrypt(), RSA_public_decrypt()
2043 This is equivalent to doing sign and verify recover operations (with a padding
2044 mode of none). See L</Deprecated low-level signing functions>.
2048 RSAPrivateKey_dup(), RSAPublicKey_dup()
2050 There is no direct replacement. Applications may use L<EVP_PKEY_dup(3)>.
2054 RSAPublicKey_it(), RSAPrivateKey_it()
2056 See L</Deprecated low-level key reading and writing functions>
2060 RSA_set0_crt_params(), RSA_set0_factors(), RSA_set0_key(),
2061 RSA_set0_multi_prime_params()
2063 See L</Deprecated low-level key parameter setters>.
2067 RSA_set_default_method(), RSA_set_method(), RSA_set_ex_data()
2069 See L</Providers are a replacement for engines and low-level method overrides>
2073 RSA_sign(), RSA_sign_ASN1_OCTET_STRING(), RSA_verify(),
2074 RSA_verify_ASN1_OCTET_STRING(), RSA_verify_PKCS1_PSS(),
2075 RSA_verify_PKCS1_PSS_mgf1()
2077 See L</Deprecated low-level signing functions>.
2081 RSA_X931_derive_ex(), RSA_X931_generate_key_ex(), RSA_X931_hash_id()
2083 There are no replacements for these functions.
2084 X931 padding can be set using L<EVP_SIGNATURE-RSA(7)/Signature Parameters>.
2085 See B<OSSL_SIGNATURE_PARAM_PAD_MODE>.
2089 SEED_encrypt(), SEED_decrypt(), SEED_set_key(), SEED_cbc_encrypt(),
2090 SEED_cfb128_encrypt(), SEED_ecb_encrypt(), SEED_ofb128_encrypt()
2092 See L</Deprecated low-level encryption functions>.
2093 The SEED algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
2097 SHA1_Init(), SHA1_Update(), SHA1_Final(), SHA1_Transform(),
2098 SHA224_Init(), SHA224_Update(), SHA224_Final(),
2099 SHA256_Init(), SHA256_Update(), SHA256_Final(), SHA256_Transform(),
2100 SHA384_Init(), SHA384_Update(), SHA384_Final(),
2101 SHA512_Init(), SHA512_Update(), SHA512_Final(), SHA512_Transform()
2103 See L</Deprecated low-level digest functions>.
2107 SRP_Calc_A(), SRP_Calc_B(), SRP_Calc_client_key(), SRP_Calc_server_key(),
2108 SRP_Calc_u(), SRP_Calc_x(), SRP_check_known_gN_param(), SRP_create_verifier(),
2109 SRP_create_verifier_BN(), SRP_get_default_gN(), SRP_user_pwd_free(), SRP_user_pwd_new(),
2110 SRP_user_pwd_set0_sv(), SRP_user_pwd_set1_ids(), SRP_user_pwd_set_gN(),
2111 SRP_VBASE_add0_user(), SRP_VBASE_free(), SRP_VBASE_get1_by_user(), SRP_VBASE_init(),
2112 SRP_VBASE_new(), SRP_Verify_A_mod_N(), SRP_Verify_B_mod_N()
2114 There are no replacements for the SRP functions.
2118 SSL_CTX_set_tmp_dh_callback(), SSL_set_tmp_dh_callback(),
2119 SSL_CTX_set_tmp_dh(), SSL_set_tmp_dh()
2121 These are used to set the Diffie-Hellman (DH) parameters that are to be used by
2122 servers requiring ephemeral DH keys. Instead applications should consider using
2123 the built-in DH parameters that are available by calling L<SSL_CTX_set_dh_auto(3)>
2124 or L<SSL_set_dh_auto(3)>. If custom parameters are necessary then applications can
2125 use the alternative functions L<SSL_CTX_set0_tmp_dh_pkey(3)> and
2126 L<SSL_set0_tmp_dh_pkey(3)>. There is no direct replacement for the "callback"
2127 functions. The callback was originally useful in order to have different
2128 parameters for export and non-export ciphersuites. Export ciphersuites are no
2129 longer supported by OpenSSL. Use of the callback functions should be replaced
2130 by one of the other methods described above.
2134 SSL_CTX_set_tlsext_ticket_key_cb()
2136 Use the new L<SSL_CTX_set_tlsext_ticket_key_evp_cb(3)> function instead.
2140 WHIRLPOOL(), WHIRLPOOL_Init(), WHIRLPOOL_Update(), WHIRLPOOL_Final(),
2141 WHIRLPOOL_BitUpdate()
2143 See L</Deprecated low-level digest functions>.
2144 The Whirlpool algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
2148 X509_certificate_type()
2150 This was an undocumented function. Applications can use L<X509_get0_pubkey(3)>
2151 and L<X509_get0_signature(3)> instead.
2155 X509_http_nbio(), X509_CRL_http_nbio()
2157 Use L<X509_load_http(3)> and L<X509_CRL_load_http(3)> instead.
2161 =head2 Using the FIPS Module in applications
2163 See L<fips_module(7)> and L<OSSL_PROVIDER-FIPS(7)> for details.
2165 =head2 OpenSSL command line application changes
2167 =head3 New applications
2169 L<B<openssl kdf>|openssl-kdf(1)> uses the new L<EVP_KDF(3)> API.
2170 L<B<openssl kdf>|openssl-mac(1)> uses the new L<EVP_MAC(3)> API.
2172 =head3 Added options
2174 B<-provider_path> and B<-provider> are available to all apps and can be used
2175 multiple times to load any providers, such as the 'legacy' provider or third
2176 party providers. If used then the 'default' provider would also need to be
2177 specified if required. The B<-provider_path> must be specified before the
2178 B<-provider> option.
2180 The B<list> app has many new options. See L<openssl-list(1)> for more
2183 B<-crl_lastupdate> and B<-crl_nextupdate> used by B<openssl ca> allows
2184 explicit setting of fields in the generated CRL.
2186 =head3 Removed options
2188 Interactive mode is not longer available.
2190 The B<-crypt> option used by B<openssl passwd>.
2191 The B<-c> option used by B<openssl x509>, B<openssl dhparam>,
2192 B<openssl dsaparam>, and B<openssl ecparam>.
2194 =head3 Other Changes
2196 The output of Command line applications may have minor changes.
2197 These are primarily changes in capitalisation and white space. However, in some
2198 cases, there are additional differences.
2199 For example, the DH parameters output from B<openssl dhparam> now lists 'P',
2200 'Q', 'G' and 'pcounter' instead of 'prime', 'generator', 'subgroup order' and
2201 'counter' respectively.
2203 The B<openssl> commands that read keys, certificates, and CRLs now
2204 automatically detect the PEM or DER format of the input files so it is not
2205 necessary to explicitly specify the input format anymore. However if the
2206 input format option is used the specified format will be required.
2208 B<openssl speed> no longer uses low-level API calls.
2209 This implies some of the performance numbers might not be comparable with the
2210 previous releases due to higher overhead. This applies particularly to
2211 measuring performance on smaller data chunks.
2213 b<openssl dhparam>, B<openssl dsa>, B<openssl gendsa>, B<openssl dsaparam>,
2214 B<openssl genrsa> and B<openssl rsa> have been modified to use PKEY APIs.
2215 B<openssl genrsa> and B<openssl rsa> now write PKCS #8 keys by default.
2217 =head3 Default settings
2219 "SHA256" is now the default digest for TS query used by B<openssl ts>.
2221 =head3 Deprecated apps
2223 B<openssl rsautl> is deprecated, use B<openssl pkeyutl> instead.
2224 B<openssl dhparam>, B<openssl dsa>, B<openssl gendsa>, B<openssl dsaparam>,
2225 B<openssl genrsa>, B<openssl rsa>, B<openssl genrsa> and B<openssl rsa> are
2226 now in maintenance mode and no new features will be added to them.
2234 TLS 1.3 FFDHE key exchange support added
2236 This uses DH safe prime named groups.
2240 Support for fully "pluggable" TLSv1.3 groups.
2242 This means that providers may supply their own group implementations (using
2243 either the "key exchange" or the "key encapsulation" methods) which will
2244 automatically be detected and used by libssl.
2248 SSL and SSL_CTX options are now 64 bit instead of 32 bit.
2250 The signatures of the functions to get and set options on SSL and
2251 SSL_CTX objects changed from "unsigned long" to "uint64_t" type.
2253 This may require source code changes. For example it is no longer possible
2254 to use the B<SSL_OP_> macro values in preprocessor C<#if> conditions.
2255 However it is still possible to test whether these macros are defined or not.
2257 See L<SSL_CTX_get_options(3)>, L<SSL_CTX_set_options(3)>,
2258 L<SSL_get_options(3)> and L<SSL_set_options(3)>.
2262 SSL_set1_host() and SSL_add1_host() Changes
2264 These functions now take IP literal addresses as well as actual hostnames.
2268 Added SSL option SSL_OP_CLEANSE_PLAINTEXT
2270 If the option is set, openssl cleanses (zeroizes) plaintext bytes from
2271 internal buffers after delivering them to the application. Note,
2272 the application is still responsible for cleansing other copies
2273 (e.g.: data received by L<SSL_read(3)>).
2277 Client-initiated renegotiation is disabled by default.
2279 To allow it, use the B<-client_renegotiation> option,
2280 the B<SSL_OP_ALLOW_CLIENT_RENEGOTIATION> flag, or the C<ClientRenegotiation>
2281 config parameter as appropriate.
2285 Secure renegotiation is now required by default for TLS connections
2287 Support for RFC 5746 secure renegotiation is now required by default for
2288 SSL or TLS connections to succeed. Applications that require the ability
2289 to connect to legacy peers will need to explicitly set
2290 SSL_OP_LEGACY_SERVER_CONNECT. Accordingly, SSL_OP_LEGACY_SERVER_CONNECT
2291 is no longer set as part of SSL_OP_ALL.
2295 Combining the Configure options no-ec and no-dh no longer disables TLSv1.3
2297 Typically if OpenSSL has no EC or DH algorithms then it cannot support
2298 connections with TLSv1.3. However OpenSSL now supports "pluggable" groups
2299 through providers. Therefore third party providers may supply group
2300 implementations even where there are no built-in ones. Attempting to create
2301 TLS connections in such a build without also disabling TLSv1.3 at run time or
2302 using third party provider groups may result in handshake failures. TLSv1.3
2303 can be disabled at compile time using the "no-tls1_3" Configure option.
2307 SSL_CTX_set_ciphersuites() and SSL_set_ciphersuites() changes.
2309 The methods now ignore unknown ciphers.
2313 Security callback change.
2315 The security callback, which can be customised by application code, supports
2316 the security operation SSL_SECOP_TMP_DH. This is defined to take an EVP_PKEY
2317 in the "other" parameter. In most places this is what is passed. All these
2318 places occur server side. However there was one client side call of this
2319 security operation and it passed a DH object instead. This is incorrect
2320 according to the definition of SSL_SECOP_TMP_DH, and is inconsistent with all
2321 of the other locations. Therefore this client side call has been changed to
2322 pass an EVP_PKEY instead.
2326 New SSL option SSL_OP_IGNORE_UNEXPECTED_EOF
2328 The SSL option SSL_OP_IGNORE_UNEXPECTED_EOF is introduced. If that option
2329 is set, an unexpected EOF is ignored, it pretends a close notify was received
2330 instead and so the returned error becomes SSL_ERROR_ZERO_RETURN.
2334 The security strength of SHA1 and MD5 based signatures in TLS has been reduced.
2336 This results in SSL 3, TLS 1.0, TLS 1.1 and DTLS 1.0 no longer
2337 working at the default security level of 1 and instead requires security
2338 level 0. The security level can be changed either using the cipher string
2339 with C<@SECLEVEL>, or calling L<SSL_CTX_set_security_level(3)>. This also means
2340 that where the signature algorithms extension is missing from a ClientHello
2341 then the handshake will fail in TLS 1.2 at security level 1. This is because,
2342 although this extension is optional, failing to provide one means that
2343 OpenSSL will fallback to a default set of signature algorithms. This default
2344 set requires the availability of SHA1.
2348 X509 certificates signed using SHA1 are no longer allowed at security level 1 and above.
2350 In TLS/SSL the default security level is 1. It can be set either using the cipher
2351 string with C<@SECLEVEL>, or calling L<SSL_CTX_set_security_level(3)>. If the
2352 leaf certificate is signed with SHA-1, a call to L<SSL_CTX_use_certificate(3)>
2353 will fail if the security level is not lowered first.
2354 Outside TLS/SSL, the default security level is -1 (effectively 0). It can
2355 be set using L<X509_VERIFY_PARAM_set_auth_level(3)> or using the B<-auth_level>
2356 options of the commands.
2366 Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
2368 Licensed under the Apache License 2.0 (the "License"). You may not use
2369 this file except in compliance with the License. You can obtain a copy
2370 in the file LICENSE in the source distribution or at
2371 L<https://www.openssl.org/source/license.html>.