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 Algorithm Fetching
201 Using calls to convenience functions such as EVP_sha256() and
203 EVP_aes_256_gcm() may incur a performance penalty when using providers.
204 Retrieving algorithms from providers involves searching for an
205 algorithm by name. This is much slower than directly accessing a
206 method table. It is recommended to prefetch algorithms if an algorithm
207 is used many times. See "Performance" in crypto(7), "Explicit
208 fetching" in crypto(7) and "Implicit fetching" in crypto(7).
209 Support for Linux Kernel TLS
211 In order to use KTLS, support for it must be compiled in using the
213 "enable-ktls" configuration option. It must also be enabled at run time
214 using the SSL_OP_ENABLE_KTLS option.
215 New Algorithms
217 • KDF algorithms "SINGLE STEP" and "SSH"
219 See EVP_KDF-SS(7) and EVP_KDF-SSHKDF(7)
221 • MAC Algorithms "GMAC" and "KMAC"
223 See EVP_MAC-GMAC(7) and EVP_MAC-KMAC(7).
225 • KEM Algorithm "RSASVE"
227 See EVP_KEM-RSA(7).
229 • Cipher Algorithm "AES-SIV"
231 See "SIV Mode" in EVP_EncryptInit(3).
233 • AES Key Wrap inverse ciphers supported by EVP layer.
235 The inverse ciphers use AES decryption for wrapping, and AES
237 encryption for unwrapping. The algorithms are: "AES-128-WRAP-INV",
238 "AES-192-WRAP-INV", "AES-256-WRAP-INV", "AES-128-WRAP-PAD-INV",
239 "AES-192-WRAP-PAD-INV" and "AES-256-WRAP-PAD-INV".
240 • CTS ciphers added to EVP layer.
242 The algorithms are "AES-128-CBC-CTS", "AES-192-CBC-CTS",
244 "AES-256-CBC-CTS", "CAMELLIA-128-CBC-CTS", "CAMELLIA-192-CBC-CTS"
245 and "CAMELLIA-256-CBC-CTS". CS1, CS2 and CS3 variants are
246 supported.
247 CMS and PKCS#7 updates
249 • Added CAdES-BES signature verification support.
251 • Added CAdES-BES signature scheme and attributes support (RFC 5126)
253 to CMS API.
254 • Added AuthEnvelopedData content type structure (RFC 5083) using
256 AES_GCM
257 This uses the AES-GCM parameter (RFC 5084) for the Cryptographic
259 Message Syntax. Its purpose is to support encryption and
260 decryption of a digital envelope that is both authenticated and
261 encrypted using AES GCM mode.
262 • PKCS7_get_octet_string(3) and PKCS7_type_is_other(3) were made
264 public.
265 PKCS#12 API updates
267 The default algorithms for pkcs12 creation with the PKCS12_create()
269 function were changed to more modern PBKDF2 and AES based algorithms.
270 The default MAC iteration count was changed to PKCS12_DEFAULT_ITER to
271 make it equal with the password-based encryption iteration count. The
272 default digest algorithm for the MAC computation was changed to
273 SHA-256. The pkcs12 application now supports -legacy option that
274 restores the previous default algorithms to support interoperability
275 with legacy systems.
276 Added enhanced PKCS#12 APIs which accept a library context OSSL_LIB_CTX
278 and (where relevant) a property query. Other APIs which handle PKCS#7
279 and PKCS#8 objects have also been enhanced where required. This
280 includes:
281 PKCS12_add_key_ex(3), PKCS12_add_safe_ex(3), PKCS12_add_safes_ex(3),
283 PKCS12_create_ex(3), PKCS12_decrypt_skey_ex(3), PKCS12_init_ex(3),
284 PKCS12_item_decrypt_d2i_ex(3), PKCS12_item_i2d_encrypt_ex(3),
285 PKCS12_key_gen_asc_ex(3), PKCS12_key_gen_uni_ex(3),
286 PKCS12_key_gen_utf8_ex(3), PKCS12_pack_p7encdata_ex(3),
287 PKCS12_pbe_crypt_ex(3), PKCS12_PBE_keyivgen_ex(3),
288 PKCS12_SAFEBAG_create_pkcs8_encrypt_ex(3), PKCS5_pbe2_set_iv_ex(3),
289 PKCS5_pbe_set0_algor_ex(3), PKCS5_pbe_set_ex(3),
290 PKCS5_pbkdf2_set_ex(3), PKCS5_v2_PBE_keyivgen_ex(3),
291 PKCS5_v2_scrypt_keyivgen_ex(3), PKCS8_decrypt_ex(3),
292 PKCS8_encrypt_ex(3), PKCS8_set0_pbe_ex(3).
293 As part of this change the EVP_PBE_xxx APIs can also accept a library
295 context and property query and will call an extended version of the
296 key/IV derivation function which supports these parameters. This
297 includes EVP_PBE_CipherInit_ex(3), EVP_PBE_find_ex(3) and
298 EVP_PBE_scrypt_ex(3).
299 Windows thread synchronization changes
301 Windows thread synchronization uses read/write primitives (SRWLock)
303 when supported by the OS, otherwise CriticalSection continues to be
304 used.
305 Trace API
307 A new generic trace API has been added which provides support for
309 enabling instrumentation through trace output. This feature is mainly
310 intended as an aid for developers and is disabled by default. To
311 utilize it, OpenSSL needs to be configured with the "enable-trace"
312 option.
313 If the tracing API is enabled, the application can activate trace
315 output by registering BIOs as trace channels for a number of tracing
316 and debugging categories. See OSSL_trace_enabled(3).
317 Key validation updates
319 EVP_PKEY_public_check(3) and EVP_PKEY_param_check(3) now work for more
321 key types. This includes RSA, DSA, ED25519, X25519, ED448 and X448.
322 Previously (in 1.1.1) they would return -2. For key types that do not
323 have parameters then EVP_PKEY_param_check(3) will always return 1.
324 Other notable deprecations and changes
326 The function code part of an OpenSSL error code is no longer relevant
328 This code is now always set to zero. Related functions are deprecated.
330 STACK and HASH macros have been cleaned up
332 The type-safe wrappers are declared everywhere and implemented once.
334 See DEFINE_STACK_OF(3) and DECLARE_LHASH_OF(3).
335 The RAND_DRBG subsystem has been removed
337 The new EVP_RAND(3) is a partial replacement: the DRBG callback
339 framework is absent. The RAND_DRBG API did not fit well into the new
340 provider concept as implemented by EVP_RAND and EVP_RAND_CTX.
341 Removed FIPS_mode() and FIPS_mode_set()
343 These functions are legacy APIs that are not applicable to the new
345 provider model. Applications should instead use
346 EVP_default_properties_is_fips_enabled(3) and
347 EVP_default_properties_enable_fips(3).
348 Key generation is slower
350 The Miller-Rabin test now uses 64 rounds, which is used for all prime
352 generation, including RSA key generation. This affects the time for
353 larger keys sizes.
354 The default key generation method for the regular 2-prime RSA keys was
356 changed to the FIPS186-4 B.3.6 method (Generation of Probable Primes
357 with Conditions Based on Auxiliary Probable Primes). This method is
358 slower than the original method.
359 Change PBKDF2 to conform to SP800-132 instead of the older PKCS5
361 RFC2898
362 This checks that the salt length is at least 128 bits, the derived key
364 length is at least 112 bits, and that the iteration count is at least
365 1000. For backwards compatibility these checks are disabled by default
366 in the default provider, but are enabled by default in the FIPS
367 provider.
368 To enable or disable the checks see OSSL_KDF_PARAM_PKCS5 in
370 EVP_KDF-PBKDF2(7). The parameter can be set using EVP_KDF_derive(3).
371 Enforce a minimum DH modulus size of 512 bits
373 Smaller sizes now result in an error.
375 SM2 key changes
377 EC EVP_PKEYs with the SM2 curve have been reworked to automatically
379 become EVP_PKEY_SM2 rather than EVP_PKEY_EC.
380 Unlike in previous OpenSSL versions, this means that applications
382 cannot call "EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2)" to get SM2
383 computations.
384 Parameter and key generation is also reworked to make it possible to
386 generate EVP_PKEY_SM2 parameters and keys. Applications must now
387 generate SM2 keys directly and must not create an EVP_PKEY_EC key
388 first. It is no longer possible to import an SM2 key with domain
389 parameters other than the SM2 elliptic curve ones.
390 Validation of SM2 keys has been separated from the validation of
392 regular EC keys, allowing to improve the SM2 validation process to
393 reject loaded private keys that are not conforming to the SM2 ISO
394 standard. In particular, a private scalar k outside the range 1 <= k <
395 n-1 is now correctly rejected.
396 EVP_PKEY_set_alias_type() method has been removed
398 This function made a EVP_PKEY object mutable after it had been set up.
400 In OpenSSL 3.0 it was decided that a provided key should not be able to
401 change its type, so this function has been removed.
402 Functions that return an internal key should be treated as read only
404 Functions such as EVP_PKEY_get0_RSA(3) behave slightly differently in
406 OpenSSL 3.0. Previously they returned a pointer to the low-level key
407 used internally by libcrypto. From OpenSSL 3.0 this key may now be held
408 in a provider. Calling these functions will only return a handle on the
409 internal key where the EVP_PKEY was constructed using this key in the
410 first place, for example using a function or macro such as
411 EVP_PKEY_assign_RSA(3), EVP_PKEY_set1_RSA(3), etc. Where the EVP_PKEY
412 holds a provider managed key, then these functions now return a cached
413 copy of the key. Changes to the internal provider key that take place
414 after the first time the cached key is accessed will not be reflected
415 back in the cached copy. Similarly any changes made to the cached copy
416 by application code will not be reflected back in the internal provider
417 key.
418 For the above reasons the keys returned from these functions should
420 typically be treated as read-only. To emphasise this the value returned
421 from EVP_PKEY_get0_RSA(3), EVP_PKEY_get0_DSA(3),
422 EVP_PKEY_get0_EC_KEY(3) and EVP_PKEY_get0_DH(3) have been made const.
423 This may break some existing code. Applications broken by this change
424 should be modified. The preferred solution is to refactor the code to
425 avoid the use of these deprecated functions. Failing this the code
426 should be modified to use a const pointer instead. The
427 EVP_PKEY_get1_RSA(3), EVP_PKEY_get1_DSA(3), EVP_PKEY_get1_EC_KEY(3) and
428 EVP_PKEY_get1_DH(3) functions continue to return a non-const pointer to
429 enable them to be "freed". However they should also be treated as read-
430 only.
431 The public key check has moved from EVP_PKEY_derive() to
433 EVP_PKEY_derive_set_peer()
434 This may mean result in an error in EVP_PKEY_derive_set_peer(3) rather
436 than during EVP_PKEY_derive(3). To disable this check use
437 EVP_PKEY_derive_set_peer_ex(dh, peer, 0).
438 The print format has cosmetic changes for some functions
440 The output from numerous "printing" functions such as
442 X509_signature_print(3), X509_print_ex(3), X509_CRL_print_ex(3), and
443 other similar functions has been amended such that there may be
444 cosmetic differences between the output observed in 1.1.1 and 3.0. This
445 also applies to the -text output from the openssl x509 and openssl crl
446 applications.
447 Interactive mode from the openssl program has been removed
449 From now on, running it without arguments is equivalent to openssl
451 help.
452 The error return values from some control calls (ctrl) have changed
454 One significant change is that controls which used to return -2 for
456 invalid inputs, now return -1 indicating a generic error condition
457 instead.
458 DH and DHX key types have different settable parameters
460 Previously (in 1.1.1) these conflicting parameters were allowed, but
462 will now result in errors. See EVP_PKEY-DH(7) for further details. This
463 affects the behaviour of openssl-genpkey(1) for DH parameter
464 generation.
465 EVP_CIPHER_CTX_set_flags() ordering change
467 If using a cipher from a provider the EVP_CIPH_FLAG_LENGTH_BITS flag
469 can only be set after the cipher has been assigned to the cipher
470 context. See "FLAGS" in EVP_EncryptInit(3) for more information.
471 Validation of operation context parameters
473 Due to move of the implementation of cryptographic operations to the
475 providers, validation of various operation parameters can be postponed
476 until the actual operation is executed where previously it happened
477 immediately when an operation parameter was set.
478 For example when setting an unsupported curve with
480 EVP_PKEY_CTX_set_ec_paramgen_curve_nid() this function call will not
481 fail but later keygen operations with the EVP_PKEY_CTX will fail.
482 Removal of function code from the error codes
484 The function code part of the error code is now always set to 0. For
486 that reason the ERR_GET_FUNC() macro was removed. Applications must
487 resolve the error codes only using the library number and the reason
488 code.
489 ChaCha20-Poly1305 cipher does not allow a truncated IV length to be
491 used
492 In OpenSSL 3.0 setting the IV length to any value other than 12 will
494 result in an error. Prior to OpenSSL 3.0 the ivlen could be smaller
495 that the required 12 byte length, using EVP_CIPHER_CTX_ctrl(ctx,
496 EVP_CRTL_AEAD_SET_IVLEN, ivlen, NULL). This resulted in an IV that had
497 leading zero padding.
498 Installation and Compilation
500 Please refer to the INSTALL.md file in the top of the distribution for
501 instructions on how to build and install OpenSSL 3.0. Please also refer
502 to the various platform specific NOTES files for your specific
503 platform.
504 Upgrading from OpenSSL 1.1.1
506 Upgrading to OpenSSL 3.0 from OpenSSL 1.1.1 should be relatively
507 straight forward in most cases. The most likely area where you will
508 encounter problems is if you have used low level APIs in your code (as
509 discussed above). In that case you are likely to start seeing
510 deprecation warnings when compiling your application. If this happens
511 you have 3 options:
512 1. Ignore the warnings. They are just warnings. The deprecated
514 functions are still present and you may still use them. However be
515 aware that they may be removed from a future version of OpenSSL.
516 2. Suppress the warnings. Refer to your compiler documentation on how
518 to do this.
519 3. Remove your usage of the low level APIs. In this case you will need
521 to rewrite your code to use the high level APIs instead
522 Error code changes
524 As OpenSSL 3.0 provides a brand new Encoder/Decoder mechanism for
526 working with widely used file formats, application code that checks for
527 particular error reason codes on key loading failures might need an
528 update.
529 Password-protected keys may deserve special attention. If only some
531 errors are treated as an indicator that the user should be asked about
532 the password again, it's worth testing these scenarios and processing
533 the newly relevant codes.
534 There may be more cases to treat specially, depending on the calling
536 application code.
537 Upgrading from OpenSSL 1.0.2
539 Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 is likely to be
540 significantly more difficult. In addition to the issues discussed above
541 in the section about "Upgrading from OpenSSL 1.1.1", the main things to
542 be aware of are:
543 1. The build and installation procedure has changed significantly.
545 Check the file INSTALL.md in the top of the installation for
547 instructions on how to build and install OpenSSL for your platform.
548 Also read the various NOTES files in the same directory, as
549 applicable for your platform.
550 2. Many structures have been made opaque in OpenSSL 3.0.
552 The structure definitions have been removed from the public header
554 files and moved to internal header files. In practice this means
555 that you can no longer stack allocate some structures. Instead they
556 must be heap allocated through some function call (typically those
557 function names have a "_new" suffix to them). Additionally you
558 must use "setter" or "getter" functions to access the fields within
559 those structures.
560 For example code that previously looked like this:
562 EVP_MD_CTX md_ctx;
564 /* This line will now generate compiler errors */
566 EVP_MD_CTX_init(&md_ctx);
567 The code needs to be amended to look like this:
569 EVP_MD_CTX *md_ctx;
571 md_ctx = EVP_MD_CTX_new();
573 ...
574 ...
575 EVP_MD_CTX_free(md_ctx);
576 3. Support for TLSv1.3 has been added.
578 This has a number of implications for SSL/TLS applications. See the
580 TLS1.3 page <https://wiki.openssl.org/index.php/TLS1.3> for further
581 details.
582 More details about the breaking changes between OpenSSL versions 1.0.2
584 and 1.1.0 can be found on the OpenSSL 1.1.0 Changes page
585 <https://wiki.openssl.org/index.php/OpenSSL_1.1.0_Changes>.
586 Upgrading from the OpenSSL 2.0 FIPS Object Module
588 The OpenSSL 2.0 FIPS Object Module was a separate download that had to
590 be built separately and then integrated into your main OpenSSL 1.0.2
591 build. In OpenSSL 3.0 the FIPS support is fully integrated into the
592 mainline version of OpenSSL and is no longer a separate download. For
593 further information see "Completing the installation of the FIPS
594 Module".
595 The function calls FIPS_mode() and FIPS_mode_set() have been removed
597 from OpenSSL 3.0. You should rewrite your application to not use them.
598 See fips_module(7) and OSSL_PROVIDER-FIPS(7) for details.
599 Completing the installation of the FIPS Module
601 The FIPS Module will be built and installed automatically if FIPS
602 support has been configured. The current documentation can be found in
603 the README-FIPS <https://github.com/openssl/openssl/blob/master/README-
604 FIPS.md> file.
605 Programming
607 Applications written to work with OpenSSL 1.1.1 will mostly just work
608 with OpenSSL 3.0. However changes will be required if you want to take
609 advantage of some of the new features that OpenSSL 3.0 makes available.
610 In order to do that you need to understand some new concepts introduced
611 in OpenSSL 3.0. Read "Library contexts" in crypto(7) for further
612 information.
613 Library Context
615 A library context allows different components of a complex application
617 to each use a different library context and have different providers
618 loaded with different configuration settings. See "Library contexts"
619 in crypto(7) for further info.
620 If the user creates an OSSL_LIB_CTX via OSSL_LIB_CTX_new(3) then many
622 functions may need to be changed to pass additional parameters to
623 handle the library context.
624 Using a Library Context - Old functions that should be changed
626 If a library context is needed then all EVP_* digest functions that
628 return a const EVP_MD * such as EVP_sha256() should be replaced with a
629 call to EVP_MD_fetch(3). See "ALGORITHM FETCHING" in crypto(7).
630 If a library context is needed then all EVP_* cipher functions that
632 return a const EVP_CIPHER * such as EVP_aes_128_cbc() should be
633 replaced vith a call to EVP_CIPHER_fetch(3). See "ALGORITHM FETCHING"
634 in crypto(7).
635 Some functions can be passed an object that has already been set up
637 with a library context such as d2i_X509(3), d2i_X509_CRL(3),
638 d2i_X509_REQ(3) and d2i_X509_PUBKEY(3). If NULL is passed instead then
639 the created object will be set up with the default library context. Use
640 X509_new_ex(3), X509_CRL_new_ex(3), X509_REQ_new_ex(3) and
641 X509_PUBKEY_new_ex(3) if a library context is required.
642 All functions listed below with a NAME have a replacment function
644 NAME_ex that takes OSSL_LIB_CTX as an additional argument. Functions
645 that have other mappings are listed along with the respective name.
646 • ASN1_item_new(3), ASN1_item_d2i(3), ASN1_item_d2i_fp(3),
648 ASN1_item_d2i_bio(3), ASN1_item_sign(3) and ASN1_item_verify(3)
649 • BIO_new(3)
651 • b2i_RSA_PVK_bio() and i2b_PVK_bio()
653 • BN_CTX_new(3) and BN_CTX_secure_new(3)
655 • CMS_AuthEnvelopedData_create(3), CMS_ContentInfo_new(3),
657 CMS_data_create(3), CMS_digest_create(3),
658 CMS_EncryptedData_encrypt(3), CMS_encrypt(3),
659 CMS_EnvelopedData_create(3), CMS_ReceiptRequest_create0(3) and
660 CMS_sign(3)
661 • CONF_modules_load_file(3)
663 • CTLOG_new(3), CTLOG_new_from_base64(3) and CTLOG_STORE_new(3)
665 • CT_POLICY_EVAL_CTX_new(3)
667 • d2i_AutoPrivateKey(3), d2i_PrivateKey(3) and d2i_PUBKEY(3)
669 • d2i_PrivateKey_bio(3) and d2i_PrivateKey_fp(3)
671 Use d2i_PrivateKey_ex_bio(3) and d2i_PrivateKey_ex_fp(3)
673 • EC_GROUP_new(3)
675 Use EC_GROUP_new_by_curve_name_ex(3) or
677 EC_GROUP_new_from_params(3).
678 • EVP_DigestSignInit(3) and EVP_DigestVerifyInit(3)
680 • EVP_PBE_CipherInit(3), EVP_PBE_find(3) and EVP_PBE_scrypt(3)
682 • PKCS5_PBE_keyivgen(3)
684 • EVP_PKCS82PKEY(3)
686 • EVP_PKEY_CTX_new_id(3)
688 Use EVP_PKEY_CTX_new_from_name(3)
690 • EVP_PKEY_derive_set_peer(3), EVP_PKEY_new_raw_private_key(3) and
692 EVP_PKEY_new_raw_public_key(3)
693 • EVP_SignFinal(3) and EVP_VerifyFinal(3)
695 • NCONF_new(3)
697 • OCSP_RESPID_match(3) and OCSP_RESPID_set_by_key(3)
699 • OPENSSL_thread_stop(3)
701 • OSSL_STORE_open(3)
703 • PEM_read_bio_Parameters(3), PEM_read_bio_PrivateKey(3),
705 PEM_read_bio_PUBKEY(3), PEM_read_PrivateKey(3) and
706 PEM_read_PUBKEY(3)
707 • PEM_write_bio_PrivateKey(3), PEM_write_bio_PUBKEY(3),
709 PEM_write_PrivateKey(3) and PEM_write_PUBKEY(3)
710 • PEM_X509_INFO_read_bio(3) and PEM_X509_INFO_read(3)
712 • PKCS12_add_key(3), PKCS12_add_safe(3), PKCS12_add_safes(3),
714 PKCS12_create(3), PKCS12_decrypt_skey(3), PKCS12_init(3),
715 PKCS12_item_decrypt_d2i(3), PKCS12_item_i2d_encrypt(3),
716 PKCS12_key_gen_asc(3), PKCS12_key_gen_uni(3),
717 PKCS12_key_gen_utf8(3), PKCS12_pack_p7encdata(3),
718 PKCS12_pbe_crypt(3), PKCS12_PBE_keyivgen(3),
719 PKCS12_SAFEBAG_create_pkcs8_encrypt(3)
720 • PKCS5_pbe_set0_algor(3), PKCS5_pbe_set(3), PKCS5_pbe2_set_iv(3),
722 PKCS5_pbkdf2_set(3) and PKCS5_v2_scrypt_keyivgen(3)
723 • PKCS7_encrypt(3), PKCS7_new(3) and PKCS7_sign(3)
725 • PKCS8_decrypt(3), PKCS8_encrypt(3) and PKCS8_set0_pbe(3)
727 • RAND_bytes(3) and RAND_priv_bytes(3)
729 • SMIME_write_ASN1(3)
731 • SSL_load_client_CA_file(3)
733 • SSL_CTX_new(3)
735 • TS_RESP_CTX_new(3)
737 • X509_CRL_new(3)
739 • X509_load_cert_crl_file(3) and X509_load_cert_file(3)
741 • X509_LOOKUP_by_subject(3) and X509_LOOKUP_ctrl(3)
743 • X509_NAME_hash(3)
745 • X509_new(3)
747 • X509_REQ_new(3) and X509_REQ_verify(3)
749 • X509_STORE_CTX_new(3), X509_STORE_set_default_paths(3),
751 X509_STORE_load_file(3), X509_STORE_load_locations(3) and
752 X509_STORE_load_store(3)
753 New functions that use a Library context
755 The following functions can be passed a library context if required.
757 Passing NULL will use the default library context.
758 • BIO_new_from_core_bio(3)
760 • EVP_ASYM_CIPHER_fetch(3) and EVP_ASYM_CIPHER_do_all_provided(3)
762 • EVP_CIPHER_fetch(3) and EVP_CIPHER_do_all_provided(3)
764 • EVP_default_properties_enable_fips(3) and
766 EVP_default_properties_is_fips_enabled(3)
767 • EVP_KDF_fetch(3) and EVP_KDF_do_all_provided(3)
769 • EVP_KEM_fetch(3) and EVP_KEM_do_all_provided(3)
771 • EVP_KEYEXCH_fetch(3) and EVP_KEYEXCH_do_all_provided(3)
773 • EVP_KEYMGMT_fetch(3) and EVP_KEYMGMT_do_all_provided(3)
775 • EVP_MAC_fetch(3) and EVP_MAC_do_all_provided(3)
777 • EVP_MD_fetch(3) and EVP_MD_do_all_provided(3)
779 • EVP_PKEY_CTX_new_from_pkey(3)
781 • EVP_PKEY_Q_keygen(3)
783 • EVP_Q_mac(3) and EVP_Q_digest(3)
785 • EVP_RAND(3) and EVP_RAND_do_all_provided(3)
787 • EVP_set_default_properties(3)
789 • EVP_SIGNATURE_fetch(3) and EVP_SIGNATURE_do_all_provided(3)
791 • OSSL_CMP_CTX_new(3) and OSSL_CMP_SRV_CTX_new(3)
793 • OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert(3)
795 • OSSL_CRMF_MSG_create_popo(3) and OSSL_CRMF_MSGS_verify_popo(3)
797 • OSSL_CRMF_pbm_new(3) and OSSL_CRMF_pbmp_new(3)
799 • OSSL_DECODER_CTX_add_extra(3) and OSSL_DECODER_CTX_new_for_pkey(3)
801 • OSSL_DECODER_fetch(3) and OSSL_DECODER_do_all_provided(3)
803 • OSSL_ENCODER_CTX_add_extra(3)
805 • OSSL_ENCODER_fetch(3) and OSSL_ENCODER_do_all_provided(3)
807 • OSSL_LIB_CTX_free(3), OSSL_LIB_CTX_load_config(3) and
809 OSSL_LIB_CTX_set0_default(3)
810 • OSSL_PROVIDER_add_builtin(3), OSSL_PROVIDER_available(3),
812 OSSL_PROVIDER_do_all(3), OSSL_PROVIDER_load(3),
813 OSSL_PROVIDER_set_default_search_path(3) and
814 OSSL_PROVIDER_try_load(3)
815 • OSSL_SELF_TEST_get_callback(3) and OSSL_SELF_TEST_set_callback(3)
817 • OSSL_STORE_attach(3)
819 • OSSL_STORE_LOADER_fetch(3) and OSSL_STORE_LOADER_do_all_provided(3)
821 • RAND_get0_primary(3), RAND_get0_private(3), RAND_get0_public(3),
823 RAND_set_DRBG_type(3) and RAND_set_seed_source_type(3)
824 Providers
826 Providers are described in detail here "Providers" in crypto(7). See
828 also "OPENSSL PROVIDERS" in crypto(7).
829 Fetching algorithms and property queries
831 Implicit and Explicit Fetching is described in detail here "ALGORITHM
833 FETCHING" in crypto(7).
834 Mapping EVP controls and flags to provider OSSL_PARAM(3) parameters
836 The existing functions for controls (such as EVP_CIPHER_CTX_ctrl(3))
838 and manipulating flags (such as EVP_MD_CTX_set_flags(3))internally use
839 OSSL_PARAMS to pass information to/from provider objects. See
840 OSSL_PARAM(3) for additional information related to parameters.
841 For ciphers see "CONTROLS" in EVP_EncryptInit(3), "FLAGS" in
843 EVP_EncryptInit(3) and "PARAMETERS" in EVP_EncryptInit(3).
844 For digests see "CONTROLS" in EVP_DigestInit(3), "FLAGS" in
846 EVP_DigestInit(3) and "PARAMETERS" in EVP_DigestInit(3).
847 Deprecation of Low Level Functions
849 A significant number of APIs have been deprecated in OpenSSL 3.0. This
851 section describes some common categories of deprecations. See
852 "Deprecated function mappings" for the list of deprecated functions
853 that refer to these categories.
854 Providers are a replacement for engines and low-level method overrides
856 Any accessor that uses an ENGINE is deprecated (such as
858 EVP_PKEY_set1_engine()). Applications using engines should instead use
859 providers.
860 Before providers were added algorithms were overriden by changing the
862 methods used by algorithms. All these methods such as RSA_new_method()
863 and RSA_meth_new() are now deprecated and can be replaced by using
864 providers instead.
865 Deprecated i2d and d2i functions for low-level key types
867 Any i2d and d2i functions such as d2i_DHparams() that take a low-level
869 key type have been deprecated. Applications should instead use the
870 OSSL_DECODER(3) and OSSL_ENCODER(3) APIs to read and write files. See
871 "Migration" in d2i_RSAPrivateKey(3) for further details.
872 Deprecated low-level key object getters and setters
874 Applications that set or get low-level key objects (such as
876 EVP_PKEY_set1_DH() or EVP_PKEY_get0()) should instead use the
877 OSSL_ENCODER (See OSSL_ENCODER_to_bio(3)) or OSSL_DECODER (See
878 OSSL_DECODER_from_bio(3)) APIs, or alternatively use
879 EVP_PKEY_fromdata(3) or EVP_PKEY_todata(3).
880 Deprecated low-level key parameter getters
882 Functions that access low-level objects directly such as RSA_get0_n(3)
884 are now deprecated. Applications should use one of
885 EVP_PKEY_get_bn_param(3), EVP_PKEY_get_int_param(3),
886 l<EVP_PKEY_get_size_t_param(3)>, EVP_PKEY_get_utf8_string_param(3),
887 EVP_PKEY_get_octet_string_param(3) or EVP_PKEY_get_params(3) to access
888 fields from an EVP_PKEY. Gettable parameters are listed in "Common RSA
889 parameters" in EVP_PKEY-RSA(7), "DH parameters" in EVP_PKEY-DH(7), "DSA
890 parameters" in EVP_PKEY-DSA(7), "FFC parameters" in EVP_PKEY-FFC(7),
891 "Common EC parameters" in EVP_PKEY-EC(7) and "Common X25519, X448,
892 ED25519 and ED448 parameters" in EVP_PKEY-X25519(7). Applications may
893 also use EVP_PKEY_todata(3) to return all fields.
894 Deprecated low-level key parameter setters
896 Functions that access low-level objects directly such as
898 RSA_set0_crt_params(3) are now deprecated. Applications should use
899 EVP_PKEY_fromdata(3) to create new keys from user provided key data.
900 Keys should be immutable once they are created, so if required the user
901 may use EVP_PKEY_todata(3), OSSL_PARAM_merge(3), and
902 EVP_PKEY_fromdata(3) to create a modified key. See "Examples" in
903 EVP_PKEY-DH(7) for more information. See "Deprecated low-level key
904 generation functions" for information on generating a key using
905 parameters.
906 Deprecated low-level object creation
908 Low-level objects were created using methods such as RSA_new(3),
910 RSA_up_ref(3) and RSA_free(3). Applications should instead use the
911 high-level EVP_PKEY APIs, e.g. EVP_PKEY_new(3), EVP_PKEY_up_ref(3) and
912 EVP_PKEY_free(3). See also EVP_PKEY_CTX_new_from_name(3) and
913 EVP_PKEY_CTX_new_from_pkey(3).
914 EVP_PKEYs may be created in a variety of ways: See also "Deprecated
916 low-level key generation functions", "Deprecated low-level key reading
917 and writing functions" and "Deprecated low-level key parameter
918 setters".
919 Deprecated low-level encryption functions
921 Low-level encryption functions such as AES_encrypt(3) and
923 AES_decrypt(3) have been informally discouraged from use for a long
924 time. Applications should instead use the high level EVP APIs
925 EVP_EncryptInit_ex(3), EVP_EncryptUpdate(3), and EVP_EncryptFinal_ex(3)
926 or EVP_DecryptInit_ex(3), EVP_DecryptUpdate(3) and
927 EVP_DecryptFinal_ex(3).
928 Deprecated low-level digest functions
930 Use of low-level digest functions such as SHA1_Init(3) have been
932 informally discouraged from use for a long time. Applications should
933 instead use the the high level EVP APIs EVP_DigestInit_ex(3),
934 EVP_DigestUpdate(3) and EVP_DigestFinal_ex(3), or the quick one-shot
935 EVP_Q_digest(3).
936 Note that the functions SHA1(3), SHA224(3), SHA256(3), SHA384(3) and
938 SHA512(3) have changed to macros that use EVP_Q_digest(3).
939 Deprecated low-level signing functions
941 Use of low-level signing functions such as DSA_sign(3) have been
943 informally discouraged for a long time. Instead applications should use
944 EVP_DigestSign(3) and EVP_DigestVerify(3). See also
945 EVP_SIGNATURE-RSA(7), EVP_SIGNATURE-DSA(7), EVP_SIGNATURE-ECDSA(7) and
946 EVP_SIGNATURE-ED25519(7).
947 Deprecated low-level MAC functions
949 Low-level mac functions such as CMAC_Init(3) are deprecated.
951 Applications should instead use the new EVP_MAC(3) interface, using
952 EVP_MAC_CTX_new(3), EVP_MAC_CTX_free(3), EVP_MAC_init(3),
953 EVP_MAC_update(3) and EVP_MAC_final(3) or the single-shot MAC function
954 EVP_Q_mac(3). See EVP_MAC(3), EVP_MAC-HMAC(7), EVP_MAC-CMAC(7),
955 EVP_MAC-GMAC(7), EVP_MAC-KMAC(7), EVP_MAC-BLAKE2(7),
956 EVP_MAC-Poly1305(7) and EVP_MAC-Siphash(7) for additional information.
957 Note that the one-shot method HMAC() is still available for
959 compatibility purposes, but this can also be replaced by using
960 EVP_Q_MAC if a library context is required.
961 Deprecated low-level validation functions
963 Low-level validation functions such as DH_check(3) have been informally
965 discouraged from use for a long time. Applications should instead use
966 the high-level EVP_PKEY APIs such as EVP_PKEY_check(3),
967 EVP_PKEY_param_check(3), EVP_PKEY_param_check_quick(3),
968 EVP_PKEY_public_check(3), EVP_PKEY_public_check_quick(3),
969 EVP_PKEY_private_check(3), and EVP_PKEY_pairwise_check(3).
970 Deprecated low-level key exchange functions
972 Many low-level functions have been informally discouraged from use for
974 a long time. Applications should instead use EVP_PKEY_derive(3). See
975 EVP_KEYEXCH-DH(7), EVP_KEYEXCH-ECDH(7) and EVP_KEYEXCH-X25519(7).
976 Deprecated low-level key generation functions
978 Many low-level functions have been informally discouraged from use for
980 a long time. Applications should instead use EVP_PKEY_keygen_init(3)
981 and EVP_PKEY_generate(3) as described in EVP_PKEY-DSA(7),
982 EVP_PKEY-DH(7), EVP_PKEY-RSA(7), EVP_PKEY-EC(7) and EVP_PKEY-X25519(7).
983 The 'quick' one-shot function EVP_PKEY_Q_keygen(3) and macros for the
984 most common cases: <EVP_RSA_gen(3)> and EVP_EC_gen(3) may also be used.
985 Deprecated low-level key reading and writing functions
987 Use of low-level objects (such as DSA) has been informally discouraged
989 from use for a long time. Functions to read and write these low-level
990 objects (such as PEM_read_DSA_PUBKEY()) should be replaced.
991 Applications should instead use OSSL_ENCODER_to_bio(3) and
992 OSSL_DECODER_from_bio(3).
993 Deprecated low-level key printing functions
995 Use of low-level objects (such as DSA) has been informally discouraged
997 from use for a long time. Functions to print these low-level objects
998 such as DSA_print() should be replaced with the equivalent EVP_PKEY
999 functions. Application should use one of EVP_PKEY_print_public(3),
1000 EVP_PKEY_print_private(3), EVP_PKEY_print_params(3),
1001 EVP_PKEY_print_public_fp(3), EVP_PKEY_print_private_fp(3) or
1002 EVP_PKEY_print_params_fp(3). Note that internally these use
1003 OSSL_ENCODER_to_bio(3) and OSSL_DECODER_from_bio(3).
1004 Deprecated function mappings
1006 The following functions have been deprecated in 3.0.
1008 • AES_bi_ige_encrypt() and AES_ige_encrypt()
1010 There is no replacement for the IGE functions. New code should not
1012 use these modes. These undocumented functions were never
1013 integrated into the EVP layer. They implemented the AES Infinite
1014 Garble Extension (IGE) mode and AES Bi-directional IGE mode. These
1015 modes were never formally standardised and usage of these functions
1016 is believed to be very small. In particular AES_bi_ige_encrypt()
1017 has a known bug. It accepts 2 AES keys, but only one is ever used.
1018 The security implications are believed to be minimal, but this
1019 issue was never fixed for backwards compatibility reasons.
1020 • AES_encrypt(), AES_decrypt(), AES_set_encrypt_key(),
1022 AES_set_decrypt_key(), AES_cbc_encrypt(), AES_cfb128_encrypt(),
1023 AES_cfb1_encrypt(), AES_cfb8_encrypt(), AES_ecb_encrypt(),
1024 AES_ofb128_encrypt()
1025 • AES_unwrap_key(), AES_wrap_key()
1027 See "Deprecated low-level encryption functions"
1029 • AES_options()
1031 There is no replacement. It returned a string indicating if the AES
1033 code was unrolled.
1034 • ASN1_digest(), ASN1_sign(), ASN1_verify()
1036 There are no replacements. These old functions are not used, and
1038 could be disabled with the macro NO_ASN1_OLD since OpenSSL 0.9.7.
1039 • ASN1_STRING_length_set()
1041 Use ASN1_STRING_set(3) or ASN1_STRING_set0(3) instead. This was a
1043 potentially unsafe function that could change the bounds of a
1044 previously passed in pointer.
1045 • BF_encrypt(), BF_decrypt(), BF_set_key(), BF_cbc_encrypt(),
1047 BF_cfb64_encrypt(), BF_ecb_encrypt(), BF_ofb64_encrypt()
1048 See "Deprecated low-level encryption functions". The Blowfish
1050 algorithm has been moved to the Legacy Provider.
1051 • BF_options()
1053 There is no replacement. This option returned a constant string.
1055 • BIO_get_callback(), BIO_set_callback(), BIO_debug_callback()
1057 Use the respective non-deprecated _ex() functions.
1059 • BN_is_prime_ex(), BN_is_prime_fasttest_ex()
1061 Use BN_check_prime(3) which avoids possible misuse and always uses
1063 at least 64 rounds of the Miller-Rabin primality test.
1064 • BN_pseudo_rand(), BN_pseudo_rand_range()
1066 Use BN_rand(3) and BN_rand_range(3).
1068 • BN_X931_derive_prime_ex(), BN_X931_generate_prime_ex(),
1070 BN_X931_generate_Xpq()
1071 There are no replacements for these low-level functions. They were
1073 used internally by RSA_X931_derive_ex() and
1074 RSA_X931_generate_key_ex() which are also deprecated. Use
1075 EVP_PKEY_keygen(3) instead.
1076 • Camellia_encrypt(), Camellia_decrypt(), Camellia_set_key(),
1078 Camellia_cbc_encrypt(), Camellia_cfb128_encrypt(),
1079 Camellia_cfb1_encrypt(), Camellia_cfb8_encrypt(),
1080 Camellia_ctr128_encrypt(), Camellia_ecb_encrypt(),
1081 Camellia_ofb128_encrypt()
1082 See "Deprecated low-level encryption functions".
1084 • CAST_encrypt(), CAST_decrypt(), CAST_set_key(), CAST_cbc_encrypt(),
1086 CAST_cfb64_encrypt(), CAST_ecb_encrypt(), CAST_ofb64_encrypt()
1087 See "Deprecated low-level encryption functions". The CAST
1089 algorithm has been moved to the Legacy Provider.
1090 • CMAC_CTX_new(), CMAC_CTX_cleanup(), CMAC_CTX_copy(),
1092 CMAC_CTX_free(), CMAC_CTX_get0_cipher_ctx()
1093 See "Deprecated low-level MAC functions".
1095 • CMAC_Init(), CMAC_Update(), CMAC_Final(), CMAC_resume()
1097 See "Deprecated low-level MAC functions".
1099 • CRYPTO_mem_ctrl(), CRYPTO_mem_debug_free(),
1101 CRYPTO_mem_debug_malloc(), CRYPTO_mem_debug_pop(),
1102 CRYPTO_mem_debug_push(), CRYPTO_mem_debug_realloc(),
1103 CRYPTO_mem_leaks(), CRYPTO_mem_leaks_cb(), CRYPTO_mem_leaks_fp(),
1104 CRYPTO_set_mem_debug()
1105 Memory-leak checking has been deprecated in favor of more modern
1107 development tools, such as compiler memory and leak sanitizers or
1108 Valgrind.
1109 • CRYPTO_cts128_encrypt_block(), CRYPTO_cts128_encrypt(),
1111 CRYPTO_cts128_decrypt_block(), CRYPTO_cts128_decrypt(),
1112 CRYPTO_nistcts128_encrypt_block(), CRYPTO_nistcts128_encrypt(),
1113 CRYPTO_nistcts128_decrypt_block(), CRYPTO_nistcts128_decrypt()
1114 Use the higher level functions EVP_CipherInit_ex2(),
1116 EVP_CipherUpdate() and EVP_CipherFinal_ex() instead. See the
1117 "cts_mode" parameter in "Gettable and Settable EVP_CIPHER_CTX
1118 parameters" in EVP_EncryptInit(3). See "EXAMPLES" in
1119 EVP_EncryptInit(3) for a AES-256-CBC-CTS example.
1120 • d2i_DHparams(), d2i_DHxparams(), d2i_DSAparams(),
1122 d2i_DSAPrivateKey(), d2i_DSAPrivateKey_bio(),
1123 d2i_DSAPrivateKey_fp(), d2i_DSA_PUBKEY(), d2i_DSA_PUBKEY_bio(),
1124 d2i_DSA_PUBKEY_fp(), d2i_DSAPublicKey(), d2i_ECParameters(),
1125 d2i_ECPrivateKey(), d2i_ECPrivateKey_bio(), d2i_ECPrivateKey_fp(),
1126 d2i_EC_PUBKEY(), d2i_EC_PUBKEY_bio(), d2i_EC_PUBKEY_fp(),
1127 o2i_ECPublicKey(), d2i_RSAPrivateKey(), d2i_RSAPrivateKey_bio(),
1128 d2i_RSAPrivateKey_fp(), d2i_RSA_PUBKEY(), d2i_RSA_PUBKEY_bio(),
1129 d2i_RSA_PUBKEY_fp(), d2i_RSAPublicKey(), d2i_RSAPublicKey_bio(),
1130 d2i_RSAPublicKey_fp()
1131 See "Deprecated i2d and d2i functions for low-level key types"
1133 • DES_crypt(), DES_fcrypt(), DES_encrypt1(), DES_encrypt2(),
1135 DES_encrypt3(), DES_decrypt3(), DES_ede3_cbc_encrypt(),
1136 DES_ede3_cfb64_encrypt(),
1137 DES_ede3_cfb_encrypt(),DES_ede3_ofb64_encrypt(), DES_ecb_encrypt(),
1138 DES_ecb3_encrypt(), DES_ofb64_encrypt(), DES_ofb_encrypt(),
1139 DES_cfb64_encrypt DES_cfb_encrypt(), DES_cbc_encrypt(),
1140 DES_ncbc_encrypt(), DES_pcbc_encrypt(), DES_xcbc_encrypt(),
1141 DES_cbc_cksum(), DES_quad_cksum(), DES_check_key_parity(),
1142 DES_is_weak_key(), DES_key_sched(), DES_options(),
1143 DES_random_key(), DES_set_key(), DES_set_key_checked(),
1144 DES_set_key_unchecked(), DES_set_odd_parity(),
1145 DES_string_to_2keys(), DES_string_to_key()
1146 See "Deprecated low-level encryption functions". Algorithms for
1148 "DESX-CBC", "DES-ECB", "DES-CBC", "DES-OFB", "DES-CFB", "DES-CFB1"
1149 and "DES-CFB8" have been moved to the Legacy Provider.
1150 • DH_bits(), DH_security_bits(), DH_size()
1152 Use EVP_PKEY_get_bits(3), EVP_PKEY_get_security_bits(3) and
1154 EVP_PKEY_get_size(3).
1155 • DH_check(), DH_check_ex(), DH_check_params(), DH_check_params_ex(),
1157 DH_check_pub_key(), DH_check_pub_key_ex()
1158 See "Deprecated low-level validation functions"
1160 • DH_clear_flags(), DH_test_flags(), DH_set_flags()
1162 The DH_FLAG_CACHE_MONT_P flag has been deprecated without
1164 replacement. The DH_FLAG_TYPE_DH and DH_FLAG_TYPE_DHX have been
1165 deprecated. Use EVP_PKEY_is_a() to determine the type of a key.
1166 There is no replacement for setting these flags.
1167 • DH_compute_key() DH_compute_key_padded()
1169 See "Deprecated low-level key exchange functions".
1171 • DH_new(), DH_new_by_nid(), DH_free(), DH_up_ref()
1173 See "Deprecated low-level object creation"
1175 • DH_generate_key(), DH_generate_parameters_ex()
1177 See "Deprecated low-level key generation functions".
1179 • DH_get0_pqg(), DH_get0_p(), DH_get0_q(), DH_get0_g(),
1181 DH_get0_key(), DH_get0_priv_key(), DH_get0_pub_key(),
1182 DH_get_length(), DH_get_nid()
1183 See "Deprecated low-level key parameter getters"
1185 • DH_get_1024_160(), DH_get_2048_224(), DH_get_2048_256()
1187 Applications should instead set the OSSL_PKEY_PARAM_GROUP_NAME as
1189 specified in "DH parameters" in EVP_PKEY-DH(7)) to one of
1190 "dh_1024_160", "dh_2048_224" or "dh_2048_256" when generating a DH
1191 key.
1192 • DH_KDF_X9_42()
1194 Applications should use EVP_PKEY_CTX_set_dh_kdf_type(3) instead.
1196 • DH_get_default_method(), DH_get0_engine(), DH_meth_*(),
1198 DH_new_method(), DH_OpenSSL(), DH_get_ex_data(),
1199 DH_set_default_method(), DH_set_method(), DH_set_ex_data()
1200 See "Providers are a replacement for engines and low-level method
1202 overrides"
1203 • DHparams_print(), DHparams_print_fp()
1205 See "Deprecated low-level key printing functions"
1207 • DH_set0_key(), DH_set0_pqg(), DH_set_length()
1209 See "Deprecated low-level key parameter setters"
1211 • DSA_bits(), DSA_security_bits(), DSA_size()
1213 Use EVP_PKEY_get_bits(3), EVP_PKEY_get_security_bits(3) and
1215 EVP_PKEY_get_size(3).
1216 • DHparams_dup(), DSA_dup_DH()
1218 There is no direct replacement. Applications may use
1220 EVP_PKEY_copy_parameters(3) and EVP_PKEY_dup(3) instead.
1221 • DSA_generate_key(), DSA_generate_parameters_ex()
1223 See "Deprecated low-level key generation functions".
1225 • DSA_get0_engine(), DSA_get_default_method(), DSA_get_ex_data(),
1227 DSA_get_method(), DSA_meth_*(), DSA_new_method(), DSA_OpenSSL(),
1228 DSA_set_default_method(), DSA_set_ex_data(), DSA_set_method()
1229 See "Providers are a replacement for engines and low-level method
1231 overrides".
1232 • DSA_get0_p(), DSA_get0_q(), DSA_get0_g(), DSA_get0_pqg(),
1234 DSA_get0_key(), DSA_get0_priv_key(), DSA_get0_pub_key()
1235 See "Deprecated low-level key parameter getters".
1237 • DSA_new(), DSA_free(), DSA_up_ref()
1239 See "Deprecated low-level object creation"
1241 • DSAparams_dup()
1243 There is no direct replacement. Applications may use
1245 EVP_PKEY_copy_parameters(3) and EVP_PKEY_dup(3) instead.
1246 • DSAparams_print(), DSAparams_print_fp(), DSA_print(),
1248 DSA_print_fp()
1249 See "Deprecated low-level key printing functions"
1251 • DSA_set0_key(), DSA_set0_pqg()
1253 See "Deprecated low-level key parameter setters"
1255 • DSA_set_flags(), DSA_clear_flags(), DSA_test_flags()
1257 The DSA_FLAG_CACHE_MONT_P flag has been deprecated without
1259 replacement.
1260 • DSA_sign(), DSA_do_sign(), DSA_sign_setup(), DSA_verify(),
1262 DSA_do_verify()
1263 See "Deprecated low-level signing functions".
1265 • ECDH_compute_key()
1267 See "Deprecated low-level key exchange functions".
1269 • ECDH_KDF_X9_62()
1271 Applications may either set this using the helper function
1273 EVP_PKEY_CTX_set_ecdh_kdf_type(3) or by setting an OSSL_PARAM(3)
1274 using the "kdf-type" as shown in "EXAMPLES" in EVP_KEYEXCH-ECDH(7)
1275 • ECDSA_sign(), ECDSA_sign_ex(), ECDSA_sign_setup(), ECDSA_do_sign(),
1277 ECDSA_do_sign_ex(), ECDSA_verify(), ECDSA_do_verify()
1278 See "Deprecated low-level signing functions".
1280 • ECDSA_size()
1282 Applications should use EVP_PKEY_get_size(3).
1284 • EC_GF2m_simple_method(), EC_GFp_mont_method(),
1286 EC_GFp_nist_method(), EC_GFp_nistp224_method(),
1287 EC_GFp_nistp256_method(), EC_GFp_nistp521_method(),
1288 EC_GFp_simple_method()
1289 There are no replacements for these functions. Applications should
1291 rely on the library automatically assigning a suitable method
1292 internally when an EC_GROUP is constructed.
1293 • EC_GROUP_clear_free()
1295 Use EC_GROUP_free(3) instead.
1297 • EC_GROUP_get_curve_GF2m(), EC_GROUP_get_curve_GFp(),
1299 EC_GROUP_set_curve_GF2m(), EC_GROUP_set_curve_GFp()
1300 Applications should use EC_GROUP_get_curve(3) and
1302 EC_GROUP_set_curve(3).
1303 • EC_GROUP_have_precompute_mult(), EC_GROUP_precompute_mult(),
1305 EC_KEY_precompute_mult()
1306 These functions are not widely used. Applications should instead
1308 switch to named curves which OpenSSL has hardcoded lookup tables
1309 for.
1310 • EC_GROUP_new(), EC_GROUP_method_of(), EC_POINT_method_of()
1312 EC_METHOD is now an internal-only concept and a suitable EC_METHOD
1314 is assigned internally without application intervention. Users of
1315 EC_GROUP_new() should switch to a different suitable constructor.
1316 • EC_KEY_can_sign()
1318 Applications should use EVP_PKEY_can_sign(3) instead.
1320 • EC_KEY_check_key()
1322 See "Deprecated low-level validation functions"
1324 • EC_KEY_set_flags(), EC_KEY_get_flags(), EC_KEY_clear_flags()
1326 See "Common EC parameters" in EVP_PKEY-EC(7) which handles flags as
1328 seperate parameters for OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT,
1329 OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE, OSSL_PKEY_PARAM_EC_ENCODING,
1330 OSSL_PKEY_PARAM_USE_COFACTOR_ECDH and
1331 OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC. See also "EXAMPLES" in
1332 EVP_PKEY-EC(7)
1333 • EC_KEY_dup(), EC_KEY_copy()
1335 There is no direct replacement. Applications may use
1337 EVP_PKEY_copy_parameters(3) and EVP_PKEY_dup(3) instead.
1338 • EC_KEY_decoded_from_explicit_params()
1340 There is no replacement.
1342 • EC_KEY_generate_key()
1344 See "Deprecated low-level key generation functions".
1346 • EC_KEY_get0_group(), EC_KEY_get0_private_key(),
1348 EC_KEY_get0_public_key(), EC_KEY_get_conv_form(),
1349 EC_KEY_get_enc_flags()
1350 See "Deprecated low-level key parameter getters".
1352 • EC_KEY_get0_engine(), EC_KEY_get_default_method(),
1354 EC_KEY_get_method(), EC_KEY_new_method(), EC_KEY_get_ex_data(),
1355 EC_KEY_OpenSSL(), EC_KEY_set_ex_data(),
1356 EC_KEY_set_default_method(), EC_KEY_METHOD_*(), EC_KEY_set_method()
1357 See "Providers are a replacement for engines and low-level method
1359 overrides"
1360 • EC_METHOD_get_field_type()
1362 Use EC_GROUP_get_field_type(3) instead. See "Providers are a
1364 replacement for engines and low-level method overrides"
1365 • EC_KEY_key2buf(), EC_KEY_oct2key(), EC_KEY_oct2priv(),
1367 EC_KEY_priv2buf(), EC_KEY_priv2oct()
1368 There are no replacements for these.
1370 • EC_KEY_new(), EC_KEY_new_by_curve_name(), EC_KEY_free(),
1372 EC_KEY_up_ref()
1373 See "Deprecated low-level object creation"
1375 • EC_KEY_print(), EC_KEY_print_fp()
1377 See "Deprecated low-level key printing functions"
1379 • EC_KEY_set_asn1_flag(), EC_KEY_set_conv_form(),
1381 EC_KEY_set_enc_flags()
1382 See "Deprecated low-level key parameter setters".
1384 • EC_KEY_set_group(), EC_KEY_set_private_key(),
1386 EC_KEY_set_public_key(), EC_KEY_set_public_key_affine_coordinates()
1387 See "Deprecated low-level key parameter setters".
1389 • ECParameters_print(), ECParameters_print_fp(),
1391 ECPKParameters_print(), ECPKParameters_print_fp()
1392 See "Deprecated low-level key printing functions"
1394 • EC_POINT_bn2point(), EC_POINT_point2bn()
1396 These functions were not particularly useful, since EC point
1398 serialization formats are not individual big-endian integers.
1399 • EC_POINT_get_affine_coordinates_GF2m(),
1401 EC_POINT_get_affine_coordinates_GFp(),
1402 EC_POINT_set_affine_coordinates_GF2m(),
1403 EC_POINT_set_affine_coordinates_GFp()
1404 Applications should use EC_POINT_get_affine_coordinates(3) and
1406 EC_POINT_set_affine_coordinates(3) instead.
1407 • EC_POINT_get_Jprojective_coordinates_GFp(),
1409 EC_POINT_set_Jprojective_coordinates_GFp()
1410 These functions are not widely used. Applications should instead
1412 use the EC_POINT_set_affine_coordinates(3) and
1413 EC_POINT_get_affine_coordinates(3) functions.
1414 • EC_POINT_make_affine(), EC_POINTs_make_affine()
1416 There is no replacement. These functions were not widely used, and
1418 OpenSSL automatically performs this conversion when needed.
1419 • EC_POINT_set_compressed_coordinates_GF2m(),
1421 EC_POINT_set_compressed_coordinates_GFp()
1422 Applications should use EC_POINT_set_compressed_coordinates(3)
1424 instead.
1425 • EC_POINTs_mul()
1427 This function is not widely used. Applications should instead use
1429 the EC_POINT_mul(3) function.
1430 • ENGINE_*()
1432 All engine functions are deprecated. An engine should be rewritten
1434 as a provider. See "Providers are a replacement for engines and
1435 low-level method overrides".
1436 • ERR_load_*(), ERR_func_error_string(), ERR_get_error_line(),
1438 ERR_get_error_line_data(), ERR_get_state()
1439 OpenSSL now loads error strings automatically so these functions
1441 are not needed.
1442 • ERR_peek_error_line_data(), ERR_peek_last_error_line_data()
1444 The new functions are ERR_peek_error_func(3),
1446 ERR_peek_last_error_func(3), ERR_peek_error_data(3),
1447 ERR_peek_last_error_data(3), ERR_get_error_all(3),
1448 ERR_peek_error_all(3) and ERR_peek_last_error_all(3). Applications
1449 should use ERR_get_error_all(3), or pick information with ERR_peek
1450 functions and finish off with getting the error code by using
1451 ERR_get_error(3).
1452 • EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_iv_noconst(),
1454 EVP_CIPHER_CTX_original_iv()
1455 Applications should instead use EVP_CIPHER_CTX_get_updated_iv(3),
1457 EVP_CIPHER_CTX_get_updated_iv(3) and
1458 EVP_CIPHER_CTX_get_original_iv(3) respectively. See
1459 EVP_CIPHER_CTX_get_original_iv(3) for further information.
1460 • EVP_CIPHER_meth_*(), EVP_MD_CTX_set_update_fn(),
1462 EVP_MD_CTX_update_fn(), EVP_MD_meth_*()
1463 See "Providers are a replacement for engines and low-level method
1465 overrides".
1466 • EVP_PKEY_CTRL_PKCS7_ENCRYPT(), EVP_PKEY_CTRL_PKCS7_DECRYPT(),
1468 EVP_PKEY_CTRL_PKCS7_SIGN(), EVP_PKEY_CTRL_CMS_ENCRYPT(),
1469 EVP_PKEY_CTRL_CMS_DECRYPT(), and EVP_PKEY_CTRL_CMS_SIGN()
1470 These control operations are not invoked by the OpenSSL library
1472 anymore and are replaced by direct checks of the key operation
1473 against the key type when the operation is initialized.
1474 • EVP_PKEY_CTX_get0_dh_kdf_ukm(), EVP_PKEY_CTX_get0_ecdh_kdf_ukm()
1476 See the "kdf-ukm" item in "DH key exchange parameters" in
1478 EVP_KEYEXCH-DH(7) and "ECDH Key Exchange parameters" in
1479 EVP_KEYEXCH-ECDH(7). These functions are obsolete and should not
1480 be required.
1481 • EVP_PKEY_CTX_set_rsa_keygen_pubexp()
1483 Applications should use EVP_PKEY_CTX_set1_rsa_keygen_pubexp(3)
1485 instead.
1486 • EVP_PKEY_cmp(), EVP_PKEY_cmp_parameters()
1488 Applications should use EVP_PKEY_eq(3) and
1490 EVP_PKEY_parameters_eq(3) instead. See EVP_PKEY_copy_parameters(3)
1491 for further details.
1492 • EVP_PKEY_encrypt_old(), EVP_PKEY_decrypt_old(),
1494 Applications should use EVP_PKEY_encrypt_init(3) and
1496 EVP_PKEY_encrypt(3) or EVP_PKEY_decrypt_init(3) and
1497 EVP_PKEY_decrypt(3) instead.
1498 • EVP_PKEY_get0()
1500 This function returns NULL if the key comes from a provider.
1502 • EVP_PKEY_get0_DH(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_EC_KEY(),
1504 EVP_PKEY_get0_RSA(), EVP_PKEY_get1_DH(), EVP_PKEY_get1_DSA(),
1505 EVP_PKEY_get1_EC_KEY and EVP_PKEY_get1_RSA(), EVP_PKEY_get0_hmac(),
1506 EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash()
1507 See "Functions that return an internal key should be treated as
1509 read only".
1510 • EVP_PKEY_meth_*()
1512 See "Providers are a replacement for engines and low-level method
1514 overrides".
1515 • EVP_PKEY_new_CMAC_key()
1517 See "Deprecated low-level MAC functions".
1519 • EVP_PKEY_assign(), EVP_PKEY_set1_DH(), EVP_PKEY_set1_DSA(),
1521 EVP_PKEY_set1_EC_KEY(), EVP_PKEY_set1_RSA()
1522 See "Deprecated low-level key object getters and setters"
1524 • EVP_PKEY_set1_tls_encodedpoint() EVP_PKEY_get1_tls_encodedpoint()
1526 These functions were previously used by libssl to set or get an
1528 encoded public key into/from an EVP_PKEY object. With OpenSSL 3.0
1529 these are replaced by the more generic functions
1530 EVP_PKEY_set1_encoded_public_key(3) and
1531 EVP_PKEY_get1_encoded_public_key(3). The old versions have been
1532 converted to deprecated macros that just call the new functions.
1533 • EVP_PKEY_set1_engine(), EVP_PKEY_get0_engine()
1535 See "Providers are a replacement for engines and low-level method
1537 overrides".
1538 • EVP_PKEY_set_alias_type()
1540 This function has been removed. There is no replacement. See
1542 "EVP_PKEY_set_alias_type() method has been removed"
1543 • HMAC_Init_ex(), HMAC_Update(), HMAC_Final(), HMAC_size()
1545 See "Deprecated low-level MAC functions".
1547 • HMAC_CTX_new(), HMAC_CTX_free(), HMAC_CTX_copy(), HMAC_CTX_reset(),
1549 HMAC_CTX_set_flags(), HMAC_CTX_get_md()
1550 See "Deprecated low-level MAC functions".
1552 • i2d_DHparams(), i2d_DHxparams()
1554 See "Deprecated low-level key reading and writing functions" and
1556 "Migration" in d2i_RSAPrivateKey(3)
1557 • i2d_DSAparams(), i2d_DSAPrivateKey(), i2d_DSAPrivateKey_bio(),
1559 i2d_DSAPrivateKey_fp(), i2d_DSA_PUBKEY(), i2d_DSA_PUBKEY_bio(),
1560 i2d_DSA_PUBKEY_fp(), i2d_DSAPublicKey()
1561 See "Deprecated low-level key reading and writing functions" and
1563 "Migration" in d2i_RSAPrivateKey(3)
1564 • i2d_ECParameters(), i2d_ECPrivateKey(), i2d_ECPrivateKey_bio(),
1566 i2d_ECPrivateKey_fp(), i2d_EC_PUBKEY(), i2d_EC_PUBKEY_bio(),
1567 i2d_EC_PUBKEY_fp(), i2o_ECPublicKey()
1568 See "Deprecated low-level key reading and writing functions" and
1570 "Migration" in d2i_RSAPrivateKey(3)
1571 • i2d_RSAPrivateKey(), i2d_RSAPrivateKey_bio(),
1573 i2d_RSAPrivateKey_fp(), i2d_RSA_PUBKEY(), i2d_RSA_PUBKEY_bio(),
1574 i2d_RSA_PUBKEY_fp(), i2d_RSAPublicKey(), i2d_RSAPublicKey_bio(),
1575 i2d_RSAPublicKey_fp()
1576 See "Deprecated low-level key reading and writing functions" and
1578 "Migration" in d2i_RSAPrivateKey(3)
1579 • IDEA_encrypt(), IDEA_set_decrypt_key(), IDEA_set_encrypt_key(),
1581 IDEA_cbc_encrypt(), IDEA_cfb64_encrypt(), IDEA_ecb_encrypt(),
1582 IDEA_ofb64_encrypt()
1583 See "Deprecated low-level encryption functions". IDEA has been
1585 moved to the Legacy Provider.
1586 • IDEA_options()
1588 There is no replacement. This function returned a constant string.
1590 • MD2(), MD2_Init(), MD2_Update(), MD2_Final()
1592 See "Deprecated low-level encryption functions". MD2 has been
1594 moved to the Legacy Provider.
1595 • MD2_options()
1597 There is no replacement. This function returned a constant string.
1599 • MD4(), MD4_Init(), MD4_Update(), MD4_Final(), MD4_Transform()
1601 See "Deprecated low-level encryption functions". MD4 has been
1603 moved to the Legacy Provider.
1604 • MDC2(), MDC2_Init(), MDC2_Update(), MDC2_Final()
1606 See "Deprecated low-level encryption functions". MDC2 has been
1608 moved to the Legacy Provider.
1609 • MD5(), MD5_Init(), MD5_Update(), MD5_Final(), MD5_Transform()
1611 See "Deprecated low-level encryption functions".
1613 • NCONF_WIN32()
1615 This undocumented function has no replacement. See "HISTORY" in
1617 config(5) for more details.
1618 • OCSP_parse_url()
1620 Use OSSL_HTTP_parse_url(3) instead.
1622 • OCSP_REQ_CTX type and OCSP_REQ_CTX_*() functions
1624 These methods were used to collect all necessary data to form a
1626 HTTP request, and to perform the HTTP transfer with that request.
1627 With OpenSSL 3.0, the type is OSSL_HTTP_REQ_CTX, and the deprecated
1628 functions are replaced with OSSL_HTTP_REQ_CTX_*(). See
1629 OSSL_HTTP_REQ_CTX(3) for additional details.
1630 • OPENSSL_fork_child(), OPENSSL_fork_parent(), OPENSSL_fork_prepare()
1632 There is no replacement for these functions. These pthread fork
1634 support methods were unused by OpenSSL.
1635 • OSSL_STORE_ctrl(), OSSL_STORE_do_all_loaders(),
1637 OSSL_STORE_LOADER_get0_engine(), OSSL_STORE_LOADER_get0_scheme(),
1638 OSSL_STORE_LOADER_new(), OSSL_STORE_LOADER_set_attach(),
1639 OSSL_STORE_LOADER_set_close(), OSSL_STORE_LOADER_set_ctrl(),
1640 OSSL_STORE_LOADER_set_eof(), OSSL_STORE_LOADER_set_error(),
1641 OSSL_STORE_LOADER_set_expect(), OSSL_STORE_LOADER_set_find(),
1642 OSSL_STORE_LOADER_set_load(), OSSL_STORE_LOADER_set_open(),
1643 OSSL_STORE_LOADER_set_open_ex(), OSSL_STORE_register_loader(),
1644 OSSL_STORE_unregister_loader(), OSSL_STORE_vctrl()
1645 These functions helped applications and engines create loaders for
1647 schemes they supported. These are all deprecated and discouraged
1648 in favour of provider implementations, see provider-storemgmt(7).
1649 • PEM_read_DHparams(), PEM_read_bio_DHparams(), PEM_read_DSAparams(),
1651 PEM_read_bio_DSAparams(), PEM_read_DSAPrivateKey(),
1652 PEM_read_DSA_PUBKEY(), PEM_read_bio_DSAPrivateKey and
1653 PEM_read_bio_DSA_PUBKEY(), PEM_read_ECPKParameters(),
1654 PEM_read_ECPrivateKey(), PEM_read_EC_PUBKEY(),
1655 PEM_read_bio_ECPKParameters(), PEM_read_bio_ECPrivateKey(),
1656 PEM_read_bio_EC_PUBKEY(), PEM_read_RSAPrivateKey(),
1657 PEM_read_RSA_PUBKEY(), PEM_read_RSAPublicKey(),
1658 PEM_read_bio_RSAPrivateKey(), PEM_read_bio_RSA_PUBKEY(),
1659 PEM_read_bio_RSAPublicKey(), PEM_write_bio_DHparams(),
1660 PEM_write_bio_DHxparams(), PEM_write_DHparams(),
1661 PEM_write_DHxparams(), PEM_write_DSAparams(),
1662 PEM_write_DSAPrivateKey(), PEM_write_DSA_PUBKEY(),
1663 PEM_write_bio_DSAparams(), PEM_write_bio_DSAPrivateKey(),
1664 PEM_write_bio_DSA_PUBKEY(), PEM_write_ECPKParameters(),
1665 PEM_write_ECPrivateKey(), PEM_write_EC_PUBKEY(),
1666 PEM_write_bio_ECPKParameters(), PEM_write_bio_ECPrivateKey(),
1667 PEM_write_bio_EC_PUBKEY(), PEM_write_RSAPrivateKey(),
1668 PEM_write_RSA_PUBKEY(), PEM_write_RSAPublicKey(),
1669 PEM_write_bio_RSAPrivateKey(), PEM_write_bio_RSA_PUBKEY(),
1670 PEM_write_bio_RSAPublicKey(),
1671 See "Deprecated low-level key reading and writing functions"
1673 • PKCS1_MGF1()
1675 See "Deprecated low-level encryption functions".
1677 • RAND_get_rand_method(), RAND_set_rand_method(), RAND_OpenSSL(),
1679 RAND_set_rand_engine()
1680 Applications should instead use RAND_set_DRBG_type(3), EVP_RAND(3)
1682 and EVP_RAND(7). See RAND_set_rand_method(3) for more details.
1683 • RC2_encrypt(), RC2_decrypt(), RC2_set_key(), RC2_cbc_encrypt(),
1685 RC2_cfb64_encrypt(), RC2_ecb_encrypt(), RC2_ofb64_encrypt(), RC4(),
1686 RC4_set_key(), RC4_options(), RC5_32_encrypt(), RC5_32_set_key(),
1687 RC5_32_decrypt(), RC5_32_cbc_encrypt(), RC5_32_cfb64_encrypt(),
1688 RC5_32_ecb_encrypt(), RC5_32_ofb64_encrypt()
1689 See "Deprecated low-level encryption functions". The Algorithms
1691 "RC2", "RC4" and "RC5" have been moved to the Legacy Provider.
1692 • RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update(),
1694 RIPEMD160_Final(), RIPEMD160_Transform()
1695 See "Deprecated low-level digest functions". The RIPE algorithm
1697 has been moved to the Legacy Provider.
1698 • RSA_bits(), RSA_security_bits(), RSA_size()
1700 Use EVP_PKEY_get_bits(3), EVP_PKEY_get_security_bits(3) and
1702 EVP_PKEY_get_size(3).
1703 • RSA_check_key(), RSA_check_key_ex()
1705 See "Deprecated low-level validation functions"
1707 • RSA_clear_flags(), RSA_flags(), RSA_set_flags(), RSA_test_flags(),
1709 RSA_setup_blinding(), RSA_blinding_off(), RSA_blinding_on()
1710 All of these RSA flags have been deprecated without replacement:
1712 RSA_FLAG_BLINDING, RSA_FLAG_CACHE_PRIVATE, RSA_FLAG_CACHE_PUBLIC,
1714 RSA_FLAG_EXT_PKEY, RSA_FLAG_NO_BLINDING, RSA_FLAG_THREAD_SAFE
1715 RSA_METHOD_FLAG_NO_CHECK
1716 • RSA_generate_key_ex(), RSA_generate_multi_prime_key()
1718 See "Deprecated low-level key generation functions".
1720 • RSA_get0_engine()
1722 See "Providers are a replacement for engines and low-level method
1724 overrides"
1725 • RSA_get0_crt_params(), RSA_get0_d(), RSA_get0_dmp1(),
1727 RSA_get0_dmq1(), RSA_get0_e(), RSA_get0_factors(), RSA_get0_iqmp(),
1728 RSA_get0_key(), RSA_get0_multi_prime_crt_params(),
1729 RSA_get0_multi_prime_factors(), RSA_get0_n(), RSA_get0_p(),
1730 RSA_get0_pss_params(), RSA_get0_q(),
1731 RSA_get_multi_prime_extra_count()
1732 See "Deprecated low-level key parameter getters"
1734 • RSA_new(), RSA_free(), RSA_up_ref()
1736 See "Deprecated low-level object creation".
1738 • RSA_get_default_method(), RSA_get_ex_data and RSA_get_method()
1740 See "Providers are a replacement for engines and low-level method
1742 overrides".
1743 • RSA_get_version()
1745 There is no replacement.
1747 • RSA_meth_*(), RSA_new_method(), RSA_null_method and
1749 RSA_PKCS1_OpenSSL()
1750 See "Providers are a replacement for engines and low-level method
1752 overrides".
1753 • RSA_padding_add_*(), RSA_padding_check_*()
1755 See "Deprecated low-level signing functions" and "Deprecated low-
1757 level encryption functions".
1758 • RSA_print(), RSA_print_fp()
1760 See "Deprecated low-level key printing functions"
1762 • RSA_public_encrypt(), RSA_private_decrypt()
1764 See "Deprecated low-level encryption functions"
1766 • RSA_private_encrypt(), RSA_public_decrypt()
1768 This is equivalent to doing sign and verify recover operations
1770 (with a padding mode of none). See "Deprecated low-level signing
1771 functions".
1772 • RSAPrivateKey_dup(), RSAPublicKey_dup()
1774 There is no direct replacement. Applications may use
1776 EVP_PKEY_dup(3).
1777 • RSAPublicKey_it(), RSAPrivateKey_it()
1779 See "Deprecated low-level key reading and writing functions"
1781 • RSA_set0_crt_params(), RSA_set0_factors(), RSA_set0_key(),
1783 RSA_set0_multi_prime_params()
1784 See "Deprecated low-level key parameter setters".
1786 • RSA_set_default_method(), RSA_set_method(), RSA_set_ex_data()
1788 See "Providers are a replacement for engines and low-level method
1790 overrides"
1791 • RSA_sign(), RSA_sign_ASN1_OCTET_STRING(), RSA_verify(),
1793 RSA_verify_ASN1_OCTET_STRING(), RSA_verify_PKCS1_PSS(),
1794 RSA_verify_PKCS1_PSS_mgf1()
1795 See "Deprecated low-level signing functions".
1797 • RSA_X931_derive_ex(), RSA_X931_generate_key_ex(),
1799 RSA_X931_hash_id()
1800 There are no replacements for these functions. X931 padding can be
1802 set using "Signature Parameters" in EVP_SIGNATURE-RSA(7). See
1803 OSSL_SIGNATURE_PARAM_PAD_MODE.
1804 • SEED_encrypt(), SEED_decrypt(), SEED_set_key(), SEED_cbc_encrypt(),
1806 SEED_cfb128_encrypt(), SEED_ecb_encrypt(), SEED_ofb128_encrypt()
1807 See "Deprecated low-level encryption functions". The SEED
1809 algorithm has been moved to the Legacy Provider.
1810 • SHA1_Init(), SHA1_Update(), SHA1_Final(), SHA1_Transform(),
1812 SHA224_Init(), SHA224_Update(), SHA224_Final(), SHA256_Init(),
1813 SHA256_Update(), SHA256_Final(), SHA256_Transform(), SHA384_Init(),
1814 SHA384_Update(), SHA384_Final(), SHA512_Init(), SHA512_Update(),
1815 SHA512_Final(), SHA512_Transform()
1816 See "Deprecated low-level digest functions".
1818 • SRP_Calc_A(), SRP_Calc_B(), SRP_Calc_client_key(),
1820 SRP_Calc_server_key(), SRP_Calc_u(), SRP_Calc_x(),
1821 SRP_check_known_gN_param(), SRP_create_verifier(),
1822 SRP_create_verifier_BN(), SRP_get_default_gN(),
1823 SRP_user_pwd_free(), SRP_user_pwd_new(), SRP_user_pwd_set0_sv(),
1824 SRP_user_pwd_set1_ids(), SRP_user_pwd_set_gN(),
1825 SRP_VBASE_add0_user(), SRP_VBASE_free(), SRP_VBASE_get1_by_user(),
1826 SRP_VBASE_init(), SRP_VBASE_new(), SRP_Verify_A_mod_N(),
1827 SRP_Verify_B_mod_N()
1828 There are no replacements for the SRP functions.
1830 • SSL_CTX_set_tmp_dh_callback(), SSL_set_tmp_dh_callback(),
1832 SSL_CTX_set_tmp_dh(), SSL_set_tmp_dh()
1833 These are used to set the Diffie-Hellman (DH) parameters that are
1835 to be used by servers requiring ephemeral DH keys. Instead
1836 applications should consider using the built-in DH parameters that
1837 are available by calling SSL_CTX_set_dh_auto(3) or
1838 SSL_set_dh_auto(3). If custom parameters are necessary then
1839 applications can use the alternative functions
1840 SSL_CTX_set0_tmp_dh_pkey(3) and SSL_set0_tmp_dh_pkey(3). There is
1841 no direct replacement for the "callback" functions. The callback
1842 was originally useful in order to have different parameters for
1843 export and non-export ciphersuites. Export ciphersuites are no
1844 longer supported by OpenSSL. Use of the callback functions should
1845 be replaced by one of the other methods described above.
1846 • SSL_CTX_set_tlsext_ticket_key_cb()
1848 Use the new SSL_CTX_set_tlsext_ticket_key_evp_cb(3) function
1850 instead.
1851 • WHIRLPOOL(), WHIRLPOOL_Init(), WHIRLPOOL_Update(),
1853 WHIRLPOOL_Final(), WHIRLPOOL_BitUpdate()
1854 See "Deprecated low-level digest functions". The Whirlpool
1856 algorithm has been moved to the Legacy Provider.
1857 • X509_certificate_type()
1859 This was an undocumented function. Applications can use
1861 X509_get0_pubkey(3) and X509_get0_signature(3) instead.
1862 • X509_http_nbio(), X509_CRL_http_nbio()
1864 Use X509_load_http(3) and X509_CRL_load_http(3) instead.
1866 NID handling for provided keys and algorithms
1868 The following functions for NID (numeric id) handling have changed
1870 semantics.
1871 • EVP_PKEY_id(), EVP_PKEY_get_id()
1873 This function was previously used to reliably return the NID of an
1875 EVP_PKEY object, e.g., to look up the name of the algorithm of such
1876 EVP_PKEY by calling OBJ_nid2sn(3). With the introduction of
1877 provider(7)s EVP_PKEY_id() or its new equivalent EVP_PKEY_get_id(3)
1878 might now also return the value -1 (EVP_PKEY_KEYMGMT) indicating
1879 the use of a provider to implement the EVP_PKEY object. Therefore,
1880 the use of EVP_PKEY_get0_type_name(3) is recommended for retrieving
1881 the name of the EVP_PKEY algorithm.
1882 Using the FIPS Module in applications
1884 See fips_module(7) and OSSL_PROVIDER-FIPS(7) for details.
1885 OpenSSL command line application changes
1887 New applications
1888 openssl kdf uses the new EVP_KDF(3) API. openssl kdf uses the new
1890 EVP_MAC(3) API.
1891 Added options
1893 -provider_path and -provider are available to all apps and can be used
1895 multiple times to load any providers, such as the 'legacy' provider or
1896 third party providers. If used then the 'default' provider would also
1897 need to be specified if required. The -provider_path must be specified
1898 before the -provider option.
1899 The list app has many new options. See openssl-list(1) for more
1901 information.
1902 -crl_lastupdate and -crl_nextupdate used by openssl ca allows explicit
1904 setting of fields in the generated CRL.
1905 Removed options
1907 Interactive mode is not longer available.
1909 The -crypt option used by openssl passwd. The -c option used by
1911 openssl x509, openssl dhparam, openssl dsaparam, and openssl ecparam.
1912 Other Changes
1914 The output of Command line applications may have minor changes. These
1916 are primarily changes in capitalisation and white space. However, in
1917 some cases, there are additional differences. For example, the DH
1918 parameters output from openssl dhparam now lists 'P', 'Q', 'G' and
1919 'pcounter' instead of 'prime', 'generator', 'subgroup order' and
1920 'counter' respectively.
1921 The openssl commands that read keys, certificates, and CRLs now
1923 automatically detect the PEM or DER format of the input files so it is
1924 not necessary to explicitly specify the input format anymore. However
1925 if the input format option is used the specified format will be
1926 required.
1927 openssl speed no longer uses low-level API calls. This implies some of
1929 the performance numbers might not be comparable with the previous
1930 releases due to higher overhead. This applies particularly to measuring
1931 performance on smaller data chunks.
1932 b<openssl dhparam>, openssl dsa, openssl gendsa, openssl dsaparam,
1934 openssl genrsa and openssl rsa have been modified to use PKEY APIs.
1935 openssl genrsa and openssl rsa now write PKCS #8 keys by default.
1936 Default settings
1938 "SHA256" is now the default digest for TS query used by openssl ts.
1940 Deprecated apps
1942 openssl rsautl is deprecated, use openssl pkeyutl instead. openssl
1944 dhparam, openssl dsa, openssl gendsa, openssl dsaparam, openssl genrsa,
1945 openssl rsa, openssl genrsa and openssl rsa are now in maintenance mode
1946 and no new features will be added to them.
1947 TLS Changes
1949 • TLS 1.3 FFDHE key exchange support added
1950 This uses DH safe prime named groups.
1952 • Support for fully "pluggable" TLSv1.3 groups.
1954 This means that providers may supply their own group
1956 implementations (using either the "key exchange" or the "key
1957 encapsulation" methods) which will automatically be detected and
1958 used by libssl.
1959 • SSL and SSL_CTX options are now 64 bit instead of 32 bit.
1961 The signatures of the functions to get and set options on SSL and
1963 SSL_CTX objects changed from "unsigned long" to "uint64_t" type.
1964 This may require source code changes. For example it is no longer
1966 possible to use the SSL_OP_ macro values in preprocessor "#if"
1967 conditions. However it is still possible to test whether these
1968 macros are defined or not.
1969 See SSL_CTX_get_options(3), SSL_CTX_set_options(3),
1971 SSL_get_options(3) and SSL_set_options(3).
1972 • SSL_set1_host() and SSL_add1_host() Changes
1974 These functions now take IP literal addresses as well as actual
1976 hostnames.
1977 • Added SSL option SSL_OP_CLEANSE_PLAINTEXT
1979 If the option is set, openssl cleanses (zeroizes) plaintext bytes
1981 from internal buffers after delivering them to the application.
1982 Note, the application is still responsible for cleansing other
1983 copies (e.g.: data received by SSL_read(3)).
1984 • Client-initiated renegotiation is disabled by default.
1986 To allow it, use the -client_renegotiation option, the
1988 SSL_OP_ALLOW_CLIENT_RENEGOTIATION flag, or the
1989 "ClientRenegotiation" config parameter as appropriate.
1990 • Secure renegotiation is now required by default for TLS connections
1992 Support for RFC 5746 secure renegotiation is now required by
1994 default for SSL or TLS connections to succeed. Applications that
1995 require the ability to connect to legacy peers will need to
1996 explicitly set SSL_OP_LEGACY_SERVER_CONNECT. Accordingly,
1997 SSL_OP_LEGACY_SERVER_CONNECT is no longer set as part of
1998 SSL_OP_ALL.
1999 • Combining the Configure options no-ec and no-dh no longer disables
2001 TLSv1.3
2002 Typically if OpenSSL has no EC or DH algorithms then it cannot
2004 support connections with TLSv1.3. However OpenSSL now supports
2005 "pluggable" groups through providers. Therefore third party
2006 providers may supply group implementations even where there are no
2007 built-in ones. Attempting to create TLS connections in such a build
2008 without also disabling TLSv1.3 at run time or using third party
2009 provider groups may result in handshake failures. TLSv1.3 can be
2010 disabled at compile time using the "no-tls1_3" Configure option.
2011 • SSL_CTX_set_ciphersuites() and SSL_set_ciphersuites() changes.
2013 The methods now ignore unknown ciphers.
2015 • Security callback change.
2017 The security callback, which can be customised by application code,
2019 supports the security operation SSL_SECOP_TMP_DH. This is defined
2020 to take an EVP_PKEY in the "other" parameter. In most places this
2021 is what is passed. All these places occur server side. However
2022 there was one client side call of this security operation and it
2023 passed a DH object instead. This is incorrect according to the
2024 definition of SSL_SECOP_TMP_DH, and is inconsistent with all of the
2025 other locations. Therefore this client side call has been changed
2026 to pass an EVP_PKEY instead.
2027 • New SSL option SSL_OP_IGNORE_UNEXPECTED_EOF
2029 The SSL option SSL_OP_IGNORE_UNEXPECTED_EOF is introduced. If that
2031 option is set, an unexpected EOF is ignored, it pretends a close
2032 notify was received instead and so the returned error becomes
2033 SSL_ERROR_ZERO_RETURN.
2034 • The security strength of SHA1 and MD5 based signatures in TLS has
2036 been reduced.
2037 This results in SSL 3, TLS 1.0, TLS 1.1 and DTLS 1.0 no longer
2039 working at the default security level of 1 and instead requires
2040 security level 0. The security level can be changed either using
2041 the cipher string with @SECLEVEL, or calling
2042 SSL_CTX_set_security_level(3). This also means that where the
2043 signature algorithms extension is missing from a ClientHello then
2044 the handshake will fail in TLS 1.2 at security level 1. This is
2045 because, although this extension is optional, failing to provide
2046 one means that OpenSSL will fallback to a default set of signature
2047 algorithms. This default set requires the availability of SHA1.
2048 • X509 certificates signed using SHA1 are no longer allowed at
2050 security level 1 and above.
2051 In TLS/SSL the default security level is 1. It can be set either
2053 using the cipher string with @SECLEVEL, or calling
2054 SSL_CTX_set_security_level(3). If the leaf certificate is signed
2055 with SHA-1, a call to SSL_CTX_use_certificate(3) will fail if the
2056 security level is not lowered first. Outside TLS/SSL, the default
2057 security level is -1 (effectively 0). It can be set using
2058 X509_VERIFY_PARAM_set_auth_level(3) or using the -auth_level
2059 options of the commands.
2060
2062 fips_module(7)
2063
2065 The migration guide was created for OpenSSL 3.0.
2066
2068 Copyright 2021-2023 The OpenSSL Project Authors. All Rights Reserved.
2069 Licensed under the Apache License 2.0 (the "License"). You may not use
2071 this file except in compliance with the License. You can obtain a copy
2072 in the file LICENSE in the source distribution or at
2073 <https://www.openssl.org/source/license.html>.
20743.0.9 2023-07-27 MIGRATION_GUIDE(7ossl)