1MIGRATION_GUIDE(7ossl) OpenSSL MIGRATION_GUIDE(7ossl)
2
6 migration_guide - OpenSSL migration guide
7
9 See the individual manual pages for details.
10
12 This guide details the changes required to migrate to new versions of
13 OpenSSL. Currently this covers OpenSSL 3.0 & 3.1. For earlier versions
14 refer to <https://github.com/openssl/openssl/blob/master/CHANGES.md>.
15 For an overview of some of the key concepts introduced in OpenSSL 3.0
16 see crypto(7).
17
19 Main Changes from OpenSSL 3.0
20 The FIPS provider in OpenSSL 3.1 includes some non-FIPS validated
21 algorithms, consequently the property query "fips=yes" is mandatory for
22 applications that want to operate in a FIPS approved manner. The
23 algorithms are:
24 Triple DES ECB
26 Triple DES CBC
27 EdDSA
28 There are no other changes requiring additional migration measures
30 since OpenSSL 3.0.
31
33 Main Changes from OpenSSL 1.1.1
34 Major Release
35 OpenSSL 3.0 is a major release and consequently any application that
37 currently uses an older version of OpenSSL will at the very least need
38 to be recompiled in order to work with the new version. It is the
39 intention that the large majority of applications will work unchanged
40 with OpenSSL 3.0 if those applications previously worked with OpenSSL
41 1.1.1. However this is not guaranteed and some changes may be required
42 in some cases. Changes may also be required if applications need to
43 take advantage of some of the new features available in OpenSSL 3.0
44 such as the availability of the FIPS module.
45 License Change
47 In previous versions, OpenSSL was licensed under the dual OpenSSL and
49 SSLeay licenses <https://www.openssl.org/source/license-openssl-
50 ssleay.txt> (both licenses apply). From OpenSSL 3.0 this is replaced by
51 the Apache License v2 <https://www.openssl.org/source/apache-
52 license-2.0.txt>.
53 Providers and FIPS support
55 One of the key changes from OpenSSL 1.1.1 is the introduction of the
57 Provider concept. Providers collect together and make available
58 algorithm implementations. With OpenSSL 3.0 it is possible to specify,
59 either programmatically or via a config file, which providers you want
60 to use for any given application. OpenSSL 3.0 comes with 5 different
61 providers as standard. Over time third parties may distribute
62 additional providers that can be plugged into OpenSSL. All algorithm
63 implementations available via providers are accessed through the "high
64 level" APIs (for example those functions prefixed with "EVP"). They
65 cannot be accessed using the "Low Level APIs".
66 One of the standard providers available is the FIPS provider. This
68 makes available FIPS validated cryptographic algorithms. The FIPS
69 provider is disabled by default and needs to be enabled explicitly at
70 configuration time using the "enable-fips" option. If it is enabled,
71 the FIPS provider gets built and installed in addition to the other
72 standard providers. No separate installation procedure is necessary.
73 There is however a dedicated "install_fips" make target, which serves
74 the special purpose of installing only the FIPS provider into an
75 existing OpenSSL installation.
76 Not all algorithms may be available for the application at a particular
78 moment. If the application code uses any digest or cipher algorithm
79 via the EVP interface, the application should verify the result of the
80 EVP_EncryptInit(3), EVP_EncryptInit_ex(3), and EVP_DigestInit(3)
81 functions. In case when the requested algorithm is not available, these
82 functions will fail.
83 See also "Legacy Algorithms" for information on the legacy provider.
85 See also "Completing the installation of the FIPS Module" and "Using
87 the FIPS Module in applications".
88 Low Level APIs
90 OpenSSL has historically provided two sets of APIs for invoking
92 cryptographic algorithms: the "high level" APIs (such as the "EVP"
93 APIs) and the "low level" APIs. The high level APIs are typically
94 designed to work across all algorithm types. The "low level" APIs are
95 targeted at a specific algorithm implementation. For example, the EVP
96 APIs provide the functions EVP_EncryptInit_ex(3), EVP_EncryptUpdate(3)
97 and EVP_EncryptFinal(3) to perform symmetric encryption. Those
98 functions can be used with the algorithms AES, CHACHA, 3DES etc. On
99 the other hand, to do AES encryption using the low level APIs you would
100 have to call AES specific functions such as AES_set_encrypt_key(3),
101 AES_encrypt(3), and so on. The functions for 3DES are different. Use
102 of the low level APIs has been informally discouraged by the OpenSSL
103 development team for a long time. However in OpenSSL 3.0 this is made
104 more formal. All such low level APIs have been deprecated. You may
105 still use them in your applications, but you may start to see
106 deprecation warnings during compilation (dependent on compiler support
107 for this). Deprecated APIs may be removed from future versions of
108 OpenSSL so you are strongly encouraged to update your code to use the
109 high level APIs instead.
110 This is described in more detail in "Deprecation of Low Level
112 Functions"
113 Legacy Algorithms
115 Some cryptographic algorithms such as MD2 and DES that were available
117 via the EVP APIs are now considered legacy and their use is strongly
118 discouraged. These legacy EVP algorithms are still available in
119 OpenSSL 3.0 but not by default. If you want to use them then you must
120 load the legacy provider. This can be as simple as a config file
121 change, or can be done programmatically. See OSSL_PROVIDER-legacy(7)
122 for a complete list of algorithms. Applications using the EVP APIs to
123 access these algorithms should instead use more modern algorithms. If
124 that is not possible then these applications should ensure that the
125 legacy provider has been loaded. This can be achieved either
126 programmatically or via configuration. See crypto(7) man page for more
127 information about providers.
128 Engines and "METHOD" APIs
130 The refactoring to support Providers conflicts internally with the APIs
132 used to support engines, including the ENGINE API and any function that
133 creates or modifies custom "METHODS" (for example EVP_MD_meth_new(3),
134 EVP_CIPHER_meth_new(3), EVP_PKEY_meth_new(3), RSA_meth_new(3),
135 EC_KEY_METHOD_new(3), etc.). These functions are being deprecated in
136 OpenSSL 3.0, and users of these APIs should know that their use can
137 likely bypass provider selection and configuration, with unintended
138 consequences. This is particularly relevant for applications written
139 to use the OpenSSL 3.0 FIPS module, as detailed below. Authors and
140 maintainers of external engines are strongly encouraged to refactor
141 their code transforming engines into providers using the new Provider
142 API and avoiding deprecated methods.
143 Support of legacy engines
145 If openssl is not built without engine support or deprecated API
147 support, engines will still work. However, their applicability will be
148 limited.
149 New algorithms provided via engines will still work.
151 Engine-backed keys can be loaded via custom OSSL_STORE implementation.
153 In this case the EVP_PKEY objects created via
154 ENGINE_load_private_key(3) will be considered legacy and will continue
155 to work.
156 To ensure the future compatibility, the engines should be turned to
158 providers. To prefer the provider-based hardware offload, you can
159 specify the default properties to prefer your provider.
160 Versioning Scheme
162 The OpenSSL versioning scheme has changed with the OpenSSL 3.0 release.
164 The new versioning scheme has this format:
165 MAJOR.MINOR.PATCH
167 For OpenSSL 1.1.1 and below, different patch levels were indicated by a
169 letter at the end of the release version number. This will no longer be
170 used and instead the patch level is indicated by the final number in
171 the version. A change in the second (MINOR) number indicates that new
172 features may have been added. OpenSSL versions with the same major
173 number are API and ABI compatible. If the major number changes then
174 API and ABI compatibility is not guaranteed.
175 For more information, see OpenSSL_version(3).
177 Other major new features
179 Certificate Management Protocol (CMP, RFC 4210)
181 This also covers CRMF (RFC 4211) and HTTP transfer (RFC 6712) See
183 openssl-cmp(1) and OSSL_CMP_exec_certreq(3) as starting points.
184 HTTP(S) client
186 A proper HTTP(S) client that supports GET and POST, redirection, plain
188 and ASN.1-encoded contents, proxies, and timeouts.
189 Key Derivation Function API (EVP_KDF)
191 This simplifies the process of adding new KDF and PRF implementations.
193 Previously KDF algorithms had been shoe-horned into using the EVP_PKEY
195 object which was not a logical mapping. Existing applications that use
196 KDF algorithms using EVP_PKEY (scrypt, TLS1 PRF and HKDF) may be slower
197 as they use an EVP_KDF bridge internally. All new applications should
198 use the new EVP_KDF(3) interface. See also "Key Derivation Function
199 (KDF)" in OSSL_PROVIDER-default(7) and "Key Derivation Function (KDF)"
200 in OSSL_PROVIDER-FIPS(7).
201 Message Authentication Code API (EVP_MAC)
203 This simplifies the process of adding MAC implementations.
205 This includes a generic EVP_PKEY to EVP_MAC bridge, to facilitate the
207 continued use of MACs through raw private keys in functionality such as
208 EVP_DigestSign(3) and EVP_DigestVerify(3).
209 All new applications should use the new EVP_MAC(3) interface. See also
211 "Message Authentication Code (MAC)" in OSSL_PROVIDER-default(7) and
212 "Message Authentication Code (MAC)" in OSSL_PROVIDER-FIPS(7).
213 Algorithm Fetching
215 Using calls to convenience functions such as EVP_sha256() and
217 EVP_aes_256_gcm() may incur a performance penalty when using providers.
218 Retrieving algorithms from providers involves searching for an
219 algorithm by name. This is much slower than directly accessing a
220 method table. It is recommended to prefetch algorithms if an algorithm
221 is used many times. See "Performance" in crypto(7), "Explicit
222 fetching" in crypto(7) and "Implicit fetching" in crypto(7).
223 Support for Linux Kernel TLS
225 In order to use KTLS, support for it must be compiled in using the
227 "enable-ktls" configuration option. It must also be enabled at run time
228 using the SSL_OP_ENABLE_KTLS option.
229 New Algorithms
231 • KDF algorithms "SINGLE STEP" and "SSH"
233 See EVP_KDF-SS(7) and EVP_KDF-SSHKDF(7)
235 • MAC Algorithms "GMAC" and "KMAC"
237 See EVP_MAC-GMAC(7) and EVP_MAC-KMAC(7).
239 • KEM Algorithm "RSASVE"
241 See EVP_KEM-RSA(7).
243 • Cipher Algorithm "AES-SIV"
245 See "SIV Mode" in EVP_EncryptInit(3).
247 • AES Key Wrap inverse ciphers supported by EVP layer.
249 The inverse ciphers use AES decryption for wrapping, and AES
251 encryption for unwrapping. The algorithms are: "AES-128-WRAP-INV",
252 "AES-192-WRAP-INV", "AES-256-WRAP-INV", "AES-128-WRAP-PAD-INV",
253 "AES-192-WRAP-PAD-INV" and "AES-256-WRAP-PAD-INV".
254 • CTS ciphers added to EVP layer.
256 The algorithms are "AES-128-CBC-CTS", "AES-192-CBC-CTS",
258 "AES-256-CBC-CTS", "CAMELLIA-128-CBC-CTS", "CAMELLIA-192-CBC-CTS"
259 and "CAMELLIA-256-CBC-CTS". CS1, CS2 and CS3 variants are
260 supported.
261 CMS and PKCS#7 updates
263 • Added CAdES-BES signature verification support.
265 • Added CAdES-BES signature scheme and attributes support (RFC 5126)
267 to CMS API.
268 • Added AuthEnvelopedData content type structure (RFC 5083) using
270 AES_GCM
271 This uses the AES-GCM parameter (RFC 5084) for the Cryptographic
273 Message Syntax. Its purpose is to support encryption and
274 decryption of a digital envelope that is both authenticated and
275 encrypted using AES GCM mode.
276 • PKCS7_get_octet_string(3) and PKCS7_type_is_other(3) were made
278 public.
279 PKCS#12 API updates
281 The default algorithms for pkcs12 creation with the PKCS12_create()
283 function were changed to more modern PBKDF2 and AES based algorithms.
284 The default MAC iteration count was changed to PKCS12_DEFAULT_ITER to
285 make it equal with the password-based encryption iteration count. The
286 default digest algorithm for the MAC computation was changed to
287 SHA-256. The pkcs12 application now supports -legacy option that
288 restores the previous default algorithms to support interoperability
289 with legacy systems.
290 Added enhanced PKCS#12 APIs which accept a library context OSSL_LIB_CTX
292 and (where relevant) a property query. Other APIs which handle PKCS#7
293 and PKCS#8 objects have also been enhanced where required. This
294 includes:
295 PKCS12_add_key_ex(3), PKCS12_add_safe_ex(3), PKCS12_add_safes_ex(3),
297 PKCS12_create_ex(3), PKCS12_decrypt_skey_ex(3), PKCS12_init_ex(3),
298 PKCS12_item_decrypt_d2i_ex(3), PKCS12_item_i2d_encrypt_ex(3),
299 PKCS12_key_gen_asc_ex(3), PKCS12_key_gen_uni_ex(3),
300 PKCS12_key_gen_utf8_ex(3), PKCS12_pack_p7encdata_ex(3),
301 PKCS12_pbe_crypt_ex(3), PKCS12_PBE_keyivgen_ex(3),
302 PKCS12_SAFEBAG_create_pkcs8_encrypt_ex(3), PKCS5_pbe2_set_iv_ex(3),
303 PKCS5_pbe_set0_algor_ex(3), PKCS5_pbe_set_ex(3),
304 PKCS5_pbkdf2_set_ex(3), PKCS5_v2_PBE_keyivgen_ex(3),
305 PKCS5_v2_scrypt_keyivgen_ex(3), PKCS8_decrypt_ex(3),
306 PKCS8_encrypt_ex(3), PKCS8_set0_pbe_ex(3).
307 As part of this change the EVP_PBE_xxx APIs can also accept a library
309 context and property query and will call an extended version of the
310 key/IV derivation function which supports these parameters. This
311 includes EVP_PBE_CipherInit_ex(3), EVP_PBE_find_ex(3) and
312 EVP_PBE_scrypt_ex(3).
313 Windows thread synchronization changes
315 Windows thread synchronization uses read/write primitives (SRWLock)
317 when supported by the OS, otherwise CriticalSection continues to be
318 used.
319 Trace API
321 A new generic trace API has been added which provides support for
323 enabling instrumentation through trace output. This feature is mainly
324 intended as an aid for developers and is disabled by default. To
325 utilize it, OpenSSL needs to be configured with the "enable-trace"
326 option.
327 If the tracing API is enabled, the application can activate trace
329 output by registering BIOs as trace channels for a number of tracing
330 and debugging categories. See OSSL_trace_enabled(3).
331 Key validation updates
333 EVP_PKEY_public_check(3) and EVP_PKEY_param_check(3) now work for more
335 key types. This includes RSA, DSA, ED25519, X25519, ED448 and X448.
336 Previously (in 1.1.1) they would return -2. For key types that do not
337 have parameters then EVP_PKEY_param_check(3) will always return 1.
338 Other notable deprecations and changes
340 The function code part of an OpenSSL error code is no longer relevant
342 This code is now always set to zero. Related functions are deprecated.
344 STACK and HASH macros have been cleaned up
346 The type-safe wrappers are declared everywhere and implemented once.
348 See DEFINE_STACK_OF(3) and DEFINE_LHASH_OF_EX(3).
349 The RAND_DRBG subsystem has been removed
351 The new EVP_RAND(3) is a partial replacement: the DRBG callback
353 framework is absent. The RAND_DRBG API did not fit well into the new
354 provider concept as implemented by EVP_RAND and EVP_RAND_CTX.
355 Removed FIPS_mode() and FIPS_mode_set()
357 These functions are legacy APIs that are not applicable to the new
359 provider model. Applications should instead use
360 EVP_default_properties_is_fips_enabled(3) and
361 EVP_default_properties_enable_fips(3).
362 Key generation is slower
364 The Miller-Rabin test now uses 64 rounds, which is used for all prime
366 generation, including RSA key generation. This affects the time for
367 larger keys sizes.
368 The default key generation method for the regular 2-prime RSA keys was
370 changed to the FIPS186-4 B.3.6 method (Generation of Probable Primes
371 with Conditions Based on Auxiliary Probable Primes). This method is
372 slower than the original method.
373 Change PBKDF2 to conform to SP800-132 instead of the older PKCS5
375 RFC2898
376 This checks that the salt length is at least 128 bits, the derived key
378 length is at least 112 bits, and that the iteration count is at least
379 1000. For backwards compatibility these checks are disabled by default
380 in the default provider, but are enabled by default in the FIPS
381 provider.
382 To enable or disable the checks see OSSL_KDF_PARAM_PKCS5 in
384 EVP_KDF-PBKDF2(7). The parameter can be set using EVP_KDF_derive(3).
385 Enforce a minimum DH modulus size of 512 bits
387 Smaller sizes now result in an error.
389 SM2 key changes
391 EC EVP_PKEYs with the SM2 curve have been reworked to automatically
393 become EVP_PKEY_SM2 rather than EVP_PKEY_EC.
394 Unlike in previous OpenSSL versions, this means that applications
396 cannot call "EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2)" to get SM2
397 computations.
398 Parameter and key generation is also reworked to make it possible to
400 generate EVP_PKEY_SM2 parameters and keys. Applications must now
401 generate SM2 keys directly and must not create an EVP_PKEY_EC key
402 first. It is no longer possible to import an SM2 key with domain
403 parameters other than the SM2 elliptic curve ones.
404 Validation of SM2 keys has been separated from the validation of
406 regular EC keys, allowing to improve the SM2 validation process to
407 reject loaded private keys that are not conforming to the SM2 ISO
408 standard. In particular, a private scalar k outside the range 1 <= k <
409 n-1 is now correctly rejected.
410 EVP_PKEY_set_alias_type() method has been removed
412 This function made a EVP_PKEY object mutable after it had been set up.
414 In OpenSSL 3.0 it was decided that a provided key should not be able to
415 change its type, so this function has been removed.
416 Functions that return an internal key should be treated as read only
418 Functions such as EVP_PKEY_get0_RSA(3) behave slightly differently in
420 OpenSSL 3.0. Previously they returned a pointer to the low-level key
421 used internally by libcrypto. From OpenSSL 3.0 this key may now be held
422 in a provider. Calling these functions will only return a handle on the
423 internal key where the EVP_PKEY was constructed using this key in the
424 first place, for example using a function or macro such as
425 EVP_PKEY_assign_RSA(3), EVP_PKEY_set1_RSA(3), etc. Where the EVP_PKEY
426 holds a provider managed key, then these functions now return a cached
427 copy of the key. Changes to the internal provider key that take place
428 after the first time the cached key is accessed will not be reflected
429 back in the cached copy. Similarly any changes made to the cached copy
430 by application code will not be reflected back in the internal provider
431 key.
432 For the above reasons the keys returned from these functions should
434 typically be treated as read-only. To emphasise this the value returned
435 from EVP_PKEY_get0_RSA(3), EVP_PKEY_get0_DSA(3),
436 EVP_PKEY_get0_EC_KEY(3) and EVP_PKEY_get0_DH(3) have been made const.
437 This may break some existing code. Applications broken by this change
438 should be modified. The preferred solution is to refactor the code to
439 avoid the use of these deprecated functions. Failing this the code
440 should be modified to use a const pointer instead. The
441 EVP_PKEY_get1_RSA(3), EVP_PKEY_get1_DSA(3), EVP_PKEY_get1_EC_KEY(3) and
442 EVP_PKEY_get1_DH(3) functions continue to return a non-const pointer to
443 enable them to be "freed". However they should also be treated as read-
444 only.
445 The public key check has moved from EVP_PKEY_derive() to
447 EVP_PKEY_derive_set_peer()
448 This may mean result in an error in EVP_PKEY_derive_set_peer(3) rather
450 than during EVP_PKEY_derive(3). To disable this check use
451 EVP_PKEY_derive_set_peer_ex(dh, peer, 0).
452 The print format has cosmetic changes for some functions
454 The output from numerous "printing" functions such as
456 X509_signature_print(3), X509_print_ex(3), X509_CRL_print_ex(3), and
457 other similar functions has been amended such that there may be
458 cosmetic differences between the output observed in 1.1.1 and 3.0. This
459 also applies to the -text output from the openssl x509 and openssl crl
460 applications.
461 Interactive mode from the openssl program has been removed
463 From now on, running it without arguments is equivalent to openssl
465 help.
466 The error return values from some control calls (ctrl) have changed
468 One significant change is that controls which used to return -2 for
470 invalid inputs, now return -1 indicating a generic error condition
471 instead.
472 DH and DHX key types have different settable parameters
474 Previously (in 1.1.1) these conflicting parameters were allowed, but
476 will now result in errors. See EVP_PKEY-DH(7) for further details. This
477 affects the behaviour of openssl-genpkey(1) for DH parameter
478 generation.
479 EVP_CIPHER_CTX_set_flags() ordering change
481 If using a cipher from a provider the EVP_CIPH_FLAG_LENGTH_BITS flag
483 can only be set after the cipher has been assigned to the cipher
484 context. See "FLAGS" in EVP_EncryptInit(3) for more information.
485 Validation of operation context parameters
487 Due to move of the implementation of cryptographic operations to the
489 providers, validation of various operation parameters can be postponed
490 until the actual operation is executed where previously it happened
491 immediately when an operation parameter was set.
492 For example when setting an unsupported curve with
494 EVP_PKEY_CTX_set_ec_paramgen_curve_nid() this function call will not
495 fail but later keygen operations with the EVP_PKEY_CTX will fail.
496 Removal of function code from the error codes
498 The function code part of the error code is now always set to 0. For
500 that reason the ERR_GET_FUNC() macro was removed. Applications must
501 resolve the error codes only using the library number and the reason
502 code.
503 ChaCha20-Poly1305 cipher does not allow a truncated IV length to be
505 used
506 In OpenSSL 3.0 setting the IV length to any value other than 12 will
508 result in an error. Prior to OpenSSL 3.0 the ivlen could be smaller
509 that the required 12 byte length, using EVP_CIPHER_CTX_ctrl(ctx,
510 EVP_CRTL_AEAD_SET_IVLEN, ivlen, NULL). This resulted in an IV that had
511 leading zero padding.
512 Installation and Compilation
514 Please refer to the INSTALL.md file in the top of the distribution for
515 instructions on how to build and install OpenSSL 3.0. Please also refer
516 to the various platform specific NOTES files for your specific
517 platform.
518 Upgrading from OpenSSL 1.1.1
520 Upgrading to OpenSSL 3.0 from OpenSSL 1.1.1 should be relatively
521 straight forward in most cases. The most likely area where you will
522 encounter problems is if you have used low level APIs in your code (as
523 discussed above). In that case you are likely to start seeing
524 deprecation warnings when compiling your application. If this happens
525 you have 3 options:
526 1. Ignore the warnings. They are just warnings. The deprecated
528 functions are still present and you may still use them. However be
529 aware that they may be removed from a future version of OpenSSL.
530 2. Suppress the warnings. Refer to your compiler documentation on how
532 to do this.
533 3. Remove your usage of the low level APIs. In this case you will need
535 to rewrite your code to use the high level APIs instead
536 Error code changes
538 As OpenSSL 3.0 provides a brand new Encoder/Decoder mechanism for
540 working with widely used file formats, application code that checks for
541 particular error reason codes on key loading failures might need an
542 update.
543 Password-protected keys may deserve special attention. If only some
545 errors are treated as an indicator that the user should be asked about
546 the password again, it's worth testing these scenarios and processing
547 the newly relevant codes.
548 There may be more cases to treat specially, depending on the calling
550 application code.
551 Upgrading from OpenSSL 1.0.2
553 Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 is likely to be
554 significantly more difficult. In addition to the issues discussed above
555 in the section about "Upgrading from OpenSSL 1.1.1", the main things to
556 be aware of are:
557 1. The build and installation procedure has changed significantly.
559 Check the file INSTALL.md in the top of the installation for
561 instructions on how to build and install OpenSSL for your platform.
562 Also read the various NOTES files in the same directory, as
563 applicable for your platform.
564 2. Many structures have been made opaque in OpenSSL 3.0.
566 The structure definitions have been removed from the public header
568 files and moved to internal header files. In practice this means
569 that you can no longer stack allocate some structures. Instead they
570 must be heap allocated through some function call (typically those
571 function names have a "_new" suffix to them). Additionally you
572 must use "setter" or "getter" functions to access the fields within
573 those structures.
574 For example code that previously looked like this:
576 EVP_MD_CTX md_ctx;
578 /* This line will now generate compiler errors */
580 EVP_MD_CTX_init(&md_ctx);
581 The code needs to be amended to look like this:
583 EVP_MD_CTX *md_ctx;
585 md_ctx = EVP_MD_CTX_new();
587 ...
588 ...
589 EVP_MD_CTX_free(md_ctx);
590 3. Support for TLSv1.3 has been added.
592 This has a number of implications for SSL/TLS applications. See the
594 TLS1.3 page <https://wiki.openssl.org/index.php/TLS1.3> for further
595 details.
596 More details about the breaking changes between OpenSSL versions 1.0.2
598 and 1.1.0 can be found on the OpenSSL 1.1.0 Changes page
599 <https://wiki.openssl.org/index.php/OpenSSL_1.1.0_Changes>.
600 Upgrading from the OpenSSL 2.0 FIPS Object Module
602 The OpenSSL 2.0 FIPS Object Module was a separate download that had to
604 be built separately and then integrated into your main OpenSSL 1.0.2
605 build. In OpenSSL 3.0 the FIPS support is fully integrated into the
606 mainline version of OpenSSL and is no longer a separate download. For
607 further information see "Completing the installation of the FIPS
608 Module".
609 The function calls FIPS_mode() and FIPS_mode_set() have been removed
611 from OpenSSL 3.0. You should rewrite your application to not use them.
612 See fips_module(7) and OSSL_PROVIDER-FIPS(7) for details.
613 Completing the installation of the FIPS Module
615 The FIPS Module will be built and installed automatically if FIPS
616 support has been configured. The current documentation can be found in
617 the README-FIPS <https://github.com/openssl/openssl/blob/master/README-
618 FIPS.md> file.
619 Programming
621 Applications written to work with OpenSSL 1.1.1 will mostly just work
622 with OpenSSL 3.0. However changes will be required if you want to take
623 advantage of some of the new features that OpenSSL 3.0 makes available.
624 In order to do that you need to understand some new concepts introduced
625 in OpenSSL 3.0. Read "Library contexts" in crypto(7) for further
626 information.
627 Library Context
629 A library context allows different components of a complex application
631 to each use a different library context and have different providers
632 loaded with different configuration settings. See "Library contexts"
633 in crypto(7) for further info.
634 If the user creates an OSSL_LIB_CTX via OSSL_LIB_CTX_new(3) then many
636 functions may need to be changed to pass additional parameters to
637 handle the library context.
638 Using a Library Context - Old functions that should be changed
640 If a library context is needed then all EVP_* digest functions that
642 return a const EVP_MD * such as EVP_sha256() should be replaced with a
643 call to EVP_MD_fetch(3). See "ALGORITHM FETCHING" in crypto(7).
644 If a library context is needed then all EVP_* cipher functions that
646 return a const EVP_CIPHER * such as EVP_aes_128_cbc() should be
647 replaced vith a call to EVP_CIPHER_fetch(3). See "ALGORITHM FETCHING"
648 in crypto(7).
649 Some functions can be passed an object that has already been set up
651 with a library context such as d2i_X509(3), d2i_X509_CRL(3),
652 d2i_X509_REQ(3) and d2i_X509_PUBKEY(3). If NULL is passed instead then
653 the created object will be set up with the default library context. Use
654 X509_new_ex(3), X509_CRL_new_ex(3), X509_REQ_new_ex(3) and
655 X509_PUBKEY_new_ex(3) if a library context is required.
656 All functions listed below with a NAME have a replacement function
658 NAME_ex that takes OSSL_LIB_CTX as an additional argument. Functions
659 that have other mappings are listed along with the respective name.
660 • ASN1_item_new(3), ASN1_item_d2i(3), ASN1_item_d2i_fp(3),
662 ASN1_item_d2i_bio(3), ASN1_item_sign(3) and ASN1_item_verify(3)
663 • BIO_new(3)
665 • b2i_RSA_PVK_bio() and i2b_PVK_bio()
667 • BN_CTX_new(3) and BN_CTX_secure_new(3)
669 • CMS_AuthEnvelopedData_create(3), CMS_ContentInfo_new(3),
671 CMS_data_create(3), CMS_digest_create(3),
672 CMS_EncryptedData_encrypt(3), CMS_encrypt(3),
673 CMS_EnvelopedData_create(3), CMS_ReceiptRequest_create0(3) and
674 CMS_sign(3)
675 • CONF_modules_load_file(3)
677 • CTLOG_new(3), CTLOG_new_from_base64(3) and CTLOG_STORE_new(3)
679 • CT_POLICY_EVAL_CTX_new(3)
681 • d2i_AutoPrivateKey(3), d2i_PrivateKey(3) and d2i_PUBKEY(3)
683 • d2i_PrivateKey_bio(3) and d2i_PrivateKey_fp(3)
685 Use d2i_PrivateKey_ex_bio(3) and d2i_PrivateKey_ex_fp(3)
687 • EC_GROUP_new(3)
689 Use EC_GROUP_new_by_curve_name_ex(3) or
691 EC_GROUP_new_from_params(3).
692 • EVP_DigestSignInit(3) and EVP_DigestVerifyInit(3)
694 • EVP_PBE_CipherInit(3), EVP_PBE_find(3) and EVP_PBE_scrypt(3)
696 • PKCS5_PBE_keyivgen(3)
698 • EVP_PKCS82PKEY(3)
700 • EVP_PKEY_CTX_new_id(3)
702 Use EVP_PKEY_CTX_new_from_name(3)
704 • EVP_PKEY_derive_set_peer(3), EVP_PKEY_new_raw_private_key(3) and
706 EVP_PKEY_new_raw_public_key(3)
707 • EVP_SignFinal(3) and EVP_VerifyFinal(3)
709 • NCONF_new(3)
711 • OCSP_RESPID_match(3) and OCSP_RESPID_set_by_key(3)
713 • OPENSSL_thread_stop(3)
715 • OSSL_STORE_open(3)
717 • PEM_read_bio_Parameters(3), PEM_read_bio_PrivateKey(3),
719 PEM_read_bio_PUBKEY(3), PEM_read_PrivateKey(3) and
720 PEM_read_PUBKEY(3)
721 • PEM_write_bio_PrivateKey(3), PEM_write_bio_PUBKEY(3),
723 PEM_write_PrivateKey(3) and PEM_write_PUBKEY(3)
724 • PEM_X509_INFO_read_bio(3) and PEM_X509_INFO_read(3)
726 • PKCS12_add_key(3), PKCS12_add_safe(3), PKCS12_add_safes(3),
728 PKCS12_create(3), PKCS12_decrypt_skey(3), PKCS12_init(3),
729 PKCS12_item_decrypt_d2i(3), PKCS12_item_i2d_encrypt(3),
730 PKCS12_key_gen_asc(3), PKCS12_key_gen_uni(3),
731 PKCS12_key_gen_utf8(3), PKCS12_pack_p7encdata(3),
732 PKCS12_pbe_crypt(3), PKCS12_PBE_keyivgen(3),
733 PKCS12_SAFEBAG_create_pkcs8_encrypt(3)
734 • PKCS5_pbe_set0_algor(3), PKCS5_pbe_set(3), PKCS5_pbe2_set_iv(3),
736 PKCS5_pbkdf2_set(3) and PKCS5_v2_scrypt_keyivgen(3)
737 • PKCS7_encrypt(3), PKCS7_new(3) and PKCS7_sign(3)
739 • PKCS8_decrypt(3), PKCS8_encrypt(3) and PKCS8_set0_pbe(3)
741 • RAND_bytes(3) and RAND_priv_bytes(3)
743 • SMIME_write_ASN1(3)
745 • SSL_load_client_CA_file(3)
747 • SSL_CTX_new(3)
749 • TS_RESP_CTX_new(3)
751 • X509_CRL_new(3)
753 • X509_load_cert_crl_file(3) and X509_load_cert_file(3)
755 • X509_LOOKUP_by_subject(3) and X509_LOOKUP_ctrl(3)
757 • X509_NAME_hash(3)
759 • X509_new(3)
761 • X509_REQ_new(3) and X509_REQ_verify(3)
763 • X509_STORE_CTX_new(3), X509_STORE_set_default_paths(3),
765 X509_STORE_load_file(3), X509_STORE_load_locations(3) and
766 X509_STORE_load_store(3)
767 New functions that use a Library context
769 The following functions can be passed a library context if required.
771 Passing NULL will use the default library context.
772 • BIO_new_from_core_bio(3)
774 • EVP_ASYM_CIPHER_fetch(3) and EVP_ASYM_CIPHER_do_all_provided(3)
776 • EVP_CIPHER_fetch(3) and EVP_CIPHER_do_all_provided(3)
778 • EVP_default_properties_enable_fips(3) and
780 EVP_default_properties_is_fips_enabled(3)
781 • EVP_KDF_fetch(3) and EVP_KDF_do_all_provided(3)
783 • EVP_KEM_fetch(3) and EVP_KEM_do_all_provided(3)
785 • EVP_KEYEXCH_fetch(3) and EVP_KEYEXCH_do_all_provided(3)
787 • EVP_KEYMGMT_fetch(3) and EVP_KEYMGMT_do_all_provided(3)
789 • EVP_MAC_fetch(3) and EVP_MAC_do_all_provided(3)
791 • EVP_MD_fetch(3) and EVP_MD_do_all_provided(3)
793 • EVP_PKEY_CTX_new_from_pkey(3)
795 • EVP_PKEY_Q_keygen(3)
797 • EVP_Q_mac(3) and EVP_Q_digest(3)
799 • EVP_RAND(3) and EVP_RAND_do_all_provided(3)
801 • EVP_set_default_properties(3)
803 • EVP_SIGNATURE_fetch(3) and EVP_SIGNATURE_do_all_provided(3)
805 • OSSL_CMP_CTX_new(3) and OSSL_CMP_SRV_CTX_new(3)
807 • OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert(3)
809 • OSSL_CRMF_MSG_create_popo(3) and OSSL_CRMF_MSGS_verify_popo(3)
811 • OSSL_CRMF_pbm_new(3) and OSSL_CRMF_pbmp_new(3)
813 • OSSL_DECODER_CTX_add_extra(3) and OSSL_DECODER_CTX_new_for_pkey(3)
815 • OSSL_DECODER_fetch(3) and OSSL_DECODER_do_all_provided(3)
817 • OSSL_ENCODER_CTX_add_extra(3)
819 • OSSL_ENCODER_fetch(3) and OSSL_ENCODER_do_all_provided(3)
821 • OSSL_LIB_CTX_free(3), OSSL_LIB_CTX_load_config(3) and
823 OSSL_LIB_CTX_set0_default(3)
824 • OSSL_PROVIDER_add_builtin(3), OSSL_PROVIDER_available(3),
826 OSSL_PROVIDER_do_all(3), OSSL_PROVIDER_load(3),
827 OSSL_PROVIDER_set_default_search_path(3) and
828 OSSL_PROVIDER_try_load(3)
829 • OSSL_SELF_TEST_get_callback(3) and OSSL_SELF_TEST_set_callback(3)
831 • OSSL_STORE_attach(3)
833 • OSSL_STORE_LOADER_fetch(3) and OSSL_STORE_LOADER_do_all_provided(3)
835 • RAND_get0_primary(3), RAND_get0_private(3), RAND_get0_public(3),
837 RAND_set_DRBG_type(3) and RAND_set_seed_source_type(3)
838 Providers
840 Providers are described in detail here "Providers" in crypto(7). See
842 also "OPENSSL PROVIDERS" in crypto(7).
843 Fetching algorithms and property queries
845 Implicit and Explicit Fetching is described in detail here "ALGORITHM
847 FETCHING" in crypto(7).
848 Mapping EVP controls and flags to provider OSSL_PARAM(3) parameters
850 The existing functions for controls (such as EVP_CIPHER_CTX_ctrl(3))
852 and manipulating flags (such as EVP_MD_CTX_set_flags(3))internally use
853 OSSL_PARAMS to pass information to/from provider objects. See
854 OSSL_PARAM(3) for additional information related to parameters.
855 For ciphers see "CONTROLS" in EVP_EncryptInit(3), "FLAGS" in
857 EVP_EncryptInit(3) and "PARAMETERS" in EVP_EncryptInit(3).
858 For digests see "CONTROLS" in EVP_DigestInit(3), "FLAGS" in
860 EVP_DigestInit(3) and "PARAMETERS" in EVP_DigestInit(3).
861 Deprecation of Low Level Functions
863 A significant number of APIs have been deprecated in OpenSSL 3.0. This
865 section describes some common categories of deprecations. See
866 "Deprecated function mappings" for the list of deprecated functions
867 that refer to these categories.
868 Providers are a replacement for engines and low-level method overrides
870 Any accessor that uses an ENGINE is deprecated (such as
872 EVP_PKEY_set1_engine()). Applications using engines should instead use
873 providers.
874 Before providers were added algorithms were overridden by changing the
876 methods used by algorithms. All these methods such as RSA_new_method()
877 and RSA_meth_new() are now deprecated and can be replaced by using
878 providers instead.
879 Deprecated i2d and d2i functions for low-level key types
881 Any i2d and d2i functions such as d2i_DHparams() that take a low-level
883 key type have been deprecated. Applications should instead use the
884 OSSL_DECODER(3) and OSSL_ENCODER(3) APIs to read and write files. See
885 "Migration" in d2i_RSAPrivateKey(3) for further details.
886 Deprecated low-level key object getters and setters
888 Applications that set or get low-level key objects (such as
890 EVP_PKEY_set1_DH() or EVP_PKEY_get0()) should instead use the
891 OSSL_ENCODER (See OSSL_ENCODER_to_bio(3)) or OSSL_DECODER (See
892 OSSL_DECODER_from_bio(3)) APIs, or alternatively use
893 EVP_PKEY_fromdata(3) or EVP_PKEY_todata(3).
894 Deprecated low-level key parameter getters
896 Functions that access low-level objects directly such as RSA_get0_n(3)
898 are now deprecated. Applications should use one of
899 EVP_PKEY_get_bn_param(3), EVP_PKEY_get_int_param(3),
900 l<EVP_PKEY_get_size_t_param(3)>, EVP_PKEY_get_utf8_string_param(3),
901 EVP_PKEY_get_octet_string_param(3) or EVP_PKEY_get_params(3) to access
902 fields from an EVP_PKEY. Gettable parameters are listed in "Common RSA
903 parameters" in EVP_PKEY-RSA(7), "DH parameters" in EVP_PKEY-DH(7), "DSA
904 parameters" in EVP_PKEY-DSA(7), "FFC parameters" in EVP_PKEY-FFC(7),
905 "Common EC parameters" in EVP_PKEY-EC(7) and "Common X25519, X448,
906 ED25519 and ED448 parameters" in EVP_PKEY-X25519(7). Applications may
907 also use EVP_PKEY_todata(3) to return all fields.
908 Deprecated low-level key parameter setters
910 Functions that access low-level objects directly such as
912 RSA_set0_crt_params(3) are now deprecated. Applications should use
913 EVP_PKEY_fromdata(3) to create new keys from user provided key data.
914 Keys should be immutable once they are created, so if required the user
915 may use EVP_PKEY_todata(3), OSSL_PARAM_merge(3), and
916 EVP_PKEY_fromdata(3) to create a modified key. See "Examples" in
917 EVP_PKEY-DH(7) for more information. See "Deprecated low-level key
918 generation functions" for information on generating a key using
919 parameters.
920 Deprecated low-level object creation
922 Low-level objects were created using methods such as RSA_new(3),
924 RSA_up_ref(3) and RSA_free(3). Applications should instead use the
925 high-level EVP_PKEY APIs, e.g. EVP_PKEY_new(3), EVP_PKEY_up_ref(3) and
926 EVP_PKEY_free(3). See also EVP_PKEY_CTX_new_from_name(3) and
927 EVP_PKEY_CTX_new_from_pkey(3).
928 EVP_PKEYs may be created in a variety of ways: See also "Deprecated
930 low-level key generation functions", "Deprecated low-level key reading
931 and writing functions" and "Deprecated low-level key parameter
932 setters".
933 Deprecated low-level encryption functions
935 Low-level encryption functions such as AES_encrypt(3) and
937 AES_decrypt(3) have been informally discouraged from use for a long
938 time. Applications should instead use the high level EVP APIs
939 EVP_EncryptInit_ex(3), EVP_EncryptUpdate(3), and EVP_EncryptFinal_ex(3)
940 or EVP_DecryptInit_ex(3), EVP_DecryptUpdate(3) and
941 EVP_DecryptFinal_ex(3).
942 Deprecated low-level digest functions
944 Use of low-level digest functions such as SHA1_Init(3) have been
946 informally discouraged from use for a long time. Applications should
947 instead use the the high level EVP APIs EVP_DigestInit_ex(3),
948 EVP_DigestUpdate(3) and EVP_DigestFinal_ex(3), or the quick one-shot
949 EVP_Q_digest(3).
950 Note that the functions SHA1(3), SHA224(3), SHA256(3), SHA384(3) and
952 SHA512(3) have changed to macros that use EVP_Q_digest(3).
953 Deprecated low-level signing functions
955 Use of low-level signing functions such as DSA_sign(3) have been
957 informally discouraged for a long time. Instead applications should use
958 EVP_DigestSign(3) and EVP_DigestVerify(3). See also
959 EVP_SIGNATURE-RSA(7), EVP_SIGNATURE-DSA(7), EVP_SIGNATURE-ECDSA(7) and
960 EVP_SIGNATURE-ED25519(7).
961 Deprecated low-level MAC functions
963 Low-level mac functions such as CMAC_Init(3) are deprecated.
965 Applications should instead use the new EVP_MAC(3) interface, using
966 EVP_MAC_CTX_new(3), EVP_MAC_CTX_free(3), EVP_MAC_init(3),
967 EVP_MAC_update(3) and EVP_MAC_final(3) or the single-shot MAC function
968 EVP_Q_mac(3). See EVP_MAC(3), EVP_MAC-HMAC(7), EVP_MAC-CMAC(7),
969 EVP_MAC-GMAC(7), EVP_MAC-KMAC(7), EVP_MAC-BLAKE2(7),
970 EVP_MAC-Poly1305(7) and EVP_MAC-Siphash(7) for additional information.
971 Note that the one-shot method HMAC() is still available for
973 compatibility purposes, but this can also be replaced by using
974 EVP_Q_MAC if a library context is required.
975 Deprecated low-level validation functions
977 Low-level validation functions such as DH_check(3) have been informally
979 discouraged from use for a long time. Applications should instead use
980 the high-level EVP_PKEY APIs such as EVP_PKEY_check(3),
981 EVP_PKEY_param_check(3), EVP_PKEY_param_check_quick(3),
982 EVP_PKEY_public_check(3), EVP_PKEY_public_check_quick(3),
983 EVP_PKEY_private_check(3), and EVP_PKEY_pairwise_check(3).
984 Deprecated low-level key exchange functions
986 Many low-level functions have been informally discouraged from use for
988 a long time. Applications should instead use EVP_PKEY_derive(3). See
989 EVP_KEYEXCH-DH(7), EVP_KEYEXCH-ECDH(7) and EVP_KEYEXCH-X25519(7).
990 Deprecated low-level key generation functions
992 Many low-level functions have been informally discouraged from use for
994 a long time. Applications should instead use EVP_PKEY_keygen_init(3)
995 and EVP_PKEY_generate(3) as described in EVP_PKEY-DSA(7),
996 EVP_PKEY-DH(7), EVP_PKEY-RSA(7), EVP_PKEY-EC(7) and EVP_PKEY-X25519(7).
997 The 'quick' one-shot function EVP_PKEY_Q_keygen(3) and macros for the
998 most common cases: <EVP_RSA_gen(3)> and EVP_EC_gen(3) may also be used.
999 Deprecated low-level key reading and writing functions
1001 Use of low-level objects (such as DSA) has been informally discouraged
1003 from use for a long time. Functions to read and write these low-level
1004 objects (such as PEM_read_DSA_PUBKEY()) should be replaced.
1005 Applications should instead use OSSL_ENCODER_to_bio(3) and
1006 OSSL_DECODER_from_bio(3).
1007 Deprecated low-level key printing functions
1009 Use of low-level objects (such as DSA) has been informally discouraged
1011 from use for a long time. Functions to print these low-level objects
1012 such as DSA_print() should be replaced with the equivalent EVP_PKEY
1013 functions. Application should use one of EVP_PKEY_print_public(3),
1014 EVP_PKEY_print_private(3), EVP_PKEY_print_params(3),
1015 EVP_PKEY_print_public_fp(3), EVP_PKEY_print_private_fp(3) or
1016 EVP_PKEY_print_params_fp(3). Note that internally these use
1017 OSSL_ENCODER_to_bio(3) and OSSL_DECODER_from_bio(3).
1018 Deprecated function mappings
1020 The following functions have been deprecated in 3.0.
1022 • AES_bi_ige_encrypt() and AES_ige_encrypt()
1024 There is no replacement for the IGE functions. New code should not
1026 use these modes. These undocumented functions were never
1027 integrated into the EVP layer. They implemented the AES Infinite
1028 Garble Extension (IGE) mode and AES Bi-directional IGE mode. These
1029 modes were never formally standardised and usage of these functions
1030 is believed to be very small. In particular AES_bi_ige_encrypt()
1031 has a known bug. It accepts 2 AES keys, but only one is ever used.
1032 The security implications are believed to be minimal, but this
1033 issue was never fixed for backwards compatibility reasons.
1034 • AES_encrypt(), AES_decrypt(), AES_set_encrypt_key(),
1036 AES_set_decrypt_key(), AES_cbc_encrypt(), AES_cfb128_encrypt(),
1037 AES_cfb1_encrypt(), AES_cfb8_encrypt(), AES_ecb_encrypt(),
1038 AES_ofb128_encrypt()
1039 • AES_unwrap_key(), AES_wrap_key()
1041 See "Deprecated low-level encryption functions"
1043 • AES_options()
1045 There is no replacement. It returned a string indicating if the AES
1047 code was unrolled.
1048 • ASN1_digest(), ASN1_sign(), ASN1_verify()
1050 There are no replacements. These old functions are not used, and
1052 could be disabled with the macro NO_ASN1_OLD since OpenSSL 0.9.7.
1053 • ASN1_STRING_length_set()
1055 Use ASN1_STRING_set(3) or ASN1_STRING_set0(3) instead. This was a
1057 potentially unsafe function that could change the bounds of a
1058 previously passed in pointer.
1059 • BF_encrypt(), BF_decrypt(), BF_set_key(), BF_cbc_encrypt(),
1061 BF_cfb64_encrypt(), BF_ecb_encrypt(), BF_ofb64_encrypt()
1062 See "Deprecated low-level encryption functions". The Blowfish
1064 algorithm has been moved to the Legacy Provider.
1065 • BF_options()
1067 There is no replacement. This option returned a constant string.
1069 • BIO_get_callback(), BIO_set_callback(), BIO_debug_callback()
1071 Use the respective non-deprecated _ex() functions.
1073 • BN_is_prime_ex(), BN_is_prime_fasttest_ex()
1075 Use BN_check_prime(3) which avoids possible misuse and always uses
1077 at least 64 rounds of the Miller-Rabin primality test.
1078 • BN_pseudo_rand(), BN_pseudo_rand_range()
1080 Use BN_rand(3) and BN_rand_range(3).
1082 • BN_X931_derive_prime_ex(), BN_X931_generate_prime_ex(),
1084 BN_X931_generate_Xpq()
1085 There are no replacements for these low-level functions. They were
1087 used internally by RSA_X931_derive_ex() and
1088 RSA_X931_generate_key_ex() which are also deprecated. Use
1089 EVP_PKEY_keygen(3) instead.
1090 • Camellia_encrypt(), Camellia_decrypt(), Camellia_set_key(),
1092 Camellia_cbc_encrypt(), Camellia_cfb128_encrypt(),
1093 Camellia_cfb1_encrypt(), Camellia_cfb8_encrypt(),
1094 Camellia_ctr128_encrypt(), Camellia_ecb_encrypt(),
1095 Camellia_ofb128_encrypt()
1096 See "Deprecated low-level encryption functions".
1098 • CAST_encrypt(), CAST_decrypt(), CAST_set_key(), CAST_cbc_encrypt(),
1100 CAST_cfb64_encrypt(), CAST_ecb_encrypt(), CAST_ofb64_encrypt()
1101 See "Deprecated low-level encryption functions". The CAST
1103 algorithm has been moved to the Legacy Provider.
1104 • CMAC_CTX_new(), CMAC_CTX_cleanup(), CMAC_CTX_copy(),
1106 CMAC_CTX_free(), CMAC_CTX_get0_cipher_ctx()
1107 See "Deprecated low-level MAC functions".
1109 • CMAC_Init(), CMAC_Update(), CMAC_Final(), CMAC_resume()
1111 See "Deprecated low-level MAC functions".
1113 • CRYPTO_mem_ctrl(), CRYPTO_mem_debug_free(),
1115 CRYPTO_mem_debug_malloc(), CRYPTO_mem_debug_pop(),
1116 CRYPTO_mem_debug_push(), CRYPTO_mem_debug_realloc(),
1117 CRYPTO_mem_leaks(), CRYPTO_mem_leaks_cb(), CRYPTO_mem_leaks_fp(),
1118 CRYPTO_set_mem_debug()
1119 Memory-leak checking has been deprecated in favor of more modern
1121 development tools, such as compiler memory and leak sanitizers or
1122 Valgrind.
1123 • CRYPTO_cts128_encrypt_block(), CRYPTO_cts128_encrypt(),
1125 CRYPTO_cts128_decrypt_block(), CRYPTO_cts128_decrypt(),
1126 CRYPTO_nistcts128_encrypt_block(), CRYPTO_nistcts128_encrypt(),
1127 CRYPTO_nistcts128_decrypt_block(), CRYPTO_nistcts128_decrypt()
1128 Use the higher level functions EVP_CipherInit_ex2(),
1130 EVP_CipherUpdate() and EVP_CipherFinal_ex() instead. See the
1131 "cts_mode" parameter in "Gettable and Settable EVP_CIPHER_CTX
1132 parameters" in EVP_EncryptInit(3). See "EXAMPLES" in
1133 EVP_EncryptInit(3) for a AES-256-CBC-CTS example.
1134 • d2i_DHparams(), d2i_DHxparams(), d2i_DSAparams(),
1136 d2i_DSAPrivateKey(), d2i_DSAPrivateKey_bio(),
1137 d2i_DSAPrivateKey_fp(), d2i_DSA_PUBKEY(), d2i_DSA_PUBKEY_bio(),
1138 d2i_DSA_PUBKEY_fp(), d2i_DSAPublicKey(), d2i_ECParameters(),
1139 d2i_ECPrivateKey(), d2i_ECPrivateKey_bio(), d2i_ECPrivateKey_fp(),
1140 d2i_EC_PUBKEY(), d2i_EC_PUBKEY_bio(), d2i_EC_PUBKEY_fp(),
1141 o2i_ECPublicKey(), d2i_RSAPrivateKey(), d2i_RSAPrivateKey_bio(),
1142 d2i_RSAPrivateKey_fp(), d2i_RSA_PUBKEY(), d2i_RSA_PUBKEY_bio(),
1143 d2i_RSA_PUBKEY_fp(), d2i_RSAPublicKey(), d2i_RSAPublicKey_bio(),
1144 d2i_RSAPublicKey_fp()
1145 See "Deprecated i2d and d2i functions for low-level key types"
1147 • DES_crypt(), DES_fcrypt(), DES_encrypt1(), DES_encrypt2(),
1149 DES_encrypt3(), DES_decrypt3(), DES_ede3_cbc_encrypt(),
1150 DES_ede3_cfb64_encrypt(),
1151 DES_ede3_cfb_encrypt(),DES_ede3_ofb64_encrypt(), DES_ecb_encrypt(),
1152 DES_ecb3_encrypt(), DES_ofb64_encrypt(), DES_ofb_encrypt(),
1153 DES_cfb64_encrypt DES_cfb_encrypt(), DES_cbc_encrypt(),
1154 DES_ncbc_encrypt(), DES_pcbc_encrypt(), DES_xcbc_encrypt(),
1155 DES_cbc_cksum(), DES_quad_cksum(), DES_check_key_parity(),
1156 DES_is_weak_key(), DES_key_sched(), DES_options(),
1157 DES_random_key(), DES_set_key(), DES_set_key_checked(),
1158 DES_set_key_unchecked(), DES_set_odd_parity(),
1159 DES_string_to_2keys(), DES_string_to_key()
1160 See "Deprecated low-level encryption functions". Algorithms for
1162 "DESX-CBC", "DES-ECB", "DES-CBC", "DES-OFB", "DES-CFB", "DES-CFB1"
1163 and "DES-CFB8" have been moved to the Legacy Provider.
1164 • DH_bits(), DH_security_bits(), DH_size()
1166 Use EVP_PKEY_get_bits(3), EVP_PKEY_get_security_bits(3) and
1168 EVP_PKEY_get_size(3).
1169 • DH_check(), DH_check_ex(), DH_check_params(), DH_check_params_ex(),
1171 DH_check_pub_key(), DH_check_pub_key_ex()
1172 See "Deprecated low-level validation functions"
1174 • DH_clear_flags(), DH_test_flags(), DH_set_flags()
1176 The DH_FLAG_CACHE_MONT_P flag has been deprecated without
1178 replacement. The DH_FLAG_TYPE_DH and DH_FLAG_TYPE_DHX have been
1179 deprecated. Use EVP_PKEY_is_a() to determine the type of a key.
1180 There is no replacement for setting these flags.
1181 • DH_compute_key() DH_compute_key_padded()
1183 See "Deprecated low-level key exchange functions".
1185 • DH_new(), DH_new_by_nid(), DH_free(), DH_up_ref()
1187 See "Deprecated low-level object creation"
1189 • DH_generate_key(), DH_generate_parameters_ex()
1191 See "Deprecated low-level key generation functions".
1193 • DH_get0_pqg(), DH_get0_p(), DH_get0_q(), DH_get0_g(),
1195 DH_get0_key(), DH_get0_priv_key(), DH_get0_pub_key(),
1196 DH_get_length(), DH_get_nid()
1197 See "Deprecated low-level key parameter getters"
1199 • DH_get_1024_160(), DH_get_2048_224(), DH_get_2048_256()
1201 Applications should instead set the OSSL_PKEY_PARAM_GROUP_NAME as
1203 specified in "DH parameters" in EVP_PKEY-DH(7)) to one of
1204 "dh_1024_160", "dh_2048_224" or "dh_2048_256" when generating a DH
1205 key.
1206 • DH_KDF_X9_42()
1208 Applications should use EVP_PKEY_CTX_set_dh_kdf_type(3) instead.
1210 • DH_get_default_method(), DH_get0_engine(), DH_meth_*(),
1212 DH_new_method(), DH_OpenSSL(), DH_get_ex_data(),
1213 DH_set_default_method(), DH_set_method(), DH_set_ex_data()
1214 See "Providers are a replacement for engines and low-level method
1216 overrides"
1217 • DHparams_print(), DHparams_print_fp()
1219 See "Deprecated low-level key printing functions"
1221 • DH_set0_key(), DH_set0_pqg(), DH_set_length()
1223 See "Deprecated low-level key parameter setters"
1225 • DSA_bits(), DSA_security_bits(), DSA_size()
1227 Use EVP_PKEY_get_bits(3), EVP_PKEY_get_security_bits(3) and
1229 EVP_PKEY_get_size(3).
1230 • DHparams_dup(), DSA_dup_DH()
1232 There is no direct replacement. Applications may use
1234 EVP_PKEY_copy_parameters(3) and EVP_PKEY_dup(3) instead.
1235 • DSA_generate_key(), DSA_generate_parameters_ex()
1237 See "Deprecated low-level key generation functions".
1239 • DSA_get0_engine(), DSA_get_default_method(), DSA_get_ex_data(),
1241 DSA_get_method(), DSA_meth_*(), DSA_new_method(), DSA_OpenSSL(),
1242 DSA_set_default_method(), DSA_set_ex_data(), DSA_set_method()
1243 See "Providers are a replacement for engines and low-level method
1245 overrides".
1246 • DSA_get0_p(), DSA_get0_q(), DSA_get0_g(), DSA_get0_pqg(),
1248 DSA_get0_key(), DSA_get0_priv_key(), DSA_get0_pub_key()
1249 See "Deprecated low-level key parameter getters".
1251 • DSA_new(), DSA_free(), DSA_up_ref()
1253 See "Deprecated low-level object creation"
1255 • DSAparams_dup()
1257 There is no direct replacement. Applications may use
1259 EVP_PKEY_copy_parameters(3) and EVP_PKEY_dup(3) instead.
1260 • DSAparams_print(), DSAparams_print_fp(), DSA_print(),
1262 DSA_print_fp()
1263 See "Deprecated low-level key printing functions"
1265 • DSA_set0_key(), DSA_set0_pqg()
1267 See "Deprecated low-level key parameter setters"
1269 • DSA_set_flags(), DSA_clear_flags(), DSA_test_flags()
1271 The DSA_FLAG_CACHE_MONT_P flag has been deprecated without
1273 replacement.
1274 • DSA_sign(), DSA_do_sign(), DSA_sign_setup(), DSA_verify(),
1276 DSA_do_verify()
1277 See "Deprecated low-level signing functions".
1279 • ECDH_compute_key()
1281 See "Deprecated low-level key exchange functions".
1283 • ECDH_KDF_X9_62()
1285 Applications may either set this using the helper function
1287 EVP_PKEY_CTX_set_ecdh_kdf_type(3) or by setting an OSSL_PARAM(3)
1288 using the "kdf-type" as shown in "EXAMPLES" in EVP_KEYEXCH-ECDH(7)
1289 • ECDSA_sign(), ECDSA_sign_ex(), ECDSA_sign_setup(), ECDSA_do_sign(),
1291 ECDSA_do_sign_ex(), ECDSA_verify(), ECDSA_do_verify()
1292 See "Deprecated low-level signing functions".
1294 • ECDSA_size()
1296 Applications should use EVP_PKEY_get_size(3).
1298 • EC_GF2m_simple_method(), EC_GFp_mont_method(),
1300 EC_GFp_nist_method(), EC_GFp_nistp224_method(),
1301 EC_GFp_nistp256_method(), EC_GFp_nistp521_method(),
1302 EC_GFp_simple_method()
1303 There are no replacements for these functions. Applications should
1305 rely on the library automatically assigning a suitable method
1306 internally when an EC_GROUP is constructed.
1307 • EC_GROUP_clear_free()
1309 Use EC_GROUP_free(3) instead.
1311 • EC_GROUP_get_curve_GF2m(), EC_GROUP_get_curve_GFp(),
1313 EC_GROUP_set_curve_GF2m(), EC_GROUP_set_curve_GFp()
1314 Applications should use EC_GROUP_get_curve(3) and
1316 EC_GROUP_set_curve(3).
1317 • EC_GROUP_have_precompute_mult(), EC_GROUP_precompute_mult(),
1319 EC_KEY_precompute_mult()
1320 These functions are not widely used. Applications should instead
1322 switch to named curves which OpenSSL has hardcoded lookup tables
1323 for.
1324 • EC_GROUP_new(), EC_GROUP_method_of(), EC_POINT_method_of()
1326 EC_METHOD is now an internal-only concept and a suitable EC_METHOD
1328 is assigned internally without application intervention. Users of
1329 EC_GROUP_new() should switch to a different suitable constructor.
1330 • EC_KEY_can_sign()
1332 Applications should use EVP_PKEY_can_sign(3) instead.
1334 • EC_KEY_check_key()
1336 See "Deprecated low-level validation functions"
1338 • EC_KEY_set_flags(), EC_KEY_get_flags(), EC_KEY_clear_flags()
1340 See "Common EC parameters" in EVP_PKEY-EC(7) which handles flags as
1342 separate parameters for OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT,
1343 OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE, OSSL_PKEY_PARAM_EC_ENCODING,
1344 OSSL_PKEY_PARAM_USE_COFACTOR_ECDH and
1345 OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC. See also "EXAMPLES" in
1346 EVP_PKEY-EC(7)
1347 • EC_KEY_dup(), EC_KEY_copy()
1349 There is no direct replacement. Applications may use
1351 EVP_PKEY_copy_parameters(3) and EVP_PKEY_dup(3) instead.
1352 • EC_KEY_decoded_from_explicit_params()
1354 There is no replacement.
1356 • EC_KEY_generate_key()
1358 See "Deprecated low-level key generation functions".
1360 • EC_KEY_get0_group(), EC_KEY_get0_private_key(),
1362 EC_KEY_get0_public_key(), EC_KEY_get_conv_form(),
1363 EC_KEY_get_enc_flags()
1364 See "Deprecated low-level key parameter getters".
1366 • EC_KEY_get0_engine(), EC_KEY_get_default_method(),
1368 EC_KEY_get_method(), EC_KEY_new_method(), EC_KEY_get_ex_data(),
1369 EC_KEY_OpenSSL(), EC_KEY_set_ex_data(),
1370 EC_KEY_set_default_method(), EC_KEY_METHOD_*(), EC_KEY_set_method()
1371 See "Providers are a replacement for engines and low-level method
1373 overrides"
1374 • EC_METHOD_get_field_type()
1376 Use EC_GROUP_get_field_type(3) instead. See "Providers are a
1378 replacement for engines and low-level method overrides"
1379 • EC_KEY_key2buf(), EC_KEY_oct2key(), EC_KEY_oct2priv(),
1381 EC_KEY_priv2buf(), EC_KEY_priv2oct()
1382 There are no replacements for these.
1384 • EC_KEY_new(), EC_KEY_new_by_curve_name(), EC_KEY_free(),
1386 EC_KEY_up_ref()
1387 See "Deprecated low-level object creation"
1389 • EC_KEY_print(), EC_KEY_print_fp()
1391 See "Deprecated low-level key printing functions"
1393 • EC_KEY_set_asn1_flag(), EC_KEY_set_conv_form(),
1395 EC_KEY_set_enc_flags()
1396 See "Deprecated low-level key parameter setters".
1398 • EC_KEY_set_group(), EC_KEY_set_private_key(),
1400 EC_KEY_set_public_key(), EC_KEY_set_public_key_affine_coordinates()
1401 See "Deprecated low-level key parameter setters".
1403 • ECParameters_print(), ECParameters_print_fp(),
1405 ECPKParameters_print(), ECPKParameters_print_fp()
1406 See "Deprecated low-level key printing functions"
1408 • EC_POINT_bn2point(), EC_POINT_point2bn()
1410 These functions were not particularly useful, since EC point
1412 serialization formats are not individual big-endian integers.
1413 • EC_POINT_get_affine_coordinates_GF2m(),
1415 EC_POINT_get_affine_coordinates_GFp(),
1416 EC_POINT_set_affine_coordinates_GF2m(),
1417 EC_POINT_set_affine_coordinates_GFp()
1418 Applications should use EC_POINT_get_affine_coordinates(3) and
1420 EC_POINT_set_affine_coordinates(3) instead.
1421 • EC_POINT_get_Jprojective_coordinates_GFp(),
1423 EC_POINT_set_Jprojective_coordinates_GFp()
1424 These functions are not widely used. Applications should instead
1426 use the EC_POINT_set_affine_coordinates(3) and
1427 EC_POINT_get_affine_coordinates(3) functions.
1428 • EC_POINT_make_affine(), EC_POINTs_make_affine()
1430 There is no replacement. These functions were not widely used, and
1432 OpenSSL automatically performs this conversion when needed.
1433 • EC_POINT_set_compressed_coordinates_GF2m(),
1435 EC_POINT_set_compressed_coordinates_GFp()
1436 Applications should use EC_POINT_set_compressed_coordinates(3)
1438 instead.
1439 • EC_POINTs_mul()
1441 This function is not widely used. Applications should instead use
1443 the EC_POINT_mul(3) function.
1444 • ENGINE_*()
1446 All engine functions are deprecated. An engine should be rewritten
1448 as a provider. See "Providers are a replacement for engines and
1449 low-level method overrides".
1450 • ERR_load_*(), ERR_func_error_string(), ERR_get_error_line(),
1452 ERR_get_error_line_data(), ERR_get_state()
1453 OpenSSL now loads error strings automatically so these functions
1455 are not needed.
1456 • ERR_peek_error_line_data(), ERR_peek_last_error_line_data()
1458 The new functions are ERR_peek_error_func(3),
1460 ERR_peek_last_error_func(3), ERR_peek_error_data(3),
1461 ERR_peek_last_error_data(3), ERR_get_error_all(3),
1462 ERR_peek_error_all(3) and ERR_peek_last_error_all(3). Applications
1463 should use ERR_get_error_all(3), or pick information with ERR_peek
1464 functions and finish off with getting the error code by using
1465 ERR_get_error(3).
1466 • EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_iv_noconst(),
1468 EVP_CIPHER_CTX_original_iv()
1469 Applications should instead use EVP_CIPHER_CTX_get_updated_iv(3),
1471 EVP_CIPHER_CTX_get_updated_iv(3) and
1472 EVP_CIPHER_CTX_get_original_iv(3) respectively. See
1473 EVP_CIPHER_CTX_get_original_iv(3) for further information.
1474 • EVP_CIPHER_meth_*(), EVP_MD_CTX_set_update_fn(),
1476 EVP_MD_CTX_update_fn(), EVP_MD_meth_*()
1477 See "Providers are a replacement for engines and low-level method
1479 overrides".
1480 • EVP_PKEY_CTRL_PKCS7_ENCRYPT(), EVP_PKEY_CTRL_PKCS7_DECRYPT(),
1482 EVP_PKEY_CTRL_PKCS7_SIGN(), EVP_PKEY_CTRL_CMS_ENCRYPT(),
1483 EVP_PKEY_CTRL_CMS_DECRYPT(), and EVP_PKEY_CTRL_CMS_SIGN()
1484 These control operations are not invoked by the OpenSSL library
1486 anymore and are replaced by direct checks of the key operation
1487 against the key type when the operation is initialized.
1488 • EVP_PKEY_CTX_get0_dh_kdf_ukm(), EVP_PKEY_CTX_get0_ecdh_kdf_ukm()
1490 See the "kdf-ukm" item in "DH key exchange parameters" in
1492 EVP_KEYEXCH-DH(7) and "ECDH Key Exchange parameters" in
1493 EVP_KEYEXCH-ECDH(7). These functions are obsolete and should not
1494 be required.
1495 • EVP_PKEY_CTX_set_rsa_keygen_pubexp()
1497 Applications should use EVP_PKEY_CTX_set1_rsa_keygen_pubexp(3)
1499 instead.
1500 • EVP_PKEY_cmp(), EVP_PKEY_cmp_parameters()
1502 Applications should use EVP_PKEY_eq(3) and
1504 EVP_PKEY_parameters_eq(3) instead. See EVP_PKEY_copy_parameters(3)
1505 for further details.
1506 • EVP_PKEY_encrypt_old(), EVP_PKEY_decrypt_old(),
1508 Applications should use EVP_PKEY_encrypt_init(3) and
1510 EVP_PKEY_encrypt(3) or EVP_PKEY_decrypt_init(3) and
1511 EVP_PKEY_decrypt(3) instead.
1512 • EVP_PKEY_get0()
1514 This function returns NULL if the key comes from a provider.
1516 • EVP_PKEY_get0_DH(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_EC_KEY(),
1518 EVP_PKEY_get0_RSA(), EVP_PKEY_get1_DH(), EVP_PKEY_get1_DSA(),
1519 EVP_PKEY_get1_EC_KEY and EVP_PKEY_get1_RSA(), EVP_PKEY_get0_hmac(),
1520 EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash()
1521 See "Functions that return an internal key should be treated as
1523 read only".
1524 • EVP_PKEY_meth_*()
1526 See "Providers are a replacement for engines and low-level method
1528 overrides".
1529 • EVP_PKEY_new_CMAC_key()
1531 See "Deprecated low-level MAC functions".
1533 • EVP_PKEY_assign(), EVP_PKEY_set1_DH(), EVP_PKEY_set1_DSA(),
1535 EVP_PKEY_set1_EC_KEY(), EVP_PKEY_set1_RSA()
1536 See "Deprecated low-level key object getters and setters"
1538 • EVP_PKEY_set1_tls_encodedpoint() EVP_PKEY_get1_tls_encodedpoint()
1540 These functions were previously used by libssl to set or get an
1542 encoded public key into/from an EVP_PKEY object. With OpenSSL 3.0
1543 these are replaced by the more generic functions
1544 EVP_PKEY_set1_encoded_public_key(3) and
1545 EVP_PKEY_get1_encoded_public_key(3). The old versions have been
1546 converted to deprecated macros that just call the new functions.
1547 • EVP_PKEY_set1_engine(), EVP_PKEY_get0_engine()
1549 See "Providers are a replacement for engines and low-level method
1551 overrides".
1552 • EVP_PKEY_set_alias_type()
1554 This function has been removed. There is no replacement. See
1556 "EVP_PKEY_set_alias_type() method has been removed"
1557 • HMAC_Init_ex(), HMAC_Update(), HMAC_Final(), HMAC_size()
1559 See "Deprecated low-level MAC functions".
1561 • HMAC_CTX_new(), HMAC_CTX_free(), HMAC_CTX_copy(), HMAC_CTX_reset(),
1563 HMAC_CTX_set_flags(), HMAC_CTX_get_md()
1564 See "Deprecated low-level MAC functions".
1566 • i2d_DHparams(), i2d_DHxparams()
1568 See "Deprecated low-level key reading and writing functions" and
1570 "Migration" in d2i_RSAPrivateKey(3)
1571 • i2d_DSAparams(), i2d_DSAPrivateKey(), i2d_DSAPrivateKey_bio(),
1573 i2d_DSAPrivateKey_fp(), i2d_DSA_PUBKEY(), i2d_DSA_PUBKEY_bio(),
1574 i2d_DSA_PUBKEY_fp(), i2d_DSAPublicKey()
1575 See "Deprecated low-level key reading and writing functions" and
1577 "Migration" in d2i_RSAPrivateKey(3)
1578 • i2d_ECParameters(), i2d_ECPrivateKey(), i2d_ECPrivateKey_bio(),
1580 i2d_ECPrivateKey_fp(), i2d_EC_PUBKEY(), i2d_EC_PUBKEY_bio(),
1581 i2d_EC_PUBKEY_fp(), i2o_ECPublicKey()
1582 See "Deprecated low-level key reading and writing functions" and
1584 "Migration" in d2i_RSAPrivateKey(3)
1585 • i2d_RSAPrivateKey(), i2d_RSAPrivateKey_bio(),
1587 i2d_RSAPrivateKey_fp(), i2d_RSA_PUBKEY(), i2d_RSA_PUBKEY_bio(),
1588 i2d_RSA_PUBKEY_fp(), i2d_RSAPublicKey(), i2d_RSAPublicKey_bio(),
1589 i2d_RSAPublicKey_fp()
1590 See "Deprecated low-level key reading and writing functions" and
1592 "Migration" in d2i_RSAPrivateKey(3)
1593 • IDEA_encrypt(), IDEA_set_decrypt_key(), IDEA_set_encrypt_key(),
1595 IDEA_cbc_encrypt(), IDEA_cfb64_encrypt(), IDEA_ecb_encrypt(),
1596 IDEA_ofb64_encrypt()
1597 See "Deprecated low-level encryption functions". IDEA has been
1599 moved to the Legacy Provider.
1600 • IDEA_options()
1602 There is no replacement. This function returned a constant string.
1604 • MD2(), MD2_Init(), MD2_Update(), MD2_Final()
1606 See "Deprecated low-level encryption functions". MD2 has been
1608 moved to the Legacy Provider.
1609 • MD2_options()
1611 There is no replacement. This function returned a constant string.
1613 • MD4(), MD4_Init(), MD4_Update(), MD4_Final(), MD4_Transform()
1615 See "Deprecated low-level encryption functions". MD4 has been
1617 moved to the Legacy Provider.
1618 • MDC2(), MDC2_Init(), MDC2_Update(), MDC2_Final()
1620 See "Deprecated low-level encryption functions". MDC2 has been
1622 moved to the Legacy Provider.
1623 • MD5(), MD5_Init(), MD5_Update(), MD5_Final(), MD5_Transform()
1625 See "Deprecated low-level encryption functions".
1627 • NCONF_WIN32()
1629 This undocumented function has no replacement. See "HISTORY" in
1631 config(5) for more details.
1632 • OCSP_parse_url()
1634 Use OSSL_HTTP_parse_url(3) instead.
1636 • OCSP_REQ_CTX type and OCSP_REQ_CTX_*() functions
1638 These methods were used to collect all necessary data to form a
1640 HTTP request, and to perform the HTTP transfer with that request.
1641 With OpenSSL 3.0, the type is OSSL_HTTP_REQ_CTX, and the deprecated
1642 functions are replaced with OSSL_HTTP_REQ_CTX_*(). See
1643 OSSL_HTTP_REQ_CTX(3) for additional details.
1644 • OPENSSL_fork_child(), OPENSSL_fork_parent(), OPENSSL_fork_prepare()
1646 There is no replacement for these functions. These pthread fork
1648 support methods were unused by OpenSSL.
1649 • OSSL_STORE_ctrl(), OSSL_STORE_do_all_loaders(),
1651 OSSL_STORE_LOADER_get0_engine(), OSSL_STORE_LOADER_get0_scheme(),
1652 OSSL_STORE_LOADER_new(), OSSL_STORE_LOADER_set_attach(),
1653 OSSL_STORE_LOADER_set_close(), OSSL_STORE_LOADER_set_ctrl(),
1654 OSSL_STORE_LOADER_set_eof(), OSSL_STORE_LOADER_set_error(),
1655 OSSL_STORE_LOADER_set_expect(), OSSL_STORE_LOADER_set_find(),
1656 OSSL_STORE_LOADER_set_load(), OSSL_STORE_LOADER_set_open(),
1657 OSSL_STORE_LOADER_set_open_ex(), OSSL_STORE_register_loader(),
1658 OSSL_STORE_unregister_loader(), OSSL_STORE_vctrl()
1659 These functions helped applications and engines create loaders for
1661 schemes they supported. These are all deprecated and discouraged
1662 in favour of provider implementations, see provider-storemgmt(7).
1663 • PEM_read_DHparams(), PEM_read_bio_DHparams(), PEM_read_DSAparams(),
1665 PEM_read_bio_DSAparams(), PEM_read_DSAPrivateKey(),
1666 PEM_read_DSA_PUBKEY(), PEM_read_bio_DSAPrivateKey and
1667 PEM_read_bio_DSA_PUBKEY(), PEM_read_ECPKParameters(),
1668 PEM_read_ECPrivateKey(), PEM_read_EC_PUBKEY(),
1669 PEM_read_bio_ECPKParameters(), PEM_read_bio_ECPrivateKey(),
1670 PEM_read_bio_EC_PUBKEY(), PEM_read_RSAPrivateKey(),
1671 PEM_read_RSA_PUBKEY(), PEM_read_RSAPublicKey(),
1672 PEM_read_bio_RSAPrivateKey(), PEM_read_bio_RSA_PUBKEY(),
1673 PEM_read_bio_RSAPublicKey(), PEM_write_bio_DHparams(),
1674 PEM_write_bio_DHxparams(), PEM_write_DHparams(),
1675 PEM_write_DHxparams(), PEM_write_DSAparams(),
1676 PEM_write_DSAPrivateKey(), PEM_write_DSA_PUBKEY(),
1677 PEM_write_bio_DSAparams(), PEM_write_bio_DSAPrivateKey(),
1678 PEM_write_bio_DSA_PUBKEY(), PEM_write_ECPKParameters(),
1679 PEM_write_ECPrivateKey(), PEM_write_EC_PUBKEY(),
1680 PEM_write_bio_ECPKParameters(), PEM_write_bio_ECPrivateKey(),
1681 PEM_write_bio_EC_PUBKEY(), PEM_write_RSAPrivateKey(),
1682 PEM_write_RSA_PUBKEY(), PEM_write_RSAPublicKey(),
1683 PEM_write_bio_RSAPrivateKey(), PEM_write_bio_RSA_PUBKEY(),
1684 PEM_write_bio_RSAPublicKey(),
1685 See "Deprecated low-level key reading and writing functions"
1687 • PKCS1_MGF1()
1689 See "Deprecated low-level encryption functions".
1691 • RAND_get_rand_method(), RAND_set_rand_method(), RAND_OpenSSL(),
1693 RAND_set_rand_engine()
1694 Applications should instead use RAND_set_DRBG_type(3), EVP_RAND(3)
1696 and EVP_RAND(7). See RAND_set_rand_method(3) for more details.
1697 • RC2_encrypt(), RC2_decrypt(), RC2_set_key(), RC2_cbc_encrypt(),
1699 RC2_cfb64_encrypt(), RC2_ecb_encrypt(), RC2_ofb64_encrypt(), RC4(),
1700 RC4_set_key(), RC4_options(), RC5_32_encrypt(), RC5_32_set_key(),
1701 RC5_32_decrypt(), RC5_32_cbc_encrypt(), RC5_32_cfb64_encrypt(),
1702 RC5_32_ecb_encrypt(), RC5_32_ofb64_encrypt()
1703 See "Deprecated low-level encryption functions". The Algorithms
1705 "RC2", "RC4" and "RC5" have been moved to the Legacy Provider.
1706 • RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update(),
1708 RIPEMD160_Final(), RIPEMD160_Transform()
1709 See "Deprecated low-level digest functions". The RIPE algorithm
1711 has been moved to the Legacy Provider.
1712 • RSA_bits(), RSA_security_bits(), RSA_size()
1714 Use EVP_PKEY_get_bits(3), EVP_PKEY_get_security_bits(3) and
1716 EVP_PKEY_get_size(3).
1717 • RSA_check_key(), RSA_check_key_ex()
1719 See "Deprecated low-level validation functions"
1721 • RSA_clear_flags(), RSA_flags(), RSA_set_flags(), RSA_test_flags(),
1723 RSA_setup_blinding(), RSA_blinding_off(), RSA_blinding_on()
1724 All of these RSA flags have been deprecated without replacement:
1726 RSA_FLAG_BLINDING, RSA_FLAG_CACHE_PRIVATE, RSA_FLAG_CACHE_PUBLIC,
1728 RSA_FLAG_EXT_PKEY, RSA_FLAG_NO_BLINDING, RSA_FLAG_THREAD_SAFE
1729 RSA_METHOD_FLAG_NO_CHECK
1730 • RSA_generate_key_ex(), RSA_generate_multi_prime_key()
1732 See "Deprecated low-level key generation functions".
1734 • RSA_get0_engine()
1736 See "Providers are a replacement for engines and low-level method
1738 overrides"
1739 • RSA_get0_crt_params(), RSA_get0_d(), RSA_get0_dmp1(),
1741 RSA_get0_dmq1(), RSA_get0_e(), RSA_get0_factors(), RSA_get0_iqmp(),
1742 RSA_get0_key(), RSA_get0_multi_prime_crt_params(),
1743 RSA_get0_multi_prime_factors(), RSA_get0_n(), RSA_get0_p(),
1744 RSA_get0_pss_params(), RSA_get0_q(),
1745 RSA_get_multi_prime_extra_count()
1746 See "Deprecated low-level key parameter getters"
1748 • RSA_new(), RSA_free(), RSA_up_ref()
1750 See "Deprecated low-level object creation".
1752 • RSA_get_default_method(), RSA_get_ex_data and RSA_get_method()
1754 See "Providers are a replacement for engines and low-level method
1756 overrides".
1757 • RSA_get_version()
1759 There is no replacement.
1761 • RSA_meth_*(), RSA_new_method(), RSA_null_method and
1763 RSA_PKCS1_OpenSSL()
1764 See "Providers are a replacement for engines and low-level method
1766 overrides".
1767 • RSA_padding_add_*(), RSA_padding_check_*()
1769 See "Deprecated low-level signing functions" and "Deprecated low-
1771 level encryption functions".
1772 • RSA_print(), RSA_print_fp()
1774 See "Deprecated low-level key printing functions"
1776 • RSA_public_encrypt(), RSA_private_decrypt()
1778 See "Deprecated low-level encryption functions"
1780 • RSA_private_encrypt(), RSA_public_decrypt()
1782 This is equivalent to doing sign and verify recover operations
1784 (with a padding mode of none). See "Deprecated low-level signing
1785 functions".
1786 • RSAPrivateKey_dup(), RSAPublicKey_dup()
1788 There is no direct replacement. Applications may use
1790 EVP_PKEY_dup(3).
1791 • RSAPublicKey_it(), RSAPrivateKey_it()
1793 See "Deprecated low-level key reading and writing functions"
1795 • RSA_set0_crt_params(), RSA_set0_factors(), RSA_set0_key(),
1797 RSA_set0_multi_prime_params()
1798 See "Deprecated low-level key parameter setters".
1800 • RSA_set_default_method(), RSA_set_method(), RSA_set_ex_data()
1802 See "Providers are a replacement for engines and low-level method
1804 overrides"
1805 • RSA_sign(), RSA_sign_ASN1_OCTET_STRING(), RSA_verify(),
1807 RSA_verify_ASN1_OCTET_STRING(), RSA_verify_PKCS1_PSS(),
1808 RSA_verify_PKCS1_PSS_mgf1()
1809 See "Deprecated low-level signing functions".
1811 • RSA_X931_derive_ex(), RSA_X931_generate_key_ex(),
1813 RSA_X931_hash_id()
1814 There are no replacements for these functions. X931 padding can be
1816 set using "Signature Parameters" in EVP_SIGNATURE-RSA(7). See
1817 OSSL_SIGNATURE_PARAM_PAD_MODE.
1818 • SEED_encrypt(), SEED_decrypt(), SEED_set_key(), SEED_cbc_encrypt(),
1820 SEED_cfb128_encrypt(), SEED_ecb_encrypt(), SEED_ofb128_encrypt()
1821 See "Deprecated low-level encryption functions". The SEED
1823 algorithm has been moved to the Legacy Provider.
1824 • SHA1_Init(), SHA1_Update(), SHA1_Final(), SHA1_Transform(),
1826 SHA224_Init(), SHA224_Update(), SHA224_Final(), SHA256_Init(),
1827 SHA256_Update(), SHA256_Final(), SHA256_Transform(), SHA384_Init(),
1828 SHA384_Update(), SHA384_Final(), SHA512_Init(), SHA512_Update(),
1829 SHA512_Final(), SHA512_Transform()
1830 See "Deprecated low-level digest functions".
1832 • SRP_Calc_A(), SRP_Calc_B(), SRP_Calc_client_key(),
1834 SRP_Calc_server_key(), SRP_Calc_u(), SRP_Calc_x(),
1835 SRP_check_known_gN_param(), SRP_create_verifier(),
1836 SRP_create_verifier_BN(), SRP_get_default_gN(),
1837 SRP_user_pwd_free(), SRP_user_pwd_new(), SRP_user_pwd_set0_sv(),
1838 SRP_user_pwd_set1_ids(), SRP_user_pwd_set_gN(),
1839 SRP_VBASE_add0_user(), SRP_VBASE_free(), SRP_VBASE_get1_by_user(),
1840 SRP_VBASE_init(), SRP_VBASE_new(), SRP_Verify_A_mod_N(),
1841 SRP_Verify_B_mod_N()
1842 There are no replacements for the SRP functions.
1844 • SSL_CTX_set_tmp_dh_callback(), SSL_set_tmp_dh_callback(),
1846 SSL_CTX_set_tmp_dh(), SSL_set_tmp_dh()
1847 These are used to set the Diffie-Hellman (DH) parameters that are
1849 to be used by servers requiring ephemeral DH keys. Instead
1850 applications should consider using the built-in DH parameters that
1851 are available by calling SSL_CTX_set_dh_auto(3) or
1852 SSL_set_dh_auto(3). If custom parameters are necessary then
1853 applications can use the alternative functions
1854 SSL_CTX_set0_tmp_dh_pkey(3) and SSL_set0_tmp_dh_pkey(3). There is
1855 no direct replacement for the "callback" functions. The callback
1856 was originally useful in order to have different parameters for
1857 export and non-export ciphersuites. Export ciphersuites are no
1858 longer supported by OpenSSL. Use of the callback functions should
1859 be replaced by one of the other methods described above.
1860 • SSL_CTX_set_tlsext_ticket_key_cb()
1862 Use the new SSL_CTX_set_tlsext_ticket_key_evp_cb(3) function
1864 instead.
1865 • WHIRLPOOL(), WHIRLPOOL_Init(), WHIRLPOOL_Update(),
1867 WHIRLPOOL_Final(), WHIRLPOOL_BitUpdate()
1868 See "Deprecated low-level digest functions". The Whirlpool
1870 algorithm has been moved to the Legacy Provider.
1871 • X509_certificate_type()
1873 This was an undocumented function. Applications can use
1875 X509_get0_pubkey(3) and X509_get0_signature(3) instead.
1876 • X509_http_nbio(), X509_CRL_http_nbio()
1878 Use X509_load_http(3) and X509_CRL_load_http(3) instead.
1880 NID handling for provided keys and algorithms
1882 The following functions for NID (numeric id) handling have changed
1884 semantics.
1885 • EVP_PKEY_id(), EVP_PKEY_get_id()
1887 This function was previously used to reliably return the NID of an
1889 EVP_PKEY object, e.g., to look up the name of the algorithm of such
1890 EVP_PKEY by calling OBJ_nid2sn(3). With the introduction of
1891 provider(7)s EVP_PKEY_id() or its new equivalent EVP_PKEY_get_id(3)
1892 might now also return the value -1 (EVP_PKEY_KEYMGMT) indicating
1893 the use of a provider to implement the EVP_PKEY object. Therefore,
1894 the use of EVP_PKEY_get0_type_name(3) is recommended for retrieving
1895 the name of the EVP_PKEY algorithm.
1896 Using the FIPS Module in applications
1898 See fips_module(7) and OSSL_PROVIDER-FIPS(7) for details.
1899 OpenSSL command line application changes
1901 New applications
1902 openssl kdf uses the new EVP_KDF(3) API. openssl kdf uses the new
1904 EVP_MAC(3) API.
1905 Added options
1907 -provider_path and -provider are available to all apps and can be used
1909 multiple times to load any providers, such as the 'legacy' provider or
1910 third party providers. If used then the 'default' provider would also
1911 need to be specified if required. The -provider_path must be specified
1912 before the -provider option.
1913 The list app has many new options. See openssl-list(1) for more
1915 information.
1916 -crl_lastupdate and -crl_nextupdate used by openssl ca allows explicit
1918 setting of fields in the generated CRL.
1919 Removed options
1921 Interactive mode is not longer available.
1923 The -crypt option used by openssl passwd. The -c option used by
1925 openssl x509, openssl dhparam, openssl dsaparam, and openssl ecparam.
1926 Other Changes
1928 The output of Command line applications may have minor changes. These
1930 are primarily changes in capitalisation and white space. However, in
1931 some cases, there are additional differences. For example, the DH
1932 parameters output from openssl dhparam now lists 'P', 'Q', 'G' and
1933 'pcounter' instead of 'prime', 'generator', 'subgroup order' and
1934 'counter' respectively.
1935 The openssl commands that read keys, certificates, and CRLs now
1937 automatically detect the PEM or DER format of the input files so it is
1938 not necessary to explicitly specify the input format anymore. However
1939 if the input format option is used the specified format will be
1940 required.
1941 openssl speed no longer uses low-level API calls. This implies some of
1943 the performance numbers might not be comparable with the previous
1944 releases due to higher overhead. This applies particularly to measuring
1945 performance on smaller data chunks.
1946 b<openssl dhparam>, openssl dsa, openssl gendsa, openssl dsaparam,
1948 openssl genrsa and openssl rsa have been modified to use PKEY APIs.
1949 openssl genrsa and openssl rsa now write PKCS #8 keys by default.
1950 Default settings
1952 "SHA256" is now the default digest for TS query used by openssl ts.
1954 Deprecated apps
1956 openssl rsautl is deprecated, use openssl pkeyutl instead. openssl
1958 dhparam, openssl dsa, openssl gendsa, openssl dsaparam, openssl genrsa,
1959 openssl rsa, openssl genrsa and openssl rsa are now in maintenance mode
1960 and no new features will be added to them.
1961 TLS Changes
1963 • TLS 1.3 FFDHE key exchange support added
1964 This uses DH safe prime named groups.
1966 • Support for fully "pluggable" TLSv1.3 groups.
1968 This means that providers may supply their own group
1970 implementations (using either the "key exchange" or the "key
1971 encapsulation" methods) which will automatically be detected and
1972 used by libssl.
1973 • SSL and SSL_CTX options are now 64 bit instead of 32 bit.
1975 The signatures of the functions to get and set options on SSL and
1977 SSL_CTX objects changed from "unsigned long" to "uint64_t" type.
1978 This may require source code changes. For example it is no longer
1980 possible to use the SSL_OP_ macro values in preprocessor "#if"
1981 conditions. However it is still possible to test whether these
1982 macros are defined or not.
1983 See SSL_CTX_get_options(3), SSL_CTX_set_options(3),
1985 SSL_get_options(3) and SSL_set_options(3).
1986 • SSL_set1_host() and SSL_add1_host() Changes
1988 These functions now take IP literal addresses as well as actual
1990 hostnames.
1991 • Added SSL option SSL_OP_CLEANSE_PLAINTEXT
1993 If the option is set, openssl cleanses (zeroizes) plaintext bytes
1995 from internal buffers after delivering them to the application.
1996 Note, the application is still responsible for cleansing other
1997 copies (e.g.: data received by SSL_read(3)).
1998 • Client-initiated renegotiation is disabled by default.
2000 To allow it, use the -client_renegotiation option, the
2002 SSL_OP_ALLOW_CLIENT_RENEGOTIATION flag, or the
2003 "ClientRenegotiation" config parameter as appropriate.
2004 • Secure renegotiation is now required by default for TLS connections
2006 Support for RFC 5746 secure renegotiation is now required by
2008 default for SSL or TLS connections to succeed. Applications that
2009 require the ability to connect to legacy peers will need to
2010 explicitly set SSL_OP_LEGACY_SERVER_CONNECT. Accordingly,
2011 SSL_OP_LEGACY_SERVER_CONNECT is no longer set as part of
2012 SSL_OP_ALL.
2013 • Combining the Configure options no-ec and no-dh no longer disables
2015 TLSv1.3
2016 Typically if OpenSSL has no EC or DH algorithms then it cannot
2018 support connections with TLSv1.3. However OpenSSL now supports
2019 "pluggable" groups through providers. Therefore third party
2020 providers may supply group implementations even where there are no
2021 built-in ones. Attempting to create TLS connections in such a build
2022 without also disabling TLSv1.3 at run time or using third party
2023 provider groups may result in handshake failures. TLSv1.3 can be
2024 disabled at compile time using the "no-tls1_3" Configure option.
2025 • SSL_CTX_set_ciphersuites() and SSL_set_ciphersuites() changes.
2027 The methods now ignore unknown ciphers.
2029 • Security callback change.
2031 The security callback, which can be customised by application code,
2033 supports the security operation SSL_SECOP_TMP_DH. This is defined
2034 to take an EVP_PKEY in the "other" parameter. In most places this
2035 is what is passed. All these places occur server side. However
2036 there was one client side call of this security operation and it
2037 passed a DH object instead. This is incorrect according to the
2038 definition of SSL_SECOP_TMP_DH, and is inconsistent with all of the
2039 other locations. Therefore this client side call has been changed
2040 to pass an EVP_PKEY instead.
2041 • New SSL option SSL_OP_IGNORE_UNEXPECTED_EOF
2043 The SSL option SSL_OP_IGNORE_UNEXPECTED_EOF is introduced. If that
2045 option is set, an unexpected EOF is ignored, it pretends a close
2046 notify was received instead and so the returned error becomes
2047 SSL_ERROR_ZERO_RETURN.
2048 • The security strength of SHA1 and MD5 based signatures in TLS has
2050 been reduced.
2051 This results in SSL 3, TLS 1.0, TLS 1.1 and DTLS 1.0 no longer
2053 working at the default security level of 1 and instead requires
2054 security level 0. The security level can be changed either using
2055 the cipher string with @SECLEVEL, or calling
2056 SSL_CTX_set_security_level(3). This also means that where the
2057 signature algorithms extension is missing from a ClientHello then
2058 the handshake will fail in TLS 1.2 at security level 1. This is
2059 because, although this extension is optional, failing to provide
2060 one means that OpenSSL will fallback to a default set of signature
2061 algorithms. This default set requires the availability of SHA1.
2062 • X509 certificates signed using SHA1 are no longer allowed at
2064 security level 1 and above.
2065 In TLS/SSL the default security level is 1. It can be set either
2067 using the cipher string with @SECLEVEL, or calling
2068 SSL_CTX_set_security_level(3). If the leaf certificate is signed
2069 with SHA-1, a call to SSL_CTX_use_certificate(3) will fail if the
2070 security level is not lowered first. Outside TLS/SSL, the default
2071 security level is -1 (effectively 0). It can be set using
2072 X509_VERIFY_PARAM_set_auth_level(3) or using the -auth_level
2073 options of the commands.
2074
2076 fips_module(7)
2077
2079 The migration guide was created for OpenSSL 3.0.
2080
2082 Copyright 2021-2023 The OpenSSL Project Authors. All Rights Reserved.
2083 Licensed under the Apache License 2.0 (the "License"). You may not use
2085 this file except in compliance with the License. You can obtain a copy
2086 in the file LICENSE in the source distribution or at
2087 <https://www.openssl.org/source/license.html>.
20883.1.1 2023-08-31 MIGRATION_GUIDE(7ossl)