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 & 3.1. 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 3.0
23 The FIPS provider in OpenSSL 3.1 includes some non-FIPS validated algorithms,
24 consequently the property query C<fips=yes> is mandatory for applications that
25 want to operate in a FIPS approved manner. The algorithms are:
35 There are no other changes requiring additional migration measures since OpenSSL 3.0.
39 =head2 Main Changes from OpenSSL 1.1.1
43 OpenSSL 3.0 is a major release and consequently any application that currently
44 uses an older version of OpenSSL will at the very least need to be recompiled in
45 order to work with the new version. It is the intention that the large majority
46 of applications will work unchanged with OpenSSL 3.0 if those applications
47 previously worked with OpenSSL 1.1.1. However this is not guaranteed and some
48 changes may be required in some cases. Changes may also be required if
49 applications need to take advantage of some of the new features available in
50 OpenSSL 3.0 such as the availability of the FIPS module.
54 In previous versions, OpenSSL was licensed under the L<dual OpenSSL and SSLeay
55 licenses|https://www.openssl.org/source/license-openssl-ssleay.txt>
56 (both licenses apply). From OpenSSL 3.0 this is replaced by the
57 L<Apache License v2|https://www.openssl.org/source/apache-license-2.0.txt>.
59 =head3 Providers and FIPS support
61 One of the key changes from OpenSSL 1.1.1 is the introduction of the Provider
62 concept. Providers collect together and make available algorithm implementations.
63 With OpenSSL 3.0 it is possible to specify, either programmatically or via a
64 config file, which providers you want to use for any given application.
65 OpenSSL 3.0 comes with 5 different providers as standard. Over time third
66 parties may distribute additional providers that can be plugged into OpenSSL.
67 All algorithm implementations available via providers are accessed through the
68 "high level" APIs (for example those functions prefixed with C<EVP>). They cannot
69 be accessed using the L</Low Level APIs>.
71 One of the standard providers available is the FIPS provider. This makes
72 available FIPS validated cryptographic algorithms.
73 The FIPS provider is disabled by default and needs to be enabled explicitly
74 at configuration time using the C<enable-fips> option. If it is enabled,
75 the FIPS provider gets built and installed in addition to the other standard
76 providers. No separate installation procedure is necessary.
77 There is however a dedicated C<install_fips> make target, which serves the
78 special purpose of installing only the FIPS provider into an existing
81 Not all algorithms may be available for the application at a particular moment.
82 If the application code uses any digest or cipher algorithm via the EVP interface,
83 the application should verify the result of the L<EVP_EncryptInit(3)>,
84 L<EVP_EncryptInit_ex(3)>, and L<EVP_DigestInit(3)> functions. In case when
85 the requested algorithm is not available, these functions will fail.
87 See also L</Legacy Algorithms> for information on the legacy provider.
89 See also L</Completing the installation of the FIPS Module> and
90 L</Using the FIPS Module in applications>.
94 OpenSSL has historically provided two sets of APIs for invoking cryptographic
95 algorithms: the "high level" APIs (such as the C<EVP> APIs) and the "low level"
96 APIs. The high level APIs are typically designed to work across all algorithm
97 types. The "low level" APIs are targeted at a specific algorithm implementation.
98 For example, the EVP APIs provide the functions L<EVP_EncryptInit_ex(3)>,
99 L<EVP_EncryptUpdate(3)> and L<EVP_EncryptFinal(3)> to perform symmetric
100 encryption. Those functions can be used with the algorithms AES, CHACHA, 3DES etc.
101 On the other hand, to do AES encryption using the low level APIs you would have
102 to call AES specific functions such as L<AES_set_encrypt_key(3)>,
103 L<AES_encrypt(3)>, and so on. The functions for 3DES are different.
104 Use of the low level APIs has been informally discouraged by the OpenSSL
105 development team for a long time. However in OpenSSL 3.0 this is made more
106 formal. All such low level APIs have been deprecated. You may still use them in
107 your applications, but you may start to see deprecation warnings during
108 compilation (dependent on compiler support for this). Deprecated APIs may be
109 removed from future versions of OpenSSL so you are strongly encouraged to update
110 your code to use the high level APIs instead.
112 This is described in more detail in L</Deprecation of Low Level Functions>
114 =head3 Legacy Algorithms
116 Some cryptographic algorithms such as B<MD2> and B<DES> that were available via
117 the EVP APIs are now considered legacy and their use is strongly discouraged.
118 These legacy EVP algorithms are still available in OpenSSL 3.0 but not by
119 default. If you want to use them then you must load the legacy provider.
120 This can be as simple as a config file change, or can be done programmatically.
121 See L<OSSL_PROVIDER-legacy(7)> for a complete list of algorithms.
122 Applications using the EVP APIs to access these algorithms should instead use
123 more modern algorithms. If that is not possible then these applications
124 should ensure that the legacy provider has been loaded. This can be achieved
125 either programmatically or via configuration. See L<crypto(7)> man page for
126 more information about providers.
128 =head3 Engines and "METHOD" APIs
130 The refactoring to support Providers conflicts internally with the APIs used to
131 support engines, including the ENGINE API and any function that creates or
132 modifies custom "METHODS" (for example L<EVP_MD_meth_new(3)>,
133 L<EVP_CIPHER_meth_new(3)>, L<EVP_PKEY_meth_new(3)>, L<RSA_meth_new(3)>,
134 L<EC_KEY_METHOD_new(3)>, etc.). These functions are being deprecated in
135 OpenSSL 3.0, and users of these APIs should know that their use can likely
136 bypass provider selection and configuration, with unintended consequences.
137 This is particularly relevant for applications written to use the OpenSSL 3.0
138 FIPS module, as detailed below. Authors and maintainers of external engines are
139 strongly encouraged to refactor their code transforming engines into providers
140 using the new Provider API and avoiding deprecated methods.
142 =head3 Support of legacy engines
144 If openssl is not built without engine support or deprecated API support, engines
145 will still work. However, their applicability will be limited.
147 New algorithms provided via engines will still work.
149 Engine-backed keys can be loaded via custom B<OSSL_STORE> implementation.
150 In this case the B<EVP_PKEY> objects created via L<ENGINE_load_private_key(3)>
151 will be considered legacy and will continue to work.
153 To ensure the future compatibility, the engines should be turned to providers.
154 To prefer the provider-based hardware offload, you can specify the default
155 properties to prefer your provider.
157 =head3 Versioning Scheme
159 The OpenSSL versioning scheme has changed with the OpenSSL 3.0 release. The new
160 versioning scheme has this format:
164 For OpenSSL 1.1.1 and below, different patch levels were indicated by a letter
165 at the end of the release version number. This will no longer be used and
166 instead the patch level is indicated by the final number in the version. A
167 change in the second (MINOR) number indicates that new features may have been
168 added. OpenSSL versions with the same major number are API and ABI compatible.
169 If the major number changes then API and ABI compatibility is not guaranteed.
171 For more information, see L<OpenSSL_version(3)>.
173 =head3 Other major new features
175 =head4 Certificate Management Protocol (CMP, RFC 4210)
177 This also covers CRMF (RFC 4211) and HTTP transfer (RFC 6712)
178 See L<openssl-cmp(1)> and L<OSSL_CMP_exec_certreq(3)> as starting points.
180 =head4 HTTP(S) client
182 A proper HTTP(S) client that supports GET and POST, redirection, plain and
183 ASN.1-encoded contents, proxies, and timeouts.
185 =head4 Key Derivation Function API (EVP_KDF)
187 This simplifies the process of adding new KDF and PRF implementations.
189 Previously KDF algorithms had been shoe-horned into using the EVP_PKEY object
190 which was not a logical mapping.
191 Existing applications that use KDF algorithms using EVP_PKEY
192 (scrypt, TLS1 PRF and HKDF) may be slower as they use an EVP_KDF bridge
194 All new applications should use the new L<EVP_KDF(3)> interface.
195 See also L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)> and
196 L<OSSL_PROVIDER-FIPS(7)/Key Derivation Function (KDF)>.
198 =head4 Message Authentication Code API (EVP_MAC)
200 This simplifies the process of adding MAC implementations.
202 This includes a generic EVP_PKEY to EVP_MAC bridge, to facilitate the continued
203 use of MACs through raw private keys in functionality such as
204 L<EVP_DigestSign(3)> and L<EVP_DigestVerify(3)>.
206 All new applications should use the new L<EVP_MAC(3)> interface.
207 See also L<OSSL_PROVIDER-default(7)/Message Authentication Code (MAC)>
208 and L<OSSL_PROVIDER-FIPS(7)/Message Authentication Code (MAC)>.
210 =head4 Support for Linux Kernel TLS
212 In order to use KTLS, support for it must be compiled in using the
213 C<enable-ktls> configuration option. It must also be enabled at run time using
214 the B<SSL_OP_ENABLE_KTLS> option.
216 =head4 New Algorithms
222 KDF algorithms "SINGLE STEP" and "SSH"
224 See L<EVP_KDF-SS(7)> and L<EVP_KDF-SSHKDF(7)>
228 MAC Algorithms "GMAC" and "KMAC"
230 See L<EVP_MAC-GMAC(7)> and L<EVP_MAC-KMAC(7)>.
234 KEM Algorithm "RSASVE"
236 See L<EVP_KEM-RSA(7)>.
240 Cipher Algorithm "AES-SIV"
242 See L<EVP_EncryptInit(3)/SIV Mode>.
246 AES Key Wrap inverse ciphers supported by EVP layer.
248 The inverse ciphers use AES decryption for wrapping, and AES encryption for
249 unwrapping. The algorithms are: "AES-128-WRAP-INV", "AES-192-WRAP-INV",
250 "AES-256-WRAP-INV", "AES-128-WRAP-PAD-INV", "AES-192-WRAP-PAD-INV" and
251 "AES-256-WRAP-PAD-INV".
255 CTS ciphers added to EVP layer.
257 The algorithms are "AES-128-CBC-CTS", "AES-192-CBC-CTS", "AES-256-CBC-CTS",
258 "CAMELLIA-128-CBC-CTS", "CAMELLIA-192-CBC-CTS" and "CAMELLIA-256-CBC-CTS".
259 CS1, CS2 and CS3 variants are supported.
263 =head4 CMS and PKCS#7 updates
269 Added CAdES-BES signature verification support.
273 Added CAdES-BES signature scheme and attributes support (RFC 5126) to CMS API.
277 Added AuthEnvelopedData content type structure (RFC 5083) using AES_GCM
279 This uses the AES-GCM parameter (RFC 5084) for the Cryptographic Message Syntax.
280 Its purpose is to support encryption and decryption of a digital envelope that
281 is both authenticated and encrypted using AES GCM mode.
285 L<PKCS7_get_octet_string(3)> and L<PKCS7_type_is_other(3)> were made public.
289 =head4 PKCS#12 API updates
291 The default algorithms for pkcs12 creation with the PKCS12_create() function
292 were changed to more modern PBKDF2 and AES based algorithms. The default
293 MAC iteration count was changed to PKCS12_DEFAULT_ITER to make it equal
294 with the password-based encryption iteration count. The default digest
295 algorithm for the MAC computation was changed to SHA-256. The pkcs12
296 application now supports -legacy option that restores the previous
297 default algorithms to support interoperability with legacy systems.
299 Added enhanced PKCS#12 APIs which accept a library context B<OSSL_LIB_CTX>
300 and (where relevant) a property query. Other APIs which handle PKCS#7 and
301 PKCS#8 objects have also been enhanced where required. This includes:
303 L<PKCS12_add_key_ex(3)>, L<PKCS12_add_safe_ex(3)>, L<PKCS12_add_safes_ex(3)>,
304 L<PKCS12_create_ex(3)>, L<PKCS12_decrypt_skey_ex(3)>, L<PKCS12_init_ex(3)>,
305 L<PKCS12_item_decrypt_d2i_ex(3)>, L<PKCS12_item_i2d_encrypt_ex(3)>,
306 L<PKCS12_key_gen_asc_ex(3)>, L<PKCS12_key_gen_uni_ex(3)>, L<PKCS12_key_gen_utf8_ex(3)>,
307 L<PKCS12_pack_p7encdata_ex(3)>, L<PKCS12_pbe_crypt_ex(3)>, L<PKCS12_PBE_keyivgen_ex(3)>,
308 L<PKCS12_SAFEBAG_create_pkcs8_encrypt_ex(3)>, L<PKCS5_pbe2_set_iv_ex(3)>,
309 L<PKCS5_pbe_set0_algor_ex(3)>, L<PKCS5_pbe_set_ex(3)>, L<PKCS5_pbkdf2_set_ex(3)>,
310 L<PKCS5_v2_PBE_keyivgen_ex(3)>, L<PKCS5_v2_scrypt_keyivgen_ex(3)>,
311 L<PKCS8_decrypt_ex(3)>, L<PKCS8_encrypt_ex(3)>, L<PKCS8_set0_pbe_ex(3)>.
313 As part of this change the EVP_PBE_xxx APIs can also accept a library
314 context and property query and will call an extended version of the key/IV
315 derivation function which supports these parameters. This includes
316 L<EVP_PBE_CipherInit_ex(3)>, L<EVP_PBE_find_ex(3)> and L<EVP_PBE_scrypt_ex(3)>.
318 =head4 Windows thread synchronization changes
320 Windows thread synchronization uses read/write primitives (SRWLock) when
321 supported by the OS, otherwise CriticalSection continues to be used.
325 A new generic trace API has been added which provides support for enabling
326 instrumentation through trace output. This feature is mainly intended as an aid
327 for developers and is disabled by default. To utilize it, OpenSSL needs to be
328 configured with the C<enable-trace> option.
330 If the tracing API is enabled, the application can activate trace output by
331 registering BIOs as trace channels for a number of tracing and debugging
332 categories. See L<OSSL_trace_enabled(3)>.
334 =head4 Key validation updates
336 L<EVP_PKEY_public_check(3)> and L<EVP_PKEY_param_check(3)> now work for
337 more key types. This includes RSA, DSA, ED25519, X25519, ED448 and X448.
338 Previously (in 1.1.1) they would return -2. For key types that do not have
339 parameters then L<EVP_PKEY_param_check(3)> will always return 1.
341 =head3 Other notable deprecations and changes
343 =head4 The function code part of an OpenSSL error code is no longer relevant
345 This code is now always set to zero. Related functions are deprecated.
347 =head4 STACK and HASH macros have been cleaned up
349 The type-safe wrappers are declared everywhere and implemented once.
350 See L<DEFINE_STACK_OF(3)> and L<DEFINE_LHASH_OF_EX(3)>.
352 =head4 The RAND_DRBG subsystem has been removed
354 The new L<EVP_RAND(3)> is a partial replacement: the DRBG callback framework is
355 absent. The RAND_DRBG API did not fit well into the new provider concept as
356 implemented by EVP_RAND and EVP_RAND_CTX.
358 =head4 Removed FIPS_mode() and FIPS_mode_set()
360 These functions are legacy APIs that are not applicable to the new provider
361 model. Applications should instead use
362 L<EVP_default_properties_is_fips_enabled(3)> and
363 L<EVP_default_properties_enable_fips(3)>.
365 =head4 Key generation is slower
367 The Miller-Rabin test now uses 64 rounds, which is used for all prime generation,
368 including RSA key generation. This affects the time for larger keys sizes.
370 The default key generation method for the regular 2-prime RSA keys was changed
371 to the FIPS186-4 B.3.6 method (Generation of Probable Primes with Conditions
372 Based on Auxiliary Probable Primes). This method is slower than the original
375 =head4 Change PBKDF2 to conform to SP800-132 instead of the older PKCS5 RFC2898
377 This checks that the salt length is at least 128 bits, the derived key length is
378 at least 112 bits, and that the iteration count is at least 1000.
379 For backwards compatibility these checks are disabled by default in the
380 default provider, but are enabled by default in the FIPS provider.
382 To enable or disable the checks see B<OSSL_KDF_PARAM_PKCS5> in
383 L<EVP_KDF-PBKDF2(7)>. The parameter can be set using L<EVP_KDF_derive(3)>.
385 =head4 Enforce a minimum DH modulus size of 512 bits
387 Smaller sizes now result in an error.
389 =head4 SM2 key changes
391 EC EVP_PKEYs with the SM2 curve have been reworked to automatically become
392 EVP_PKEY_SM2 rather than EVP_PKEY_EC.
394 Unlike in previous OpenSSL versions, this means that applications cannot
395 call C<EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2)> to get SM2 computations.
397 Parameter and key generation is also reworked to make it possible
398 to generate EVP_PKEY_SM2 parameters and keys. Applications must now generate
399 SM2 keys directly and must not create an EVP_PKEY_EC key first. It is no longer
400 possible to import an SM2 key with domain parameters other than the SM2 elliptic
403 Validation of SM2 keys has been separated from the validation of regular EC
404 keys, allowing to improve the SM2 validation process to reject loaded private
405 keys that are not conforming to the SM2 ISO standard.
406 In particular, a private scalar I<k> outside the range I<< 1 <= k < n-1 >> is
407 now correctly rejected.
409 =head4 EVP_PKEY_set_alias_type() method has been removed
411 This function made a B<EVP_PKEY> object mutable after it had been set up. In
412 OpenSSL 3.0 it was decided that a provided key should not be able to change its
413 type, so this function has been removed.
415 =head4 Functions that return an internal key should be treated as read only
417 Functions such as L<EVP_PKEY_get0_RSA(3)> behave slightly differently in
418 OpenSSL 3.0. Previously they returned a pointer to the low-level key used
419 internally by libcrypto. From OpenSSL 3.0 this key may now be held in a
420 provider. Calling these functions will only return a handle on the internal key
421 where the EVP_PKEY was constructed using this key in the first place, for
422 example using a function or macro such as L<EVP_PKEY_assign_RSA(3)>,
423 L<EVP_PKEY_set1_RSA(3)>, etc.
424 Where the EVP_PKEY holds a provider managed key, then these functions now return
425 a cached copy of the key. Changes to the internal provider key that take place
426 after the first time the cached key is accessed will not be reflected back in
427 the cached copy. Similarly any changes made to the cached copy by application
428 code will not be reflected back in the internal provider key.
430 For the above reasons the keys returned from these functions should typically be
431 treated as read-only. To emphasise this the value returned from
432 L<EVP_PKEY_get0_RSA(3)>, L<EVP_PKEY_get0_DSA(3)>, L<EVP_PKEY_get0_EC_KEY(3)> and
433 L<EVP_PKEY_get0_DH(3)> have been made const. This may break some existing code.
434 Applications broken by this change should be modified. The preferred solution is
435 to refactor the code to avoid the use of these deprecated functions. Failing
436 this the code should be modified to use a const pointer instead.
437 The L<EVP_PKEY_get1_RSA(3)>, L<EVP_PKEY_get1_DSA(3)>, L<EVP_PKEY_get1_EC_KEY(3)>
438 and L<EVP_PKEY_get1_DH(3)> functions continue to return a non-const pointer to
439 enable them to be "freed". However they should also be treated as read-only.
441 =head4 The public key check has moved from EVP_PKEY_derive() to EVP_PKEY_derive_set_peer()
443 This may mean result in an error in L<EVP_PKEY_derive_set_peer(3)> rather than
444 during L<EVP_PKEY_derive(3)>.
445 To disable this check use EVP_PKEY_derive_set_peer_ex(dh, peer, 0).
447 =head4 The print format has cosmetic changes for some functions
449 The output from numerous "printing" functions such as L<X509_signature_print(3)>,
450 L<X509_print_ex(3)>, L<X509_CRL_print_ex(3)>, and other similar functions has been
451 amended such that there may be cosmetic differences between the output
452 observed in 1.1.1 and 3.0. This also applies to the B<-text> output from the
453 B<openssl x509> and B<openssl crl> applications.
455 =head4 Interactive mode from the B<openssl> program has been removed
457 From now on, running it without arguments is equivalent to B<openssl help>.
459 =head4 The error return values from some control calls (ctrl) have changed
461 One significant change is that controls which used to return -2 for
462 invalid inputs, now return -1 indicating a generic error condition instead.
464 =head4 DH and DHX key types have different settable parameters
466 Previously (in 1.1.1) these conflicting parameters were allowed, but will now
467 result in errors. See L<EVP_PKEY-DH(7)> for further details. This affects the
468 behaviour of L<openssl-genpkey(1)> for DH parameter generation.
470 =head4 EVP_CIPHER_CTX_set_flags() ordering change
472 If using a cipher from a provider the B<EVP_CIPH_FLAG_LENGTH_BITS> flag can only
473 be set B<after> the cipher has been assigned to the cipher context.
474 See L<EVP_EncryptInit(3)/FLAGS> for more information.
476 =head4 Validation of operation context parameters
478 Due to move of the implementation of cryptographic operations to the
479 providers, validation of various operation parameters can be postponed until
480 the actual operation is executed where previously it happened immediately
481 when an operation parameter was set.
483 For example when setting an unsupported curve with
484 EVP_PKEY_CTX_set_ec_paramgen_curve_nid() this function call will not fail
485 but later keygen operations with the EVP_PKEY_CTX will fail.
487 =head4 Removal of function code from the error codes
489 The function code part of the error code is now always set to 0. For that
490 reason the ERR_GET_FUNC() macro was removed. Applications must resolve
491 the error codes only using the library number and the reason code.
493 =head2 Installation and Compilation
495 Please refer to the INSTALL.md file in the top of the distribution for
496 instructions on how to build and install OpenSSL 3.0. Please also refer to the
497 various platform specific NOTES files for your specific platform.
499 =head2 Upgrading from OpenSSL 1.1.1
501 Upgrading to OpenSSL 3.0 from OpenSSL 1.1.1 should be relatively straight
502 forward in most cases. The most likely area where you will encounter problems
503 is if you have used low level APIs in your code (as discussed above). In that
504 case you are likely to start seeing deprecation warnings when compiling your
505 application. If this happens you have 3 options:
511 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.
515 Suppress the warnings. Refer to your compiler documentation on how to do this.
519 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
523 =head3 Error code changes
525 As OpenSSL 3.0 provides a brand new Encoder/Decoder mechanism for working with
526 widely used file formats, application code that checks for particular error
527 reason codes on key loading failures might need an update.
529 Password-protected keys may deserve special attention. If only some errors
530 are treated as an indicator that the user should be asked about the password again,
531 it's worth testing these scenarios and processing the newly relevant codes.
533 There may be more cases to treat specially, depending on the calling application code.
535 =head2 Upgrading from OpenSSL 1.0.2
537 Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 is likely to be significantly more
538 difficult. In addition to the issues discussed above in the section about
539 L</Upgrading from OpenSSL 1.1.1>, the main things to be aware of are:
545 The build and installation procedure has changed significantly.
547 Check the file INSTALL.md in the top of the installation for instructions on how
548 to build and install OpenSSL for your platform. Also read the various NOTES
549 files in the same directory, as applicable for your platform.
553 Many structures have been made opaque in OpenSSL 3.0.
555 The structure definitions have been removed from the public header files and
556 moved to internal header files. In practice this means that you can no longer
557 stack allocate some structures. Instead they must be heap allocated through some
558 function call (typically those function names have a C<_new> suffix to them).
559 Additionally you must use "setter" or "getter" functions to access the fields
560 within those structures.
562 For example code that previously looked like this:
566 /* This line will now generate compiler errors */
567 EVP_MD_CTX_init(&md_ctx);
569 The code needs to be amended to look like this:
573 md_ctx = EVP_MD_CTX_new();
576 EVP_MD_CTX_free(md_ctx);
580 Support for TLSv1.3 has been added.
582 This has a number of implications for SSL/TLS applications. See the
583 L<TLS1.3 page|https://wiki.openssl.org/index.php/TLS1.3> for further details.
587 More details about the breaking changes between OpenSSL versions 1.0.2 and 1.1.0
589 L<OpenSSL 1.1.0 Changes page|https://wiki.openssl.org/index.php/OpenSSL_1.1.0_Changes>.
591 =head3 Upgrading from the OpenSSL 2.0 FIPS Object Module
593 The OpenSSL 2.0 FIPS Object Module was a separate download that had to be built
594 separately and then integrated into your main OpenSSL 1.0.2 build.
595 In OpenSSL 3.0 the FIPS support is fully integrated into the mainline version of
596 OpenSSL and is no longer a separate download. For further information see
597 L</Completing the installation of the FIPS Module>.
599 The function calls FIPS_mode() and FIPS_mode_set() have been removed
600 from OpenSSL 3.0. You should rewrite your application to not use them.
601 See L<fips_module(7)> and L<OSSL_PROVIDER-FIPS(7)> for details.
603 =head2 Completing the installation of the FIPS Module
605 The FIPS Module will be built and installed automatically if FIPS support has
606 been configured. The current documentation can be found in the
607 L<README-FIPS|https://github.com/openssl/openssl/blob/master/README-FIPS.md> file.
611 Applications written to work with OpenSSL 1.1.1 will mostly just work with
612 OpenSSL 3.0. However changes will be required if you want to take advantage of
613 some of the new features that OpenSSL 3.0 makes available. In order to do that
614 you need to understand some new concepts introduced in OpenSSL 3.0.
615 Read L<crypto(7)/Library contexts> for further information.
617 =head3 Library Context
619 A library context allows different components of a complex application to each
620 use a different library context and have different providers loaded with
621 different configuration settings.
622 See L<crypto(7)/Library contexts> for further info.
624 If the user creates an B<OSSL_LIB_CTX> via L<OSSL_LIB_CTX_new(3)> then many
625 functions may need to be changed to pass additional parameters to handle the
628 =head4 Using a Library Context - Old functions that should be changed
630 If a library context is needed then all EVP_* digest functions that return a
631 B<const EVP_MD *> such as EVP_sha256() should be replaced with a call to
632 L<EVP_MD_fetch(3)>. See L<crypto(7)/ALGORITHM FETCHING>.
634 If a library context is needed then all EVP_* cipher functions that return a
635 B<const EVP_CIPHER *> such as EVP_aes_128_cbc() should be replaced vith a call to
636 L<EVP_CIPHER_fetch(3)>. See L<crypto(7)/ALGORITHM FETCHING>.
638 Some functions can be passed an object that has already been set up with a library
639 context such as L<d2i_X509(3)>, L<d2i_X509_CRL(3)>, L<d2i_X509_REQ(3)> and
640 L<d2i_X509_PUBKEY(3)>. If NULL is passed instead then the created object will be
641 set up with the default library context. Use L<X509_new_ex(3)>,
642 L<X509_CRL_new_ex(3)>, L<X509_REQ_new_ex(3)> and L<X509_PUBKEY_new_ex(3)> if a
643 library context is required.
645 All functions listed below with a I<NAME> have a replacement function I<NAME_ex>
646 that takes B<OSSL_LIB_CTX> as an additional argument. Functions that have other
647 mappings are listed along with the respective name.
653 L<ASN1_item_new(3)>, L<ASN1_item_d2i(3)>, L<ASN1_item_d2i_fp(3)>,
654 L<ASN1_item_d2i_bio(3)>, L<ASN1_item_sign(3)> and L<ASN1_item_verify(3)>
662 b2i_RSA_PVK_bio() and i2b_PVK_bio()
666 L<BN_CTX_new(3)> and L<BN_CTX_secure_new(3)>
670 L<CMS_AuthEnvelopedData_create(3)>, L<CMS_ContentInfo_new(3)>, L<CMS_data_create(3)>,
671 L<CMS_digest_create(3)>, L<CMS_EncryptedData_encrypt(3)>, L<CMS_encrypt(3)>,
672 L<CMS_EnvelopedData_create(3)>, L<CMS_ReceiptRequest_create0(3)> and L<CMS_sign(3)>
676 L<CONF_modules_load_file(3)>
680 L<CTLOG_new(3)>, L<CTLOG_new_from_base64(3)> and L<CTLOG_STORE_new(3)>
684 L<CT_POLICY_EVAL_CTX_new(3)>
688 L<d2i_AutoPrivateKey(3)>, L<d2i_PrivateKey(3)> and L<d2i_PUBKEY(3)>
692 L<d2i_PrivateKey_bio(3)> and L<d2i_PrivateKey_fp(3)>
694 Use L<d2i_PrivateKey_ex_bio(3)> and L<d2i_PrivateKey_ex_fp(3)>
700 Use L<EC_GROUP_new_by_curve_name_ex(3)> or L<EC_GROUP_new_from_params(3)>.
704 L<EVP_DigestSignInit(3)> and L<EVP_DigestVerifyInit(3)>
708 L<EVP_PBE_CipherInit(3)>, L<EVP_PBE_find(3)> and L<EVP_PBE_scrypt(3)>
712 L<PKCS5_PBE_keyivgen(3)>
720 L<EVP_PKEY_CTX_new_id(3)>
722 Use L<EVP_PKEY_CTX_new_from_name(3)>
726 L<EVP_PKEY_derive_set_peer(3)>, L<EVP_PKEY_new_raw_private_key(3)>
727 and L<EVP_PKEY_new_raw_public_key(3)>
731 L<EVP_SignFinal(3)> and L<EVP_VerifyFinal(3)>
739 L<OCSP_RESPID_match(3)> and L<OCSP_RESPID_set_by_key(3)>
743 L<OPENSSL_thread_stop(3)>
747 L<OSSL_STORE_open(3)>
751 L<PEM_read_bio_Parameters(3)>, L<PEM_read_bio_PrivateKey(3)>, L<PEM_read_bio_PUBKEY(3)>,
752 L<PEM_read_PrivateKey(3)> and L<PEM_read_PUBKEY(3)>
756 L<PEM_write_bio_PrivateKey(3)>, L<PEM_write_bio_PUBKEY(3)>, L<PEM_write_PrivateKey(3)>
757 and L<PEM_write_PUBKEY(3)>
761 L<PEM_X509_INFO_read_bio(3)> and L<PEM_X509_INFO_read(3)>
765 L<PKCS12_add_key(3)>, L<PKCS12_add_safe(3)>, L<PKCS12_add_safes(3)>,
766 L<PKCS12_create(3)>, L<PKCS12_decrypt_skey(3)>, L<PKCS12_init(3)>, L<PKCS12_item_decrypt_d2i(3)>,
767 L<PKCS12_item_i2d_encrypt(3)>, L<PKCS12_key_gen_asc(3)>, L<PKCS12_key_gen_uni(3)>,
768 L<PKCS12_key_gen_utf8(3)>, L<PKCS12_pack_p7encdata(3)>, L<PKCS12_pbe_crypt(3)>,
769 L<PKCS12_PBE_keyivgen(3)>, L<PKCS12_SAFEBAG_create_pkcs8_encrypt(3)>
773 L<PKCS5_pbe_set0_algor(3)>, L<PKCS5_pbe_set(3)>, L<PKCS5_pbe2_set_iv(3)>,
774 L<PKCS5_pbkdf2_set(3)> and L<PKCS5_v2_scrypt_keyivgen(3)>
778 L<PKCS7_encrypt(3)>, L<PKCS7_new(3)> and L<PKCS7_sign(3)>
782 L<PKCS8_decrypt(3)>, L<PKCS8_encrypt(3)> and L<PKCS8_set0_pbe(3)>
786 L<RAND_bytes(3)> and L<RAND_priv_bytes(3)>
790 L<SMIME_write_ASN1(3)>
794 L<SSL_load_client_CA_file(3)>
802 L<TS_RESP_CTX_new(3)>
810 L<X509_load_cert_crl_file(3)> and L<X509_load_cert_file(3)>
814 L<X509_LOOKUP_by_subject(3)> and L<X509_LOOKUP_ctrl(3)>
826 L<X509_REQ_new(3)> and L<X509_REQ_verify(3)>
830 L<X509_STORE_CTX_new(3)>, L<X509_STORE_set_default_paths(3)>, L<X509_STORE_load_file(3)>,
831 L<X509_STORE_load_locations(3)> and L<X509_STORE_load_store(3)>
835 =head4 New functions that use a Library context
837 The following functions can be passed a library context if required.
838 Passing NULL will use the default library context.
844 L<BIO_new_from_core_bio(3)>
848 L<EVP_ASYM_CIPHER_fetch(3)> and L<EVP_ASYM_CIPHER_do_all_provided(3)>
852 L<EVP_CIPHER_fetch(3)> and L<EVP_CIPHER_do_all_provided(3)>
856 L<EVP_default_properties_enable_fips(3)> and
857 L<EVP_default_properties_is_fips_enabled(3)>
861 L<EVP_KDF_fetch(3)> and L<EVP_KDF_do_all_provided(3)>
865 L<EVP_KEM_fetch(3)> and L<EVP_KEM_do_all_provided(3)>
869 L<EVP_KEYEXCH_fetch(3)> and L<EVP_KEYEXCH_do_all_provided(3)>
873 L<EVP_KEYMGMT_fetch(3)> and L<EVP_KEYMGMT_do_all_provided(3)>
877 L<EVP_MAC_fetch(3)> and L<EVP_MAC_do_all_provided(3)>
881 L<EVP_MD_fetch(3)> and L<EVP_MD_do_all_provided(3)>
885 L<EVP_PKEY_CTX_new_from_pkey(3)>
889 L<EVP_PKEY_Q_keygen(3)>
893 L<EVP_Q_mac(3)> and L<EVP_Q_digest(3)>
897 L<EVP_RAND(3)> and L<EVP_RAND_do_all_provided(3)>
901 L<EVP_set_default_properties(3)>
905 L<EVP_SIGNATURE_fetch(3)> and L<EVP_SIGNATURE_do_all_provided(3)>
909 L<OSSL_CMP_CTX_new(3)> and L<OSSL_CMP_SRV_CTX_new(3)>
913 L<OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert(3)>
917 L<OSSL_CRMF_MSG_create_popo(3)> and L<OSSL_CRMF_MSGS_verify_popo(3)>
921 L<OSSL_CRMF_pbm_new(3)> and L<OSSL_CRMF_pbmp_new(3)>
925 L<OSSL_DECODER_CTX_add_extra(3)> and L<OSSL_DECODER_CTX_new_for_pkey(3)>
929 L<OSSL_DECODER_fetch(3)> and L<OSSL_DECODER_do_all_provided(3)>
933 L<OSSL_ENCODER_CTX_add_extra(3)>
937 L<OSSL_ENCODER_fetch(3)> and L<OSSL_ENCODER_do_all_provided(3)>
941 L<OSSL_LIB_CTX_free(3)>, L<OSSL_LIB_CTX_load_config(3)> and L<OSSL_LIB_CTX_set0_default(3)>
945 L<OSSL_PROVIDER_add_builtin(3)>, L<OSSL_PROVIDER_available(3)>,
946 L<OSSL_PROVIDER_do_all(3)>, L<OSSL_PROVIDER_load(3)>,
947 L<OSSL_PROVIDER_set_default_search_path(3)> and L<OSSL_PROVIDER_try_load(3)>
951 L<OSSL_SELF_TEST_get_callback(3)> and L<OSSL_SELF_TEST_set_callback(3)>
955 L<OSSL_STORE_attach(3)>
959 L<OSSL_STORE_LOADER_fetch(3)> and L<OSSL_STORE_LOADER_do_all_provided(3)>
963 L<RAND_get0_primary(3)>, L<RAND_get0_private(3)>, L<RAND_get0_public(3)>,
964 L<RAND_set_DRBG_type(3)> and L<RAND_set_seed_source_type(3)>
970 Providers are described in detail here L<crypto(7)/Providers>.
971 See also L<crypto(7)/OPENSSL PROVIDERS>.
973 =head3 Fetching algorithms and property queries
975 Implicit and Explicit Fetching is described in detail here
976 L<crypto(7)/ALGORITHM FETCHING>.
978 =head3 Mapping EVP controls and flags to provider L<OSSL_PARAM(3)> parameters
980 The existing functions for controls (such as L<EVP_CIPHER_CTX_ctrl(3)>) and
981 manipulating flags (such as L<EVP_MD_CTX_set_flags(3)>)internally use
982 B<OSSL_PARAMS> to pass information to/from provider objects.
983 See L<OSSL_PARAM(3)> for additional information related to parameters.
985 For ciphers see L<EVP_EncryptInit(3)/CONTROLS>, L<EVP_EncryptInit(3)/FLAGS> and
986 L<EVP_EncryptInit(3)/PARAMETERS>.
988 For digests see L<EVP_DigestInit(3)/CONTROLS>, L<EVP_DigestInit(3)/FLAGS> and
989 L<EVP_DigestInit(3)/PARAMETERS>.
991 =head3 Deprecation of Low Level Functions
993 A significant number of APIs have been deprecated in OpenSSL 3.0.
994 This section describes some common categories of deprecations.
995 See L</Deprecated function mappings> for the list of deprecated functions
996 that refer to these categories.
998 =head4 Providers are a replacement for engines and low-level method overrides
1000 Any accessor that uses an ENGINE is deprecated (such as EVP_PKEY_set1_engine()).
1001 Applications using engines should instead use providers.
1003 Before providers were added algorithms were overridden by changing the methods
1004 used by algorithms. All these methods such as RSA_new_method() and RSA_meth_new()
1005 are now deprecated and can be replaced by using providers instead.
1007 =head4 Deprecated i2d and d2i functions for low-level key types
1009 Any i2d and d2i functions such as d2i_DHparams() that take a low-level key type
1010 have been deprecated. Applications should instead use the L<OSSL_DECODER(3)> and
1011 L<OSSL_ENCODER(3)> APIs to read and write files.
1012 See L<d2i_RSAPrivateKey(3)/Migration> for further details.
1014 =head4 Deprecated low-level key object getters and setters
1016 Applications that set or get low-level key objects (such as EVP_PKEY_set1_DH()
1017 or EVP_PKEY_get0()) should instead use the OSSL_ENCODER
1018 (See L<OSSL_ENCODER_to_bio(3)>) or OSSL_DECODER (See L<OSSL_DECODER_from_bio(3)>)
1019 APIs, or alternatively use L<EVP_PKEY_fromdata(3)> or L<EVP_PKEY_todata(3)>.
1021 =head4 Deprecated low-level key parameter getters
1023 Functions that access low-level objects directly such as L<RSA_get0_n(3)> are now
1024 deprecated. Applications should use one of L<EVP_PKEY_get_bn_param(3)>,
1025 L<EVP_PKEY_get_int_param(3)>, l<EVP_PKEY_get_size_t_param(3)>,
1026 L<EVP_PKEY_get_utf8_string_param(3)>, L<EVP_PKEY_get_octet_string_param(3)> or
1027 L<EVP_PKEY_get_params(3)> to access fields from an EVP_PKEY.
1028 Gettable parameters are listed in L<EVP_PKEY-RSA(7)/Common RSA parameters>,
1029 L<EVP_PKEY-DH(7)/DH parameters>, L<EVP_PKEY-DSA(7)/DSA parameters>,
1030 L<EVP_PKEY-FFC(7)/FFC parameters>, L<EVP_PKEY-EC(7)/Common EC parameters> and
1031 L<EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>.
1032 Applications may also use L<EVP_PKEY_todata(3)> to return all fields.
1034 =head4 Deprecated low-level key parameter setters
1036 Functions that access low-level objects directly such as L<RSA_set0_crt_params(3)>
1037 are now deprecated. Applications should use L<EVP_PKEY_fromdata(3)> to create
1038 new keys from user provided key data. Keys should be immutable once they are
1039 created, so if required the user may use L<EVP_PKEY_todata(3)>, L<OSSL_PARAM_merge(3)>,
1040 and L<EVP_PKEY_fromdata(3)> to create a modified key.
1041 See L<EVP_PKEY-DH(7)/Examples> for more information.
1042 See L</Deprecated low-level key generation functions> for information on
1043 generating a key using parameters.
1045 =head4 Deprecated low-level object creation
1047 Low-level objects were created using methods such as L<RSA_new(3)>,
1048 L<RSA_up_ref(3)> and L<RSA_free(3)>. Applications should instead use the
1049 high-level EVP_PKEY APIs, e.g. L<EVP_PKEY_new(3)>, L<EVP_PKEY_up_ref(3)> and
1050 L<EVP_PKEY_free(3)>.
1051 See also L<EVP_PKEY_CTX_new_from_name(3)> and L<EVP_PKEY_CTX_new_from_pkey(3)>.
1053 EVP_PKEYs may be created in a variety of ways:
1054 See also L</Deprecated low-level key generation functions>,
1055 L</Deprecated low-level key reading and writing functions> and
1056 L</Deprecated low-level key parameter setters>.
1058 =head4 Deprecated low-level encryption functions
1060 Low-level encryption functions such as L<AES_encrypt(3)> and L<AES_decrypt(3)>
1061 have been informally discouraged from use for a long time. Applications should
1062 instead use the high level EVP APIs L<EVP_EncryptInit_ex(3)>,
1063 L<EVP_EncryptUpdate(3)>, and L<EVP_EncryptFinal_ex(3)> or
1064 L<EVP_DecryptInit_ex(3)>, L<EVP_DecryptUpdate(3)> and L<EVP_DecryptFinal_ex(3)>.
1066 =head4 Deprecated low-level digest functions
1068 Use of low-level digest functions such as L<SHA1_Init(3)> have been
1069 informally discouraged from use for a long time. Applications should instead
1070 use the the high level EVP APIs L<EVP_DigestInit_ex(3)>, L<EVP_DigestUpdate(3)>
1071 and L<EVP_DigestFinal_ex(3)>, or the quick one-shot L<EVP_Q_digest(3)>.
1073 Note that the functions L<SHA1(3)>, L<SHA224(3)>, L<SHA256(3)>, L<SHA384(3)>
1074 and L<SHA512(3)> have changed to macros that use L<EVP_Q_digest(3)>.
1076 =head4 Deprecated low-level signing functions
1078 Use of low-level signing functions such as L<DSA_sign(3)> have been
1079 informally discouraged for a long time. Instead applications should use
1080 L<EVP_DigestSign(3)> and L<EVP_DigestVerify(3)>.
1081 See also L<EVP_SIGNATURE-RSA(7)>, L<EVP_SIGNATURE-DSA(7)>,
1082 L<EVP_SIGNATURE-ECDSA(7)> and L<EVP_SIGNATURE-ED25519(7)>.
1084 =head4 Deprecated low-level MAC functions
1086 Low-level mac functions such as L<CMAC_Init(3)> are deprecated.
1087 Applications should instead use the new L<EVP_MAC(3)> interface, using
1088 L<EVP_MAC_CTX_new(3)>, L<EVP_MAC_CTX_free(3)>, L<EVP_MAC_init(3)>,
1089 L<EVP_MAC_update(3)> and L<EVP_MAC_final(3)> or the single-shot MAC function
1091 See L<EVP_MAC(3)>, L<EVP_MAC-HMAC(7)>, L<EVP_MAC-CMAC(7)>, L<EVP_MAC-GMAC(7)>,
1092 L<EVP_MAC-KMAC(7)>, L<EVP_MAC-BLAKE2(7)>, L<EVP_MAC-Poly1305(7)> and
1093 L<EVP_MAC-Siphash(7)> for additional information.
1095 Note that the one-shot method HMAC() is still available for compatibility purposes,
1096 but this can also be replaced by using EVP_Q_MAC if a library context is required.
1098 =head4 Deprecated low-level validation functions
1100 Low-level validation functions such as L<DH_check(3)> have been informally
1101 discouraged from use for a long time. Applications should instead use the high-level
1102 EVP_PKEY APIs such as L<EVP_PKEY_check(3)>, L<EVP_PKEY_param_check(3)>,
1103 L<EVP_PKEY_param_check_quick(3)>, L<EVP_PKEY_public_check(3)>,
1104 L<EVP_PKEY_public_check_quick(3)>, L<EVP_PKEY_private_check(3)>,
1105 and L<EVP_PKEY_pairwise_check(3)>.
1107 =head4 Deprecated low-level key exchange functions
1109 Many low-level functions have been informally discouraged from use for a long
1110 time. Applications should instead use L<EVP_PKEY_derive(3)>.
1111 See L<EVP_KEYEXCH-DH(7)>, L<EVP_KEYEXCH-ECDH(7)> and L<EVP_KEYEXCH-X25519(7)>.
1113 =head4 Deprecated low-level key generation functions
1115 Many low-level functions have been informally discouraged from use for a long
1116 time. Applications should instead use L<EVP_PKEY_keygen_init(3)> and
1117 L<EVP_PKEY_generate(3)> as described in L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>,
1118 L<EVP_PKEY-RSA(7)>, L<EVP_PKEY-EC(7)> and L<EVP_PKEY-X25519(7)>.
1119 The 'quick' one-shot function L<EVP_PKEY_Q_keygen(3)> and macros for the most
1120 common cases: <EVP_RSA_gen(3)> and L<EVP_EC_gen(3)> may also be used.
1122 =head4 Deprecated low-level key reading and writing functions
1124 Use of low-level objects (such as DSA) has been informally discouraged from use
1125 for a long time. Functions to read and write these low-level objects (such as
1126 PEM_read_DSA_PUBKEY()) should be replaced. Applications should instead use
1127 L<OSSL_ENCODER_to_bio(3)> and L<OSSL_DECODER_from_bio(3)>.
1129 =head4 Deprecated low-level key printing functions
1131 Use of low-level objects (such as DSA) has been informally discouraged from use
1132 for a long time. Functions to print these low-level objects such as
1133 DSA_print() should be replaced with the equivalent EVP_PKEY functions.
1134 Application should use one of L<EVP_PKEY_print_public(3)>,
1135 L<EVP_PKEY_print_private(3)>, L<EVP_PKEY_print_params(3)>,
1136 L<EVP_PKEY_print_public_fp(3)>, L<EVP_PKEY_print_private_fp(3)> or
1137 L<EVP_PKEY_print_params_fp(3)>. Note that internally these use
1138 L<OSSL_ENCODER_to_bio(3)> and L<OSSL_DECODER_from_bio(3)>.
1140 =head3 Deprecated function mappings
1142 The following functions have been deprecated in 3.0.
1148 AES_bi_ige_encrypt() and AES_ige_encrypt()
1150 There is no replacement for the IGE functions. New code should not use these modes.
1151 These undocumented functions were never integrated into the EVP layer.
1152 They implemented the AES Infinite Garble Extension (IGE) mode and AES
1153 Bi-directional IGE mode. These modes were never formally standardised and
1154 usage of these functions is believed to be very small. In particular
1155 AES_bi_ige_encrypt() has a known bug. It accepts 2 AES keys, but only one
1156 is ever used. The security implications are believed to be minimal, but
1157 this issue was never fixed for backwards compatibility reasons.
1161 AES_encrypt(), AES_decrypt(), AES_set_encrypt_key(), AES_set_decrypt_key(),
1162 AES_cbc_encrypt(), AES_cfb128_encrypt(), AES_cfb1_encrypt(), AES_cfb8_encrypt(),
1163 AES_ecb_encrypt(), AES_ofb128_encrypt()
1167 AES_unwrap_key(), AES_wrap_key()
1169 See L</Deprecated low-level encryption functions>
1175 There is no replacement. It returned a string indicating if the AES code was unrolled.
1179 ASN1_digest(), ASN1_sign(), ASN1_verify()
1181 There are no replacements. These old functions are not used, and could be
1182 disabled with the macro NO_ASN1_OLD since OpenSSL 0.9.7.
1186 ASN1_STRING_length_set()
1188 Use L<ASN1_STRING_set(3)> or L<ASN1_STRING_set0(3)> instead.
1189 This was a potentially unsafe function that could change the bounds of a
1190 previously passed in pointer.
1194 BF_encrypt(), BF_decrypt(), BF_set_key(), BF_cbc_encrypt(), BF_cfb64_encrypt(),
1195 BF_ecb_encrypt(), BF_ofb64_encrypt()
1197 See L</Deprecated low-level encryption functions>.
1198 The Blowfish algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1204 There is no replacement. This option returned a constant string.
1208 BIO_get_callback(), BIO_set_callback(), BIO_debug_callback()
1210 Use the respective non-deprecated _ex() functions.
1214 BN_is_prime_ex(), BN_is_prime_fasttest_ex()
1216 Use L<BN_check_prime(3)> which avoids possible misuse and always uses at least
1217 64 rounds of the Miller-Rabin primality test.
1221 BN_pseudo_rand(), BN_pseudo_rand_range()
1223 Use L<BN_rand(3)> and L<BN_rand_range(3)>.
1227 BN_X931_derive_prime_ex(), BN_X931_generate_prime_ex(), BN_X931_generate_Xpq()
1229 There are no replacements for these low-level functions. They were used internally
1230 by RSA_X931_derive_ex() and RSA_X931_generate_key_ex() which are also deprecated.
1231 Use L<EVP_PKEY_keygen(3)> instead.
1235 Camellia_encrypt(), Camellia_decrypt(), Camellia_set_key(),
1236 Camellia_cbc_encrypt(), Camellia_cfb128_encrypt(), Camellia_cfb1_encrypt(),
1237 Camellia_cfb8_encrypt(), Camellia_ctr128_encrypt(), Camellia_ecb_encrypt(),
1238 Camellia_ofb128_encrypt()
1240 See L</Deprecated low-level encryption functions>.
1244 CAST_encrypt(), CAST_decrypt(), CAST_set_key(), CAST_cbc_encrypt(),
1245 CAST_cfb64_encrypt(), CAST_ecb_encrypt(), CAST_ofb64_encrypt()
1247 See L</Deprecated low-level encryption functions>.
1248 The CAST algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1252 CMAC_CTX_new(), CMAC_CTX_cleanup(), CMAC_CTX_copy(), CMAC_CTX_free(),
1253 CMAC_CTX_get0_cipher_ctx()
1255 See L</Deprecated low-level MAC functions>.
1259 CMAC_Init(), CMAC_Update(), CMAC_Final(), CMAC_resume()
1261 See L</Deprecated low-level MAC functions>.
1265 CRYPTO_mem_ctrl(), CRYPTO_mem_debug_free(), CRYPTO_mem_debug_malloc(),
1266 CRYPTO_mem_debug_pop(), CRYPTO_mem_debug_push(), CRYPTO_mem_debug_realloc(),
1267 CRYPTO_mem_leaks(), CRYPTO_mem_leaks_cb(), CRYPTO_mem_leaks_fp(),
1268 CRYPTO_set_mem_debug()
1270 Memory-leak checking has been deprecated in favor of more modern development
1271 tools, such as compiler memory and leak sanitizers or Valgrind.
1275 CRYPTO_cts128_encrypt_block(), CRYPTO_cts128_encrypt(),
1276 CRYPTO_cts128_decrypt_block(), CRYPTO_cts128_decrypt(),
1277 CRYPTO_nistcts128_encrypt_block(), CRYPTO_nistcts128_encrypt(),
1278 CRYPTO_nistcts128_decrypt_block(), CRYPTO_nistcts128_decrypt()
1280 Use the higher level functions EVP_CipherInit_ex2(), EVP_CipherUpdate() and
1281 EVP_CipherFinal_ex() instead.
1282 See the "cts_mode" parameter in
1283 L<EVP_EncryptInit(3)/Gettable and Settable EVP_CIPHER_CTX parameters>.
1284 See L<EVP_EncryptInit(3)/EXAMPLES> for a AES-256-CBC-CTS example.
1288 d2i_DHparams(), d2i_DHxparams(), d2i_DSAparams(), d2i_DSAPrivateKey(),
1289 d2i_DSAPrivateKey_bio(), d2i_DSAPrivateKey_fp(), d2i_DSA_PUBKEY(),
1290 d2i_DSA_PUBKEY_bio(), d2i_DSA_PUBKEY_fp(), d2i_DSAPublicKey(),
1291 d2i_ECParameters(), d2i_ECPrivateKey(), d2i_ECPrivateKey_bio(),
1292 d2i_ECPrivateKey_fp(), d2i_EC_PUBKEY(), d2i_EC_PUBKEY_bio(),
1293 d2i_EC_PUBKEY_fp(), o2i_ECPublicKey(), d2i_RSAPrivateKey(),
1294 d2i_RSAPrivateKey_bio(), d2i_RSAPrivateKey_fp(), d2i_RSA_PUBKEY(),
1295 d2i_RSA_PUBKEY_bio(), d2i_RSA_PUBKEY_fp(), d2i_RSAPublicKey(),
1296 d2i_RSAPublicKey_bio(), d2i_RSAPublicKey_fp()
1298 See L</Deprecated i2d and d2i functions for low-level key types>
1302 DES_crypt(), DES_fcrypt(), DES_encrypt1(), DES_encrypt2(), DES_encrypt3(),
1303 DES_decrypt3(), DES_ede3_cbc_encrypt(), DES_ede3_cfb64_encrypt(),
1304 DES_ede3_cfb_encrypt(),DES_ede3_ofb64_encrypt(),
1305 DES_ecb_encrypt(), DES_ecb3_encrypt(), DES_ofb64_encrypt(), DES_ofb_encrypt(),
1306 DES_cfb64_encrypt DES_cfb_encrypt(), DES_cbc_encrypt(), DES_ncbc_encrypt(),
1307 DES_pcbc_encrypt(), DES_xcbc_encrypt(), DES_cbc_cksum(), DES_quad_cksum(),
1308 DES_check_key_parity(), DES_is_weak_key(), DES_key_sched(), DES_options(),
1309 DES_random_key(), DES_set_key(), DES_set_key_checked(), DES_set_key_unchecked(),
1310 DES_set_odd_parity(), DES_string_to_2keys(), DES_string_to_key()
1312 See L</Deprecated low-level encryption functions>.
1313 Algorithms for "DESX-CBC", "DES-ECB", "DES-CBC", "DES-OFB", "DES-CFB",
1314 "DES-CFB1" and "DES-CFB8" have been moved to the L<Legacy Provider|/Legacy Algorithms>.
1318 DH_bits(), DH_security_bits(), DH_size()
1320 Use L<EVP_PKEY_get_bits(3)>, L<EVP_PKEY_get_security_bits(3)> and
1321 L<EVP_PKEY_get_size(3)>.
1325 DH_check(), DH_check_ex(), DH_check_params(), DH_check_params_ex(),
1326 DH_check_pub_key(), DH_check_pub_key_ex()
1328 See L</Deprecated low-level validation functions>
1332 DH_clear_flags(), DH_test_flags(), DH_set_flags()
1334 The B<DH_FLAG_CACHE_MONT_P> flag has been deprecated without replacement.
1335 The B<DH_FLAG_TYPE_DH> and B<DH_FLAG_TYPE_DHX> have been deprecated.
1336 Use EVP_PKEY_is_a() to determine the type of a key.
1337 There is no replacement for setting these flags.
1341 DH_compute_key() DH_compute_key_padded()
1343 See L</Deprecated low-level key exchange functions>.
1347 DH_new(), DH_new_by_nid(), DH_free(), DH_up_ref()
1349 See L</Deprecated low-level object creation>
1353 DH_generate_key(), DH_generate_parameters_ex()
1355 See L</Deprecated low-level key generation functions>.
1359 DH_get0_pqg(), DH_get0_p(), DH_get0_q(), DH_get0_g(), DH_get0_key(),
1360 DH_get0_priv_key(), DH_get0_pub_key(), DH_get_length(), DH_get_nid()
1362 See L</Deprecated low-level key parameter getters>
1366 DH_get_1024_160(), DH_get_2048_224(), DH_get_2048_256()
1368 Applications should instead set the B<OSSL_PKEY_PARAM_GROUP_NAME> as specified in
1369 L<EVP_PKEY-DH(7)/DH parameters>) to one of "dh_1024_160", "dh_2048_224" or
1370 "dh_2048_256" when generating a DH key.
1376 Applications should use L<EVP_PKEY_CTX_set_dh_kdf_type(3)> instead.
1380 DH_get_default_method(), DH_get0_engine(), DH_meth_*(), DH_new_method(),
1381 DH_OpenSSL(), DH_get_ex_data(), DH_set_default_method(), DH_set_method(),
1384 See L</Providers are a replacement for engines and low-level method overrides>
1388 DHparams_print(), DHparams_print_fp()
1390 See L</Deprecated low-level key printing functions>
1394 DH_set0_key(), DH_set0_pqg(), DH_set_length()
1396 See L</Deprecated low-level key parameter setters>
1400 DSA_bits(), DSA_security_bits(), DSA_size()
1402 Use L<EVP_PKEY_get_bits(3)>, L<EVP_PKEY_get_security_bits(3)> and
1403 L<EVP_PKEY_get_size(3)>.
1407 DHparams_dup(), DSA_dup_DH()
1409 There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)>
1410 and L<EVP_PKEY_dup(3)> instead.
1414 DSA_generate_key(), DSA_generate_parameters_ex()
1416 See L</Deprecated low-level key generation functions>.
1420 DSA_get0_engine(), DSA_get_default_method(), DSA_get_ex_data(),
1421 DSA_get_method(), DSA_meth_*(), DSA_new_method(), DSA_OpenSSL(),
1422 DSA_set_default_method(), DSA_set_ex_data(), DSA_set_method()
1424 See L</Providers are a replacement for engines and low-level method overrides>.
1428 DSA_get0_p(), DSA_get0_q(), DSA_get0_g(), DSA_get0_pqg(), DSA_get0_key(),
1429 DSA_get0_priv_key(), DSA_get0_pub_key()
1431 See L</Deprecated low-level key parameter getters>.
1435 DSA_new(), DSA_free(), DSA_up_ref()
1437 See L</Deprecated low-level object creation>
1443 There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)>
1444 and L<EVP_PKEY_dup(3)> instead.
1448 DSAparams_print(), DSAparams_print_fp(), DSA_print(), DSA_print_fp()
1450 See L</Deprecated low-level key printing functions>
1454 DSA_set0_key(), DSA_set0_pqg()
1456 See L</Deprecated low-level key parameter setters>
1460 DSA_set_flags(), DSA_clear_flags(), DSA_test_flags()
1462 The B<DSA_FLAG_CACHE_MONT_P> flag has been deprecated without replacement.
1466 DSA_sign(), DSA_do_sign(), DSA_sign_setup(), DSA_verify(), DSA_do_verify()
1468 See L</Deprecated low-level signing functions>.
1474 See L</Deprecated low-level key exchange functions>.
1480 Applications may either set this using the helper function
1481 L<EVP_PKEY_CTX_set_ecdh_kdf_type(3)> or by setting an L<OSSL_PARAM(3)> using the
1482 "kdf-type" as shown in L<EVP_KEYEXCH-ECDH(7)/EXAMPLES>
1486 ECDSA_sign(), ECDSA_sign_ex(), ECDSA_sign_setup(), ECDSA_do_sign(),
1487 ECDSA_do_sign_ex(), ECDSA_verify(), ECDSA_do_verify()
1489 See L</Deprecated low-level signing functions>.
1495 Applications should use L<EVP_PKEY_get_size(3)>.
1499 EC_GF2m_simple_method(), EC_GFp_mont_method(), EC_GFp_nist_method(),
1500 EC_GFp_nistp224_method(), EC_GFp_nistp256_method(), EC_GFp_nistp521_method(),
1501 EC_GFp_simple_method()
1503 There are no replacements for these functions. Applications should rely on the
1504 library automatically assigning a suitable method internally when an EC_GROUP
1509 EC_GROUP_clear_free()
1511 Use L<EC_GROUP_free(3)> instead.
1515 EC_GROUP_get_curve_GF2m(), EC_GROUP_get_curve_GFp(), EC_GROUP_set_curve_GF2m(),
1516 EC_GROUP_set_curve_GFp()
1518 Applications should use L<EC_GROUP_get_curve(3)> and L<EC_GROUP_set_curve(3)>.
1522 EC_GROUP_have_precompute_mult(), EC_GROUP_precompute_mult(),
1523 EC_KEY_precompute_mult()
1525 These functions are not widely used. Applications should instead switch to
1526 named curves which OpenSSL has hardcoded lookup tables for.
1530 EC_GROUP_new(), EC_GROUP_method_of(), EC_POINT_method_of()
1532 EC_METHOD is now an internal-only concept and a suitable EC_METHOD is assigned
1533 internally without application intervention.
1534 Users of EC_GROUP_new() should switch to a different suitable constructor.
1540 Applications should use L<EVP_PKEY_can_sign(3)> instead.
1546 See L</Deprecated low-level validation functions>
1550 EC_KEY_set_flags(), EC_KEY_get_flags(), EC_KEY_clear_flags()
1552 See L<EVP_PKEY-EC(7)/Common EC parameters> which handles flags as separate
1553 parameters for B<OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT>,
1554 B<OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE>, B<OSSL_PKEY_PARAM_EC_ENCODING>,
1555 B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH> and
1556 B<OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC>.
1557 See also L<EVP_PKEY-EC(7)/EXAMPLES>
1561 EC_KEY_dup(), EC_KEY_copy()
1563 There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)>
1564 and L<EVP_PKEY_dup(3)> instead.
1568 EC_KEY_decoded_from_explicit_params()
1570 There is no replacement.
1574 EC_KEY_generate_key()
1576 See L</Deprecated low-level key generation functions>.
1580 EC_KEY_get0_group(), EC_KEY_get0_private_key(), EC_KEY_get0_public_key(),
1581 EC_KEY_get_conv_form(), EC_KEY_get_enc_flags()
1583 See L</Deprecated low-level key parameter getters>.
1587 EC_KEY_get0_engine(), EC_KEY_get_default_method(), EC_KEY_get_method(),
1588 EC_KEY_new_method(), EC_KEY_get_ex_data(), EC_KEY_OpenSSL(),
1589 EC_KEY_set_ex_data(), EC_KEY_set_default_method(), EC_KEY_METHOD_*(),
1592 See L</Providers are a replacement for engines and low-level method overrides>
1596 EC_METHOD_get_field_type()
1598 Use L<EC_GROUP_get_field_type(3)> instead.
1599 See L</Providers are a replacement for engines and low-level method overrides>
1603 EC_KEY_key2buf(), EC_KEY_oct2key(), EC_KEY_oct2priv(), EC_KEY_priv2buf(),
1606 There are no replacements for these.
1610 EC_KEY_new(), EC_KEY_new_by_curve_name(), EC_KEY_free(), EC_KEY_up_ref()
1612 See L</Deprecated low-level object creation>
1616 EC_KEY_print(), EC_KEY_print_fp()
1618 See L</Deprecated low-level key printing functions>
1622 EC_KEY_set_asn1_flag(), EC_KEY_set_conv_form(), EC_KEY_set_enc_flags()
1624 See L</Deprecated low-level key parameter setters>.
1628 EC_KEY_set_group(), EC_KEY_set_private_key(), EC_KEY_set_public_key(),
1629 EC_KEY_set_public_key_affine_coordinates()
1631 See L</Deprecated low-level key parameter setters>.
1635 ECParameters_print(), ECParameters_print_fp(), ECPKParameters_print(),
1636 ECPKParameters_print_fp()
1638 See L</Deprecated low-level key printing functions>
1642 EC_POINT_bn2point(), EC_POINT_point2bn()
1644 These functions were not particularly useful, since EC point serialization
1645 formats are not individual big-endian integers.
1649 EC_POINT_get_affine_coordinates_GF2m(), EC_POINT_get_affine_coordinates_GFp(),
1650 EC_POINT_set_affine_coordinates_GF2m(), EC_POINT_set_affine_coordinates_GFp()
1652 Applications should use L<EC_POINT_get_affine_coordinates(3)> and
1653 L<EC_POINT_set_affine_coordinates(3)> instead.
1657 EC_POINT_get_Jprojective_coordinates_GFp(), EC_POINT_set_Jprojective_coordinates_GFp()
1659 These functions are not widely used. Applications should instead use the
1660 L<EC_POINT_set_affine_coordinates(3)> and L<EC_POINT_get_affine_coordinates(3)>
1665 EC_POINT_make_affine(), EC_POINTs_make_affine()
1667 There is no replacement. These functions were not widely used, and OpenSSL
1668 automatically performs this conversion when needed.
1672 EC_POINT_set_compressed_coordinates_GF2m(), EC_POINT_set_compressed_coordinates_GFp()
1674 Applications should use L<EC_POINT_set_compressed_coordinates(3)> instead.
1680 This function is not widely used. Applications should instead use the
1681 L<EC_POINT_mul(3)> function.
1687 All engine functions are deprecated. An engine should be rewritten as a provider.
1688 See L</Providers are a replacement for engines and low-level method overrides>.
1692 B<ERR_load_*()>, ERR_func_error_string(), ERR_get_error_line(),
1693 ERR_get_error_line_data(), ERR_get_state()
1695 OpenSSL now loads error strings automatically so these functions are not needed.
1699 ERR_peek_error_line_data(), ERR_peek_last_error_line_data()
1701 The new functions are L<ERR_peek_error_func(3)>, L<ERR_peek_last_error_func(3)>,
1702 L<ERR_peek_error_data(3)>, L<ERR_peek_last_error_data(3)>, L<ERR_get_error_all(3)>,
1703 L<ERR_peek_error_all(3)> and L<ERR_peek_last_error_all(3)>.
1704 Applications should use L<ERR_get_error_all(3)>, or pick information
1705 with ERR_peek functions and finish off with getting the error code by using
1706 L<ERR_get_error(3)>.
1710 EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_iv_noconst(), EVP_CIPHER_CTX_original_iv()
1712 Applications should instead use L<EVP_CIPHER_CTX_get_updated_iv(3)>,
1713 L<EVP_CIPHER_CTX_get_updated_iv(3)> and L<EVP_CIPHER_CTX_get_original_iv(3)>
1715 See L<EVP_CIPHER_CTX_get_original_iv(3)> for further information.
1719 B<EVP_CIPHER_meth_*()>, EVP_MD_CTX_set_update_fn(), EVP_MD_CTX_update_fn(),
1722 See L</Providers are a replacement for engines and low-level method overrides>.
1726 EVP_PKEY_CTRL_PKCS7_ENCRYPT(), EVP_PKEY_CTRL_PKCS7_DECRYPT(),
1727 EVP_PKEY_CTRL_PKCS7_SIGN(), EVP_PKEY_CTRL_CMS_ENCRYPT(),
1728 EVP_PKEY_CTRL_CMS_DECRYPT(), and EVP_PKEY_CTRL_CMS_SIGN()
1730 These control operations are not invoked by the OpenSSL library anymore and
1731 are replaced by direct checks of the key operation against the key type
1732 when the operation is initialized.
1736 EVP_PKEY_CTX_get0_dh_kdf_ukm(), EVP_PKEY_CTX_get0_ecdh_kdf_ukm()
1738 See the "kdf-ukm" item in L<EVP_KEYEXCH-DH(7)/DH key exchange parameters> and
1739 L<EVP_KEYEXCH-ECDH(7)/ECDH Key Exchange parameters>.
1740 These functions are obsolete and should not be required.
1744 EVP_PKEY_CTX_set_rsa_keygen_pubexp()
1746 Applications should use L<EVP_PKEY_CTX_set1_rsa_keygen_pubexp(3)> instead.
1750 EVP_PKEY_cmp(), EVP_PKEY_cmp_parameters()
1752 Applications should use L<EVP_PKEY_eq(3)> and L<EVP_PKEY_parameters_eq(3)> instead.
1753 See L<EVP_PKEY_copy_parameters(3)> for further details.
1757 EVP_PKEY_encrypt_old(), EVP_PKEY_decrypt_old(),
1759 Applications should use L<EVP_PKEY_encrypt_init(3)> and L<EVP_PKEY_encrypt(3)> or
1760 L<EVP_PKEY_decrypt_init(3)> and L<EVP_PKEY_decrypt(3)> instead.
1766 This function returns NULL if the key comes from a provider.
1770 EVP_PKEY_get0_DH(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_EC_KEY(), EVP_PKEY_get0_RSA(),
1771 EVP_PKEY_get1_DH(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_EC_KEY and EVP_PKEY_get1_RSA(),
1772 EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash()
1774 See L</Functions that return an internal key should be treated as read only>.
1778 B<EVP_PKEY_meth_*()>
1780 See L</Providers are a replacement for engines and low-level method overrides>.
1784 EVP_PKEY_new_CMAC_key()
1786 See L</Deprecated low-level MAC functions>.
1790 EVP_PKEY_assign(), EVP_PKEY_set1_DH(), EVP_PKEY_set1_DSA(),
1791 EVP_PKEY_set1_EC_KEY(), EVP_PKEY_set1_RSA()
1793 See L</Deprecated low-level key object getters and setters>
1797 EVP_PKEY_set1_tls_encodedpoint() EVP_PKEY_get1_tls_encodedpoint()
1799 These functions were previously used by libssl to set or get an encoded public
1800 key into/from an EVP_PKEY object. With OpenSSL 3.0 these are replaced by the more
1801 generic functions L<EVP_PKEY_set1_encoded_public_key(3)> and
1802 L<EVP_PKEY_get1_encoded_public_key(3)>.
1803 The old versions have been converted to deprecated macros that just call the
1808 EVP_PKEY_set1_engine(), EVP_PKEY_get0_engine()
1810 See L</Providers are a replacement for engines and low-level method overrides>.
1814 EVP_PKEY_set_alias_type()
1816 This function has been removed. There is no replacement.
1817 See L</EVP_PKEY_set_alias_type() method has been removed>
1821 HMAC_Init_ex(), HMAC_Update(), HMAC_Final(), HMAC_size()
1823 See L</Deprecated low-level MAC functions>.
1827 HMAC_CTX_new(), HMAC_CTX_free(), HMAC_CTX_copy(), HMAC_CTX_reset(),
1828 HMAC_CTX_set_flags(), HMAC_CTX_get_md()
1830 See L</Deprecated low-level MAC functions>.
1834 i2d_DHparams(), i2d_DHxparams()
1836 See L</Deprecated low-level key reading and writing functions>
1837 and L<d2i_RSAPrivateKey(3)/Migration>
1841 i2d_DSAparams(), i2d_DSAPrivateKey(), i2d_DSAPrivateKey_bio(),
1842 i2d_DSAPrivateKey_fp(), i2d_DSA_PUBKEY(), i2d_DSA_PUBKEY_bio(),
1843 i2d_DSA_PUBKEY_fp(), i2d_DSAPublicKey()
1845 See L</Deprecated low-level key reading and writing functions>
1846 and L<d2i_RSAPrivateKey(3)/Migration>
1850 i2d_ECParameters(), i2d_ECPrivateKey(), i2d_ECPrivateKey_bio(),
1851 i2d_ECPrivateKey_fp(), i2d_EC_PUBKEY(), i2d_EC_PUBKEY_bio(),
1852 i2d_EC_PUBKEY_fp(), i2o_ECPublicKey()
1854 See L</Deprecated low-level key reading and writing functions>
1855 and L<d2i_RSAPrivateKey(3)/Migration>
1859 i2d_RSAPrivateKey(), i2d_RSAPrivateKey_bio(), i2d_RSAPrivateKey_fp(),
1860 i2d_RSA_PUBKEY(), i2d_RSA_PUBKEY_bio(), i2d_RSA_PUBKEY_fp(),
1861 i2d_RSAPublicKey(), i2d_RSAPublicKey_bio(), i2d_RSAPublicKey_fp()
1863 See L</Deprecated low-level key reading and writing functions>
1864 and L<d2i_RSAPrivateKey(3)/Migration>
1868 IDEA_encrypt(), IDEA_set_decrypt_key(), IDEA_set_encrypt_key(),
1869 IDEA_cbc_encrypt(), IDEA_cfb64_encrypt(), IDEA_ecb_encrypt(),
1870 IDEA_ofb64_encrypt()
1872 See L</Deprecated low-level encryption functions>.
1873 IDEA has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1879 There is no replacement. This function returned a constant string.
1883 MD2(), MD2_Init(), MD2_Update(), MD2_Final()
1885 See L</Deprecated low-level encryption functions>.
1886 MD2 has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1892 There is no replacement. This function returned a constant string.
1896 MD4(), MD4_Init(), MD4_Update(), MD4_Final(), MD4_Transform()
1898 See L</Deprecated low-level encryption functions>.
1899 MD4 has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1903 MDC2(), MDC2_Init(), MDC2_Update(), MDC2_Final()
1905 See L</Deprecated low-level encryption functions>.
1906 MDC2 has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1910 MD5(), MD5_Init(), MD5_Update(), MD5_Final(), MD5_Transform()
1912 See L</Deprecated low-level encryption functions>.
1918 This undocumented function has no replacement.
1919 See L<config(5)/HISTORY> for more details.
1925 Use L<OSSL_HTTP_parse_url(3)> instead.
1929 B<OCSP_REQ_CTX> type and B<OCSP_REQ_CTX_*()> functions
1931 These methods were used to collect all necessary data to form a HTTP request,
1932 and to perform the HTTP transfer with that request. With OpenSSL 3.0, the
1933 type is B<OSSL_HTTP_REQ_CTX>, and the deprecated functions are replaced
1934 with B<OSSL_HTTP_REQ_CTX_*()>. See L<OSSL_HTTP_REQ_CTX(3)> for additional
1939 OPENSSL_fork_child(), OPENSSL_fork_parent(), OPENSSL_fork_prepare()
1941 There is no replacement for these functions. These pthread fork support methods
1942 were unused by OpenSSL.
1946 OSSL_STORE_ctrl(), OSSL_STORE_do_all_loaders(), OSSL_STORE_LOADER_get0_engine(),
1947 OSSL_STORE_LOADER_get0_scheme(), OSSL_STORE_LOADER_new(),
1948 OSSL_STORE_LOADER_set_attach(), OSSL_STORE_LOADER_set_close(),
1949 OSSL_STORE_LOADER_set_ctrl(), OSSL_STORE_LOADER_set_eof(),
1950 OSSL_STORE_LOADER_set_error(), OSSL_STORE_LOADER_set_expect(),
1951 OSSL_STORE_LOADER_set_find(), OSSL_STORE_LOADER_set_load(),
1952 OSSL_STORE_LOADER_set_open(), OSSL_STORE_LOADER_set_open_ex(),
1953 OSSL_STORE_register_loader(), OSSL_STORE_unregister_loader(),
1956 These functions helped applications and engines create loaders for
1957 schemes they supported. These are all deprecated and discouraged in favour of
1958 provider implementations, see L<provider-storemgmt(7)>.
1962 PEM_read_DHparams(), PEM_read_bio_DHparams(),
1963 PEM_read_DSAparams(), PEM_read_bio_DSAparams(),
1964 PEM_read_DSAPrivateKey(), PEM_read_DSA_PUBKEY(),
1965 PEM_read_bio_DSAPrivateKey and PEM_read_bio_DSA_PUBKEY(),
1966 PEM_read_ECPKParameters(), PEM_read_ECPrivateKey(), PEM_read_EC_PUBKEY(),
1967 PEM_read_bio_ECPKParameters(), PEM_read_bio_ECPrivateKey(), PEM_read_bio_EC_PUBKEY(),
1968 PEM_read_RSAPrivateKey(), PEM_read_RSA_PUBKEY(), PEM_read_RSAPublicKey(),
1969 PEM_read_bio_RSAPrivateKey(), PEM_read_bio_RSA_PUBKEY(), PEM_read_bio_RSAPublicKey(),
1970 PEM_write_bio_DHparams(), PEM_write_bio_DHxparams(), PEM_write_DHparams(), PEM_write_DHxparams(),
1971 PEM_write_DSAparams(), PEM_write_DSAPrivateKey(), PEM_write_DSA_PUBKEY(),
1972 PEM_write_bio_DSAparams(), PEM_write_bio_DSAPrivateKey(), PEM_write_bio_DSA_PUBKEY(),
1973 PEM_write_ECPKParameters(), PEM_write_ECPrivateKey(), PEM_write_EC_PUBKEY(),
1974 PEM_write_bio_ECPKParameters(), PEM_write_bio_ECPrivateKey(), PEM_write_bio_EC_PUBKEY(),
1975 PEM_write_RSAPrivateKey(), PEM_write_RSA_PUBKEY(), PEM_write_RSAPublicKey(),
1976 PEM_write_bio_RSAPrivateKey(), PEM_write_bio_RSA_PUBKEY(),
1977 PEM_write_bio_RSAPublicKey(),
1979 See L</Deprecated low-level key reading and writing functions>
1985 See L</Deprecated low-level encryption functions>.
1989 RAND_get_rand_method(), RAND_set_rand_method(), RAND_OpenSSL(),
1990 RAND_set_rand_engine()
1992 Applications should instead use L<RAND_set_DRBG_type(3)>,
1993 L<EVP_RAND(3)> and L<EVP_RAND(7)>.
1994 See L<RAND_set_rand_method(3)> for more details.
1998 RC2_encrypt(), RC2_decrypt(), RC2_set_key(), RC2_cbc_encrypt(), RC2_cfb64_encrypt(),
1999 RC2_ecb_encrypt(), RC2_ofb64_encrypt(),
2000 RC4(), RC4_set_key(), RC4_options(),
2001 RC5_32_encrypt(), RC5_32_set_key(), RC5_32_decrypt(), RC5_32_cbc_encrypt(),
2002 RC5_32_cfb64_encrypt(), RC5_32_ecb_encrypt(), RC5_32_ofb64_encrypt()
2004 See L</Deprecated low-level encryption functions>.
2005 The Algorithms "RC2", "RC4" and "RC5" have been moved to the L<Legacy Provider|/Legacy Algorithms>.
2009 RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update(), RIPEMD160_Final(),
2010 RIPEMD160_Transform()
2012 See L</Deprecated low-level digest functions>.
2013 The RIPE algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
2017 RSA_bits(), RSA_security_bits(), RSA_size()
2019 Use L<EVP_PKEY_get_bits(3)>, L<EVP_PKEY_get_security_bits(3)> and
2020 L<EVP_PKEY_get_size(3)>.
2024 RSA_check_key(), RSA_check_key_ex()
2026 See L</Deprecated low-level validation functions>
2030 RSA_clear_flags(), RSA_flags(), RSA_set_flags(), RSA_test_flags(),
2031 RSA_setup_blinding(), RSA_blinding_off(), RSA_blinding_on()
2033 All of these RSA flags have been deprecated without replacement:
2035 B<RSA_FLAG_BLINDING>, B<RSA_FLAG_CACHE_PRIVATE>, B<RSA_FLAG_CACHE_PUBLIC>,
2036 B<RSA_FLAG_EXT_PKEY>, B<RSA_FLAG_NO_BLINDING>, B<RSA_FLAG_THREAD_SAFE>
2037 B<RSA_METHOD_FLAG_NO_CHECK>
2041 RSA_generate_key_ex(), RSA_generate_multi_prime_key()
2043 See L</Deprecated low-level key generation functions>.
2049 See L</Providers are a replacement for engines and low-level method overrides>
2053 RSA_get0_crt_params(), RSA_get0_d(), RSA_get0_dmp1(), RSA_get0_dmq1(),
2054 RSA_get0_e(), RSA_get0_factors(), RSA_get0_iqmp(), RSA_get0_key(),
2055 RSA_get0_multi_prime_crt_params(), RSA_get0_multi_prime_factors(), RSA_get0_n(),
2056 RSA_get0_p(), RSA_get0_pss_params(), RSA_get0_q(),
2057 RSA_get_multi_prime_extra_count()
2059 See L</Deprecated low-level key parameter getters>
2063 RSA_new(), RSA_free(), RSA_up_ref()
2065 See L</Deprecated low-level object creation>.
2069 RSA_get_default_method(), RSA_get_ex_data and RSA_get_method()
2071 See L</Providers are a replacement for engines and low-level method overrides>.
2077 There is no replacement.
2081 B<RSA_meth_*()>, RSA_new_method(), RSA_null_method and RSA_PKCS1_OpenSSL()
2083 See L</Providers are a replacement for engines and low-level method overrides>.
2087 B<RSA_padding_add_*()>, B<RSA_padding_check_*()>
2089 See L</Deprecated low-level signing functions> and
2090 L</Deprecated low-level encryption functions>.
2094 RSA_print(), RSA_print_fp()
2096 See L</Deprecated low-level key printing functions>
2100 RSA_public_encrypt(), RSA_private_decrypt()
2102 See L</Deprecated low-level encryption functions>
2106 RSA_private_encrypt(), RSA_public_decrypt()
2108 This is equivalent to doing sign and verify recover operations (with a padding
2109 mode of none). See L</Deprecated low-level signing functions>.
2113 RSAPrivateKey_dup(), RSAPublicKey_dup()
2115 There is no direct replacement. Applications may use L<EVP_PKEY_dup(3)>.
2119 RSAPublicKey_it(), RSAPrivateKey_it()
2121 See L</Deprecated low-level key reading and writing functions>
2125 RSA_set0_crt_params(), RSA_set0_factors(), RSA_set0_key(),
2126 RSA_set0_multi_prime_params()
2128 See L</Deprecated low-level key parameter setters>.
2132 RSA_set_default_method(), RSA_set_method(), RSA_set_ex_data()
2134 See L</Providers are a replacement for engines and low-level method overrides>
2138 RSA_sign(), RSA_sign_ASN1_OCTET_STRING(), RSA_verify(),
2139 RSA_verify_ASN1_OCTET_STRING(), RSA_verify_PKCS1_PSS(),
2140 RSA_verify_PKCS1_PSS_mgf1()
2142 See L</Deprecated low-level signing functions>.
2146 RSA_X931_derive_ex(), RSA_X931_generate_key_ex(), RSA_X931_hash_id()
2148 There are no replacements for these functions.
2149 X931 padding can be set using L<EVP_SIGNATURE-RSA(7)/Signature Parameters>.
2150 See B<OSSL_SIGNATURE_PARAM_PAD_MODE>.
2154 SEED_encrypt(), SEED_decrypt(), SEED_set_key(), SEED_cbc_encrypt(),
2155 SEED_cfb128_encrypt(), SEED_ecb_encrypt(), SEED_ofb128_encrypt()
2157 See L</Deprecated low-level encryption functions>.
2158 The SEED algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
2162 SHA1_Init(), SHA1_Update(), SHA1_Final(), SHA1_Transform(),
2163 SHA224_Init(), SHA224_Update(), SHA224_Final(),
2164 SHA256_Init(), SHA256_Update(), SHA256_Final(), SHA256_Transform(),
2165 SHA384_Init(), SHA384_Update(), SHA384_Final(),
2166 SHA512_Init(), SHA512_Update(), SHA512_Final(), SHA512_Transform()
2168 See L</Deprecated low-level digest functions>.
2172 SRP_Calc_A(), SRP_Calc_B(), SRP_Calc_client_key(), SRP_Calc_server_key(),
2173 SRP_Calc_u(), SRP_Calc_x(), SRP_check_known_gN_param(), SRP_create_verifier(),
2174 SRP_create_verifier_BN(), SRP_get_default_gN(), SRP_user_pwd_free(), SRP_user_pwd_new(),
2175 SRP_user_pwd_set0_sv(), SRP_user_pwd_set1_ids(), SRP_user_pwd_set_gN(),
2176 SRP_VBASE_add0_user(), SRP_VBASE_free(), SRP_VBASE_get1_by_user(), SRP_VBASE_init(),
2177 SRP_VBASE_new(), SRP_Verify_A_mod_N(), SRP_Verify_B_mod_N()
2179 There are no replacements for the SRP functions.
2183 SSL_CTX_set_tmp_dh_callback(), SSL_set_tmp_dh_callback(),
2184 SSL_CTX_set_tmp_dh(), SSL_set_tmp_dh()
2186 These are used to set the Diffie-Hellman (DH) parameters that are to be used by
2187 servers requiring ephemeral DH keys. Instead applications should consider using
2188 the built-in DH parameters that are available by calling L<SSL_CTX_set_dh_auto(3)>
2189 or L<SSL_set_dh_auto(3)>. If custom parameters are necessary then applications can
2190 use the alternative functions L<SSL_CTX_set0_tmp_dh_pkey(3)> and
2191 L<SSL_set0_tmp_dh_pkey(3)>. There is no direct replacement for the "callback"
2192 functions. The callback was originally useful in order to have different
2193 parameters for export and non-export ciphersuites. Export ciphersuites are no
2194 longer supported by OpenSSL. Use of the callback functions should be replaced
2195 by one of the other methods described above.
2199 SSL_CTX_set_tlsext_ticket_key_cb()
2201 Use the new L<SSL_CTX_set_tlsext_ticket_key_evp_cb(3)> function instead.
2205 WHIRLPOOL(), WHIRLPOOL_Init(), WHIRLPOOL_Update(), WHIRLPOOL_Final(),
2206 WHIRLPOOL_BitUpdate()
2208 See L</Deprecated low-level digest functions>.
2209 The Whirlpool algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
2213 X509_certificate_type()
2215 This was an undocumented function. Applications can use L<X509_get0_pubkey(3)>
2216 and L<X509_get0_signature(3)> instead.
2220 X509_http_nbio(), X509_CRL_http_nbio()
2222 Use L<X509_load_http(3)> and L<X509_CRL_load_http(3)> instead.
2226 =head2 Using the FIPS Module in applications
2228 See L<fips_module(7)> and L<OSSL_PROVIDER-FIPS(7)> for details.
2230 =head2 OpenSSL command line application changes
2232 =head3 New applications
2234 L<B<openssl kdf>|openssl-kdf(1)> uses the new L<EVP_KDF(3)> API.
2235 L<B<openssl kdf>|openssl-mac(1)> uses the new L<EVP_MAC(3)> API.
2237 =head3 Added options
2239 B<-provider_path> and B<-provider> are available to all apps and can be used
2240 multiple times to load any providers, such as the 'legacy' provider or third
2241 party providers. If used then the 'default' provider would also need to be
2242 specified if required. The B<-provider_path> must be specified before the
2243 B<-provider> option.
2245 The B<list> app has many new options. See L<openssl-list(1)> for more
2248 B<-crl_lastupdate> and B<-crl_nextupdate> used by B<openssl ca> allows
2249 explicit setting of fields in the generated CRL.
2251 =head3 Removed options
2253 Interactive mode is not longer available.
2255 The B<-crypt> option used by B<openssl passwd>.
2256 The B<-c> option used by B<openssl x509>, B<openssl dhparam>,
2257 B<openssl dsaparam>, and B<openssl ecparam>.
2259 =head3 Other Changes
2261 The output of Command line applications may have minor changes.
2262 These are primarily changes in capitalisation and white space. However, in some
2263 cases, there are additional differences.
2264 For example, the DH parameters output from B<openssl dhparam> now lists 'P',
2265 'Q', 'G' and 'pcounter' instead of 'prime', 'generator', 'subgroup order' and
2266 'counter' respectively.
2268 The B<openssl> commands that read keys, certificates, and CRLs now
2269 automatically detect the PEM or DER format of the input files so it is not
2270 necessary to explicitly specify the input format anymore. However if the
2271 input format option is used the specified format will be required.
2273 B<openssl speed> no longer uses low-level API calls.
2274 This implies some of the performance numbers might not be comparable with the
2275 previous releases due to higher overhead. This applies particularly to
2276 measuring performance on smaller data chunks.
2278 b<openssl dhparam>, B<openssl dsa>, B<openssl gendsa>, B<openssl dsaparam>,
2279 B<openssl genrsa> and B<openssl rsa> have been modified to use PKEY APIs.
2280 B<openssl genrsa> and B<openssl rsa> now write PKCS #8 keys by default.
2282 =head3 Default settings
2284 "SHA256" is now the default digest for TS query used by B<openssl ts>.
2286 =head3 Deprecated apps
2288 B<openssl rsautl> is deprecated, use B<openssl pkeyutl> instead.
2289 B<openssl dhparam>, B<openssl dsa>, B<openssl gendsa>, B<openssl dsaparam>,
2290 B<openssl genrsa>, B<openssl rsa>, B<openssl genrsa> and B<openssl rsa> are
2291 now in maintenance mode and no new features will be added to them.
2299 TLS 1.3 FFDHE key exchange support added
2301 This uses DH safe prime named groups.
2305 Support for fully "pluggable" TLSv1.3 groups.
2307 This means that providers may supply their own group implementations (using
2308 either the "key exchange" or the "key encapsulation" methods) which will
2309 automatically be detected and used by libssl.
2313 SSL and SSL_CTX options are now 64 bit instead of 32 bit.
2315 The signatures of the functions to get and set options on SSL and
2316 SSL_CTX objects changed from "unsigned long" to "uint64_t" type.
2318 This may require source code changes. For example it is no longer possible
2319 to use the B<SSL_OP_> macro values in preprocessor C<#if> conditions.
2320 However it is still possible to test whether these macros are defined or not.
2322 See L<SSL_CTX_get_options(3)>, L<SSL_CTX_set_options(3)>,
2323 L<SSL_get_options(3)> and L<SSL_set_options(3)>.
2327 SSL_set1_host() and SSL_add1_host() Changes
2329 These functions now take IP literal addresses as well as actual hostnames.
2333 Added SSL option SSL_OP_CLEANSE_PLAINTEXT
2335 If the option is set, openssl cleanses (zeroizes) plaintext bytes from
2336 internal buffers after delivering them to the application. Note,
2337 the application is still responsible for cleansing other copies
2338 (e.g.: data received by L<SSL_read(3)>).
2342 Client-initiated renegotiation is disabled by default.
2344 To allow it, use the B<-client_renegotiation> option,
2345 the B<SSL_OP_ALLOW_CLIENT_RENEGOTIATION> flag, or the C<ClientRenegotiation>
2346 config parameter as appropriate.
2350 Secure renegotiation is now required by default for TLS connections
2352 Support for RFC 5746 secure renegotiation is now required by default for
2353 SSL or TLS connections to succeed. Applications that require the ability
2354 to connect to legacy peers will need to explicitly set
2355 SSL_OP_LEGACY_SERVER_CONNECT. Accordingly, SSL_OP_LEGACY_SERVER_CONNECT
2356 is no longer set as part of SSL_OP_ALL.
2360 Combining the Configure options no-ec and no-dh no longer disables TLSv1.3
2362 Typically if OpenSSL has no EC or DH algorithms then it cannot support
2363 connections with TLSv1.3. However OpenSSL now supports "pluggable" groups
2364 through providers. Therefore third party providers may supply group
2365 implementations even where there are no built-in ones. Attempting to create
2366 TLS connections in such a build without also disabling TLSv1.3 at run time or
2367 using third party provider groups may result in handshake failures. TLSv1.3
2368 can be disabled at compile time using the "no-tls1_3" Configure option.
2372 SSL_CTX_set_ciphersuites() and SSL_set_ciphersuites() changes.
2374 The methods now ignore unknown ciphers.
2378 Security callback change.
2380 The security callback, which can be customised by application code, supports
2381 the security operation SSL_SECOP_TMP_DH. This is defined to take an EVP_PKEY
2382 in the "other" parameter. In most places this is what is passed. All these
2383 places occur server side. However there was one client side call of this
2384 security operation and it passed a DH object instead. This is incorrect
2385 according to the definition of SSL_SECOP_TMP_DH, and is inconsistent with all
2386 of the other locations. Therefore this client side call has been changed to
2387 pass an EVP_PKEY instead.
2391 New SSL option SSL_OP_IGNORE_UNEXPECTED_EOF
2393 The SSL option SSL_OP_IGNORE_UNEXPECTED_EOF is introduced. If that option
2394 is set, an unexpected EOF is ignored, it pretends a close notify was received
2395 instead and so the returned error becomes SSL_ERROR_ZERO_RETURN.
2399 The security strength of SHA1 and MD5 based signatures in TLS has been reduced.
2401 This results in SSL 3, TLS 1.0, TLS 1.1 and DTLS 1.0 no longer
2402 working at the default security level of 1 and instead requires security
2403 level 0. The security level can be changed either using the cipher string
2404 with C<@SECLEVEL>, or calling L<SSL_CTX_set_security_level(3)>. This also means
2405 that where the signature algorithms extension is missing from a ClientHello
2406 then the handshake will fail in TLS 1.2 at security level 1. This is because,
2407 although this extension is optional, failing to provide one means that
2408 OpenSSL will fallback to a default set of signature algorithms. This default
2409 set requires the availability of SHA1.
2413 X509 certificates signed using SHA1 are no longer allowed at security level 1 and above.
2415 In TLS/SSL the default security level is 1. It can be set either using the cipher
2416 string with C<@SECLEVEL>, or calling L<SSL_CTX_set_security_level(3)>. If the
2417 leaf certificate is signed with SHA-1, a call to L<SSL_CTX_use_certificate(3)>
2418 will fail if the security level is not lowered first.
2419 Outside TLS/SSL, the default security level is -1 (effectively 0). It can
2420 be set using L<X509_VERIFY_PARAM_set_auth_level(3)> or using the B<-auth_level>
2421 options of the commands.
2431 The migration guide was created for OpenSSL 3.0.
2435 Copyright 2021-2022 The OpenSSL Project Authors. All Rights Reserved.
2437 Licensed under the Apache License 2.0 (the "License"). You may not use
2438 this file except in compliance with the License. You can obtain a copy
2439 in the file LICENSE in the source distribution or at
2440 L<https://www.openssl.org/source/license.html>.