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. For earlier versions refer
14 to <https://github.com/openssl/openssl/blob/master/CHANGES.md>. For an
15 overview of some of the key concepts introduced in OpenSSL 3.0 see
16 crypto(7).
17
19 Main Changes from OpenSSL 1.1.1
20 Major Release
21 OpenSSL 3.0 is a major release and consequently any application that
23 currently uses an older version of OpenSSL will at the very least need
24 to be recompiled in order to work with the new version. It is the
25 intention that the large majority of applications will work unchanged
26 with OpenSSL 3.0 if those applications previously worked with OpenSSL
27 1.1.1. However this is not guaranteed and some changes may be required
28 in some cases. Changes may also be required if applications need to
29 take advantage of some of the new features available in OpenSSL 3.0
30 such as the availability of the FIPS module.
31 License Change
33 In previous versions, OpenSSL was licensed under the dual OpenSSL and
35 SSLeay licenses <https://www.openssl.org/source/license-openssl-
36 ssleay.txt> (both licenses apply). From OpenSSL 3.0 this is replaced by
37 the Apache License v2 <https://www.openssl.org/source/apache-
38 license-2.0.txt>.
39 Providers and FIPS support
41 One of the key changes from OpenSSL 1.1.1 is the introduction of the
43 Provider concept. Providers collect together and make available
44 algorithm implementations. With OpenSSL 3.0 it is possible to specify,
45 either programmatically or via a config file, which providers you want
46 to use for any given application. OpenSSL 3.0 comes with 5 different
47 providers as standard. Over time third parties may distribute
48 additional providers that can be plugged into OpenSSL. All algorithm
49 implementations available via providers are accessed through the "high
50 level" APIs (for example those functions prefixed with "EVP"). They
51 cannot be accessed using the "Low Level APIs".
52 One of the standard providers available is the FIPS provider. This
54 makes available FIPS validated cryptographic algorithms. The FIPS
55 provider is disabled by default and needs to be enabled explicitly at
56 configuration time using the "enable-fips" option. If it is enabled,
57 the FIPS provider gets built and installed in addition to the other
58 standard providers. No separate installation procedure is necessary.
59 There is however a dedicated "install_fips" make target, which serves
60 the special purpose of installing only the FIPS provider into an
61 existing OpenSSL installation.
62 Not all algorithms may be available for the application at a particular
64 moment. If the application code uses any digest or cipher algorithm
65 via the EVP interface, the application should verify the result of the
66 EVP_EncryptInit(3), EVP_EncryptInit_ex(3), and EVP_DigestInit(3)
67 functions. In case when the requested algorithm is not available, these
68 functions will fail.
69 See also "Legacy Algorithms" for information on the legacy provider.
71 See also "Completing the installation of the FIPS Module" and "Using
73 the FIPS Module in applications".
74 Low Level APIs
76 OpenSSL has historically provided two sets of APIs for invoking
78 cryptographic algorithms: the "high level" APIs (such as the "EVP"
79 APIs) and the "low level" APIs. The high level APIs are typically
80 designed to work across all algorithm types. The "low level" APIs are
81 targeted at a specific algorithm implementation. For example, the EVP
82 APIs provide the functions EVP_EncryptInit_ex(3), EVP_EncryptUpdate(3)
83 and EVP_EncryptFinal(3) to perform symmetric encryption. Those
84 functions can be used with the algorithms AES, CHACHA, 3DES etc. On
85 the other hand, to do AES encryption using the low level APIs you would
86 have to call AES specific functions such as AES_set_encrypt_key(3),
87 AES_encrypt(3), and so on. The functions for 3DES are different. Use
88 of the low level APIs has been informally discouraged by the OpenSSL
89 development team for a long time. However in OpenSSL 3.0 this is made
90 more formal. All such low level APIs have been deprecated. You may
91 still use them in your applications, but you may start to see
92 deprecation warnings during compilation (dependent on compiler support
93 for this). Deprecated APIs may be removed from future versions of
94 OpenSSL so you are strongly encouraged to update your code to use the
95 high level APIs instead.
96 This is described in more detail in "Deprecation of Low Level
98 Functions"
99 Legacy Algorithms
101 Some cryptographic algorithms such as MD2 and DES that were available
103 via the EVP APIs are now considered legacy and their use is strongly
104 discouraged. These legacy EVP algorithms are still available in
105 OpenSSL 3.0 but not by default. If you want to use them then you must
106 load the legacy provider. This can be as simple as a config file
107 change, or can be done programmatically. See OSSL_PROVIDER-legacy(7)
108 for a complete list of algorithms. Applications using the EVP APIs to
109 access these algorithms should instead use more modern algorithms. If
110 that is not possible then these applications should ensure that the
111 legacy provider has been loaded. This can be achieved either
112 programmatically or via configuration. See crypto(7) man page for more
113 information about providers.
114 Engines and "METHOD" APIs
116 The refactoring to support Providers conflicts internally with the APIs
118 used to support engines, including the ENGINE API and any function that
119 creates or modifies custom "METHODS" (for example EVP_MD_meth_new(3),
120 EVP_CIPHER_meth_new(3), EVP_PKEY_meth_new(3), RSA_meth_new(3),
121 EC_KEY_METHOD_new(3), etc.). These functions are being deprecated in
122 OpenSSL 3.0, and users of these APIs should know that their use can
123 likely bypass provider selection and configuration, with unintended
124 consequences. This is particularly relevant for applications written
125 to use the OpenSSL 3.0 FIPS module, as detailed below. Authors and
126 maintainers of external engines are strongly encouraged to refactor
127 their code transforming engines into providers using the new Provider
128 API and avoiding deprecated methods.
129 Support of legacy engines
131 If openssl is not built without engine support or deprecated API
133 support, engines will still work. However, their applicability will be
134 limited.
135 New algorithms provided via engines will still work.
137 Engine-backed keys can be loaded via custom OSSL_STORE implementation.
139 In this case the EVP_PKEY objects created via
140 ENGINE_load_private_key(3) will be concidered legacy and will continue
141 to work.
142 To ensure the future compatibility, the engines should be turned to
144 providers. To prefer the provider-based hardware offload, you can
145 specify the default properties to prefer your provider.
146 Versioning Scheme
148 The OpenSSL versioning scheme has changed with the OpenSSL 3.0 release.
150 The new versioning scheme has this format:
151 MAJOR.MINOR.PATCH
153 For OpenSSL 1.1.1 and below, different patch levels were indicated by a
155 letter at the end of the release version number. This will no longer be
156 used and instead the patch level is indicated by the final number in
157 the version. A change in the second (MINOR) number indicates that new
158 features may have been added. OpenSSL versions with the same major
159 number are API and ABI compatible. If the major number changes then
160 API and ABI compatibility is not guaranteed.
161 For more information, see OpenSSL_version(3).
163 Other major new features
165 Certificate Management Protocol (CMP, RFC 4210)
167 This also covers CRMF (RFC 4211) and HTTP transfer (RFC 6712) See
169 openssl-cmp(1) and OSSL_CMP_exec_certreq(3) as starting points.
170 HTTP(S) client
172 A proper HTTP(S) client that supports GET and POST, redirection, plain
174 and ASN.1-encoded contents, proxies, and timeouts.
175 Key Derivation Function API (EVP_KDF)
177 This simplifies the process of adding new KDF and PRF implementations.
179 Previously KDF algorithms had been shoe-horned into using the EVP_PKEY
181 object which was not a logical mapping. Existing applications that use
182 KDF algorithms using EVP_PKEY (scrypt, TLS1 PRF and HKDF) may be slower
183 as they use an EVP_KDF bridge internally. All new applications should
184 use the new EVP_KDF(3) interface. See also "Key Derivation Function
185 (KDF)" in OSSL_PROVIDER-default(7) and "Key Derivation Function (KDF)"
186 in OSSL_PROVIDER-FIPS(7).
187 Message Authentication Code API (EVP_MAC)
189 This simplifies the process of adding MAC implementations.
191 This includes a generic EVP_PKEY to EVP_MAC bridge, to facilitate the
193 continued use of MACs through raw private keys in functionality such as
194 EVP_DigestSign(3) and EVP_DigestVerify(3).
195 All new applications should use the new EVP_MAC(3) interface. See also
197 "Message Authentication Code (MAC)" in OSSL_PROVIDER-default(7) and
198 "Message Authentication Code (MAC)" in OSSL_PROVIDER-FIPS(7).
199 Support for Linux Kernel TLS
201 In order to use KTLS, support for it must be compiled in using the
203 "enable-ktls" configuration option. It must also be enabled at run time
204 using the SSL_OP_ENABLE_KTLS option.
205 New Algorithms
207 • KDF algorithms "SINGLE STEP" and "SSH"
209 See EVP_KDF-SS(7) and EVP_KDF-SSHKDF(7)
211 • MAC Algorithms "GMAC" and "KMAC"
213 See EVP_MAC-GMAC(7) and EVP_MAC-KMAC(7).
215 • KEM Algorithm "RSASVE"
217 See EVP_KEM-RSA(7).
219 • Cipher Algorithm "AES-SIV"
221 See "SIV Mode" in EVP_EncryptInit(3).
223 • AES Key Wrap inverse ciphers supported by EVP layer.
225 The inverse ciphers use AES decryption for wrapping, and AES
227 encryption for unwrapping. The algorithms are: "AES-128-WRAP-INV",
228 "AES-192-WRAP-INV", "AES-256-WRAP-INV", "AES-128-WRAP-PAD-INV",
229 "AES-192-WRAP-PAD-INV" and "AES-256-WRAP-PAD-INV".
230 • CTS ciphers added to EVP layer.
232 The algorithms are "AES-128-CBC-CTS", "AES-192-CBC-CTS",
234 "AES-256-CBC-CTS", "CAMELLIA-128-CBC-CTS", "CAMELLIA-192-CBC-CTS"
235 and "CAMELLIA-256-CBC-CTS". CS1, CS2 and CS3 variants are
236 supported.
237 CMS and PKCS#7 updates
239 • Added CAdES-BES signature verification support.
241 • Added CAdES-BES signature scheme and attributes support (RFC 5126)
243 to CMS API.
244 • Added AuthEnvelopedData content type structure (RFC 5083) using
246 AES_GCM
247 This uses the AES-GCM parameter (RFC 5084) for the Cryptographic
249 Message Syntax. Its purpose is to support encryption and
250 decryption of a digital envelope that is both authenticated and
251 encrypted using AES GCM mode.
252 • PKCS7_get_octet_string(3) and PKCS7_type_is_other(3) were made
254 public.
255 PKCS#12 API updates
257 The default algorithms for pkcs12 creation with the PKCS12_create()
259 function were changed to more modern PBKDF2 and AES based algorithms.
260 The default MAC iteration count was changed to PKCS12_DEFAULT_ITER to
261 make it equal with the password-based encryption iteration count. The
262 default digest algorithm for the MAC computation was changed to
263 SHA-256. The pkcs12 application now supports -legacy option that
264 restores the previous default algorithms to support interoperability
265 with legacy systems.
266 Added enhanced PKCS#12 APIs which accept a library context OSSL_LIB_CTX
268 and (where relevant) a property query. Other APIs which handle PKCS#7
269 and PKCS#8 objects have also been enhanced where required. This
270 includes:
271 PKCS12_add_key_ex(3), PKCS12_add_safe_ex(3), PKCS12_add_safes_ex(3),
273 PKCS12_create_ex(3), PKCS12_decrypt_skey_ex(3), PKCS12_init_ex(3),
274 PKCS12_item_decrypt_d2i_ex(3), PKCS12_item_i2d_encrypt_ex(3),
275 PKCS12_key_gen_asc_ex(3), PKCS12_key_gen_uni_ex(3),
276 PKCS12_key_gen_utf8_ex(3), PKCS12_pack_p7encdata_ex(3),
277 PKCS12_pbe_crypt_ex(3), PKCS12_PBE_keyivgen_ex(3),
278 PKCS12_SAFEBAG_create_pkcs8_encrypt_ex(3), PKCS5_pbe2_set_iv_ex(3),
279 PKCS5_pbe_set0_algor_ex(3), PKCS5_pbe_set_ex(3),
280 PKCS5_pbkdf2_set_ex(3), PKCS5_v2_PBE_keyivgen_ex(3),
281 PKCS5_v2_scrypt_keyivgen_ex(3), PKCS8_decrypt_ex(3),
282 PKCS8_encrypt_ex(3), PKCS8_set0_pbe_ex(3).
283 As part of this change the EVP_PBE_xxx APIs can also accept a library
285 context and property query and will call an extended version of the
286 key/IV derivation function which supports these parameters. This
287 includes EVP_PBE_CipherInit_ex(3), EVP_PBE_find_ex(3) and
288 EVP_PBE_scrypt_ex(3).
289 Windows thread synchronization changes
291 Windows thread synchronization uses read/write primitives (SRWLock)
293 when supported by the OS, otherwise CriticalSection continues to be
294 used.
295 Trace API
297 A new generic trace API has been added which provides support for
299 enabling instrumentation through trace output. This feature is mainly
300 intended as an aid for developers and is disabled by default. To
301 utilize it, OpenSSL needs to be configured with the "enable-trace"
302 option.
303 If the tracing API is enabled, the application can activate trace
305 output by registering BIOs as trace channels for a number of tracing
306 and debugging categories. See OSSL_trace_enabled(3).
307 Key validation updates
309 EVP_PKEY_public_check(3) and EVP_PKEY_param_check(3) now work for more
311 key types. This includes RSA, DSA, ED25519, X25519, ED448 and X448.
312 Previously (in 1.1.1) they would return -2. For key types that do not
313 have parameters then EVP_PKEY_param_check(3) will always return 1.
314 Other notable deprecations and changes
316 The function code part of an OpenSSL error code is no longer relevant
318 This code is now always set to zero. Related functions are deprecated.
320 STACK and HASH macros have been cleaned up
322 The type-safe wrappers are declared everywhere and implemented once.
324 See DEFINE_STACK_OF(3) and DECLARE_LHASH_OF(3).
325 The RAND_DRBG subsystem has been removed
327 The new EVP_RAND(3) is a partial replacement: the DRBG callback
329 framework is absent. The RAND_DRBG API did not fit well into the new
330 provider concept as implemented by EVP_RAND and EVP_RAND_CTX.
331 Removed FIPS_mode() and FIPS_mode_set()
333 These functions are legacy APIs that are not applicable to the new
335 provider model. Applications should instead use
336 EVP_default_properties_is_fips_enabled(3) and
337 EVP_default_properties_enable_fips(3).
338 Key generation is slower
340 The Miller-Rabin test now uses 64 rounds, which is used for all prime
342 generation, including RSA key generation. This affects the time for
343 larger keys sizes.
344 The default key generation method for the regular 2-prime RSA keys was
346 changed to the FIPS186-4 B.3.6 method (Generation of Probable Primes
347 with Conditions Based on Auxiliary Probable Primes). This method is
348 slower than the original method.
349 Change PBKDF2 to conform to SP800-132 instead of the older PKCS5
351 RFC2898
352 This checks that the salt length is at least 128 bits, the derived key
354 length is at least 112 bits, and that the iteration count is at least
355 1000. For backwards compatibility these checks are disabled by default
356 in the default provider, but are enabled by default in the FIPS
357 provider.
358 To enable or disable the checks see OSSL_KDF_PARAM_PKCS5 in
360 EVP_KDF-PBKDF2(7). The parameter can be set using EVP_KDF_derive(3).
361 Enforce a minimum DH modulus size of 512 bits
363 Smaller sizes now result in an error.
365 SM2 key changes
367 EC EVP_PKEYs with the SM2 curve have been reworked to automatically
369 become EVP_PKEY_SM2 rather than EVP_PKEY_EC.
370 Unlike in previous OpenSSL versions, this means that applications
372 cannot call "EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2)" to get SM2
373 computations.
374 Parameter and key generation is also reworked to make it possible to
376 generate EVP_PKEY_SM2 parameters and keys. Applications must now
377 generate SM2 keys directly and must not create an EVP_PKEY_EC key
378 first. It is no longer possible to import an SM2 key with domain
379 parameters other than the SM2 elliptic curve ones.
380 Validation of SM2 keys has been separated from the validation of
382 regular EC keys, allowing to improve the SM2 validation process to
383 reject loaded private keys that are not conforming to the SM2 ISO
384 standard. In particular, a private scalar k outside the range 1 <= k <
385 n-1 is now correctly rejected.
386 EVP_PKEY_set_alias_type() method has been removed
388 This function made a EVP_PKEY object mutable after it had been set up.
390 In OpenSSL 3.0 it was decided that a provided key should not be able to
391 change its type, so this function has been removed.
392 Functions that return an internal key should be treated as read only
394 Functions such as EVP_PKEY_get0_RSA(3) behave slightly differently in
396 OpenSSL 3.0. Previously they returned a pointer to the low-level key
397 used internally by libcrypto. From OpenSSL 3.0 this key may now be held
398 in a provider. Calling these functions will only return a handle on the
399 internal key where the EVP_PKEY was constructed using this key in the
400 first place, for example using a function or macro such as
401 EVP_PKEY_assign_RSA(3), EVP_PKEY_set1_RSA(3), etc. Where the EVP_PKEY
402 holds a provider managed key, then these functions now return a cached
403 copy of the key. Changes to the internal provider key that take place
404 after the first time the cached key is accessed will not be reflected
405 back in the cached copy. Similarly any changes made to the cached copy
406 by application code will not be reflected back in the internal provider
407 key.
408 For the above reasons the keys returned from these functions should
410 typically be treated as read-only. To emphasise this the value returned
411 from EVP_PKEY_get0_RSA(3), EVP_PKEY_get0_DSA(3),
412 EVP_PKEY_get0_EC_KEY(3) and EVP_PKEY_get0_DH(3) have been made const.
413 This may break some existing code. Applications broken by this change
414 should be modified. The preferred solution is to refactor the code to
415 avoid the use of these deprecated functions. Failing this the code
416 should be modified to use a const pointer instead. The
417 EVP_PKEY_get1_RSA(3), EVP_PKEY_get1_DSA(3), EVP_PKEY_get1_EC_KEY(3) and
418 EVP_PKEY_get1_DH(3) functions continue to return a non-const pointer to
419 enable them to be "freed". However they should also be treated as read-
420 only.
421 The public key check has moved from EVP_PKEY_derive() to
423 EVP_PKEY_derive_set_peer()
424 This may mean result in an error in EVP_PKEY_derive_set_peer(3) rather
426 than during EVP_PKEY_derive(3). To disable this check use
427 EVP_PKEY_derive_set_peer_ex(dh, peer, 0).
428 The print format has cosmetic changes for some functions
430 The output from numerous "printing" functions such as
432 X509_signature_print(3), X509_print_ex(3), X509_CRL_print_ex(3), and
433 other similar functions has been amended such that there may be
434 cosmetic differences between the output observed in 1.1.1 and 3.0. This
435 also applies to the -text output from the openssl x509 and openssl crl
436 applications.
437 Interactive mode from the openssl program has been removed
439 From now on, running it without arguments is equivalent to openssl
441 help.
442 The error return values from some control calls (ctrl) have changed
444 One significant change is that controls which used to return -2 for
446 invalid inputs, now return -1 indicating a generic error condition
447 instead.
448 DH and DHX key types have different settable parameters
450 Previously (in 1.1.1) these conflicting parameters were allowed, but
452 will now result in errors. See EVP_PKEY-DH(7) for further details. This
453 affects the behaviour of openssl-genpkey(1) for DH parameter
454 generation.
455 EVP_CIPHER_CTX_set_flags() ordering change
457 If using a cipher from a provider the EVP_CIPH_FLAG_LENGTH_BITS flag
459 can only be set after the cipher has been assigned to the cipher
460 context. See "FLAGS" in EVP_EncryptInit(3) for more information.
461 Validation of operation context parameters
463 Due to move of the implementation of cryptographic operations to the
465 providers, validation of various operation parameters can be postponed
466 until the actual operation is executed where previously it happened
467 immediately when an operation parameter was set.
468 For example when setting an unsupported curve with
470 EVP_PKEY_CTX_set_ec_paramgen_curve_nid() this function call will not
471 fail but later keygen operations with the EVP_PKEY_CTX will fail.
472 Removal of function code from the error codes
474 The function code part of the error code is now always set to 0. For
476 that reason the ERR_GET_FUNC() macro was removed. Applications must
477 resolve the error codes only using the library number and the reason
478 code.
479 Installation and Compilation
481 Please refer to the INSTALL.md file in the top of the distribution for
482 instructions on how to build and install OpenSSL 3.0. Please also refer
483 to the various platform specific NOTES files for your specific
484 platform.
485 Upgrading from OpenSSL 1.1.1
487 Upgrading to OpenSSL 3.0 from OpenSSL 1.1.1 should be relatively
488 straight forward in most cases. The most likely area where you will
489 encounter problems is if you have used low level APIs in your code (as
490 discussed above). In that case you are likely to start seeing
491 deprecation warnings when compiling your application. If this happens
492 you have 3 options:
493 1. Ignore the warnings. They are just warnings. The deprecated
495 functions are still present and you may still use them. However be
496 aware that they may be removed from a future version of OpenSSL.
497 2. Suppress the warnings. Refer to your compiler documentation on how
499 to do this.
500 3. Remove your usage of the low level APIs. In this case you will need
502 to rewrite your code to use the high level APIs instead
503 Error code changes
505 As OpenSSL 3.0 provides a brand new Encoder/Decoder mechanism for
507 working with widely used file formats, application code that checks for
508 particular error reason codes on key loading failures might need an
509 update.
510 Password-protected keys may deserve special attention. If only some
512 errors are treated as an indicator that the user should be asked about
513 the password again, it's worth testing these scenarios and processing
514 the newly relevant codes.
515 There may be more cases to treat specially, depending on the calling
517 application code.
518 Upgrading from OpenSSL 1.0.2
520 Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 is likely to be
521 significantly more difficult. In addition to the issues discussed above
522 in the section about "Upgrading from OpenSSL 1.1.1", the main things to
523 be aware of are:
524 1. The build and installation procedure has changed significantly.
526 Check the file INSTALL.md in the top of the installation for
528 instructions on how to build and install OpenSSL for your platform.
529 Also read the various NOTES files in the same directory, as
530 applicable for your platform.
531 2. Many structures have been made opaque in OpenSSL 3.0.
533 The structure definitions have been removed from the public header
535 files and moved to internal header files. In practice this means
536 that you can no longer stack allocate some structures. Instead they
537 must be heap allocated through some function call (typically those
538 function names have a "_new" suffix to them). Additionally you
539 must use "setter" or "getter" functions to access the fields within
540 those structures.
541 For example code that previously looked like this:
543 EVP_MD_CTX md_ctx;
545 /* This line will now generate compiler errors */
547 EVP_MD_CTX_init(&md_ctx);
548 The code needs to be amended to look like this:
550 EVP_MD_CTX *md_ctx;
552 md_ctx = EVP_MD_CTX_new();
554 ...
555 ...
556 EVP_MD_CTX_free(md_ctx);
557 3. Support for TLSv1.3 has been added.
559 This has a number of implications for SSL/TLS applications. See the
561 TLS1.3 page <https://wiki.openssl.org/index.php/TLS1.3> for further
562 details.
563 More details about the breaking changes between OpenSSL versions 1.0.2
565 and 1.1.0 can be found on the OpenSSL 1.1.0 Changes page
566 <https://wiki.openssl.org/index.php/OpenSSL_1.1.0_Changes>.
567 Upgrading from the OpenSSL 2.0 FIPS Object Module
569 The OpenSSL 2.0 FIPS Object Module was a separate download that had to
571 be built separately and then integrated into your main OpenSSL 1.0.2
572 build. In OpenSSL 3.0 the FIPS support is fully integrated into the
573 mainline version of OpenSSL and is no longer a separate download. For
574 further information see "Completing the installation of the FIPS
575 Module".
576 The function calls FIPS_mode() and FIPS_mode_set() have been removed
578 from OpenSSL 3.0. You should rewrite your application to not use them.
579 See fips_module(7) and OSSL_PROVIDER-FIPS(7) for details.
580 Completing the installation of the FIPS Module
582 The FIPS Module will be built and installed automatically if FIPS
583 support has been configured. The current documentation can be found in
584 the README-FIPS <https://github.com/openssl/openssl/blob/master/README-
585 FIPS.md> file.
586 Programming
588 Applications written to work with OpenSSL 1.1.1 will mostly just work
589 with OpenSSL 3.0. However changes will be required if you want to take
590 advantage of some of the new features that OpenSSL 3.0 makes available.
591 In order to do that you need to understand some new concepts introduced
592 in OpenSSL 3.0. Read "Library contexts" in crypto(7) for further
593 information.
594 Library Context
596 A library context allows different components of a complex application
598 to each use a different library context and have different providers
599 loaded with different configuration settings. See "Library contexts"
600 in crypto(7) for further info.
601 If the user creates an OSSL_LIB_CTX via OSSL_LIB_CTX_new(3) then many
603 functions may need to be changed to pass additional parameters to
604 handle the library context.
605 Using a Library Context - Old functions that should be changed
607 If a library context is needed then all EVP_* digest functions that
609 return a const EVP_MD * such as EVP_sha256() should be replaced with a
610 call to EVP_MD_fetch(3). See "ALGORITHM FETCHING" in crypto(7).
611 If a library context is needed then all EVP_* cipher functions that
613 return a const EVP_CIPHER * such as EVP_aes_128_cbc() should be
614 replaced vith a call to EVP_CIPHER_fetch(3). See "ALGORITHM FETCHING"
615 in crypto(7).
616 Some functions can be passed an object that has already been set up
618 with a library context such as d2i_X509(3), d2i_X509_CRL(3),
619 d2i_X509_REQ(3) and d2i_X509_PUBKEY(3). If NULL is passed instead then
620 the created object will be set up with the default library context. Use
621 X509_new_ex(3), X509_CRL_new_ex(3), X509_REQ_new_ex(3) and
622 X509_PUBKEY_new_ex(3) if a library context is required.
623 All functions listed below with a NAME have a replacment function
625 NAME_ex that takes OSSL_LIB_CTX as an additional argument. Functions
626 that have other mappings are listed along with the respective name.
627 • ASN1_item_new(3), ASN1_item_d2i(3), ASN1_item_d2i_fp(3),
629 ASN1_item_d2i_bio(3), ASN1_item_sign(3) and ASN1_item_verify(3)
630 • BIO_new(3)
632 • b2i_RSA_PVK_bio() and i2b_PVK_bio()
634 • BN_CTX_new(3) and BN_CTX_secure_new(3)
636 • CMS_AuthEnvelopedData_create(3), CMS_ContentInfo_new(3),
638 CMS_data_create(3), CMS_digest_create(3),
639 CMS_EncryptedData_encrypt(3), CMS_encrypt(3),
640 CMS_EnvelopedData_create(3), CMS_ReceiptRequest_create0(3) and
641 CMS_sign(3)
642 • CONF_modules_load_file(3)
644 • CTLOG_new(3), CTLOG_new_from_base64(3) and CTLOG_STORE_new(3)
646 • CT_POLICY_EVAL_CTX_new(3)
648 • d2i_AutoPrivateKey(3), d2i_PrivateKey(3) and d2i_PUBKEY(3)
650 • d2i_PrivateKey_bio(3) and d2i_PrivateKey_fp(3)
652 Use d2i_PrivateKey_ex_bio(3) and d2i_PrivateKey_ex_fp(3)
654 • EC_GROUP_new(3)
656 Use EC_GROUP_new_by_curve_name_ex(3) or
658 EC_GROUP_new_from_params(3).
659 • EVP_DigestSignInit(3) and EVP_DigestVerifyInit(3)
661 • EVP_PBE_CipherInit(3), EVP_PBE_find(3) and EVP_PBE_scrypt(3)
663 • PKCS5_PBE_keyivgen(3)
665 • EVP_PKCS82PKEY(3)
667 • EVP_PKEY_CTX_new_id(3)
669 Use EVP_PKEY_CTX_new_from_name(3)
671 • EVP_PKEY_derive_set_peer(3), EVP_PKEY_new_raw_private_key(3) and
673 EVP_PKEY_new_raw_public_key(3)
674 • EVP_SignFinal(3) and EVP_VerifyFinal(3)
676 • NCONF_new(3)
678 • OCSP_RESPID_match(3) and OCSP_RESPID_set_by_key(3)
680 • OPENSSL_thread_stop(3)
682 • OSSL_STORE_open(3)
684 • PEM_read_bio_Parameters(3), PEM_read_bio_PrivateKey(3),
686 PEM_read_bio_PUBKEY(3), PEM_read_PrivateKey(3) and
687 PEM_read_PUBKEY(3)
688 • PEM_write_bio_PrivateKey(3), PEM_write_bio_PUBKEY(3),
690 PEM_write_PrivateKey(3) and PEM_write_PUBKEY(3)
691 • PEM_X509_INFO_read_bio(3) and PEM_X509_INFO_read(3)
693 • PKCS12_add_key(3), PKCS12_add_safe(3), PKCS12_add_safes(3),
695 PKCS12_create(3), PKCS12_decrypt_skey(3), PKCS12_init(3),
696 PKCS12_item_decrypt_d2i(3), PKCS12_item_i2d_encrypt(3),
697 PKCS12_key_gen_asc(3), PKCS12_key_gen_uni(3),
698 PKCS12_key_gen_utf8(3), PKCS12_pack_p7encdata(3),
699 PKCS12_pbe_crypt(3), PKCS12_PBE_keyivgen(3),
700 PKCS12_SAFEBAG_create_pkcs8_encrypt(3)
701 • PKCS5_pbe_set0_algor(3), PKCS5_pbe_set(3), PKCS5_pbe2_set_iv(3),
703 PKCS5_pbkdf2_set(3) and PKCS5_v2_scrypt_keyivgen(3)
704 • PKCS7_encrypt(3), PKCS7_new(3) and PKCS7_sign(3)
706 • PKCS8_decrypt(3), PKCS8_encrypt(3) and PKCS8_set0_pbe(3)
708 • RAND_bytes(3) and RAND_priv_bytes(3)
710 • SMIME_write_ASN1(3)
712 • SSL_load_client_CA_file(3)
714 • SSL_CTX_new(3)
716 • TS_RESP_CTX_new(3)
718 • X509_CRL_new(3)
720 • X509_load_cert_crl_file(3) and X509_load_cert_file(3)
722 • X509_LOOKUP_by_subject(3) and X509_LOOKUP_ctrl(3)
724 • X509_NAME_hash(3)
726 • X509_new(3)
728 • X509_REQ_new(3) and X509_REQ_verify(3)
730 • X509_STORE_CTX_new(3), X509_STORE_set_default_paths(3),
732 X509_STORE_load_file(3), X509_STORE_load_locations(3) and
733 X509_STORE_load_store(3)
734 New functions that use a Library context
736 The following functions can be passed a library context if required.
738 Passing NULL will use the default library context.
739 • BIO_new_from_core_bio(3)
741 • EVP_ASYM_CIPHER_fetch(3) and EVP_ASYM_CIPHER_do_all_provided(3)
743 • EVP_CIPHER_fetch(3) and EVP_CIPHER_do_all_provided(3)
745 • EVP_default_properties_enable_fips(3) and
747 EVP_default_properties_is_fips_enabled(3)
748 • EVP_KDF_fetch(3) and EVP_KDF_do_all_provided(3)
750 • EVP_KEM_fetch(3) and EVP_KEM_do_all_provided(3)
752 • EVP_KEYEXCH_fetch(3) and EVP_KEYEXCH_do_all_provided(3)
754 • EVP_KEYMGMT_fetch(3) and EVP_KEYMGMT_do_all_provided(3)
756 • EVP_MAC_fetch(3) and EVP_MAC_do_all_provided(3)
758 • EVP_MD_fetch(3) and EVP_MD_do_all_provided(3)
760 • EVP_PKEY_CTX_new_from_pkey(3)
762 • EVP_PKEY_Q_keygen(3)
764 • EVP_Q_mac(3) and EVP_Q_digest(3)
766 • EVP_RAND(3) and EVP_RAND_do_all_provided(3)
768 • EVP_set_default_properties(3)
770 • EVP_SIGNATURE_fetch(3) and EVP_SIGNATURE_do_all_provided(3)
772 • OSSL_CMP_CTX_new(3) and OSSL_CMP_SRV_CTX_new(3)
774 • OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert(3)
776 • OSSL_CRMF_MSG_create_popo(3) and OSSL_CRMF_MSGS_verify_popo(3)
778 • OSSL_CRMF_pbm_new(3) and OSSL_CRMF_pbmp_new(3)
780 • OSSL_DECODER_CTX_add_extra(3) and OSSL_DECODER_CTX_new_for_pkey(3)
782 • OSSL_DECODER_fetch(3) and OSSL_DECODER_do_all_provided(3)
784 • OSSL_ENCODER_CTX_add_extra(3)
786 • OSSL_ENCODER_fetch(3) and OSSL_ENCODER_do_all_provided(3)
788 • OSSL_LIB_CTX_free(3), OSSL_LIB_CTX_load_config(3) and
790 OSSL_LIB_CTX_set0_default(3)
791 • OSSL_PROVIDER_add_builtin(3), OSSL_PROVIDER_available(3),
793 OSSL_PROVIDER_do_all(3), OSSL_PROVIDER_load(3),
794 OSSL_PROVIDER_set_default_search_path(3) and
795 OSSL_PROVIDER_try_load(3)
796 • OSSL_SELF_TEST_get_callback(3) and OSSL_SELF_TEST_set_callback(3)
798 • OSSL_STORE_attach(3)
800 • OSSL_STORE_LOADER_fetch(3) and OSSL_STORE_LOADER_do_all_provided(3)
802 • RAND_get0_primary(3), RAND_get0_private(3), RAND_get0_public(3),
804 RAND_set_DRBG_type(3) and RAND_set_seed_source_type(3)
805 Providers
807 Providers are described in detail here "Providers" in crypto(7). See
809 also "OPENSSL PROVIDERS" in crypto(7).
810 Fetching algorithms and property queries
812 Implicit and Explicit Fetching is described in detail here "ALGORITHM
814 FETCHING" in crypto(7).
815 Mapping EVP controls and flags to provider OSSL_PARAM parameters
817 The existing functions for controls (such as EVP_CIPHER_CTX_ctrl(3))
819 and manipulating flags (such as EVP_MD_CTX_set_flags(3))internally use
820 OSSL_PARAMS to pass information to/from provider objects. See
821 OSSL_PARAM(3) for additional information related to parameters.
822 For ciphers see "CONTROLS" in EVP_EncryptInit(3), "FLAGS" in
824 EVP_EncryptInit(3) and "PARAMETERS" in EVP_EncryptInit(3).
825 For digests see "CONTROLS" in EVP_DigestInit(3), "FLAGS" in
827 EVP_DigestInit(3) and "PARAMETERS" in EVP_DigestInit(3).
828 Deprecation of Low Level Functions
830 A significant number of APIs have been deprecated in OpenSSL 3.0. This
832 section describes some common categories of deprecations. See
833 "Deprecated function mappings" for the list of deprecated functions
834 that refer to these categories.
835 Providers are a replacement for engines and low-level method overrides
837 Any accessor that uses an ENGINE is deprecated (such as
839 EVP_PKEY_set1_engine()). Applications using engines should instead use
840 providers.
841 Before providers were added algorithms were overriden by changing the
843 methods used by algorithms. All these methods such as RSA_new_method()
844 and RSA_meth_new() are now deprecated and can be replaced by using
845 providers instead.
846 Deprecated i2d and d2i functions for low-level key types
848 Any i2d and d2i functions such as d2i_DHparams() that take a low-level
850 key type have been deprecated. Applications should instead use the
851 OSSL_DECODER(3) and OSSL_ENCODER(3) APIs to read and write files. See
852 "Migration" in d2i_RSAPrivateKey(3) for further details.
853 Deprecated low-level key object getters and setters
855 Applications that set or get low-level key objects (such as
857 EVP_PKEY_set1_DH() or EVP_PKEY_get0()) should instead use the
858 OSSL_ENCODER (See OSSL_ENCODER_to_bio(3)) or OSSL_DECODER (See
859 OSSL_DECODER_from_bio(3)) APIs, or alternatively use
860 EVP_PKEY_fromdata(3) or EVP_PKEY_todata(3).
861 Deprecated low-level key parameter getters
863 Functions that access low-level objects directly such as RSA_get0_n(3)
865 are now deprecated. Applications should use one of
866 EVP_PKEY_get_bn_param(3), EVP_PKEY_get_int_param(3),
867 l<EVP_PKEY_get_size_t_param(3)>, EVP_PKEY_get_utf8_string_param(3),
868 EVP_PKEY_get_octet_string_param(3) or EVP_PKEY_get_params(3) to access
869 fields from an EVP_PKEY. Gettable parameters are listed in "Common RSA
870 parameters" in EVP_PKEY-RSA(7), "DH parameters" in EVP_PKEY-DH(7), "DSA
871 parameters" in EVP_PKEY-DSA(7), "FFC parameters" in EVP_PKEY-FFC(7),
872 "Common EC parameters" in EVP_PKEY-EC(7) and "Common X25519, X448,
873 ED25519 and ED448 parameters" in EVP_PKEY-X25519(7). Applications may
874 also use EVP_PKEY_todata(3) to return all fields.
875 Deprecated low-level key parameter setters
877 Functions that access low-level objects directly such as
879 RSA_set0_crt_params(3) are now deprecated. Applications should use
880 EVP_PKEY_fromdata(3) to create new keys from user provided key data.
881 Keys should be immutable once they are created, so if required the user
882 may use EVP_PKEY_todata(3), OSSL_PARAM_merge(3), and
883 EVP_PKEY_fromdata(3) to create a modified key. See "Examples" in
884 EVP_PKEY-DH(7) for more information. See "Deprecated low-level key
885 generation functions" for information on generating a key using
886 parameters.
887 Deprecated low-level object creation
889 Low-level objects were created using methods such as RSA_new(3),
891 RSA_up_ref(3) and RSA_free(3). Applications should instead use the
892 high-level EVP_PKEY APIs, e.g. EVP_PKEY_new(3), EVP_PKEY_up_ref(3) and
893 EVP_PKEY_free(3). See also EVP_PKEY_CTX_new_from_name(3) and
894 EVP_PKEY_CTX_new_from_pkey(3).
895 EVP_PKEYs may be created in a variety of ways: See also "Deprecated
897 low-level key generation functions", "Deprecated low-level key reading
898 and writing functions" and "Deprecated low-level key parameter
899 setters".
900 Deprecated low-level encryption functions
902 Low-level encryption functions such as AES_encrypt(3) and
904 AES_decrypt(3) have been informally discouraged from use for a long
905 time. Applications should instead use the high level EVP APIs
906 EVP_EncryptInit_ex(3), EVP_EncryptUpdate(3), and EVP_EncryptFinal_ex(3)
907 or EVP_DecryptInit_ex(3), EVP_DecryptUpdate(3) and
908 EVP_DecryptFinal_ex(3).
909 Deprecated low-level digest functions
911 Use of low-level digest functions such as SHA1_Init(3) have been
913 informally discouraged from use for a long time. Applications should
914 instead use the the high level EVP APIs EVP_DigestInit_ex(3),
915 EVP_DigestUpdate(3) and EVP_DigestFinal_ex(3), or the quick one-shot
916 EVP_Q_digest(3).
917 Note that the functions SHA1(3), SHA224(3), SHA256(3), SHA384(3) and
919 SHA512(3) have changed to macros that use EVP_Q_digest(3).
920 Deprecated low-level signing functions
922 Use of low-level signing functions such as DSA_sign(3) have been
924 informally discouraged for a long time. Instead applications should use
925 EVP_DigestSign(3) and EVP_DigestVerify(3). See also
926 EVP_SIGNATURE-RSA(7), EVP_SIGNATURE-DSA(7), EVP_SIGNATURE-ECDSA(7) and
927 EVP_SIGNATURE-ED25519(7).
928 Deprecated low-level MAC functions
930 Low-level mac functions such as CMAC_Init(3) are deprecated.
932 Applications should instead use the new EVP_MAC(3) interface, using
933 EVP_MAC_CTX_new(3), EVP_MAC_CTX_free(3), EVP_MAC_init(3),
934 EVP_MAC_update(3) and EVP_MAC_final(3) or the single-shot MAC function
935 EVP_Q_mac(3). See EVP_MAC(3), EVP_MAC-HMAC(7), EVP_MAC-CMAC(7),
936 EVP_MAC-GMAC(7), EVP_MAC-KMAC(7), EVP_MAC-BLAKE2(7),
937 EVP_MAC-Poly1305(7) and EVP_MAC-Siphash(7) for additional information.
938 Note that the one-shot method HMAC() is still available for
940 compatability purposes.
941 Deprecated low-level validation functions
943 Low-level validation functions such as DH_check(3) have been informally
945 discouraged from use for a long time. Applications should instead use
946 the high-level EVP_PKEY APIs such as EVP_PKEY_check(3),
947 EVP_PKEY_param_check(3), EVP_PKEY_param_check_quick(3),
948 EVP_PKEY_public_check(3), EVP_PKEY_public_check_quick(3),
949 EVP_PKEY_private_check(3), and EVP_PKEY_pairwise_check(3).
950 Deprecated low-level key exchange functions
952 Many low-level functions have been informally discouraged from use for
954 a long time. Applications should instead use EVP_PKEY_derive(3). See
955 EVP_KEYEXCH-DH(7), EVP_KEYEXCH-ECDH(7) and EVP_KEYEXCH-X25519(7).
956 Deprecated low-level key generation functions
958 Many low-level functions have been informally discouraged from use for
960 a long time. Applications should instead use EVP_PKEY_keygen_init(3)
961 and EVP_PKEY_generate(3) as described in EVP_PKEY-DSA(7),
962 EVP_PKEY-DH(7), EVP_PKEY-RSA(7), EVP_PKEY-EC(7) and EVP_PKEY-X25519(7).
963 The 'quick' one-shot function EVP_PKEY_Q_keygen(3) and macros for the
964 most common cases: <EVP_RSA_gen(3)> and EVP_EC_gen(3) may also be used.
965 Deprecated low-level key reading and writing functions
967 Use of low-level objects (such as DSA) has been informally discouraged
969 from use for a long time. Functions to read and write these low-level
970 objects (such as PEM_read_DSA_PUBKEY()) should be replaced.
971 Applications should instead use OSSL_ENCODER_to_bio(3) and
972 OSSL_DECODER_from_bio(3).
973 Deprecated low-level key printing functions
975 Use of low-level objects (such as DSA) has been informally discouraged
977 from use for a long time. Functions to print these low-level objects
978 such as DSA_print() should be replaced with the equivalent EVP_PKEY
979 functions. Application should use one of EVP_PKEY_print_public(3),
980 EVP_PKEY_print_private(3), EVP_PKEY_print_params(3),
981 EVP_PKEY_print_public_fp(3), EVP_PKEY_print_private_fp(3) or
982 EVP_PKEY_print_params_fp(3). Note that internally these use
983 OSSL_ENCODER_to_bio(3) and OSSL_DECODER_from_bio(3).
984 Deprecated function mappings
986 The following functions have been deprecated in 3.0.
988 • AES_bi_ige_encrypt() and AES_ige_encrypt()
990 There is no replacement for the IGE functions. New code should not
992 use these modes. These undocumented functions were never
993 integrated into the EVP layer. They implemented the AES Infinite
994 Garble Extension (IGE) mode and AES Bi-directional IGE mode. These
995 modes were never formally standardised and usage of these functions
996 is believed to be very small. In particular AES_bi_ige_encrypt()
997 has a known bug. It accepts 2 AES keys, but only one is ever used.
998 The security implications are believed to be minimal, but this
999 issue was never fixed for backwards compatibility reasons.
1000 • AES_encrypt(), AES_decrypt(), AES_set_encrypt_key(),
1002 AES_set_decrypt_key(), AES_cbc_encrypt(), AES_cfb128_encrypt(),
1003 AES_cfb1_encrypt(), AES_cfb8_encrypt(), AES_ecb_encrypt(),
1004 AES_ofb128_encrypt()
1005 • AES_unwrap_key(), AES_wrap_key()
1007 See "Deprecated low-level encryption functions"
1009 • AES_options()
1011 There is no replacement. It returned a string indicating if the AES
1013 code was unrolled.
1014 • ASN1_digest(), ASN1_sign(), ASN1_verify()
1016 There are no replacements. These old functions are not used, and
1018 could be disabled with the macro NO_ASN1_OLD since OpenSSL 0.9.7.
1019 • ASN1_STRING_length_set()
1021 Use ASN1_STRING_set(3) or ASN1_STRING_set0(3) instead. This was a
1023 potentially unsafe function that could change the bounds of a
1024 previously passed in pointer.
1025 • BF_encrypt(), BF_decrypt(), BF_set_key(), BF_cbc_encrypt(),
1027 BF_cfb64_encrypt(), BF_ecb_encrypt(), BF_ofb64_encrypt()
1028 See "Deprecated low-level encryption functions". The Blowfish
1030 algorithm has been moved to the Legacy Provider.
1031 • BF_options()
1033 There is no replacement. This option returned a constant string.
1035 • BIO_get_callback(), BIO_set_callback(), BIO_debug_callback()
1037 Use the respective non-deprecated _ex() functions.
1039 • BN_is_prime_ex(), BN_is_prime_fasttest_ex()
1041 Use BN_check_prime(3) which that avoids possible misuse and always
1043 uses at least 64 rounds of the Miller-Rabin primality test.
1044 • BN_pseudo_rand(), BN_pseudo_rand_range()
1046 Use BN_rand(3) and BN_rand_range(3).
1048 • BN_X931_derive_prime_ex(), BN_X931_generate_prime_ex(),
1050 BN_X931_generate_Xpq()
1051 There are no replacements for these low-level functions. They were
1053 used internally by RSA_X931_derive_ex() and
1054 RSA_X931_generate_key_ex() which are also deprecated. Use
1055 EVP_PKEY_keygen(3) instead.
1056 • Camellia_encrypt(), Camellia_decrypt(), Camellia_set_key(),
1058 Camellia_cbc_encrypt(), Camellia_cfb128_encrypt(),
1059 Camellia_cfb1_encrypt(), Camellia_cfb8_encrypt(),
1060 Camellia_ctr128_encrypt(), Camellia_ecb_encrypt(),
1061 Camellia_ofb128_encrypt()
1062 See "Deprecated low-level encryption functions".
1064 • CAST_encrypt(), CAST_decrypt(), CAST_set_key(), CAST_cbc_encrypt(),
1066 CAST_cfb64_encrypt(), CAST_ecb_encrypt(), CAST_ofb64_encrypt()
1067 See "Deprecated low-level encryption functions". The CAST
1069 algorithm has been moved to the Legacy Provider.
1070 • CMAC_CTX_new(), CMAC_CTX_cleanup(), CMAC_CTX_copy(),
1072 CMAC_CTX_free(), CMAC_CTX_get0_cipher_ctx()
1073 See "Deprecated low-level MAC functions".
1075 • CMAC_Init(), CMAC_Update(), CMAC_Final(), CMAC_resume()
1077 See "Deprecated low-level MAC functions".
1079 • CRYPTO_mem_ctrl(), CRYPTO_mem_debug_free(),
1081 CRYPTO_mem_debug_malloc(), CRYPTO_mem_debug_pop(),
1082 CRYPTO_mem_debug_push(), CRYPTO_mem_debug_realloc(),
1083 CRYPTO_mem_leaks(), CRYPTO_mem_leaks_cb(), CRYPTO_mem_leaks_fp(),
1084 CRYPTO_set_mem_debug()
1085 Memory-leak checking has been deprecated in favor of more modern
1087 development tools, such as compiler memory and leak sanitizers or
1088 Valgrind.
1089 • CRYPTO_cts128_encrypt_block(), CRYPTO_cts128_encrypt(),
1091 CRYPTO_cts128_decrypt_block(), CRYPTO_cts128_decrypt(),
1092 CRYPTO_nistcts128_encrypt_block(), CRYPTO_nistcts128_encrypt(),
1093 CRYPTO_nistcts128_decrypt_block(), CRYPTO_nistcts128_decrypt()
1094 Use the higher level functions EVP_CipherInit_ex2(),
1096 EVP_CipherUpdate() and EVP_CipherFinal_ex() instead. See the
1097 "cts_mode" parameter in "Gettable and Settable EVP_CIPHER_CTX
1098 parameters" in EVP_EncryptInit(3). See "EXAMPLES" in
1099 EVP_EncryptInit(3) for a AES-256-CBC-CTS example.
1100 • d2i_DHparams(), d2i_DHxparams(), d2i_DSAparams(),
1102 d2i_DSAPrivateKey(), d2i_DSAPrivateKey_bio(),
1103 d2i_DSAPrivateKey_fp(), d2i_DSA_PUBKEY(), d2i_DSA_PUBKEY_bio(),
1104 d2i_DSA_PUBKEY_fp(), d2i_DSAPublicKey(), d2i_ECParameters(),
1105 d2i_ECPrivateKey(), d2i_ECPrivateKey_bio(), d2i_ECPrivateKey_fp(),
1106 d2i_EC_PUBKEY(), d2i_EC_PUBKEY_bio(), d2i_EC_PUBKEY_fp(),
1107 o2i_ECPublicKey(), d2i_RSAPrivateKey(), d2i_RSAPrivateKey_bio(),
1108 d2i_RSAPrivateKey_fp(), d2i_RSA_PUBKEY(), d2i_RSA_PUBKEY_bio(),
1109 d2i_RSA_PUBKEY_fp(), d2i_RSAPublicKey(), d2i_RSAPublicKey_bio(),
1110 d2i_RSAPublicKey_fp()
1111 See "Deprecated i2d and d2i functions for low-level key types"
1113 • DES_crypt(), DES_fcrypt(), DES_encrypt1(), DES_encrypt2(),
1115 DES_encrypt3(), DES_decrypt3(), DES_ede3_cbc_encrypt(),
1116 DES_ede3_cfb64_encrypt(),
1117 DES_ede3_cfb_encrypt(),DES_ede3_ofb64_encrypt(), DES_ecb_encrypt(),
1118 DES_ecb3_encrypt(), DES_ofb64_encrypt(), DES_ofb_encrypt(),
1119 DES_cfb64_encrypt DES_cfb_encrypt(), DES_cbc_encrypt(),
1120 DES_ncbc_encrypt(), DES_pcbc_encrypt(), DES_xcbc_encrypt(),
1121 DES_cbc_cksum(), DES_quad_cksum(), DES_check_key_parity(),
1122 DES_is_weak_key(), DES_key_sched(), DES_options(),
1123 DES_random_key(), DES_set_key(), DES_set_key_checked(),
1124 DES_set_key_unchecked(), DES_set_odd_parity(),
1125 DES_string_to_2keys(), DES_string_to_key()
1126 See "Deprecated low-level encryption functions". Algorithms for
1128 "DESX-CBC", "DES-ECB", "DES-CBC", "DES-OFB", "DES-CFB", "DES-CFB1"
1129 and "DES-CFB8" have been moved to the Legacy Provider.
1130 • DH_bits(), DH_security_bits(), DH_size()
1132 Use EVP_PKEY_get_bits(3), EVP_PKEY_get_security_bits(3) and
1134 EVP_PKEY_get_size(3).
1135 • DH_check(), DH_check_ex(), DH_check_params(), DH_check_params_ex(),
1137 DH_check_pub_key(), DH_check_pub_key_ex()
1138 See "Deprecated low-level validation functions"
1140 • DH_clear_flags(), DH_test_flags(), DH_set_flags()
1142 The DH_FLAG_CACHE_MONT_P flag has been deprecated without
1144 replacement. The DH_FLAG_TYPE_DH and DH_FLAG_TYPE_DHX have been
1145 deprecated. Use EVP_PKEY_is_a() to determine the type of a key.
1146 There is no replacement for setting these flags.
1147 • DH_compute_key() DH_compute_key_padded()
1149 See "Deprecated low-level key exchange functions".
1151 • DH_new(), DH_new_by_nid(), DH_free(), DH_up_ref()
1153 See "Deprecated low-level object creation"
1155 • DH_generate_key(), DH_generate_parameters_ex()
1157 See "Deprecated low-level key generation functions".
1159 • DH_get0_pqg(), DH_get0_p(), DH_get0_q(), DH_get0_g(),
1161 DH_get0_key(), DH_get0_priv_key(), DH_get0_pub_key(),
1162 DH_get_length(), DH_get_nid()
1163 See "Deprecated low-level key parameter getters"
1165 • DH_get_1024_160(), DH_get_2048_224(), DH_get_2048_256()
1167 Applications should instead set the OSSL_PKEY_PARAM_GROUP_NAME as
1169 specified in "DH parameters" in EVP_PKEY-DH(7)) to one of
1170 "dh_1024_160", "dh_2048_224" or "dh_2048_256" when generating a DH
1171 key.
1172 • DH_KDF_X9_42()
1174 Applications should use EVP_PKEY_CTX_set_dh_kdf_type(3) instead.
1176 • DH_get_default_method(), DH_get0_engine(), DH_meth_*(),
1178 DH_new_method(), DH_OpenSSL(), DH_get_ex_data(),
1179 DH_set_default_method(), DH_set_method(), DH_set_ex_data()
1180 See "Providers are a replacement for engines and low-level method
1182 overrides"
1183 • DHparams_print(), DHparams_print_fp()
1185 See "Deprecated low-level key printing functions"
1187 • DH_set0_key(), DH_set0_pqg(), DH_set_length()
1189 See "Deprecated low-level key parameter setters"
1191 • DSA_bits(), DSA_security_bits(), DSA_size()
1193 Use EVP_PKEY_get_bits(3), EVP_PKEY_get_security_bits(3) and
1195 EVP_PKEY_get_size(3).
1196 • DHparams_dup(), DSA_dup_DH()
1198 There is no direct replacement. Applications may use
1200 EVP_PKEY_copy_parameters(3) and EVP_PKEY_dup(3) instead.
1201 • DSA_generate_key(), DSA_generate_parameters_ex()
1203 See "Deprecated low-level key generation functions".
1205 • DSA_get0_engine(), DSA_get_default_method(), DSA_get_ex_data(),
1207 DSA_get_method(), DSA_meth_*(), DSA_new_method(), DSA_OpenSSL(),
1208 DSA_set_default_method(), DSA_set_ex_data(), DSA_set_method()
1209 See "Providers are a replacement for engines and low-level method
1211 overrides".
1212 • DSA_get0_p(), DSA_get0_q(), DSA_get0_g(), DSA_get0_pqg(),
1214 DSA_get0_key(), DSA_get0_priv_key(), DSA_get0_pub_key()
1215 See "Deprecated low-level key parameter getters".
1217 • DSA_new(), DSA_free(), DSA_up_ref()
1219 See "Deprecated low-level object creation"
1221 • DSAparams_dup()
1223 There is no direct replacement. Applications may use
1225 EVP_PKEY_copy_parameters(3) and EVP_PKEY_dup(3) instead.
1226 • DSAparams_print(), DSAparams_print_fp(), DSA_print(),
1228 DSA_print_fp()
1229 See "Deprecated low-level key printing functions"
1231 • DSA_set0_key(), DSA_set0_pqg()
1233 See "Deprecated low-level key parameter setters"
1235 • DSA_set_flags(), DSA_clear_flags(), DSA_test_flags()
1237 The DSA_FLAG_CACHE_MONT_P flag has been deprecated without
1239 replacement.
1240 • DSA_sign(), DSA_do_sign(), DSA_sign_setup(), DSA_verify(),
1242 DSA_do_verify()
1243 See "Deprecated low-level signing functions".
1245 • ECDH_compute_key()
1247 See "Deprecated low-level key exchange functions".
1249 • ECDH_KDF_X9_62()
1251 Applications may either set this using the helper function
1253 EVP_PKEY_CTX_set_ecdh_kdf_type(3) or by setting an OSSL_PARAM using
1254 the "kdf-type" as shown in "EXAMPLES" in EVP_KEYEXCH-ECDH(7)
1255 • ECDSA_sign(), ECDSA_sign_ex(), ECDSA_sign_setup(), ECDSA_do_sign(),
1257 ECDSA_do_sign_ex(), ECDSA_verify(), ECDSA_do_verify()
1258 See "Deprecated low-level signing functions".
1260 • ECDSA_size()
1262 Applications should use EVP_PKEY_get_size(3).
1264 • EC_GF2m_simple_method(), EC_GFp_mont_method(),
1266 EC_GFp_nist_method(), EC_GFp_nistp224_method(),
1267 EC_GFp_nistp256_method(), EC_GFp_nistp521_method(),
1268 EC_GFp_simple_method()
1269 There are no replacements for these functions. Applications should
1271 rely on the library automatically assigning a suitable method
1272 internally when an EC_GROUP is constructed.
1273 • EC_GROUP_clear_free()
1275 Use EC_GROUP_free(3) instead.
1277 • EC_GROUP_get_curve_GF2m(), EC_GROUP_get_curve_GFp(),
1279 EC_GROUP_set_curve_GF2m(), EC_GROUP_set_curve_GFp()
1280 Applications should use EC_GROUP_get_curve(3) and
1282 EC_GROUP_set_curve(3).
1283 • EC_GROUP_have_precompute_mult(), EC_GROUP_precompute_mult(),
1285 EC_KEY_precompute_mult()
1286 These functions are not widely used. Applications should instead
1288 switch to named curves which OpenSSL has hardcoded lookup tables
1289 for.
1290 • EC_GROUP_new(), EC_GROUP_method_of(), EC_POINT_method_of()
1292 EC_METHOD is now an internal-only concept and a suitable EC_METHOD
1294 is assigned internally without application intervention. Users of
1295 EC_GROUP_new() should switch to a different suitable constructor.
1296 • EC_KEY_can_sign()
1298 Applications should use EVP_PKEY_can_sign(3) instead.
1300 • EC_KEY_check_key()
1302 See "Deprecated low-level validation functions"
1304 • EC_KEY_set_flags(), EC_KEY_get_flags(), EC_KEY_clear_flags()
1306 See "Common EC parameters" in EVP_PKEY-EC(7) which handles flags as
1308 seperate parameters for OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT,
1309 OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE, OSSL_PKEY_PARAM_EC_ENCODING,
1310 OSSL_PKEY_PARAM_USE_COFACTOR_ECDH and
1311 OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC. See also "EXAMPLES" in
1312 EVP_PKEY-EC(7)
1313 • EC_KEY_dup(), EC_KEY_copy()
1315 There is no direct replacement. Applications may use
1317 EVP_PKEY_copy_parameters(3) and EVP_PKEY_dup(3) instead.
1318 • EC_KEY_decoded_from_explicit_params()
1320 There is no replacement.
1322 • EC_KEY_generate_key()
1324 See "Deprecated low-level key generation functions".
1326 • EC_KEY_get0_group(), EC_KEY_get0_private_key(),
1328 EC_KEY_get0_public_key(), EC_KEY_get_conv_form(),
1329 EC_KEY_get_enc_flags()
1330 See "Deprecated low-level key parameter getters".
1332 • EC_KEY_get0_engine(), EC_KEY_get_default_method(),
1334 EC_KEY_get_method(), EC_KEY_new_method(), EC_KEY_get_ex_data(),
1335 EC_KEY_OpenSSL(), EC_KEY_set_ex_data(),
1336 EC_KEY_set_default_method(), EC_KEY_METHOD_*(), EC_KEY_set_method()
1337 See "Providers are a replacement for engines and low-level method
1339 overrides"
1340 • EC_METHOD_get_field_type()
1342 Use EC_GROUP_get_field_type(3) instead. See "Providers are a
1344 replacement for engines and low-level method overrides"
1345 • EC_KEY_key2buf(), EC_KEY_oct2key(), EC_KEY_oct2priv(),
1347 EC_KEY_priv2buf(), EC_KEY_priv2oct()
1348 There are no replacements for these.
1350 • EC_KEY_new(), EC_KEY_new_by_curve_name(), EC_KEY_free(),
1352 EC_KEY_up_ref()
1353 See "Deprecated low-level object creation"
1355 • EC_KEY_print(), EC_KEY_print_fp()
1357 See "Deprecated low-level key printing functions"
1359 • EC_KEY_set_asn1_flag(), EC_KEY_set_conv_form(),
1361 EC_KEY_set_enc_flags()
1362 See "Deprecated low-level key parameter setters".
1364 • EC_KEY_set_group(), EC_KEY_set_private_key(),
1366 EC_KEY_set_public_key(), EC_KEY_set_public_key_affine_coordinates()
1367 See "Deprecated low-level key parameter setters".
1369 • ECParameters_print(), ECParameters_print_fp(),
1371 ECPKParameters_print(), ECPKParameters_print_fp()
1372 See "Deprecated low-level key printing functions"
1374 • EC_POINT_bn2point(), EC_POINT_point2bn()
1376 These functions were not particularly useful, since EC point
1378 serialization formats are not individual big-endian integers.
1379 • EC_POINT_get_affine_coordinates_GF2m(),
1381 EC_POINT_get_affine_coordinates_GFp(),
1382 EC_POINT_set_affine_coordinates_GF2m(),
1383 EC_POINT_set_affine_coordinates_GFp()
1384 Applications should use EC_POINT_get_affine_coordinates(3) and
1386 EC_POINT_set_affine_coordinates(3) instead.
1387 • EC_POINT_get_Jprojective_coordinates_GFp(),
1389 EC_POINT_set_Jprojective_coordinates_GFp()
1390 These functions are not widely used. Applications should instead
1392 use the EC_POINT_set_affine_coordinates(3) and
1393 EC_POINT_get_affine_coordinates(3) functions.
1394 • EC_POINT_make_affine(), EC_POINTs_make_affine()
1396 There is no replacement. These functions were not widely used, and
1398 OpenSSL automatically performs this conversion when needed.
1399 • EC_POINT_set_compressed_coordinates_GF2m(),
1401 EC_POINT_set_compressed_coordinates_GFp()
1402 Applications should use EC_POINT_set_compressed_coordinates(3)
1404 instead.
1405 • EC_POINTs_mul()
1407 This function is not widely used. Applications should instead use
1409 the EC_POINT_mul(3) function.
1410 • ENGINE_*()
1412 All engine functions are deprecated. An engine should be rewritten
1414 as a provider. See "Providers are a replacement for engines and
1415 low-level method overrides".
1416 • ERR_load_*(), ERR_func_error_string(), ERR_get_error_line(),
1418 ERR_get_error_line_data(), ERR_get_state()
1419 OpenSSL now loads error strings automatically so these functions
1421 are not needed.
1422 • ERR_peek_error_line_data(), ERR_peek_last_error_line_data()
1424 The new functions are ERR_peek_error_func(3),
1426 ERR_peek_last_error_func(3), ERR_peek_error_data(3),
1427 ERR_peek_last_error_data(3), ERR_get_error_all(3),
1428 ERR_peek_error_all(3) and ERR_peek_last_error_all(3). Applications
1429 should use ERR_get_error_all(3), or pick information with ERR_peek
1430 functions and finish off with getting the error code by using
1431 ERR_get_error(3).
1432 • EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_iv_noconst(),
1434 EVP_CIPHER_CTX_original_iv()
1435 Applications should instead use EVP_CIPHER_CTX_get_updated_iv(3),
1437 EVP_CIPHER_CTX_get_updated_iv(3) and
1438 EVP_CIPHER_CTX_get_original_iv(3) respectively. See
1439 EVP_CIPHER_CTX_get_original_iv(3) for further information.
1440 • EVP_CIPHER_meth_*(), EVP_MD_CTX_set_update_fn(),
1442 EVP_MD_CTX_update_fn(), EVP_MD_meth_*()
1443 See "Providers are a replacement for engines and low-level method
1445 overrides".
1446 • EVP_PKEY_CTRL_PKCS7_ENCRYPT(), EVP_PKEY_CTRL_PKCS7_DECRYPT(),
1448 EVP_PKEY_CTRL_PKCS7_SIGN(), EVP_PKEY_CTRL_CMS_ENCRYPT(),
1449 EVP_PKEY_CTRL_CMS_DECRYPT(), and EVP_PKEY_CTRL_CMS_SIGN()
1450 These control operations are not invoked by the OpenSSL library
1452 anymore and are replaced by direct checks of the key operation
1453 against the key type when the operation is initialized.
1454 • EVP_PKEY_CTX_get0_dh_kdf_ukm(), EVP_PKEY_CTX_get0_ecdh_kdf_ukm()
1456 See the "kdf-ukm" item in "DH key exchange parameters" in
1458 EVP_KEYEXCH-DH(7) and "ECDH Key Exchange parameters" in
1459 EVP_KEYEXCH-ECDH(7). These functions are obsolete and should not
1460 be required.
1461 • EVP_PKEY_CTX_set_rsa_keygen_pubexp()
1463 Applications should use EVP_PKEY_CTX_set1_rsa_keygen_pubexp(3)
1465 instead.
1466 • EVP_PKEY_cmp(), EVP_PKEY_cmp_parameters()
1468 Applications should use EVP_PKEY_eq(3) and
1470 EVP_PKEY_parameters_eq(3) instead. See EVP_PKEY_copy_parameters(3)
1471 for further details.
1472 • EVP_PKEY_encrypt_old(), EVP_PKEY_decrypt_old(),
1474 Applications should use EVP_PKEY_encrypt_init(3) and
1476 EVP_PKEY_encrypt(3) or EVP_PKEY_decrypt_init(3) and
1477 EVP_PKEY_decrypt(3) instead.
1478 • EVP_PKEY_get0()
1480 This function returns NULL if the key comes from a provider.
1482 • EVP_PKEY_get0_DH(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_EC_KEY(),
1484 EVP_PKEY_get0_RSA(), EVP_PKEY_get1_DH(), EVP_PKEY_get1_DSA(),
1485 EVP_PKEY_get1_EC_KEY and EVP_PKEY_get1_RSA(), EVP_PKEY_get0_hmac(),
1486 EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash()
1487 See "Functions that return an internal key should be treated as
1489 read only".
1490 • EVP_PKEY_meth_*()
1492 See "Providers are a replacement for engines and low-level method
1494 overrides".
1495 • EVP_PKEY_new_CMAC_key()
1497 See "Deprecated low-level MAC functions".
1499 • EVP_PKEY_assign(), EVP_PKEY_set1_DH(), EVP_PKEY_set1_DSA(),
1501 EVP_PKEY_set1_EC_KEY(), EVP_PKEY_set1_RSA()
1502 See "Deprecated low-level key object getters and setters"
1504 • EVP_PKEY_set1_tls_encodedpoint() EVP_PKEY_get1_tls_encodedpoint()
1506 These functions were previously used by libssl to set or get an
1508 encoded public key into/from an EVP_PKEY object. With OpenSSL 3.0
1509 these are replaced by the more generic functions
1510 EVP_PKEY_set1_encoded_public_key(3) and
1511 EVP_PKEY_get1_encoded_public_key(3). The old versions have been
1512 converted to deprecated macros that just call the new functions.
1513 • EVP_PKEY_set1_engine(), EVP_PKEY_get0_engine()
1515 See "Providers are a replacement for engines and low-level method
1517 overrides".
1518 • EVP_PKEY_set_alias_type()
1520 This function has been removed. There is no replacement. See
1522 "EVP_PKEY_set_alias_type() method has been removed"
1523 • HMAC_Init_ex(), HMAC_Update(), HMAC_Final(), HMAC_size()
1525 See "Deprecated low-level MAC functions".
1527 • HMAC_CTX_new(), HMAC_CTX_free(), HMAC_CTX_copy(), HMAC_CTX_reset(),
1529 HMAC_CTX_set_flags(), HMAC_CTX_get_md()
1530 See "Deprecated low-level MAC functions".
1532 • i2d_DHparams(), i2d_DHxparams()
1534 See "Deprecated low-level key reading and writing functions" and
1536 "Migration" in d2i_RSAPrivateKey(3)
1537 • i2d_DSAparams(), i2d_DSAPrivateKey(), i2d_DSAPrivateKey_bio(),
1539 i2d_DSAPrivateKey_fp(), i2d_DSA_PUBKEY(), i2d_DSA_PUBKEY_bio(),
1540 i2d_DSA_PUBKEY_fp(), i2d_DSAPublicKey()
1541 See "Deprecated low-level key reading and writing functions" and
1543 "Migration" in d2i_RSAPrivateKey(3)
1544 • i2d_ECParameters(), i2d_ECPrivateKey(), i2d_ECPrivateKey_bio(),
1546 i2d_ECPrivateKey_fp(), i2d_EC_PUBKEY(), i2d_EC_PUBKEY_bio(),
1547 i2d_EC_PUBKEY_fp(), i2o_ECPublicKey()
1548 See "Deprecated low-level key reading and writing functions" and
1550 "Migration" in d2i_RSAPrivateKey(3)
1551 • i2d_RSAPrivateKey(), i2d_RSAPrivateKey_bio(),
1553 i2d_RSAPrivateKey_fp(), i2d_RSA_PUBKEY(), i2d_RSA_PUBKEY_bio(),
1554 i2d_RSA_PUBKEY_fp(), i2d_RSAPublicKey(), i2d_RSAPublicKey_bio(),
1555 i2d_RSAPublicKey_fp()
1556 See "Deprecated low-level key reading and writing functions" and
1558 "Migration" in d2i_RSAPrivateKey(3)
1559 • IDEA_encrypt(), IDEA_set_decrypt_key(), IDEA_set_encrypt_key(),
1561 IDEA_cbc_encrypt(), IDEA_cfb64_encrypt(), IDEA_ecb_encrypt(),
1562 IDEA_ofb64_encrypt()
1563 See "Deprecated low-level encryption functions". IDEA has been
1565 moved to the Legacy Provider.
1566 • IDEA_options()
1568 There is no replacement. This function returned a constant string.
1570 • MD2(), MD2_Init(), MD2_Update(), MD2_Final()
1572 See "Deprecated low-level encryption functions". MD2 has been
1574 moved to the Legacy Provider.
1575 • MD2_options()
1577 There is no replacement. This function returned a constant string.
1579 • MD4(), MD4_Init(), MD4_Update(), MD4_Final(), MD4_Transform()
1581 See "Deprecated low-level encryption functions". MD4 has been
1583 moved to the Legacy Provider.
1584 • MDC2(), MDC2_Init(), MDC2_Update(), MDC2_Final()
1586 See "Deprecated low-level encryption functions". MDC2 has been
1588 moved to the Legacy Provider.
1589 • MD5(), MD5_Init(), MD5_Update(), MD5_Final(), MD5_Transform()
1591 See "Deprecated low-level encryption functions".
1593 • NCONF_WIN32()
1595 This undocumented function has no replacement. See "HISTORY" in
1597 config(5) for more details.
1598 • OCSP_parse_url()
1600 Use OSSL_HTTP_parse_url(3) instead.
1602 • OCSP_REQ_CTX type and OCSP_REQ_CTX_*() functions
1604 These methods were used to collect all necessary data to form a
1606 HTTP request, and to perform the HTTP transfer with that request.
1607 With OpenSSL 3.0, the type is OSSL_HTTP_REQ_CTX, and the deprecated
1608 functions are replaced with OSSL_HTTP_REQ_CTX_*(). See
1609 OSSL_HTTP_REQ_CTX(3) for additional details.
1610 • OPENSSL_fork_child(), OPENSSL_fork_parent(), OPENSSL_fork_prepare()
1612 There is no replacement for these functions. These pthread fork
1614 support methods were unused by OpenSSL.
1615 • OSSL_STORE_ctrl(), OSSL_STORE_do_all_loaders(),
1617 OSSL_STORE_LOADER_get0_engine(), OSSL_STORE_LOADER_get0_scheme(),
1618 OSSL_STORE_LOADER_new(), OSSL_STORE_LOADER_set_attach(),
1619 OSSL_STORE_LOADER_set_close(), OSSL_STORE_LOADER_set_ctrl(),
1620 OSSL_STORE_LOADER_set_eof(), OSSL_STORE_LOADER_set_error(),
1621 OSSL_STORE_LOADER_set_expect(), OSSL_STORE_LOADER_set_find(),
1622 OSSL_STORE_LOADER_set_load(), OSSL_STORE_LOADER_set_open(),
1623 OSSL_STORE_LOADER_set_open_ex(), OSSL_STORE_register_loader(),
1624 OSSL_STORE_unregister_loader(), OSSL_STORE_vctrl()
1625 These functions helped applications and engines create loaders for
1627 schemes they supported. These are all deprecated and discouraged
1628 in favour of provider implementations, see provider-storemgmt(7).
1629 • PEM_read_DHparams(), PEM_read_bio_DHparams(), PEM_read_DSAparams(),
1631 PEM_read_bio_DSAparams(), PEM_read_DSAPrivateKey(),
1632 PEM_read_DSA_PUBKEY(), PEM_read_bio_DSAPrivateKey and
1633 PEM_read_bio_DSA_PUBKEY(), PEM_read_ECPKParameters(),
1634 PEM_read_ECPrivateKey(), PEM_read_EC_PUBKEY(),
1635 PEM_read_bio_ECPKParameters(), PEM_read_bio_ECPrivateKey(),
1636 PEM_read_bio_EC_PUBKEY(), PEM_read_RSAPrivateKey(),
1637 PEM_read_RSA_PUBKEY(), PEM_read_RSAPublicKey(),
1638 PEM_read_bio_RSAPrivateKey(), PEM_read_bio_RSA_PUBKEY(),
1639 PEM_read_bio_RSAPublicKey(), PEM_write_bio_DHparams(),
1640 PEM_write_bio_DHxparams(), PEM_write_DHparams(),
1641 PEM_write_DHxparams(), PEM_write_DSAparams(),
1642 PEM_write_DSAPrivateKey(), PEM_write_DSA_PUBKEY(),
1643 PEM_write_bio_DSAparams(), PEM_write_bio_DSAPrivateKey(),
1644 PEM_write_bio_DSA_PUBKEY(), PEM_write_ECPKParameters(),
1645 PEM_write_ECPrivateKey(), PEM_write_EC_PUBKEY(),
1646 PEM_write_bio_ECPKParameters(), PEM_write_bio_ECPrivateKey(),
1647 PEM_write_bio_EC_PUBKEY(), PEM_write_RSAPrivateKey(),
1648 PEM_write_RSA_PUBKEY(), PEM_write_RSAPublicKey(),
1649 PEM_write_bio_RSAPrivateKey(), PEM_write_bio_RSA_PUBKEY(),
1650 PEM_write_bio_RSAPublicKey(),
1651 See "Deprecated low-level key reading and writing functions"
1653 • PKCS1_MGF1()
1655 See "Deprecated low-level encryption functions".
1657 • RAND_get_rand_method(), RAND_set_rand_method(), RAND_OpenSSL(),
1659 RAND_set_rand_engine()
1660 Applications should instead use RAND_set_DRBG_type(3), EVP_RAND(3)
1662 and EVP_RAND(7). See RAND_set_rand_method(3) for more details.
1663 • RC2_encrypt(), RC2_decrypt(), RC2_set_key(), RC2_cbc_encrypt(),
1665 RC2_cfb64_encrypt(), RC2_ecb_encrypt(), RC2_ofb64_encrypt(), RC4(),
1666 RC4_set_key(), RC4_options(), RC5_32_encrypt(), RC5_32_set_key(),
1667 RC5_32_decrypt(), RC5_32_cbc_encrypt(), RC5_32_cfb64_encrypt(),
1668 RC5_32_ecb_encrypt(), RC5_32_ofb64_encrypt()
1669 See "Deprecated low-level encryption functions". The Algorithms
1671 "RC2", "RC4" and "RC5" have been moved to the Legacy Provider.
1672 • RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update(),
1674 RIPEMD160_Final(), RIPEMD160_Transform()
1675 See "Deprecated low-level digest functions". The RIPE algorithm
1677 has been moved to the Legacy Provider.
1678 • RSA_bits(), RSA_security_bits(), RSA_size()
1680 Use EVP_PKEY_get_bits(3), EVP_PKEY_get_security_bits(3) and
1682 EVP_PKEY_get_size(3).
1683 • RSA_check_key(), RSA_check_key_ex()
1685 See "Deprecated low-level validation functions"
1687 • RSA_clear_flags(), RSA_flags(), RSA_set_flags(), RSA_test_flags(),
1689 RSA_setup_blinding(), RSA_blinding_off(), RSA_blinding_on()
1690 All of these RSA flags have been deprecated without replacement:
1692 RSA_FLAG_BLINDING, RSA_FLAG_CACHE_PRIVATE, RSA_FLAG_CACHE_PUBLIC,
1694 RSA_FLAG_EXT_PKEY, RSA_FLAG_NO_BLINDING, RSA_FLAG_THREAD_SAFE
1695 RSA_METHOD_FLAG_NO_CHECK
1696 • RSA_generate_key_ex(), RSA_generate_multi_prime_key()
1698 See "Deprecated low-level key generation functions".
1700 • RSA_get0_engine()
1702 See "Providers are a replacement for engines and low-level method
1704 overrides"
1705 • RSA_get0_crt_params(), RSA_get0_d(), RSA_get0_dmp1(),
1707 RSA_get0_dmq1(), RSA_get0_e(), RSA_get0_factors(), RSA_get0_iqmp(),
1708 RSA_get0_key(), RSA_get0_multi_prime_crt_params(),
1709 RSA_get0_multi_prime_factors(), RSA_get0_n(), RSA_get0_p(),
1710 RSA_get0_pss_params(), RSA_get0_q(),
1711 RSA_get_multi_prime_extra_count()
1712 See "Deprecated low-level key parameter getters"
1714 • RSA_new(), RSA_free(), RSA_up_ref()
1716 See "Deprecated low-level object creation".
1718 • RSA_get_default_method(), RSA_get_ex_data and RSA_get_method()
1720 See "Providers are a replacement for engines and low-level method
1722 overrides".
1723 • RSA_get_version()
1725 There is no replacement.
1727 • RSA_meth_*(), RSA_new_method(), RSA_null_method and
1729 RSA_PKCS1_OpenSSL()
1730 See "Providers are a replacement for engines and low-level method
1732 overrides".
1733 • RSA_padding_add_*(), RSA_padding_check_*()
1735 See "Deprecated low-level signing functions" and "Deprecated low-
1737 level encryption functions".
1738 • RSA_print(), RSA_print_fp()
1740 See "Deprecated low-level key printing functions"
1742 • RSA_public_encrypt(), RSA_private_decrypt()
1744 See "Deprecated low-level encryption functions"
1746 • RSA_private_encrypt(), RSA_public_decrypt()
1748 This is equivalent to doing sign and verify recover operations
1750 (with a padding mode of none). See "Deprecated low-level signing
1751 functions".
1752 • RSAPrivateKey_dup(), RSAPublicKey_dup()
1754 There is no direct replacement. Applications may use
1756 EVP_PKEY_dup(3).
1757 • RSAPublicKey_it(), RSAPrivateKey_it()
1759 See "Deprecated low-level key reading and writing functions"
1761 • RSA_set0_crt_params(), RSA_set0_factors(), RSA_set0_key(),
1763 RSA_set0_multi_prime_params()
1764 See "Deprecated low-level key parameter setters".
1766 • RSA_set_default_method(), RSA_set_method(), RSA_set_ex_data()
1768 See "Providers are a replacement for engines and low-level method
1770 overrides"
1771 • RSA_sign(), RSA_sign_ASN1_OCTET_STRING(), RSA_verify(),
1773 RSA_verify_ASN1_OCTET_STRING(), RSA_verify_PKCS1_PSS(),
1774 RSA_verify_PKCS1_PSS_mgf1()
1775 See "Deprecated low-level signing functions".
1777 • RSA_X931_derive_ex(), RSA_X931_generate_key_ex(),
1779 RSA_X931_hash_id()
1780 There are no replacements for these functions. X931 padding can be
1782 set using "Signature Parameters" in EVP_SIGNATURE-RSA(7). See
1783 OSSL_SIGNATURE_PARAM_PAD_MODE.
1784 • SEED_encrypt(), SEED_decrypt(), SEED_set_key(), SEED_cbc_encrypt(),
1786 SEED_cfb128_encrypt(), SEED_ecb_encrypt(), SEED_ofb128_encrypt()
1787 See "Deprecated low-level encryption functions". The SEED
1789 algorithm has been moved to the Legacy Provider.
1790 • SHA1_Init(), SHA1_Update(), SHA1_Final(), SHA1_Transform(),
1792 SHA224_Init(), SHA224_Update(), SHA224_Final(), SHA256_Init(),
1793 SHA256_Update(), SHA256_Final(), SHA256_Transform(), SHA384_Init(),
1794 SHA384_Update(), SHA384_Final(), SHA512_Init(), SHA512_Update(),
1795 SHA512_Final(), SHA512_Transform()
1796 See "Deprecated low-level digest functions".
1798 • SRP_Calc_A(), SRP_Calc_B(), SRP_Calc_client_key(),
1800 SRP_Calc_server_key(), SRP_Calc_u(), SRP_Calc_x(),
1801 SRP_check_known_gN_param(), SRP_create_verifier(),
1802 SRP_create_verifier_BN(), SRP_get_default_gN(),
1803 SRP_user_pwd_free(), SRP_user_pwd_new(), SRP_user_pwd_set0_sv(),
1804 SRP_user_pwd_set1_ids(), SRP_user_pwd_set_gN(),
1805 SRP_VBASE_add0_user(), SRP_VBASE_free(), SRP_VBASE_get1_by_user(),
1806 SRP_VBASE_init(), SRP_VBASE_new(), SRP_Verify_A_mod_N(),
1807 SRP_Verify_B_mod_N()
1808 There are no replacements for the SRP functions.
1810 • SSL_CTX_set_tmp_dh_callback(), SSL_set_tmp_dh_callback(),
1812 SSL_CTX_set_tmp_dh(), SSL_set_tmp_dh()
1813 These are used to set the Diffie-Hellman (DH) parameters that are
1815 to be used by servers requiring ephemeral DH keys. Instead
1816 applications should consider using the built-in DH parameters that
1817 are available by calling SSL_CTX_set_dh_auto(3) or
1818 SSL_set_dh_auto(3). If custom parameters are necessary then
1819 applications can use the alternative functions
1820 SSL_CTX_set0_tmp_dh_pkey(3) and SSL_set0_tmp_dh_pkey(3). There is
1821 no direct replacement for the "callback" functions. The callback
1822 was originally useful in order to have different parameters for
1823 export and non-export ciphersuites. Export ciphersuites are no
1824 longer supported by OpenSSL. Use of the callback functions should
1825 be replaced by one of the other methods described above.
1826 • SSL_CTX_set_tlsext_ticket_key_cb()
1828 Use the new SSL_CTX_set_tlsext_ticket_key_evp_cb(3) function
1830 instead.
1831 • WHIRLPOOL(), WHIRLPOOL_Init(), WHIRLPOOL_Update(),
1833 WHIRLPOOL_Final(), WHIRLPOOL_BitUpdate()
1834 See "Deprecated low-level digest functions". The Whirlpool
1836 algorithm has been moved to the Legacy Provider.
1837 • X509_certificate_type()
1839 This was an undocumented function. Applications can use
1841 X509_get0_pubkey(3) and X509_get0_signature(3) instead.
1842 • X509_http_nbio(), X509_CRL_http_nbio()
1844 Use X509_load_http(3) and X509_CRL_load_http(3) instead.
1846 Using the FIPS Module in applications
1848 See fips_module(7) and OSSL_PROVIDER-FIPS(7) for details.
1849 OpenSSL command line application changes
1851 New applications
1852 openssl kdf uses the new EVP_KDF(3) API. openssl kdf uses the new
1854 EVP_MAC(3) API.
1855 Added options
1857 -provider_path and -provider are available to all apps and can be used
1859 multiple times to load any providers, such as the 'legacy' provider or
1860 third party providers. If used then the 'default' provider would also
1861 need to be specified if required. The -provider_path must be specified
1862 before the -provider option.
1863 The list app has many new options. See openssl-list(1) for more
1865 information.
1866 -crl_lastupdate and -crl_nextupdate used by openssl ca allows explicit
1868 setting of fields in the generated CRL.
1869 Removed options
1871 Interactive mode is not longer available.
1873 The -crypt option used by openssl passwd. The -c option used by
1875 openssl x509, openssl dhparam, openssl dsaparam, and openssl ecparam.
1876 Other Changes
1878 The output of Command line applications may have minor changes. These
1880 are primarily changes in capitalisation and white space. However, in
1881 some cases, there are additional differences. For example, the DH
1882 parameters output from openssl dhparam now lists 'P', 'Q', 'G' and
1883 'pcounter' instead of 'prime', 'generator', 'subgroup order' and
1884 'counter' respectively.
1885 The openssl commands that read keys, certificates, and CRLs now
1887 automatically detect the PEM or DER format of the input files so it is
1888 not necessary to explicitly specify the input format anymore. However
1889 if the input format option is used the specified format will be
1890 required.
1891 openssl speed no longer uses low-level API calls. This implies some of
1893 the performance numbers might not be comparable with the previous
1894 releases due to higher overhead. This applies particularly to measuring
1895 performance on smaller data chunks.
1896 b<openssl dhparam>, openssl dsa, openssl gendsa, openssl dsaparam,
1898 openssl genrsa and openssl rsa have been modified to use PKEY APIs.
1899 openssl genrsa and openssl rsa now write PKCS #8 keys by default.
1900 Default settings
1902 "SHA256" is now the default digest for TS query used by openssl ts.
1904 Deprecated apps
1906 openssl rsautl is deprecated, use openssl pkeyutl instead. openssl
1908 dhparam, openssl dsa, openssl gendsa, openssl dsaparam, openssl genrsa,
1909 openssl rsa, openssl genrsa and openssl rsa are now in maintenance mode
1910 and no new features will be added to them.
1911 TLS Changes
1913 • TLS 1.3 FFDHE key exchange support added
1914 This uses DH safe prime named groups.
1916 • Support for fully "pluggable" TLSv1.3 groups.
1918 This means that providers may supply their own group
1920 implementations (using either the "key exchange" or the "key
1921 encapsulation" methods) which will automatically be detected and
1922 used by libssl.
1923 • SSL and SSL_CTX options are now 64 bit instead of 32 bit.
1925 The signatures of the functions to get and set options on SSL and
1927 SSL_CTX objects changed from "unsigned long" to "uint64_t" type.
1928 This may require source code changes. For example it is no longer
1930 possible to use the SSL_OP_ macro values in preprocessor "#if"
1931 conditions. However it is still possible to test whether these
1932 macros are defined or not.
1933 See SSL_CTX_get_options(3), SSL_CTX_set_options(3),
1935 SSL_get_options(3) and SSL_set_options(3).
1936 • SSL_set1_host() and SSL_add1_host() Changes
1938 These functions now take IP literal addresses as well as actual
1940 hostnames.
1941 • Added SSL option SSL_OP_CLEANSE_PLAINTEXT
1943 If the option is set, openssl cleanses (zeroizes) plaintext bytes
1945 from internal buffers after delivering them to the application.
1946 Note, the application is still responsible for cleansing other
1947 copies (e.g.: data received by SSL_read(3)).
1948 • Client-initiated renegotiation is disabled by default.
1950 To allow it, use the -client_renegotiation option, the
1952 SSL_OP_ALLOW_CLIENT_RENEGOTIATION flag, or the
1953 "ClientRenegotiation" config parameter as appropriate.
1954 • Secure renegotiation is now required by default for TLS connections
1956 Support for RFC 5746 secure renegotiation is now required by
1958 default for SSL or TLS connections to succeed. Applications that
1959 require the ability to connect to legacy peers will need to
1960 explicitly set SSL_OP_LEGACY_SERVER_CONNECT. Accordingly,
1961 SSL_OP_LEGACY_SERVER_CONNECT is no longer set as part of
1962 SSL_OP_ALL.
1963 • Combining the Configure options no-ec and no-dh no longer disables
1965 TLSv1.3
1966 Typically if OpenSSL has no EC or DH algorithms then it cannot
1968 support connections with TLSv1.3. However OpenSSL now supports
1969 "pluggable" groups through providers. Therefore third party
1970 providers may supply group implementations even where there are no
1971 built-in ones. Attempting to create TLS connections in such a build
1972 without also disabling TLSv1.3 at run time or using third party
1973 provider groups may result in handshake failures. TLSv1.3 can be
1974 disabled at compile time using the "no-tls1_3" Configure option.
1975 • SSL_CTX_set_ciphersuites() and SSL_set_ciphersuites() changes.
1977 The methods now ignore unknown ciphers.
1979 • Security callback change.
1981 The security callback, which can be customised by application code,
1983 supports the security operation SSL_SECOP_TMP_DH. This is defined
1984 to take an EVP_PKEY in the "other" parameter. In most places this
1985 is what is passed. All these places occur server side. However
1986 there was one client side call of this security operation and it
1987 passed a DH object instead. This is incorrect according to the
1988 definition of SSL_SECOP_TMP_DH, and is inconsistent with all of the
1989 other locations. Therefore this client side call has been changed
1990 to pass an EVP_PKEY instead.
1991 • New SSL option SSL_OP_IGNORE_UNEXPECTED_EOF
1993 The SSL option SSL_OP_IGNORE_UNEXPECTED_EOF is introduced. If that
1995 option is set, an unexpected EOF is ignored, it pretends a close
1996 notify was received instead and so the returned error becomes
1997 SSL_ERROR_ZERO_RETURN.
1998 • The security strength of SHA1 and MD5 based signatures in TLS has
2000 been reduced.
2001 This results in SSL 3, TLS 1.0, TLS 1.1 and DTLS 1.0 no longer
2003 working at the default security level of 1 and instead requires
2004 security level 0. The security level can be changed either using
2005 the cipher string with @SECLEVEL, or calling
2006 SSL_CTX_set_security_level(3). This also means that where the
2007 signature algorithms extension is missing from a ClientHello then
2008 the handshake will fail in TLS 1.2 at security level 1. This is
2009 because, although this extension is optional, failing to provide
2010 one means that OpenSSL will fallback to a default set of signature
2011 algorithms. This default set requires the availability of SHA1.
2012 • X509 certificates signed using SHA1 are no longer allowed at
2014 security level 1 and above.
2015 In TLS/SSL the default security level is 1. It can be set either
2017 using the cipher string with @SECLEVEL, or calling
2018 SSL_CTX_set_security_level(3). If the leaf certificate is signed
2019 with SHA-1, a call to SSL_CTX_use_certificate(3) will fail if the
2020 security level is not lowered first. Outside TLS/SSL, the default
2021 security level is -1 (effectively 0). It can be set using
2022 X509_VERIFY_PARAM_set_auth_level(3) or using the -auth_level
2023 options of the commands.
2024
2026 fips_module(7)
2027
2029 Copyright 2021-2022 The OpenSSL Project Authors. All Rights Reserved.
2030 Licensed under the Apache License 2.0 (the "License"). You may not use
2032 this file except in compliance with the License. You can obtain a copy
2033 in the file LICENSE in the source distribution or at
2034 <https://www.openssl.org/source/license.html>.
20353.0.5 2022-11-01 MIGRATION_GUIDE(7ossl)