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 Support of legacy engines
126 If openssl is not built without engine support or deprecated API support, engines
127 will still work. However, their applicability will be limited.
129 New algorithms provided via engines will still work.
131 Engine-backed keys can be loaded via custom B<OSSL_STORE> implementation.
132 In this case the B<EVP_PKEY> objects created via L<ENGINE_load_private_key(3)>
133 will be considered legacy and will continue to work.
135 To ensure the future compatibility, the engines should be turned to providers.
136 To prefer the provider-based hardware offload, you can specify the default
137 properties to prefer your provider.
139 =head3 Versioning Scheme
141 The OpenSSL versioning scheme has changed with the OpenSSL 3.0 release. The new
142 versioning scheme has this format:
146 For OpenSSL 1.1.1 and below, different patch levels were indicated by a letter
147 at the end of the release version number. This will no longer be used and
148 instead the patch level is indicated by the final number in the version. A
149 change in the second (MINOR) number indicates that new features may have been
150 added. OpenSSL versions with the same major number are API and ABI compatible.
151 If the major number changes then API and ABI compatibility is not guaranteed.
153 For more information, see L<OpenSSL_version(3)>.
155 =head3 Other major new features
157 =head4 Certificate Management Protocol (CMP, RFC 4210)
159 This also covers CRMF (RFC 4211) and HTTP transfer (RFC 6712)
160 See L<openssl-cmp(1)> and L<OSSL_CMP_exec_certreq(3)> as starting points.
162 =head4 HTTP(S) client
164 A proper HTTP(S) client that supports GET and POST, redirection, plain and
165 ASN.1-encoded contents, proxies, and timeouts.
167 =head4 Key Derivation Function API (EVP_KDF)
169 This simplifies the process of adding new KDF and PRF implementations.
171 Previously KDF algorithms had been shoe-horned into using the EVP_PKEY object
172 which was not a logical mapping.
173 Existing applications that use KDF algorithms using EVP_PKEY
174 (scrypt, TLS1 PRF and HKDF) may be slower as they use an EVP_KDF bridge
176 All new applications should use the new L<EVP_KDF(3)> interface.
177 See also L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)> and
178 L<OSSL_PROVIDER-FIPS(7)/Key Derivation Function (KDF)>.
180 =head4 Message Authentication Code API (EVP_MAC)
182 This simplifies the process of adding MAC implementations.
184 This includes a generic EVP_PKEY to EVP_MAC bridge, to facilitate the continued
185 use of MACs through raw private keys in functionality such as
186 L<EVP_DigestSign(3)> and L<EVP_DigestVerify(3)>.
188 All new applications should use the new L<EVP_MAC(3)> interface.
189 See also L<OSSL_PROVIDER-default(7)/Message Authentication Code (MAC)>
190 and L<OSSL_PROVIDER-FIPS(7)/Message Authentication Code (MAC)>.
192 =head4 Support for Linux Kernel TLS
194 In order to use KTLS, support for it must be compiled in using the
195 C<enable-ktls> configuration option. It must also be enabled at run time using
196 the B<SSL_OP_ENABLE_KTLS> option.
198 =head4 New Algorithms
204 KDF algorithms "SINGLE STEP" and "SSH"
206 See L<EVP_KDF-SS(7)> and L<EVP_KDF-SSHKDF(7)>
210 MAC Algorithms "GMAC" and "KMAC"
212 See L<EVP_MAC-GMAC(7)> and L<EVP_MAC-KMAC(7)>.
216 KEM Algorithm "RSASVE"
218 See L<EVP_KEM-RSA(7)>.
222 Cipher Algorithm "AES-SIV"
224 See L<EVP_EncryptInit(3)/SIV Mode>.
228 AES Key Wrap inverse ciphers supported by EVP layer.
230 The inverse ciphers use AES decryption for wrapping, and AES encryption for
231 unwrapping. The algorithms are: "AES-128-WRAP-INV", "AES-192-WRAP-INV",
232 "AES-256-WRAP-INV", "AES-128-WRAP-PAD-INV", "AES-192-WRAP-PAD-INV" and
233 "AES-256-WRAP-PAD-INV".
237 CTS ciphers added to EVP layer.
239 The algorithms are "AES-128-CBC-CTS", "AES-192-CBC-CTS", "AES-256-CBC-CTS",
240 "CAMELLIA-128-CBC-CTS", "CAMELLIA-192-CBC-CTS" and "CAMELLIA-256-CBC-CTS".
241 CS1, CS2 and CS3 variants are supported.
245 =head4 CMS and PKCS#7 updates
251 Added CAdES-BES signature verification support.
255 Added CAdES-BES signature scheme and attributes support (RFC 5126) to CMS API.
259 Added AuthEnvelopedData content type structure (RFC 5083) using AES_GCM
261 This uses the AES-GCM parameter (RFC 5084) for the Cryptographic Message Syntax.
262 Its purpose is to support encryption and decryption of a digital envelope that
263 is both authenticated and encrypted using AES GCM mode.
267 L<PKCS7_get_octet_string(3)> and L<PKCS7_type_is_other(3)> were made public.
271 =head4 PKCS#12 API updates
273 The default algorithms for pkcs12 creation with the PKCS12_create() function
274 were changed to more modern PBKDF2 and AES based algorithms. The default
275 MAC iteration count was changed to PKCS12_DEFAULT_ITER to make it equal
276 with the password-based encryption iteration count. The default digest
277 algorithm for the MAC computation was changed to SHA-256. The pkcs12
278 application now supports -legacy option that restores the previous
279 default algorithms to support interoperability with legacy systems.
281 Added enhanced PKCS#12 APIs which accept a library context B<OSSL_LIB_CTX>
282 and (where relevant) a property query. Other APIs which handle PKCS#7 and
283 PKCS#8 objects have also been enhanced where required. This includes:
285 L<PKCS12_add_key_ex(3)>, L<PKCS12_add_safe_ex(3)>, L<PKCS12_add_safes_ex(3)>,
286 L<PKCS12_create_ex(3)>, L<PKCS12_decrypt_skey_ex(3)>, L<PKCS12_init_ex(3)>,
287 L<PKCS12_item_decrypt_d2i_ex(3)>, L<PKCS12_item_i2d_encrypt_ex(3)>,
288 L<PKCS12_key_gen_asc_ex(3)>, L<PKCS12_key_gen_uni_ex(3)>, L<PKCS12_key_gen_utf8_ex(3)>,
289 L<PKCS12_pack_p7encdata_ex(3)>, L<PKCS12_pbe_crypt_ex(3)>, L<PKCS12_PBE_keyivgen_ex(3)>,
290 L<PKCS12_SAFEBAG_create_pkcs8_encrypt_ex(3)>, L<PKCS5_pbe2_set_iv_ex(3)>,
291 L<PKCS5_pbe_set0_algor_ex(3)>, L<PKCS5_pbe_set_ex(3)>, L<PKCS5_pbkdf2_set_ex(3)>,
292 L<PKCS5_v2_PBE_keyivgen_ex(3)>, L<PKCS5_v2_scrypt_keyivgen_ex(3)>,
293 L<PKCS8_decrypt_ex(3)>, L<PKCS8_encrypt_ex(3)>, L<PKCS8_set0_pbe_ex(3)>.
295 As part of this change the EVP_PBE_xxx APIs can also accept a library
296 context and property query and will call an extended version of the key/IV
297 derivation function which supports these parameters. This includes
298 L<EVP_PBE_CipherInit_ex(3)>, L<EVP_PBE_find_ex(3)> and L<EVP_PBE_scrypt_ex(3)>.
300 =head4 Windows thread synchronization changes
302 Windows thread synchronization uses read/write primitives (SRWLock) when
303 supported by the OS, otherwise CriticalSection continues to be used.
307 A new generic trace API has been added which provides support for enabling
308 instrumentation through trace output. This feature is mainly intended as an aid
309 for developers and is disabled by default. To utilize it, OpenSSL needs to be
310 configured with the C<enable-trace> option.
312 If the tracing API is enabled, the application can activate trace output by
313 registering BIOs as trace channels for a number of tracing and debugging
314 categories. See L<OSSL_trace_enabled(3)>.
316 =head4 Key validation updates
318 L<EVP_PKEY_public_check(3)> and L<EVP_PKEY_param_check(3)> now work for
319 more key types. This includes RSA, DSA, ED25519, X25519, ED448 and X448.
320 Previously (in 1.1.1) they would return -2. For key types that do not have
321 parameters then L<EVP_PKEY_param_check(3)> will always return 1.
323 =head3 Other notable deprecations and changes
325 =head4 The function code part of an OpenSSL error code is no longer relevant
327 This code is now always set to zero. Related functions are deprecated.
329 =head4 STACK and HASH macros have been cleaned up
331 The type-safe wrappers are declared everywhere and implemented once.
332 See L<DEFINE_STACK_OF(3)> and L<DEFINE_LHASH_OF_EX(3)>.
334 =head4 The RAND_DRBG subsystem has been removed
336 The new L<EVP_RAND(3)> is a partial replacement: the DRBG callback framework is
337 absent. The RAND_DRBG API did not fit well into the new provider concept as
338 implemented by EVP_RAND and EVP_RAND_CTX.
340 =head4 Removed FIPS_mode() and FIPS_mode_set()
342 These functions are legacy APIs that are not applicable to the new provider
343 model. Applications should instead use
344 L<EVP_default_properties_is_fips_enabled(3)> and
345 L<EVP_default_properties_enable_fips(3)>.
347 =head4 Key generation is slower
349 The Miller-Rabin test now uses 64 rounds, which is used for all prime generation,
350 including RSA key generation. This affects the time for larger keys sizes.
352 The default key generation method for the regular 2-prime RSA keys was changed
353 to the FIPS186-4 B.3.6 method (Generation of Probable Primes with Conditions
354 Based on Auxiliary Probable Primes). This method is slower than the original
357 =head4 Change PBKDF2 to conform to SP800-132 instead of the older PKCS5 RFC2898
359 This checks that the salt length is at least 128 bits, the derived key length is
360 at least 112 bits, and that the iteration count is at least 1000.
361 For backwards compatibility these checks are disabled by default in the
362 default provider, but are enabled by default in the FIPS provider.
364 To enable or disable the checks see B<OSSL_KDF_PARAM_PKCS5> in
365 L<EVP_KDF-PBKDF2(7)>. The parameter can be set using L<EVP_KDF_derive(3)>.
367 =head4 Enforce a minimum DH modulus size of 512 bits
369 Smaller sizes now result in an error.
371 =head4 SM2 key changes
373 EC EVP_PKEYs with the SM2 curve have been reworked to automatically become
374 EVP_PKEY_SM2 rather than EVP_PKEY_EC.
376 Unlike in previous OpenSSL versions, this means that applications cannot
377 call C<EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2)> to get SM2 computations.
379 Parameter and key generation is also reworked to make it possible
380 to generate EVP_PKEY_SM2 parameters and keys. Applications must now generate
381 SM2 keys directly and must not create an EVP_PKEY_EC key first. It is no longer
382 possible to import an SM2 key with domain parameters other than the SM2 elliptic
385 Validation of SM2 keys has been separated from the validation of regular EC
386 keys, allowing to improve the SM2 validation process to reject loaded private
387 keys that are not conforming to the SM2 ISO standard.
388 In particular, a private scalar I<k> outside the range I<< 1 <= k < n-1 >> is
389 now correctly rejected.
391 =head4 EVP_PKEY_set_alias_type() method has been removed
393 This function made a B<EVP_PKEY> object mutable after it had been set up. In
394 OpenSSL 3.0 it was decided that a provided key should not be able to change its
395 type, so this function has been removed.
397 =head4 Functions that return an internal key should be treated as read only
399 Functions such as L<EVP_PKEY_get0_RSA(3)> behave slightly differently in
400 OpenSSL 3.0. Previously they returned a pointer to the low-level key used
401 internally by libcrypto. From OpenSSL 3.0 this key may now be held in a
402 provider. Calling these functions will only return a handle on the internal key
403 where the EVP_PKEY was constructed using this key in the first place, for
404 example using a function or macro such as L<EVP_PKEY_assign_RSA(3)>,
405 L<EVP_PKEY_set1_RSA(3)>, etc.
406 Where the EVP_PKEY holds a provider managed key, then these functions now return
407 a cached copy of the key. Changes to the internal provider key that take place
408 after the first time the cached key is accessed will not be reflected back in
409 the cached copy. Similarly any changes made to the cached copy by application
410 code will not be reflected back in the internal provider key.
412 For the above reasons the keys returned from these functions should typically be
413 treated as read-only. To emphasise this the value returned from
414 L<EVP_PKEY_get0_RSA(3)>, L<EVP_PKEY_get0_DSA(3)>, L<EVP_PKEY_get0_EC_KEY(3)> and
415 L<EVP_PKEY_get0_DH(3)> have been made const. This may break some existing code.
416 Applications broken by this change should be modified. The preferred solution is
417 to refactor the code to avoid the use of these deprecated functions. Failing
418 this the code should be modified to use a const pointer instead.
419 The L<EVP_PKEY_get1_RSA(3)>, L<EVP_PKEY_get1_DSA(3)>, L<EVP_PKEY_get1_EC_KEY(3)>
420 and L<EVP_PKEY_get1_DH(3)> functions continue to return a non-const pointer to
421 enable them to be "freed". However they should also be treated as read-only.
423 =head4 The public key check has moved from EVP_PKEY_derive() to EVP_PKEY_derive_set_peer()
425 This may mean result in an error in L<EVP_PKEY_derive_set_peer(3)> rather than
426 during L<EVP_PKEY_derive(3)>.
427 To disable this check use EVP_PKEY_derive_set_peer_ex(dh, peer, 0).
429 =head4 The print format has cosmetic changes for some functions
431 The output from numerous "printing" functions such as L<X509_signature_print(3)>,
432 L<X509_print_ex(3)>, L<X509_CRL_print_ex(3)>, and other similar functions has been
433 amended such that there may be cosmetic differences between the output
434 observed in 1.1.1 and 3.0. This also applies to the B<-text> output from the
435 B<openssl x509> and B<openssl crl> applications.
437 =head4 Interactive mode from the B<openssl> program has been removed
439 From now on, running it without arguments is equivalent to B<openssl help>.
441 =head4 The error return values from some control calls (ctrl) have changed
443 One significant change is that controls which used to return -2 for
444 invalid inputs, now return -1 indicating a generic error condition instead.
446 =head4 DH and DHX key types have different settable parameters
448 Previously (in 1.1.1) these conflicting parameters were allowed, but will now
449 result in errors. See L<EVP_PKEY-DH(7)> for further details. This affects the
450 behaviour of L<openssl-genpkey(1)> for DH parameter generation.
452 =head4 EVP_CIPHER_CTX_set_flags() ordering change
454 If using a cipher from a provider the B<EVP_CIPH_FLAG_LENGTH_BITS> flag can only
455 be set B<after> the cipher has been assigned to the cipher context.
456 See L<EVP_EncryptInit(3)/FLAGS> for more information.
458 =head4 Validation of operation context parameters
460 Due to move of the implementation of cryptographic operations to the
461 providers, validation of various operation parameters can be postponed until
462 the actual operation is executed where previously it happened immediately
463 when an operation parameter was set.
465 For example when setting an unsupported curve with
466 EVP_PKEY_CTX_set_ec_paramgen_curve_nid() this function call will not fail
467 but later keygen operations with the EVP_PKEY_CTX will fail.
469 =head4 Removal of function code from the error codes
471 The function code part of the error code is now always set to 0. For that
472 reason the ERR_GET_FUNC() macro was removed. Applications must resolve
473 the error codes only using the library number and the reason code.
475 =head2 Installation and Compilation
477 Please refer to the INSTALL.md file in the top of the distribution for
478 instructions on how to build and install OpenSSL 3.0. Please also refer to the
479 various platform specific NOTES files for your specific platform.
481 =head2 Upgrading from OpenSSL 1.1.1
483 Upgrading to OpenSSL 3.0 from OpenSSL 1.1.1 should be relatively straight
484 forward in most cases. The most likely area where you will encounter problems
485 is if you have used low level APIs in your code (as discussed above). In that
486 case you are likely to start seeing deprecation warnings when compiling your
487 application. If this happens you have 3 options:
493 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.
497 Suppress the warnings. Refer to your compiler documentation on how to do this.
501 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
505 =head3 Error code changes
507 As OpenSSL 3.0 provides a brand new Encoder/Decoder mechanism for working with
508 widely used file formats, application code that checks for particular error
509 reason codes on key loading failures might need an update.
511 Password-protected keys may deserve special attention. If only some errors
512 are treated as an indicator that the user should be asked about the password again,
513 it's worth testing these scenarios and processing the newly relevant codes.
515 There may be more cases to treat specially, depending on the calling application code.
517 =head2 Upgrading from OpenSSL 1.0.2
519 Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 is likely to be significantly more
520 difficult. In addition to the issues discussed above in the section about
521 L</Upgrading from OpenSSL 1.1.1>, the main things to be aware of are:
527 The build and installation procedure has changed significantly.
529 Check the file INSTALL.md in the top of the installation for instructions on how
530 to build and install OpenSSL for your platform. Also read the various NOTES
531 files in the same directory, as applicable for your platform.
535 Many structures have been made opaque in OpenSSL 3.0.
537 The structure definitions have been removed from the public header files and
538 moved to internal header files. In practice this means that you can no longer
539 stack allocate some structures. Instead they must be heap allocated through some
540 function call (typically those function names have a C<_new> suffix to them).
541 Additionally you must use "setter" or "getter" functions to access the fields
542 within those structures.
544 For example code that previously looked like this:
548 /* This line will now generate compiler errors */
549 EVP_MD_CTX_init(&md_ctx);
551 The code needs to be amended to look like this:
555 md_ctx = EVP_MD_CTX_new();
558 EVP_MD_CTX_free(md_ctx);
562 Support for TLSv1.3 has been added.
564 This has a number of implications for SSL/TLS applications. See the
565 L<TLS1.3 page|https://wiki.openssl.org/index.php/TLS1.3> for further details.
569 More details about the breaking changes between OpenSSL versions 1.0.2 and 1.1.0
571 L<OpenSSL 1.1.0 Changes page|https://wiki.openssl.org/index.php/OpenSSL_1.1.0_Changes>.
573 =head3 Upgrading from the OpenSSL 2.0 FIPS Object Module
575 The OpenSSL 2.0 FIPS Object Module was a separate download that had to be built
576 separately and then integrated into your main OpenSSL 1.0.2 build.
577 In OpenSSL 3.0 the FIPS support is fully integrated into the mainline version of
578 OpenSSL and is no longer a separate download. For further information see
579 L</Completing the installation of the FIPS Module>.
581 The function calls FIPS_mode() and FIPS_mode_set() have been removed
582 from OpenSSL 3.0. You should rewrite your application to not use them.
583 See L<fips_module(7)> and L<OSSL_PROVIDER-FIPS(7)> for details.
585 =head2 Completing the installation of the FIPS Module
587 The FIPS Module will be built and installed automatically if FIPS support has
588 been configured. The current documentation can be found in the
589 L<README-FIPS|https://github.com/openssl/openssl/blob/master/README-FIPS.md> file.
593 Applications written to work with OpenSSL 1.1.1 will mostly just work with
594 OpenSSL 3.0. However changes will be required if you want to take advantage of
595 some of the new features that OpenSSL 3.0 makes available. In order to do that
596 you need to understand some new concepts introduced in OpenSSL 3.0.
597 Read L<crypto(7)/Library contexts> for further information.
599 =head3 Library Context
601 A library context allows different components of a complex application to each
602 use a different library context and have different providers loaded with
603 different configuration settings.
604 See L<crypto(7)/Library contexts> for further info.
606 If the user creates an B<OSSL_LIB_CTX> via L<OSSL_LIB_CTX_new(3)> then many
607 functions may need to be changed to pass additional parameters to handle the
610 =head4 Using a Library Context - Old functions that should be changed
612 If a library context is needed then all EVP_* digest functions that return a
613 B<const EVP_MD *> such as EVP_sha256() should be replaced with a call to
614 L<EVP_MD_fetch(3)>. See L<crypto(7)/ALGORITHM FETCHING>.
616 If a library context is needed then all EVP_* cipher functions that return a
617 B<const EVP_CIPHER *> such as EVP_aes_128_cbc() should be replaced vith a call to
618 L<EVP_CIPHER_fetch(3)>. See L<crypto(7)/ALGORITHM FETCHING>.
620 Some functions can be passed an object that has already been set up with a library
621 context such as L<d2i_X509(3)>, L<d2i_X509_CRL(3)>, L<d2i_X509_REQ(3)> and
622 L<d2i_X509_PUBKEY(3)>. If NULL is passed instead then the created object will be
623 set up with the default library context. Use L<X509_new_ex(3)>,
624 L<X509_CRL_new_ex(3)>, L<X509_REQ_new_ex(3)> and L<X509_PUBKEY_new_ex(3)> if a
625 library context is required.
627 All functions listed below with a I<NAME> have a replacement function I<NAME_ex>
628 that takes B<OSSL_LIB_CTX> as an additional argument. Functions that have other
629 mappings are listed along with the respective name.
635 L<ASN1_item_new(3)>, L<ASN1_item_d2i(3)>, L<ASN1_item_d2i_fp(3)>,
636 L<ASN1_item_d2i_bio(3)>, L<ASN1_item_sign(3)> and L<ASN1_item_verify(3)>
644 b2i_RSA_PVK_bio() and i2b_PVK_bio()
648 L<BN_CTX_new(3)> and L<BN_CTX_secure_new(3)>
652 L<CMS_AuthEnvelopedData_create(3)>, L<CMS_ContentInfo_new(3)>, L<CMS_data_create(3)>,
653 L<CMS_digest_create(3)>, L<CMS_EncryptedData_encrypt(3)>, L<CMS_encrypt(3)>,
654 L<CMS_EnvelopedData_create(3)>, L<CMS_ReceiptRequest_create0(3)> and L<CMS_sign(3)>
658 L<CONF_modules_load_file(3)>
662 L<CTLOG_new(3)>, L<CTLOG_new_from_base64(3)> and L<CTLOG_STORE_new(3)>
666 L<CT_POLICY_EVAL_CTX_new(3)>
670 L<d2i_AutoPrivateKey(3)>, L<d2i_PrivateKey(3)> and L<d2i_PUBKEY(3)>
674 L<d2i_PrivateKey_bio(3)> and L<d2i_PrivateKey_fp(3)>
676 Use L<d2i_PrivateKey_ex_bio(3)> and L<d2i_PrivateKey_ex_fp(3)>
682 Use L<EC_GROUP_new_by_curve_name_ex(3)> or L<EC_GROUP_new_from_params(3)>.
686 L<EVP_DigestSignInit(3)> and L<EVP_DigestVerifyInit(3)>
690 L<EVP_PBE_CipherInit(3)>, L<EVP_PBE_find(3)> and L<EVP_PBE_scrypt(3)>
694 L<PKCS5_PBE_keyivgen(3)>
702 L<EVP_PKEY_CTX_new_id(3)>
704 Use L<EVP_PKEY_CTX_new_from_name(3)>
708 L<EVP_PKEY_derive_set_peer(3)>, L<EVP_PKEY_new_raw_private_key(3)>
709 and L<EVP_PKEY_new_raw_public_key(3)>
713 L<EVP_SignFinal(3)> and L<EVP_VerifyFinal(3)>
721 L<OCSP_RESPID_match(3)> and L<OCSP_RESPID_set_by_key(3)>
725 L<OPENSSL_thread_stop(3)>
729 L<OSSL_STORE_open(3)>
733 L<PEM_read_bio_Parameters(3)>, L<PEM_read_bio_PrivateKey(3)>, L<PEM_read_bio_PUBKEY(3)>,
734 L<PEM_read_PrivateKey(3)> and L<PEM_read_PUBKEY(3)>
738 L<PEM_write_bio_PrivateKey(3)>, L<PEM_write_bio_PUBKEY(3)>, L<PEM_write_PrivateKey(3)>
739 and L<PEM_write_PUBKEY(3)>
743 L<PEM_X509_INFO_read_bio(3)> and L<PEM_X509_INFO_read(3)>
747 L<PKCS12_add_key(3)>, L<PKCS12_add_safe(3)>, L<PKCS12_add_safes(3)>,
748 L<PKCS12_create(3)>, L<PKCS12_decrypt_skey(3)>, L<PKCS12_init(3)>, L<PKCS12_item_decrypt_d2i(3)>,
749 L<PKCS12_item_i2d_encrypt(3)>, L<PKCS12_key_gen_asc(3)>, L<PKCS12_key_gen_uni(3)>,
750 L<PKCS12_key_gen_utf8(3)>, L<PKCS12_pack_p7encdata(3)>, L<PKCS12_pbe_crypt(3)>,
751 L<PKCS12_PBE_keyivgen(3)>, L<PKCS12_SAFEBAG_create_pkcs8_encrypt(3)>
755 L<PKCS5_pbe_set0_algor(3)>, L<PKCS5_pbe_set(3)>, L<PKCS5_pbe2_set_iv(3)>,
756 L<PKCS5_pbkdf2_set(3)> and L<PKCS5_v2_scrypt_keyivgen(3)>
760 L<PKCS7_encrypt(3)>, L<PKCS7_new(3)> and L<PKCS7_sign(3)>
764 L<PKCS8_decrypt(3)>, L<PKCS8_encrypt(3)> and L<PKCS8_set0_pbe(3)>
768 L<RAND_bytes(3)> and L<RAND_priv_bytes(3)>
772 L<SMIME_write_ASN1(3)>
776 L<SSL_load_client_CA_file(3)>
784 L<TS_RESP_CTX_new(3)>
792 L<X509_load_cert_crl_file(3)> and L<X509_load_cert_file(3)>
796 L<X509_LOOKUP_by_subject(3)> and L<X509_LOOKUP_ctrl(3)>
808 L<X509_REQ_new(3)> and L<X509_REQ_verify(3)>
812 L<X509_STORE_CTX_new(3)>, L<X509_STORE_set_default_paths(3)>, L<X509_STORE_load_file(3)>,
813 L<X509_STORE_load_locations(3)> and L<X509_STORE_load_store(3)>
817 =head4 New functions that use a Library context
819 The following functions can be passed a library context if required.
820 Passing NULL will use the default library context.
826 L<BIO_new_from_core_bio(3)>
830 L<EVP_ASYM_CIPHER_fetch(3)> and L<EVP_ASYM_CIPHER_do_all_provided(3)>
834 L<EVP_CIPHER_fetch(3)> and L<EVP_CIPHER_do_all_provided(3)>
838 L<EVP_default_properties_enable_fips(3)> and
839 L<EVP_default_properties_is_fips_enabled(3)>
843 L<EVP_KDF_fetch(3)> and L<EVP_KDF_do_all_provided(3)>
847 L<EVP_KEM_fetch(3)> and L<EVP_KEM_do_all_provided(3)>
851 L<EVP_KEYEXCH_fetch(3)> and L<EVP_KEYEXCH_do_all_provided(3)>
855 L<EVP_KEYMGMT_fetch(3)> and L<EVP_KEYMGMT_do_all_provided(3)>
859 L<EVP_MAC_fetch(3)> and L<EVP_MAC_do_all_provided(3)>
863 L<EVP_MD_fetch(3)> and L<EVP_MD_do_all_provided(3)>
867 L<EVP_PKEY_CTX_new_from_pkey(3)>
871 L<EVP_PKEY_Q_keygen(3)>
875 L<EVP_Q_mac(3)> and L<EVP_Q_digest(3)>
879 L<EVP_RAND(3)> and L<EVP_RAND_do_all_provided(3)>
883 L<EVP_set_default_properties(3)>
887 L<EVP_SIGNATURE_fetch(3)> and L<EVP_SIGNATURE_do_all_provided(3)>
891 L<OSSL_CMP_CTX_new(3)> and L<OSSL_CMP_SRV_CTX_new(3)>
895 L<OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert(3)>
899 L<OSSL_CRMF_MSG_create_popo(3)> and L<OSSL_CRMF_MSGS_verify_popo(3)>
903 L<OSSL_CRMF_pbm_new(3)> and L<OSSL_CRMF_pbmp_new(3)>
907 L<OSSL_DECODER_CTX_add_extra(3)> and L<OSSL_DECODER_CTX_new_for_pkey(3)>
911 L<OSSL_DECODER_fetch(3)> and L<OSSL_DECODER_do_all_provided(3)>
915 L<OSSL_ENCODER_CTX_add_extra(3)>
919 L<OSSL_ENCODER_fetch(3)> and L<OSSL_ENCODER_do_all_provided(3)>
923 L<OSSL_LIB_CTX_free(3)>, L<OSSL_LIB_CTX_load_config(3)> and L<OSSL_LIB_CTX_set0_default(3)>
927 L<OSSL_PROVIDER_add_builtin(3)>, L<OSSL_PROVIDER_available(3)>,
928 L<OSSL_PROVIDER_do_all(3)>, L<OSSL_PROVIDER_load(3)>,
929 L<OSSL_PROVIDER_set_default_search_path(3)> and L<OSSL_PROVIDER_try_load(3)>
933 L<OSSL_SELF_TEST_get_callback(3)> and L<OSSL_SELF_TEST_set_callback(3)>
937 L<OSSL_STORE_attach(3)>
941 L<OSSL_STORE_LOADER_fetch(3)> and L<OSSL_STORE_LOADER_do_all_provided(3)>
945 L<RAND_get0_primary(3)>, L<RAND_get0_private(3)>, L<RAND_get0_public(3)>,
946 L<RAND_set_DRBG_type(3)> and L<RAND_set_seed_source_type(3)>
952 Providers are described in detail here L<crypto(7)/Providers>.
953 See also L<crypto(7)/OPENSSL PROVIDERS>.
955 =head3 Fetching algorithms and property queries
957 Implicit and Explicit Fetching is described in detail here
958 L<crypto(7)/ALGORITHM FETCHING>.
960 =head3 Mapping EVP controls and flags to provider B<OSSL_PARAM> parameters
962 The existing functions for controls (such as L<EVP_CIPHER_CTX_ctrl(3)>) and
963 manipulating flags (such as L<EVP_MD_CTX_set_flags(3)>)internally use
964 B<OSSL_PARAMS> to pass information to/from provider objects.
965 See L<OSSL_PARAM(3)> for additional information related to parameters.
967 For ciphers see L<EVP_EncryptInit(3)/CONTROLS>, L<EVP_EncryptInit(3)/FLAGS> and
968 L<EVP_EncryptInit(3)/PARAMETERS>.
970 For digests see L<EVP_DigestInit(3)/CONTROLS>, L<EVP_DigestInit(3)/FLAGS> and
971 L<EVP_DigestInit(3)/PARAMETERS>.
973 =head3 Deprecation of Low Level Functions
975 A significant number of APIs have been deprecated in OpenSSL 3.0.
976 This section describes some common categories of deprecations.
977 See L</Deprecated function mappings> for the list of deprecated functions
978 that refer to these categories.
980 =head4 Providers are a replacement for engines and low-level method overrides
982 Any accessor that uses an ENGINE is deprecated (such as EVP_PKEY_set1_engine()).
983 Applications using engines should instead use providers.
985 Before providers were added algorithms were overridden by changing the methods
986 used by algorithms. All these methods such as RSA_new_method() and RSA_meth_new()
987 are now deprecated and can be replaced by using providers instead.
989 =head4 Deprecated i2d and d2i functions for low-level key types
991 Any i2d and d2i functions such as d2i_DHparams() that take a low-level key type
992 have been deprecated. Applications should instead use the L<OSSL_DECODER(3)> and
993 L<OSSL_ENCODER(3)> APIs to read and write files.
994 See L<d2i_RSAPrivateKey(3)/Migration> for further details.
996 =head4 Deprecated low-level key object getters and setters
998 Applications that set or get low-level key objects (such as EVP_PKEY_set1_DH()
999 or EVP_PKEY_get0()) should instead use the OSSL_ENCODER
1000 (See L<OSSL_ENCODER_to_bio(3)>) or OSSL_DECODER (See L<OSSL_DECODER_from_bio(3)>)
1001 APIs, or alternatively use L<EVP_PKEY_fromdata(3)> or L<EVP_PKEY_todata(3)>.
1003 =head4 Deprecated low-level key parameter getters
1005 Functions that access low-level objects directly such as L<RSA_get0_n(3)> are now
1006 deprecated. Applications should use one of L<EVP_PKEY_get_bn_param(3)>,
1007 L<EVP_PKEY_get_int_param(3)>, l<EVP_PKEY_get_size_t_param(3)>,
1008 L<EVP_PKEY_get_utf8_string_param(3)>, L<EVP_PKEY_get_octet_string_param(3)> or
1009 L<EVP_PKEY_get_params(3)> to access fields from an EVP_PKEY.
1010 Gettable parameters are listed in L<EVP_PKEY-RSA(7)/Common RSA parameters>,
1011 L<EVP_PKEY-DH(7)/DH parameters>, L<EVP_PKEY-DSA(7)/DSA parameters>,
1012 L<EVP_PKEY-FFC(7)/FFC parameters>, L<EVP_PKEY-EC(7)/Common EC parameters> and
1013 L<EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>.
1014 Applications may also use L<EVP_PKEY_todata(3)> to return all fields.
1016 =head4 Deprecated low-level key parameter setters
1018 Functions that access low-level objects directly such as L<RSA_set0_crt_params(3)>
1019 are now deprecated. Applications should use L<EVP_PKEY_fromdata(3)> to create
1020 new keys from user provided key data. Keys should be immutable once they are
1021 created, so if required the user may use L<EVP_PKEY_todata(3)>, L<OSSL_PARAM_merge(3)>,
1022 and L<EVP_PKEY_fromdata(3)> to create a modified key.
1023 See L<EVP_PKEY-DH(7)/Examples> for more information.
1024 See L</Deprecated low-level key generation functions> for information on
1025 generating a key using parameters.
1027 =head4 Deprecated low-level object creation
1029 Low-level objects were created using methods such as L<RSA_new(3)>,
1030 L<RSA_up_ref(3)> and L<RSA_free(3)>. Applications should instead use the
1031 high-level EVP_PKEY APIs, e.g. L<EVP_PKEY_new(3)>, L<EVP_PKEY_up_ref(3)> and
1032 L<EVP_PKEY_free(3)>.
1033 See also L<EVP_PKEY_CTX_new_from_name(3)> and L<EVP_PKEY_CTX_new_from_pkey(3)>.
1035 EVP_PKEYs may be created in a variety of ways:
1036 See also L</Deprecated low-level key generation functions>,
1037 L</Deprecated low-level key reading and writing functions> and
1038 L</Deprecated low-level key parameter setters>.
1040 =head4 Deprecated low-level encryption functions
1042 Low-level encryption functions such as L<AES_encrypt(3)> and L<AES_decrypt(3)>
1043 have been informally discouraged from use for a long time. Applications should
1044 instead use the high level EVP APIs L<EVP_EncryptInit_ex(3)>,
1045 L<EVP_EncryptUpdate(3)>, and L<EVP_EncryptFinal_ex(3)> or
1046 L<EVP_DecryptInit_ex(3)>, L<EVP_DecryptUpdate(3)> and L<EVP_DecryptFinal_ex(3)>.
1048 =head4 Deprecated low-level digest functions
1050 Use of low-level digest functions such as L<SHA1_Init(3)> have been
1051 informally discouraged from use for a long time. Applications should instead
1052 use the the high level EVP APIs L<EVP_DigestInit_ex(3)>, L<EVP_DigestUpdate(3)>
1053 and L<EVP_DigestFinal_ex(3)>, or the quick one-shot L<EVP_Q_digest(3)>.
1055 Note that the functions L<SHA1(3)>, L<SHA224(3)>, L<SHA256(3)>, L<SHA384(3)>
1056 and L<SHA512(3)> have changed to macros that use L<EVP_Q_digest(3)>.
1058 =head4 Deprecated low-level signing functions
1060 Use of low-level signing functions such as L<DSA_sign(3)> have been
1061 informally discouraged for a long time. Instead applications should use
1062 L<EVP_DigestSign(3)> and L<EVP_DigestVerify(3)>.
1063 See also L<EVP_SIGNATURE-RSA(7)>, L<EVP_SIGNATURE-DSA(7)>,
1064 L<EVP_SIGNATURE-ECDSA(7)> and L<EVP_SIGNATURE-ED25519(7)>.
1066 =head4 Deprecated low-level MAC functions
1068 Low-level mac functions such as L<CMAC_Init(3)> are deprecated.
1069 Applications should instead use the new L<EVP_MAC(3)> interface, using
1070 L<EVP_MAC_CTX_new(3)>, L<EVP_MAC_CTX_free(3)>, L<EVP_MAC_init(3)>,
1071 L<EVP_MAC_update(3)> and L<EVP_MAC_final(3)> or the single-shot MAC function
1073 See L<EVP_MAC(3)>, L<EVP_MAC-HMAC(7)>, L<EVP_MAC-CMAC(7)>, L<EVP_MAC-GMAC(7)>,
1074 L<EVP_MAC-KMAC(7)>, L<EVP_MAC-BLAKE2(7)>, L<EVP_MAC-Poly1305(7)> and
1075 L<EVP_MAC-Siphash(7)> for additional information.
1077 Note that the one-shot method HMAC() is still available for compatibility purposes.
1079 =head4 Deprecated low-level validation functions
1081 Low-level validation functions such as L<DH_check(3)> have been informally
1082 discouraged from use for a long time. Applications should instead use the high-level
1083 EVP_PKEY APIs such as L<EVP_PKEY_check(3)>, L<EVP_PKEY_param_check(3)>,
1084 L<EVP_PKEY_param_check_quick(3)>, L<EVP_PKEY_public_check(3)>,
1085 L<EVP_PKEY_public_check_quick(3)>, L<EVP_PKEY_private_check(3)>,
1086 and L<EVP_PKEY_pairwise_check(3)>.
1088 =head4 Deprecated low-level key exchange functions
1090 Many low-level functions have been informally discouraged from use for a long
1091 time. Applications should instead use L<EVP_PKEY_derive(3)>.
1092 See L<EVP_KEYEXCH-DH(7)>, L<EVP_KEYEXCH-ECDH(7)> and L<EVP_KEYEXCH-X25519(7)>.
1094 =head4 Deprecated low-level key generation functions
1096 Many low-level functions have been informally discouraged from use for a long
1097 time. Applications should instead use L<EVP_PKEY_keygen_init(3)> and
1098 L<EVP_PKEY_generate(3)> as described in L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>,
1099 L<EVP_PKEY-RSA(7)>, L<EVP_PKEY-EC(7)> and L<EVP_PKEY-X25519(7)>.
1100 The 'quick' one-shot function L<EVP_PKEY_Q_keygen(3)> and macros for the most
1101 common cases: <EVP_RSA_gen(3)> and L<EVP_EC_gen(3)> may also be used.
1103 =head4 Deprecated low-level key reading and writing functions
1105 Use of low-level objects (such as DSA) has been informally discouraged from use
1106 for a long time. Functions to read and write these low-level objects (such as
1107 PEM_read_DSA_PUBKEY()) should be replaced. Applications should instead use
1108 L<OSSL_ENCODER_to_bio(3)> and L<OSSL_DECODER_from_bio(3)>.
1110 =head4 Deprecated low-level key printing functions
1112 Use of low-level objects (such as DSA) has been informally discouraged from use
1113 for a long time. Functions to print these low-level objects such as
1114 DSA_print() should be replaced with the equivalent EVP_PKEY functions.
1115 Application should use one of L<EVP_PKEY_print_public(3)>,
1116 L<EVP_PKEY_print_private(3)>, L<EVP_PKEY_print_params(3)>,
1117 L<EVP_PKEY_print_public_fp(3)>, L<EVP_PKEY_print_private_fp(3)> or
1118 L<EVP_PKEY_print_params_fp(3)>. Note that internally these use
1119 L<OSSL_ENCODER_to_bio(3)> and L<OSSL_DECODER_from_bio(3)>.
1121 =head3 Deprecated function mappings
1123 The following functions have been deprecated in 3.0.
1129 AES_bi_ige_encrypt() and AES_ige_encrypt()
1131 There is no replacement for the IGE functions. New code should not use these modes.
1132 These undocumented functions were never integrated into the EVP layer.
1133 They implemented the AES Infinite Garble Extension (IGE) mode and AES
1134 Bi-directional IGE mode. These modes were never formally standardised and
1135 usage of these functions is believed to be very small. In particular
1136 AES_bi_ige_encrypt() has a known bug. It accepts 2 AES keys, but only one
1137 is ever used. The security implications are believed to be minimal, but
1138 this issue was never fixed for backwards compatibility reasons.
1142 AES_encrypt(), AES_decrypt(), AES_set_encrypt_key(), AES_set_decrypt_key(),
1143 AES_cbc_encrypt(), AES_cfb128_encrypt(), AES_cfb1_encrypt(), AES_cfb8_encrypt(),
1144 AES_ecb_encrypt(), AES_ofb128_encrypt()
1148 AES_unwrap_key(), AES_wrap_key()
1150 See L</Deprecated low-level encryption functions>
1156 There is no replacement. It returned a string indicating if the AES code was unrolled.
1160 ASN1_digest(), ASN1_sign(), ASN1_verify()
1162 There are no replacements. These old functions are not used, and could be
1163 disabled with the macro NO_ASN1_OLD since OpenSSL 0.9.7.
1167 ASN1_STRING_length_set()
1169 Use L<ASN1_STRING_set(3)> or L<ASN1_STRING_set0(3)> instead.
1170 This was a potentially unsafe function that could change the bounds of a
1171 previously passed in pointer.
1175 BF_encrypt(), BF_decrypt(), BF_set_key(), BF_cbc_encrypt(), BF_cfb64_encrypt(),
1176 BF_ecb_encrypt(), BF_ofb64_encrypt()
1178 See L</Deprecated low-level encryption functions>.
1179 The Blowfish algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1185 There is no replacement. This option returned a constant string.
1189 BIO_get_callback(), BIO_set_callback(), BIO_debug_callback()
1191 Use the respective non-deprecated _ex() functions.
1195 BN_is_prime_ex(), BN_is_prime_fasttest_ex()
1197 Use L<BN_check_prime(3)> which that avoids possible misuse and always uses at least
1198 64 rounds of the Miller-Rabin primality test.
1202 BN_pseudo_rand(), BN_pseudo_rand_range()
1204 Use L<BN_rand(3)> and L<BN_rand_range(3)>.
1208 BN_X931_derive_prime_ex(), BN_X931_generate_prime_ex(), BN_X931_generate_Xpq()
1210 There are no replacements for these low-level functions. They were used internally
1211 by RSA_X931_derive_ex() and RSA_X931_generate_key_ex() which are also deprecated.
1212 Use L<EVP_PKEY_keygen(3)> instead.
1216 Camellia_encrypt(), Camellia_decrypt(), Camellia_set_key(),
1217 Camellia_cbc_encrypt(), Camellia_cfb128_encrypt(), Camellia_cfb1_encrypt(),
1218 Camellia_cfb8_encrypt(), Camellia_ctr128_encrypt(), Camellia_ecb_encrypt(),
1219 Camellia_ofb128_encrypt()
1221 See L</Deprecated low-level encryption functions>.
1225 CAST_encrypt(), CAST_decrypt(), CAST_set_key(), CAST_cbc_encrypt(),
1226 CAST_cfb64_encrypt(), CAST_ecb_encrypt(), CAST_ofb64_encrypt()
1228 See L</Deprecated low-level encryption functions>.
1229 The CAST algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1233 CMAC_CTX_new(), CMAC_CTX_cleanup(), CMAC_CTX_copy(), CMAC_CTX_free(),
1234 CMAC_CTX_get0_cipher_ctx()
1236 See L</Deprecated low-level MAC functions>.
1240 CMAC_Init(), CMAC_Update(), CMAC_Final(), CMAC_resume()
1242 See L</Deprecated low-level MAC functions>.
1246 CRYPTO_mem_ctrl(), CRYPTO_mem_debug_free(), CRYPTO_mem_debug_malloc(),
1247 CRYPTO_mem_debug_pop(), CRYPTO_mem_debug_push(), CRYPTO_mem_debug_realloc(),
1248 CRYPTO_mem_leaks(), CRYPTO_mem_leaks_cb(), CRYPTO_mem_leaks_fp(),
1249 CRYPTO_set_mem_debug()
1251 Memory-leak checking has been deprecated in favor of more modern development
1252 tools, such as compiler memory and leak sanitizers or Valgrind.
1256 CRYPTO_cts128_encrypt_block(), CRYPTO_cts128_encrypt(),
1257 CRYPTO_cts128_decrypt_block(), CRYPTO_cts128_decrypt(),
1258 CRYPTO_nistcts128_encrypt_block(), CRYPTO_nistcts128_encrypt(),
1259 CRYPTO_nistcts128_decrypt_block(), CRYPTO_nistcts128_decrypt()
1261 Use the higher level functions EVP_CipherInit_ex2(), EVP_CipherUpdate() and
1262 EVP_CipherFinal_ex() instead.
1263 See the "cts_mode" parameter in
1264 L<EVP_EncryptInit(3)/Gettable and Settable EVP_CIPHER_CTX parameters>.
1265 See L<EVP_EncryptInit(3)/EXAMPLES> for a AES-256-CBC-CTS example.
1269 d2i_DHparams(), d2i_DHxparams(), d2i_DSAparams(), d2i_DSAPrivateKey(),
1270 d2i_DSAPrivateKey_bio(), d2i_DSAPrivateKey_fp(), d2i_DSA_PUBKEY(),
1271 d2i_DSA_PUBKEY_bio(), d2i_DSA_PUBKEY_fp(), d2i_DSAPublicKey(),
1272 d2i_ECParameters(), d2i_ECPrivateKey(), d2i_ECPrivateKey_bio(),
1273 d2i_ECPrivateKey_fp(), d2i_EC_PUBKEY(), d2i_EC_PUBKEY_bio(),
1274 d2i_EC_PUBKEY_fp(), o2i_ECPublicKey(), d2i_RSAPrivateKey(),
1275 d2i_RSAPrivateKey_bio(), d2i_RSAPrivateKey_fp(), d2i_RSA_PUBKEY(),
1276 d2i_RSA_PUBKEY_bio(), d2i_RSA_PUBKEY_fp(), d2i_RSAPublicKey(),
1277 d2i_RSAPublicKey_bio(), d2i_RSAPublicKey_fp()
1279 See L</Deprecated i2d and d2i functions for low-level key types>
1283 DES_crypt(), DES_fcrypt(), DES_encrypt1(), DES_encrypt2(), DES_encrypt3(),
1284 DES_decrypt3(), DES_ede3_cbc_encrypt(), DES_ede3_cfb64_encrypt(),
1285 DES_ede3_cfb_encrypt(),DES_ede3_ofb64_encrypt(),
1286 DES_ecb_encrypt(), DES_ecb3_encrypt(), DES_ofb64_encrypt(), DES_ofb_encrypt(),
1287 DES_cfb64_encrypt DES_cfb_encrypt(), DES_cbc_encrypt(), DES_ncbc_encrypt(),
1288 DES_pcbc_encrypt(), DES_xcbc_encrypt(), DES_cbc_cksum(), DES_quad_cksum(),
1289 DES_check_key_parity(), DES_is_weak_key(), DES_key_sched(), DES_options(),
1290 DES_random_key(), DES_set_key(), DES_set_key_checked(), DES_set_key_unchecked(),
1291 DES_set_odd_parity(), DES_string_to_2keys(), DES_string_to_key()
1293 See L</Deprecated low-level encryption functions>.
1294 Algorithms for "DESX-CBC", "DES-ECB", "DES-CBC", "DES-OFB", "DES-CFB",
1295 "DES-CFB1" and "DES-CFB8" have been moved to the L<Legacy Provider|/Legacy Algorithms>.
1299 DH_bits(), DH_security_bits(), DH_size()
1301 Use L<EVP_PKEY_get_bits(3)>, L<EVP_PKEY_get_security_bits(3)> and
1302 L<EVP_PKEY_get_size(3)>.
1306 DH_check(), DH_check_ex(), DH_check_params(), DH_check_params_ex(),
1307 DH_check_pub_key(), DH_check_pub_key_ex()
1309 See L</Deprecated low-level validation functions>
1313 DH_clear_flags(), DH_test_flags(), DH_set_flags()
1315 The B<DH_FLAG_CACHE_MONT_P> flag has been deprecated without replacement.
1316 The B<DH_FLAG_TYPE_DH> and B<DH_FLAG_TYPE_DHX> have been deprecated.
1317 Use EVP_PKEY_is_a() to determine the type of a key.
1318 There is no replacement for setting these flags.
1322 DH_compute_key() DH_compute_key_padded()
1324 See L</Deprecated low-level key exchange functions>.
1328 DH_new(), DH_new_by_nid(), DH_free(), DH_up_ref()
1330 See L</Deprecated low-level object creation>
1334 DH_generate_key(), DH_generate_parameters_ex()
1336 See L</Deprecated low-level key generation functions>.
1340 DH_get0_pqg(), DH_get0_p(), DH_get0_q(), DH_get0_g(), DH_get0_key(),
1341 DH_get0_priv_key(), DH_get0_pub_key(), DH_get_length(), DH_get_nid()
1343 See L</Deprecated low-level key parameter getters>
1347 DH_get_1024_160(), DH_get_2048_224(), DH_get_2048_256()
1349 Applications should instead set the B<OSSL_PKEY_PARAM_GROUP_NAME> as specified in
1350 L<EVP_PKEY-DH(7)/DH parameters>) to one of "dh_1024_160", "dh_2048_224" or
1351 "dh_2048_256" when generating a DH key.
1357 Applications should use L<EVP_PKEY_CTX_set_dh_kdf_type(3)> instead.
1361 DH_get_default_method(), DH_get0_engine(), DH_meth_*(), DH_new_method(),
1362 DH_OpenSSL(), DH_get_ex_data(), DH_set_default_method(), DH_set_method(),
1365 See L</Providers are a replacement for engines and low-level method overrides>
1369 DHparams_print(), DHparams_print_fp()
1371 See L</Deprecated low-level key printing functions>
1375 DH_set0_key(), DH_set0_pqg(), DH_set_length()
1377 See L</Deprecated low-level key parameter setters>
1381 DSA_bits(), DSA_security_bits(), DSA_size()
1383 Use L<EVP_PKEY_get_bits(3)>, L<EVP_PKEY_get_security_bits(3)> and
1384 L<EVP_PKEY_get_size(3)>.
1388 DHparams_dup(), DSA_dup_DH()
1390 There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)>
1391 and L<EVP_PKEY_dup(3)> instead.
1395 DSA_generate_key(), DSA_generate_parameters_ex()
1397 See L</Deprecated low-level key generation functions>.
1401 DSA_get0_engine(), DSA_get_default_method(), DSA_get_ex_data(),
1402 DSA_get_method(), DSA_meth_*(), DSA_new_method(), DSA_OpenSSL(),
1403 DSA_set_default_method(), DSA_set_ex_data(), DSA_set_method()
1405 See L</Providers are a replacement for engines and low-level method overrides>.
1409 DSA_get0_p(), DSA_get0_q(), DSA_get0_g(), DSA_get0_pqg(), DSA_get0_key(),
1410 DSA_get0_priv_key(), DSA_get0_pub_key()
1412 See L</Deprecated low-level key parameter getters>.
1416 DSA_new(), DSA_free(), DSA_up_ref()
1418 See L</Deprecated low-level object creation>
1424 There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)>
1425 and L<EVP_PKEY_dup(3)> instead.
1429 DSAparams_print(), DSAparams_print_fp(), DSA_print(), DSA_print_fp()
1431 See L</Deprecated low-level key printing functions>
1435 DSA_set0_key(), DSA_set0_pqg()
1437 See L</Deprecated low-level key parameter setters>
1441 DSA_set_flags(), DSA_clear_flags(), DSA_test_flags()
1443 The B<DSA_FLAG_CACHE_MONT_P> flag has been deprecated without replacement.
1447 DSA_sign(), DSA_do_sign(), DSA_sign_setup(), DSA_verify(), DSA_do_verify()
1449 See L</Deprecated low-level signing functions>.
1455 See L</Deprecated low-level key exchange functions>.
1461 Applications may either set this using the helper function
1462 L<EVP_PKEY_CTX_set_ecdh_kdf_type(3)> or by setting an B<OSSL_PARAM> using the
1463 "kdf-type" as shown in L<EVP_KEYEXCH-ECDH(7)/EXAMPLES>
1467 ECDSA_sign(), ECDSA_sign_ex(), ECDSA_sign_setup(), ECDSA_do_sign(),
1468 ECDSA_do_sign_ex(), ECDSA_verify(), ECDSA_do_verify()
1470 See L</Deprecated low-level signing functions>.
1476 Applications should use L<EVP_PKEY_get_size(3)>.
1480 EC_GF2m_simple_method(), EC_GFp_mont_method(), EC_GFp_nist_method(),
1481 EC_GFp_nistp224_method(), EC_GFp_nistp256_method(), EC_GFp_nistp521_method(),
1482 EC_GFp_simple_method()
1484 There are no replacements for these functions. Applications should rely on the
1485 library automatically assigning a suitable method internally when an EC_GROUP
1490 EC_GROUP_clear_free()
1492 Use L<EC_GROUP_free(3)> instead.
1496 EC_GROUP_get_curve_GF2m(), EC_GROUP_get_curve_GFp(), EC_GROUP_set_curve_GF2m(),
1497 EC_GROUP_set_curve_GFp()
1499 Applications should use L<EC_GROUP_get_curve(3)> and L<EC_GROUP_set_curve(3)>.
1503 EC_GROUP_have_precompute_mult(), EC_GROUP_precompute_mult(),
1504 EC_KEY_precompute_mult()
1506 These functions are not widely used. Applications should instead switch to
1507 named curves which OpenSSL has hardcoded lookup tables for.
1511 EC_GROUP_new(), EC_GROUP_method_of(), EC_POINT_method_of()
1513 EC_METHOD is now an internal-only concept and a suitable EC_METHOD is assigned
1514 internally without application intervention.
1515 Users of EC_GROUP_new() should switch to a different suitable constructor.
1521 Applications should use L<EVP_PKEY_can_sign(3)> instead.
1527 See L</Deprecated low-level validation functions>
1531 EC_KEY_set_flags(), EC_KEY_get_flags(), EC_KEY_clear_flags()
1533 See L<EVP_PKEY-EC(7)/Common EC parameters> which handles flags as separate
1534 parameters for B<OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT>,
1535 B<OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE>, B<OSSL_PKEY_PARAM_EC_ENCODING>,
1536 B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH> and
1537 B<OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC>.
1538 See also L<EVP_PKEY-EC(7)/EXAMPLES>
1542 EC_KEY_dup(), EC_KEY_copy()
1544 There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)>
1545 and L<EVP_PKEY_dup(3)> instead.
1549 EC_KEY_decoded_from_explicit_params()
1551 There is no replacement.
1555 EC_KEY_generate_key()
1557 See L</Deprecated low-level key generation functions>.
1561 EC_KEY_get0_group(), EC_KEY_get0_private_key(), EC_KEY_get0_public_key(),
1562 EC_KEY_get_conv_form(), EC_KEY_get_enc_flags()
1564 See L</Deprecated low-level key parameter getters>.
1568 EC_KEY_get0_engine(), EC_KEY_get_default_method(), EC_KEY_get_method(),
1569 EC_KEY_new_method(), EC_KEY_get_ex_data(), EC_KEY_OpenSSL(),
1570 EC_KEY_set_ex_data(), EC_KEY_set_default_method(), EC_KEY_METHOD_*(),
1573 See L</Providers are a replacement for engines and low-level method overrides>
1577 EC_METHOD_get_field_type()
1579 Use L<EC_GROUP_get_field_type(3)> instead.
1580 See L</Providers are a replacement for engines and low-level method overrides>
1584 EC_KEY_key2buf(), EC_KEY_oct2key(), EC_KEY_oct2priv(), EC_KEY_priv2buf(),
1587 There are no replacements for these.
1591 EC_KEY_new(), EC_KEY_new_by_curve_name(), EC_KEY_free(), EC_KEY_up_ref()
1593 See L</Deprecated low-level object creation>
1597 EC_KEY_print(), EC_KEY_print_fp()
1599 See L</Deprecated low-level key printing functions>
1603 EC_KEY_set_asn1_flag(), EC_KEY_set_conv_form(), EC_KEY_set_enc_flags()
1605 See L</Deprecated low-level key parameter setters>.
1609 EC_KEY_set_group(), EC_KEY_set_private_key(), EC_KEY_set_public_key(),
1610 EC_KEY_set_public_key_affine_coordinates()
1612 See L</Deprecated low-level key parameter setters>.
1616 ECParameters_print(), ECParameters_print_fp(), ECPKParameters_print(),
1617 ECPKParameters_print_fp()
1619 See L</Deprecated low-level key printing functions>
1623 EC_POINT_bn2point(), EC_POINT_point2bn()
1625 These functions were not particularly useful, since EC point serialization
1626 formats are not individual big-endian integers.
1630 EC_POINT_get_affine_coordinates_GF2m(), EC_POINT_get_affine_coordinates_GFp(),
1631 EC_POINT_set_affine_coordinates_GF2m(), EC_POINT_set_affine_coordinates_GFp()
1633 Applications should use L<EC_POINT_get_affine_coordinates(3)> and
1634 L<EC_POINT_set_affine_coordinates(3)> instead.
1638 EC_POINT_get_Jprojective_coordinates_GFp(), EC_POINT_set_Jprojective_coordinates_GFp()
1640 These functions are not widely used. Applications should instead use the
1641 L<EC_POINT_set_affine_coordinates(3)> and L<EC_POINT_get_affine_coordinates(3)>
1646 EC_POINT_make_affine(), EC_POINTs_make_affine()
1648 There is no replacement. These functions were not widely used, and OpenSSL
1649 automatically performs this conversion when needed.
1653 EC_POINT_set_compressed_coordinates_GF2m(), EC_POINT_set_compressed_coordinates_GFp()
1655 Applications should use L<EC_POINT_set_compressed_coordinates(3)> instead.
1661 This function is not widely used. Applications should instead use the
1662 L<EC_POINT_mul(3)> function.
1668 All engine functions are deprecated. An engine should be rewritten as a provider.
1669 See L</Providers are a replacement for engines and low-level method overrides>.
1673 B<ERR_load_*()>, ERR_func_error_string(), ERR_get_error_line(),
1674 ERR_get_error_line_data(), ERR_get_state()
1676 OpenSSL now loads error strings automatically so these functions are not needed.
1680 ERR_peek_error_line_data(), ERR_peek_last_error_line_data()
1682 The new functions are L<ERR_peek_error_func(3)>, L<ERR_peek_last_error_func(3)>,
1683 L<ERR_peek_error_data(3)>, L<ERR_peek_last_error_data(3)>, L<ERR_get_error_all(3)>,
1684 L<ERR_peek_error_all(3)> and L<ERR_peek_last_error_all(3)>.
1685 Applications should use L<ERR_get_error_all(3)>, or pick information
1686 with ERR_peek functions and finish off with getting the error code by using
1687 L<ERR_get_error(3)>.
1691 EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_iv_noconst(), EVP_CIPHER_CTX_original_iv()
1693 Applications should instead use L<EVP_CIPHER_CTX_get_updated_iv(3)>,
1694 L<EVP_CIPHER_CTX_get_updated_iv(3)> and L<EVP_CIPHER_CTX_get_original_iv(3)>
1696 See L<EVP_CIPHER_CTX_get_original_iv(3)> for further information.
1700 B<EVP_CIPHER_meth_*()>, EVP_MD_CTX_set_update_fn(), EVP_MD_CTX_update_fn(),
1703 See L</Providers are a replacement for engines and low-level method overrides>.
1707 EVP_PKEY_CTRL_PKCS7_ENCRYPT(), EVP_PKEY_CTRL_PKCS7_DECRYPT(),
1708 EVP_PKEY_CTRL_PKCS7_SIGN(), EVP_PKEY_CTRL_CMS_ENCRYPT(),
1709 EVP_PKEY_CTRL_CMS_DECRYPT(), and EVP_PKEY_CTRL_CMS_SIGN()
1711 These control operations are not invoked by the OpenSSL library anymore and
1712 are replaced by direct checks of the key operation against the key type
1713 when the operation is initialized.
1717 EVP_PKEY_CTX_get0_dh_kdf_ukm(), EVP_PKEY_CTX_get0_ecdh_kdf_ukm()
1719 See the "kdf-ukm" item in L<EVP_KEYEXCH-DH(7)/DH key exchange parameters> and
1720 L<EVP_KEYEXCH-ECDH(7)/ECDH Key Exchange parameters>.
1721 These functions are obsolete and should not be required.
1725 EVP_PKEY_CTX_set_rsa_keygen_pubexp()
1727 Applications should use L<EVP_PKEY_CTX_set1_rsa_keygen_pubexp(3)> instead.
1731 EVP_PKEY_cmp(), EVP_PKEY_cmp_parameters()
1733 Applications should use L<EVP_PKEY_eq(3)> and L<EVP_PKEY_parameters_eq(3)> instead.
1734 See L<EVP_PKEY_copy_parameters(3)> for further details.
1738 EVP_PKEY_encrypt_old(), EVP_PKEY_decrypt_old(),
1740 Applications should use L<EVP_PKEY_encrypt_init(3)> and L<EVP_PKEY_encrypt(3)> or
1741 L<EVP_PKEY_decrypt_init(3)> and L<EVP_PKEY_decrypt(3)> instead.
1747 This function returns NULL if the key comes from a provider.
1751 EVP_PKEY_get0_DH(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_EC_KEY(), EVP_PKEY_get0_RSA(),
1752 EVP_PKEY_get1_DH(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_EC_KEY and EVP_PKEY_get1_RSA(),
1753 EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash()
1755 See L</Functions that return an internal key should be treated as read only>.
1759 B<EVP_PKEY_meth_*()>
1761 See L</Providers are a replacement for engines and low-level method overrides>.
1765 EVP_PKEY_new_CMAC_key()
1767 See L</Deprecated low-level MAC functions>.
1771 EVP_PKEY_assign(), EVP_PKEY_set1_DH(), EVP_PKEY_set1_DSA(),
1772 EVP_PKEY_set1_EC_KEY(), EVP_PKEY_set1_RSA()
1774 See L</Deprecated low-level key object getters and setters>
1778 EVP_PKEY_set1_tls_encodedpoint() EVP_PKEY_get1_tls_encodedpoint()
1780 These functions were previously used by libssl to set or get an encoded public
1781 key into/from an EVP_PKEY object. With OpenSSL 3.0 these are replaced by the more
1782 generic functions L<EVP_PKEY_set1_encoded_public_key(3)> and
1783 L<EVP_PKEY_get1_encoded_public_key(3)>.
1784 The old versions have been converted to deprecated macros that just call the
1789 EVP_PKEY_set1_engine(), EVP_PKEY_get0_engine()
1791 See L</Providers are a replacement for engines and low-level method overrides>.
1795 EVP_PKEY_set_alias_type()
1797 This function has been removed. There is no replacement.
1798 See L</EVP_PKEY_set_alias_type() method has been removed>
1802 HMAC_Init_ex(), HMAC_Update(), HMAC_Final(), HMAC_size()
1804 See L</Deprecated low-level MAC functions>.
1808 HMAC_CTX_new(), HMAC_CTX_free(), HMAC_CTX_copy(), HMAC_CTX_reset(),
1809 HMAC_CTX_set_flags(), HMAC_CTX_get_md()
1811 See L</Deprecated low-level MAC functions>.
1815 i2d_DHparams(), i2d_DHxparams()
1817 See L</Deprecated low-level key reading and writing functions>
1818 and L<d2i_RSAPrivateKey(3)/Migration>
1822 i2d_DSAparams(), i2d_DSAPrivateKey(), i2d_DSAPrivateKey_bio(),
1823 i2d_DSAPrivateKey_fp(), i2d_DSA_PUBKEY(), i2d_DSA_PUBKEY_bio(),
1824 i2d_DSA_PUBKEY_fp(), i2d_DSAPublicKey()
1826 See L</Deprecated low-level key reading and writing functions>
1827 and L<d2i_RSAPrivateKey(3)/Migration>
1831 i2d_ECParameters(), i2d_ECPrivateKey(), i2d_ECPrivateKey_bio(),
1832 i2d_ECPrivateKey_fp(), i2d_EC_PUBKEY(), i2d_EC_PUBKEY_bio(),
1833 i2d_EC_PUBKEY_fp(), i2o_ECPublicKey()
1835 See L</Deprecated low-level key reading and writing functions>
1836 and L<d2i_RSAPrivateKey(3)/Migration>
1840 i2d_RSAPrivateKey(), i2d_RSAPrivateKey_bio(), i2d_RSAPrivateKey_fp(),
1841 i2d_RSA_PUBKEY(), i2d_RSA_PUBKEY_bio(), i2d_RSA_PUBKEY_fp(),
1842 i2d_RSAPublicKey(), i2d_RSAPublicKey_bio(), i2d_RSAPublicKey_fp()
1844 See L</Deprecated low-level key reading and writing functions>
1845 and L<d2i_RSAPrivateKey(3)/Migration>
1849 IDEA_encrypt(), IDEA_set_decrypt_key(), IDEA_set_encrypt_key(),
1850 IDEA_cbc_encrypt(), IDEA_cfb64_encrypt(), IDEA_ecb_encrypt(),
1851 IDEA_ofb64_encrypt()
1853 See L</Deprecated low-level encryption functions>.
1854 IDEA has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1860 There is no replacement. This function returned a constant string.
1864 MD2(), MD2_Init(), MD2_Update(), MD2_Final()
1866 See L</Deprecated low-level encryption functions>.
1867 MD2 has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1873 There is no replacement. This function returned a constant string.
1877 MD4(), MD4_Init(), MD4_Update(), MD4_Final(), MD4_Transform()
1879 See L</Deprecated low-level encryption functions>.
1880 MD4 has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1884 MDC2(), MDC2_Init(), MDC2_Update(), MDC2_Final()
1886 See L</Deprecated low-level encryption functions>.
1887 MDC2 has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1891 MD5(), MD5_Init(), MD5_Update(), MD5_Final(), MD5_Transform()
1893 See L</Deprecated low-level encryption functions>.
1899 This undocumented function has no replacement.
1900 See L<config(5)/HISTORY> for more details.
1906 Use L<OSSL_HTTP_parse_url(3)> instead.
1910 B<OCSP_REQ_CTX> type and B<OCSP_REQ_CTX_*()> functions
1912 These methods were used to collect all necessary data to form a HTTP request,
1913 and to perform the HTTP transfer with that request. With OpenSSL 3.0, the
1914 type is B<OSSL_HTTP_REQ_CTX>, and the deprecated functions are replaced
1915 with B<OSSL_HTTP_REQ_CTX_*()>. See L<OSSL_HTTP_REQ_CTX(3)> for additional
1920 OPENSSL_fork_child(), OPENSSL_fork_parent(), OPENSSL_fork_prepare()
1922 There is no replacement for these functions. These pthread fork support methods
1923 were unused by OpenSSL.
1927 OSSL_STORE_ctrl(), OSSL_STORE_do_all_loaders(), OSSL_STORE_LOADER_get0_engine(),
1928 OSSL_STORE_LOADER_get0_scheme(), OSSL_STORE_LOADER_new(),
1929 OSSL_STORE_LOADER_set_attach(), OSSL_STORE_LOADER_set_close(),
1930 OSSL_STORE_LOADER_set_ctrl(), OSSL_STORE_LOADER_set_eof(),
1931 OSSL_STORE_LOADER_set_error(), OSSL_STORE_LOADER_set_expect(),
1932 OSSL_STORE_LOADER_set_find(), OSSL_STORE_LOADER_set_load(),
1933 OSSL_STORE_LOADER_set_open(), OSSL_STORE_LOADER_set_open_ex(),
1934 OSSL_STORE_register_loader(), OSSL_STORE_unregister_loader(),
1937 These functions helped applications and engines create loaders for
1938 schemes they supported. These are all deprecated and discouraged in favour of
1939 provider implementations, see L<provider-storemgmt(7)>.
1943 PEM_read_DHparams(), PEM_read_bio_DHparams(),
1944 PEM_read_DSAparams(), PEM_read_bio_DSAparams(),
1945 PEM_read_DSAPrivateKey(), PEM_read_DSA_PUBKEY(),
1946 PEM_read_bio_DSAPrivateKey and PEM_read_bio_DSA_PUBKEY(),
1947 PEM_read_ECPKParameters(), PEM_read_ECPrivateKey(), PEM_read_EC_PUBKEY(),
1948 PEM_read_bio_ECPKParameters(), PEM_read_bio_ECPrivateKey(), PEM_read_bio_EC_PUBKEY(),
1949 PEM_read_RSAPrivateKey(), PEM_read_RSA_PUBKEY(), PEM_read_RSAPublicKey(),
1950 PEM_read_bio_RSAPrivateKey(), PEM_read_bio_RSA_PUBKEY(), PEM_read_bio_RSAPublicKey(),
1951 PEM_write_bio_DHparams(), PEM_write_bio_DHxparams(), PEM_write_DHparams(), PEM_write_DHxparams(),
1952 PEM_write_DSAparams(), PEM_write_DSAPrivateKey(), PEM_write_DSA_PUBKEY(),
1953 PEM_write_bio_DSAparams(), PEM_write_bio_DSAPrivateKey(), PEM_write_bio_DSA_PUBKEY(),
1954 PEM_write_ECPKParameters(), PEM_write_ECPrivateKey(), PEM_write_EC_PUBKEY(),
1955 PEM_write_bio_ECPKParameters(), PEM_write_bio_ECPrivateKey(), PEM_write_bio_EC_PUBKEY(),
1956 PEM_write_RSAPrivateKey(), PEM_write_RSA_PUBKEY(), PEM_write_RSAPublicKey(),
1957 PEM_write_bio_RSAPrivateKey(), PEM_write_bio_RSA_PUBKEY(),
1958 PEM_write_bio_RSAPublicKey(),
1960 See L</Deprecated low-level key reading and writing functions>
1966 See L</Deprecated low-level encryption functions>.
1970 RAND_get_rand_method(), RAND_set_rand_method(), RAND_OpenSSL(),
1971 RAND_set_rand_engine()
1973 Applications should instead use L<RAND_set_DRBG_type(3)>,
1974 L<EVP_RAND(3)> and L<EVP_RAND(7)>.
1975 See L<RAND_set_rand_method(3)> for more details.
1979 RC2_encrypt(), RC2_decrypt(), RC2_set_key(), RC2_cbc_encrypt(), RC2_cfb64_encrypt(),
1980 RC2_ecb_encrypt(), RC2_ofb64_encrypt(),
1981 RC4(), RC4_set_key(), RC4_options(),
1982 RC5_32_encrypt(), RC5_32_set_key(), RC5_32_decrypt(), RC5_32_cbc_encrypt(),
1983 RC5_32_cfb64_encrypt(), RC5_32_ecb_encrypt(), RC5_32_ofb64_encrypt()
1985 See L</Deprecated low-level encryption functions>.
1986 The Algorithms "RC2", "RC4" and "RC5" have been moved to the L<Legacy Provider|/Legacy Algorithms>.
1990 RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update(), RIPEMD160_Final(),
1991 RIPEMD160_Transform()
1993 See L</Deprecated low-level digest functions>.
1994 The RIPE algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1998 RSA_bits(), RSA_security_bits(), RSA_size()
2000 Use L<EVP_PKEY_get_bits(3)>, L<EVP_PKEY_get_security_bits(3)> and
2001 L<EVP_PKEY_get_size(3)>.
2005 RSA_check_key(), RSA_check_key_ex()
2007 See L</Deprecated low-level validation functions>
2011 RSA_clear_flags(), RSA_flags(), RSA_set_flags(), RSA_test_flags(),
2012 RSA_setup_blinding(), RSA_blinding_off(), RSA_blinding_on()
2014 All of these RSA flags have been deprecated without replacement:
2016 B<RSA_FLAG_BLINDING>, B<RSA_FLAG_CACHE_PRIVATE>, B<RSA_FLAG_CACHE_PUBLIC>,
2017 B<RSA_FLAG_EXT_PKEY>, B<RSA_FLAG_NO_BLINDING>, B<RSA_FLAG_THREAD_SAFE>
2018 B<RSA_METHOD_FLAG_NO_CHECK>
2022 RSA_generate_key_ex(), RSA_generate_multi_prime_key()
2024 See L</Deprecated low-level key generation functions>.
2030 See L</Providers are a replacement for engines and low-level method overrides>
2034 RSA_get0_crt_params(), RSA_get0_d(), RSA_get0_dmp1(), RSA_get0_dmq1(),
2035 RSA_get0_e(), RSA_get0_factors(), RSA_get0_iqmp(), RSA_get0_key(),
2036 RSA_get0_multi_prime_crt_params(), RSA_get0_multi_prime_factors(), RSA_get0_n(),
2037 RSA_get0_p(), RSA_get0_pss_params(), RSA_get0_q(),
2038 RSA_get_multi_prime_extra_count()
2040 See L</Deprecated low-level key parameter getters>
2044 RSA_new(), RSA_free(), RSA_up_ref()
2046 See L</Deprecated low-level object creation>.
2050 RSA_get_default_method(), RSA_get_ex_data and RSA_get_method()
2052 See L</Providers are a replacement for engines and low-level method overrides>.
2058 There is no replacement.
2062 B<RSA_meth_*()>, RSA_new_method(), RSA_null_method and RSA_PKCS1_OpenSSL()
2064 See L</Providers are a replacement for engines and low-level method overrides>.
2068 B<RSA_padding_add_*()>, B<RSA_padding_check_*()>
2070 See L</Deprecated low-level signing functions> and
2071 L</Deprecated low-level encryption functions>.
2075 RSA_print(), RSA_print_fp()
2077 See L</Deprecated low-level key printing functions>
2081 RSA_public_encrypt(), RSA_private_decrypt()
2083 See L</Deprecated low-level encryption functions>
2087 RSA_private_encrypt(), RSA_public_decrypt()
2089 This is equivalent to doing sign and verify recover operations (with a padding
2090 mode of none). See L</Deprecated low-level signing functions>.
2094 RSAPrivateKey_dup(), RSAPublicKey_dup()
2096 There is no direct replacement. Applications may use L<EVP_PKEY_dup(3)>.
2100 RSAPublicKey_it(), RSAPrivateKey_it()
2102 See L</Deprecated low-level key reading and writing functions>
2106 RSA_set0_crt_params(), RSA_set0_factors(), RSA_set0_key(),
2107 RSA_set0_multi_prime_params()
2109 See L</Deprecated low-level key parameter setters>.
2113 RSA_set_default_method(), RSA_set_method(), RSA_set_ex_data()
2115 See L</Providers are a replacement for engines and low-level method overrides>
2119 RSA_sign(), RSA_sign_ASN1_OCTET_STRING(), RSA_verify(),
2120 RSA_verify_ASN1_OCTET_STRING(), RSA_verify_PKCS1_PSS(),
2121 RSA_verify_PKCS1_PSS_mgf1()
2123 See L</Deprecated low-level signing functions>.
2127 RSA_X931_derive_ex(), RSA_X931_generate_key_ex(), RSA_X931_hash_id()
2129 There are no replacements for these functions.
2130 X931 padding can be set using L<EVP_SIGNATURE-RSA(7)/Signature Parameters>.
2131 See B<OSSL_SIGNATURE_PARAM_PAD_MODE>.
2135 SEED_encrypt(), SEED_decrypt(), SEED_set_key(), SEED_cbc_encrypt(),
2136 SEED_cfb128_encrypt(), SEED_ecb_encrypt(), SEED_ofb128_encrypt()
2138 See L</Deprecated low-level encryption functions>.
2139 The SEED algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
2143 SHA1_Init(), SHA1_Update(), SHA1_Final(), SHA1_Transform(),
2144 SHA224_Init(), SHA224_Update(), SHA224_Final(),
2145 SHA256_Init(), SHA256_Update(), SHA256_Final(), SHA256_Transform(),
2146 SHA384_Init(), SHA384_Update(), SHA384_Final(),
2147 SHA512_Init(), SHA512_Update(), SHA512_Final(), SHA512_Transform()
2149 See L</Deprecated low-level digest functions>.
2153 SRP_Calc_A(), SRP_Calc_B(), SRP_Calc_client_key(), SRP_Calc_server_key(),
2154 SRP_Calc_u(), SRP_Calc_x(), SRP_check_known_gN_param(), SRP_create_verifier(),
2155 SRP_create_verifier_BN(), SRP_get_default_gN(), SRP_user_pwd_free(), SRP_user_pwd_new(),
2156 SRP_user_pwd_set0_sv(), SRP_user_pwd_set1_ids(), SRP_user_pwd_set_gN(),
2157 SRP_VBASE_add0_user(), SRP_VBASE_free(), SRP_VBASE_get1_by_user(), SRP_VBASE_init(),
2158 SRP_VBASE_new(), SRP_Verify_A_mod_N(), SRP_Verify_B_mod_N()
2160 There are no replacements for the SRP functions.
2164 SSL_CTX_set_tmp_dh_callback(), SSL_set_tmp_dh_callback(),
2165 SSL_CTX_set_tmp_dh(), SSL_set_tmp_dh()
2167 These are used to set the Diffie-Hellman (DH) parameters that are to be used by
2168 servers requiring ephemeral DH keys. Instead applications should consider using
2169 the built-in DH parameters that are available by calling L<SSL_CTX_set_dh_auto(3)>
2170 or L<SSL_set_dh_auto(3)>. If custom parameters are necessary then applications can
2171 use the alternative functions L<SSL_CTX_set0_tmp_dh_pkey(3)> and
2172 L<SSL_set0_tmp_dh_pkey(3)>. There is no direct replacement for the "callback"
2173 functions. The callback was originally useful in order to have different
2174 parameters for export and non-export ciphersuites. Export ciphersuites are no
2175 longer supported by OpenSSL. Use of the callback functions should be replaced
2176 by one of the other methods described above.
2180 SSL_CTX_set_tlsext_ticket_key_cb()
2182 Use the new L<SSL_CTX_set_tlsext_ticket_key_evp_cb(3)> function instead.
2186 WHIRLPOOL(), WHIRLPOOL_Init(), WHIRLPOOL_Update(), WHIRLPOOL_Final(),
2187 WHIRLPOOL_BitUpdate()
2189 See L</Deprecated low-level digest functions>.
2190 The Whirlpool algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
2194 X509_certificate_type()
2196 This was an undocumented function. Applications can use L<X509_get0_pubkey(3)>
2197 and L<X509_get0_signature(3)> instead.
2201 X509_http_nbio(), X509_CRL_http_nbio()
2203 Use L<X509_load_http(3)> and L<X509_CRL_load_http(3)> instead.
2207 =head2 Using the FIPS Module in applications
2209 See L<fips_module(7)> and L<OSSL_PROVIDER-FIPS(7)> for details.
2211 =head2 OpenSSL command line application changes
2213 =head3 New applications
2215 L<B<openssl kdf>|openssl-kdf(1)> uses the new L<EVP_KDF(3)> API.
2216 L<B<openssl kdf>|openssl-mac(1)> uses the new L<EVP_MAC(3)> API.
2218 =head3 Added options
2220 B<-provider_path> and B<-provider> are available to all apps and can be used
2221 multiple times to load any providers, such as the 'legacy' provider or third
2222 party providers. If used then the 'default' provider would also need to be
2223 specified if required. The B<-provider_path> must be specified before the
2224 B<-provider> option.
2226 The B<list> app has many new options. See L<openssl-list(1)> for more
2229 B<-crl_lastupdate> and B<-crl_nextupdate> used by B<openssl ca> allows
2230 explicit setting of fields in the generated CRL.
2232 =head3 Removed options
2234 Interactive mode is not longer available.
2236 The B<-crypt> option used by B<openssl passwd>.
2237 The B<-c> option used by B<openssl x509>, B<openssl dhparam>,
2238 B<openssl dsaparam>, and B<openssl ecparam>.
2240 =head3 Other Changes
2242 The output of Command line applications may have minor changes.
2243 These are primarily changes in capitalisation and white space. However, in some
2244 cases, there are additional differences.
2245 For example, the DH parameters output from B<openssl dhparam> now lists 'P',
2246 'Q', 'G' and 'pcounter' instead of 'prime', 'generator', 'subgroup order' and
2247 'counter' respectively.
2249 The B<openssl> commands that read keys, certificates, and CRLs now
2250 automatically detect the PEM or DER format of the input files so it is not
2251 necessary to explicitly specify the input format anymore. However if the
2252 input format option is used the specified format will be required.
2254 B<openssl speed> no longer uses low-level API calls.
2255 This implies some of the performance numbers might not be comparable with the
2256 previous releases due to higher overhead. This applies particularly to
2257 measuring performance on smaller data chunks.
2259 b<openssl dhparam>, B<openssl dsa>, B<openssl gendsa>, B<openssl dsaparam>,
2260 B<openssl genrsa> and B<openssl rsa> have been modified to use PKEY APIs.
2261 B<openssl genrsa> and B<openssl rsa> now write PKCS #8 keys by default.
2263 =head3 Default settings
2265 "SHA256" is now the default digest for TS query used by B<openssl ts>.
2267 =head3 Deprecated apps
2269 B<openssl rsautl> is deprecated, use B<openssl pkeyutl> instead.
2270 B<openssl dhparam>, B<openssl dsa>, B<openssl gendsa>, B<openssl dsaparam>,
2271 B<openssl genrsa>, B<openssl rsa>, B<openssl genrsa> and B<openssl rsa> are
2272 now in maintenance mode and no new features will be added to them.
2280 TLS 1.3 FFDHE key exchange support added
2282 This uses DH safe prime named groups.
2286 Support for fully "pluggable" TLSv1.3 groups.
2288 This means that providers may supply their own group implementations (using
2289 either the "key exchange" or the "key encapsulation" methods) which will
2290 automatically be detected and used by libssl.
2294 SSL and SSL_CTX options are now 64 bit instead of 32 bit.
2296 The signatures of the functions to get and set options on SSL and
2297 SSL_CTX objects changed from "unsigned long" to "uint64_t" type.
2299 This may require source code changes. For example it is no longer possible
2300 to use the B<SSL_OP_> macro values in preprocessor C<#if> conditions.
2301 However it is still possible to test whether these macros are defined or not.
2303 See L<SSL_CTX_get_options(3)>, L<SSL_CTX_set_options(3)>,
2304 L<SSL_get_options(3)> and L<SSL_set_options(3)>.
2308 SSL_set1_host() and SSL_add1_host() Changes
2310 These functions now take IP literal addresses as well as actual hostnames.
2314 Added SSL option SSL_OP_CLEANSE_PLAINTEXT
2316 If the option is set, openssl cleanses (zeroizes) plaintext bytes from
2317 internal buffers after delivering them to the application. Note,
2318 the application is still responsible for cleansing other copies
2319 (e.g.: data received by L<SSL_read(3)>).
2323 Client-initiated renegotiation is disabled by default.
2325 To allow it, use the B<-client_renegotiation> option,
2326 the B<SSL_OP_ALLOW_CLIENT_RENEGOTIATION> flag, or the C<ClientRenegotiation>
2327 config parameter as appropriate.
2331 Secure renegotiation is now required by default for TLS connections
2333 Support for RFC 5746 secure renegotiation is now required by default for
2334 SSL or TLS connections to succeed. Applications that require the ability
2335 to connect to legacy peers will need to explicitly set
2336 SSL_OP_LEGACY_SERVER_CONNECT. Accordingly, SSL_OP_LEGACY_SERVER_CONNECT
2337 is no longer set as part of SSL_OP_ALL.
2341 Combining the Configure options no-ec and no-dh no longer disables TLSv1.3
2343 Typically if OpenSSL has no EC or DH algorithms then it cannot support
2344 connections with TLSv1.3. However OpenSSL now supports "pluggable" groups
2345 through providers. Therefore third party providers may supply group
2346 implementations even where there are no built-in ones. Attempting to create
2347 TLS connections in such a build without also disabling TLSv1.3 at run time or
2348 using third party provider groups may result in handshake failures. TLSv1.3
2349 can be disabled at compile time using the "no-tls1_3" Configure option.
2353 SSL_CTX_set_ciphersuites() and SSL_set_ciphersuites() changes.
2355 The methods now ignore unknown ciphers.
2359 Security callback change.
2361 The security callback, which can be customised by application code, supports
2362 the security operation SSL_SECOP_TMP_DH. This is defined to take an EVP_PKEY
2363 in the "other" parameter. In most places this is what is passed. All these
2364 places occur server side. However there was one client side call of this
2365 security operation and it passed a DH object instead. This is incorrect
2366 according to the definition of SSL_SECOP_TMP_DH, and is inconsistent with all
2367 of the other locations. Therefore this client side call has been changed to
2368 pass an EVP_PKEY instead.
2372 New SSL option SSL_OP_IGNORE_UNEXPECTED_EOF
2374 The SSL option SSL_OP_IGNORE_UNEXPECTED_EOF is introduced. If that option
2375 is set, an unexpected EOF is ignored, it pretends a close notify was received
2376 instead and so the returned error becomes SSL_ERROR_ZERO_RETURN.
2380 The security strength of SHA1 and MD5 based signatures in TLS has been reduced.
2382 This results in SSL 3, TLS 1.0, TLS 1.1 and DTLS 1.0 no longer
2383 working at the default security level of 1 and instead requires security
2384 level 0. The security level can be changed either using the cipher string
2385 with C<@SECLEVEL>, or calling L<SSL_CTX_set_security_level(3)>. This also means
2386 that where the signature algorithms extension is missing from a ClientHello
2387 then the handshake will fail in TLS 1.2 at security level 1. This is because,
2388 although this extension is optional, failing to provide one means that
2389 OpenSSL will fallback to a default set of signature algorithms. This default
2390 set requires the availability of SHA1.
2394 X509 certificates signed using SHA1 are no longer allowed at security level 1 and above.
2396 In TLS/SSL the default security level is 1. It can be set either using the cipher
2397 string with C<@SECLEVEL>, or calling L<SSL_CTX_set_security_level(3)>. If the
2398 leaf certificate is signed with SHA-1, a call to L<SSL_CTX_use_certificate(3)>
2399 will fail if the security level is not lowered first.
2400 Outside TLS/SSL, the default security level is -1 (effectively 0). It can
2401 be set using L<X509_VERIFY_PARAM_set_auth_level(3)> or using the B<-auth_level>
2402 options of the commands.
2412 Copyright 2021-2022 The OpenSSL Project Authors. All Rights Reserved.
2414 Licensed under the Apache License 2.0 (the "License"). You may not use
2415 this file except in compliance with the License. You can obtain a copy
2416 in the file LICENSE in the source distribution or at
2417 L<https://www.openssl.org/source/license.html>.