1MIGRATION_GUIDE(7ossl)              OpenSSL             MIGRATION_GUIDE(7ossl)
2
3
4

NAME

6       migration_guide - OpenSSL migration guide
7

SYNOPSIS

9       See the individual manual pages for details.
10

DESCRIPTION

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

OPENSSL 3.0

19   Main Changes from OpenSSL 1.1.1
20       Major Release
21
22       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
32       License Change
33
34       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
40       Providers and FIPS support
41
42       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
53       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
63       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
70       See also "Legacy Algorithms" for information on the legacy provider.
71
72       See also "Completing the installation of the FIPS Module" and "Using
73       the FIPS Module in applications".
74
75       Low Level APIs
76
77       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
97       This is described in more detail in "Deprecation of Low Level
98       Functions"
99
100       Legacy Algorithms
101
102       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
115       Engines and "METHOD" APIs
116
117       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
130       Support of legacy engines
131
132       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
136       New algorithms provided via engines will still work.
137
138       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
143       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
147       Versioning Scheme
148
149       The OpenSSL versioning scheme has changed with the OpenSSL 3.0 release.
150       The new versioning scheme has this format:
151
152       MAJOR.MINOR.PATCH
153
154       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
162       For more information, see OpenSSL_version(3).
163
164       Other major new features
165
166       Certificate Management Protocol (CMP, RFC 4210)
167
168       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
171       HTTP(S) client
172
173       A proper HTTP(S) client that supports GET and POST, redirection, plain
174       and ASN.1-encoded contents, proxies, and timeouts.
175
176       Key Derivation Function API (EVP_KDF)
177
178       This simplifies the process of adding new KDF and PRF implementations.
179
180       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
188       Message Authentication Code API (EVP_MAC)
189
190       This simplifies the process of adding MAC implementations.
191
192       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
196       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
200       Support for Linux Kernel TLS
201
202       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
206       New Algorithms
207
208       •   KDF algorithms "SINGLE STEP" and "SSH"
209
210           See EVP_KDF-SS(7) and EVP_KDF-SSHKDF(7)
211
212       •   MAC Algorithms "GMAC" and "KMAC"
213
214           See EVP_MAC-GMAC(7) and EVP_MAC-KMAC(7).
215
216       •   KEM Algorithm "RSASVE"
217
218           See EVP_KEM-RSA(7).
219
220       •   Cipher Algorithm "AES-SIV"
221
222           See "SIV Mode" in EVP_EncryptInit(3).
223
224       •   AES Key Wrap inverse ciphers supported by EVP layer.
225
226           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
231       •   CTS ciphers added to EVP layer.
232
233           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
238       CMS and PKCS#7 updates
239
240       •   Added CAdES-BES signature verification support.
241
242       •   Added CAdES-BES signature scheme and attributes support (RFC 5126)
243           to CMS API.
244
245       •   Added AuthEnvelopedData content type structure (RFC 5083) using
246           AES_GCM
247
248           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
253       •   PKCS7_get_octet_string(3) and PKCS7_type_is_other(3) were made
254           public.
255
256       PKCS#12 API updates
257
258       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
267       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
272       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
284       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
290       Windows thread synchronization changes
291
292       Windows thread synchronization uses read/write primitives (SRWLock)
293       when supported by the OS, otherwise CriticalSection continues to be
294       used.
295
296       Trace API
297
298       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
304       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
308       Key validation updates
309
310       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
315       Other notable deprecations and changes
316
317       The function code part of an OpenSSL error code is no longer relevant
318
319       This code is now always set to zero. Related functions are deprecated.
320
321       STACK and HASH macros have been cleaned up
322
323       The type-safe wrappers are declared everywhere and implemented once.
324       See DEFINE_STACK_OF(3) and DECLARE_LHASH_OF(3).
325
326       The RAND_DRBG subsystem has been removed
327
328       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
332       Removed FIPS_mode() and FIPS_mode_set()
333
334       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
339       Key generation is slower
340
341       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
345       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
350       Change PBKDF2 to conform to SP800-132 instead of the older PKCS5
351       RFC2898
352
353       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
359       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
362       Enforce a minimum DH modulus size of 512 bits
363
364       Smaller sizes now result in an error.
365
366       SM2 key changes
367
368       EC EVP_PKEYs with the SM2 curve have been reworked to automatically
369       become EVP_PKEY_SM2 rather than EVP_PKEY_EC.
370
371       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
375       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
381       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
387       EVP_PKEY_set_alias_type() method has been removed
388
389       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
393       Functions that return an internal key should be treated as read only
394
395       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
409       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
422       The public key check has moved from EVP_PKEY_derive() to
423       EVP_PKEY_derive_set_peer()
424
425       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
429       The print format has cosmetic changes for some functions
430
431       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
438       Interactive mode from the openssl program has been removed
439
440       From now on, running it without arguments is equivalent to openssl
441       help.
442
443       The error return values from some control calls (ctrl) have changed
444
445       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
449       DH and DHX key types have different settable parameters
450
451       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
456       EVP_CIPHER_CTX_set_flags() ordering change
457
458       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
462       Validation of operation context parameters
463
464       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
469       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
473       Removal of function code from the error codes
474
475       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
480   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
486   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
494       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
498       2.  Suppress the warnings. Refer to your compiler documentation on how
499           to do this.
500
501       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
504       Error code changes
505
506       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
511       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
516       There may be more cases to treat specially, depending on the calling
517       application code.
518
519   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
525       1.  The build and installation procedure has changed significantly.
526
527           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
532       2.  Many structures have been made opaque in OpenSSL 3.0.
533
534           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
542           For example code that previously looked like this:
543
544            EVP_MD_CTX md_ctx;
545
546            /* This line will now generate compiler errors */
547            EVP_MD_CTX_init(&md_ctx);
548
549           The code needs to be amended to look like this:
550
551            EVP_MD_CTX *md_ctx;
552
553            md_ctx = EVP_MD_CTX_new();
554            ...
555            ...
556            EVP_MD_CTX_free(md_ctx);
557
558       3.  Support for TLSv1.3 has been added.
559
560           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
564       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
568       Upgrading from the OpenSSL 2.0 FIPS Object Module
569
570       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
577       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
581   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
587   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
595       Library Context
596
597       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
602       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
606       Using a Library Context - Old functions that should be changed
607
608       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
612       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
617       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
624       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
628       •   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
631       •   BIO_new(3)
632
633b2i_RSA_PVK_bio() and i2b_PVK_bio()
634
635       •   BN_CTX_new(3) and BN_CTX_secure_new(3)
636
637       •   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
643       •   CONF_modules_load_file(3)
644
645       •   CTLOG_new(3), CTLOG_new_from_base64(3) and CTLOG_STORE_new(3)
646
647       •   CT_POLICY_EVAL_CTX_new(3)
648
649       •   d2i_AutoPrivateKey(3), d2i_PrivateKey(3) and d2i_PUBKEY(3)
650
651       •   d2i_PrivateKey_bio(3) and d2i_PrivateKey_fp(3)
652
653           Use d2i_PrivateKey_ex_bio(3) and d2i_PrivateKey_ex_fp(3)
654
655       •   EC_GROUP_new(3)
656
657           Use EC_GROUP_new_by_curve_name_ex(3) or
658           EC_GROUP_new_from_params(3).
659
660       •   EVP_DigestSignInit(3) and EVP_DigestVerifyInit(3)
661
662       •   EVP_PBE_CipherInit(3), EVP_PBE_find(3) and EVP_PBE_scrypt(3)
663
664       •   PKCS5_PBE_keyivgen(3)
665
666       •   EVP_PKCS82PKEY(3)
667
668       •   EVP_PKEY_CTX_new_id(3)
669
670           Use EVP_PKEY_CTX_new_from_name(3)
671
672       •   EVP_PKEY_derive_set_peer(3), EVP_PKEY_new_raw_private_key(3) and
673           EVP_PKEY_new_raw_public_key(3)
674
675       •   EVP_SignFinal(3) and EVP_VerifyFinal(3)
676
677       •   NCONF_new(3)
678
679       •   OCSP_RESPID_match(3) and OCSP_RESPID_set_by_key(3)
680
681       •   OPENSSL_thread_stop(3)
682
683       •   OSSL_STORE_open(3)
684
685       •   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
689       •   PEM_write_bio_PrivateKey(3), PEM_write_bio_PUBKEY(3),
690           PEM_write_PrivateKey(3) and PEM_write_PUBKEY(3)
691
692       •   PEM_X509_INFO_read_bio(3) and PEM_X509_INFO_read(3)
693
694       •   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
702       •   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
705       •   PKCS7_encrypt(3), PKCS7_new(3) and PKCS7_sign(3)
706
707       •   PKCS8_decrypt(3), PKCS8_encrypt(3) and PKCS8_set0_pbe(3)
708
709       •   RAND_bytes(3) and RAND_priv_bytes(3)
710
711       •   SMIME_write_ASN1(3)
712
713       •   SSL_load_client_CA_file(3)
714
715       •   SSL_CTX_new(3)
716
717       •   TS_RESP_CTX_new(3)
718
719       •   X509_CRL_new(3)
720
721       •   X509_load_cert_crl_file(3) and X509_load_cert_file(3)
722
723       •   X509_LOOKUP_by_subject(3) and X509_LOOKUP_ctrl(3)
724
725       •   X509_NAME_hash(3)
726
727       •   X509_new(3)
728
729       •   X509_REQ_new(3) and X509_REQ_verify(3)
730
731       •   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
735       New functions that use a Library context
736
737       The following functions can be passed a library context if required.
738       Passing NULL will use the default library context.
739
740       •   BIO_new_from_core_bio(3)
741
742       •   EVP_ASYM_CIPHER_fetch(3) and EVP_ASYM_CIPHER_do_all_provided(3)
743
744       •   EVP_CIPHER_fetch(3) and EVP_CIPHER_do_all_provided(3)
745
746       •   EVP_default_properties_enable_fips(3) and
747           EVP_default_properties_is_fips_enabled(3)
748
749       •   EVP_KDF_fetch(3) and EVP_KDF_do_all_provided(3)
750
751       •   EVP_KEM_fetch(3) and EVP_KEM_do_all_provided(3)
752
753       •   EVP_KEYEXCH_fetch(3) and EVP_KEYEXCH_do_all_provided(3)
754
755       •   EVP_KEYMGMT_fetch(3) and EVP_KEYMGMT_do_all_provided(3)
756
757       •   EVP_MAC_fetch(3) and EVP_MAC_do_all_provided(3)
758
759       •   EVP_MD_fetch(3) and EVP_MD_do_all_provided(3)
760
761       •   EVP_PKEY_CTX_new_from_pkey(3)
762
763       •   EVP_PKEY_Q_keygen(3)
764
765       •   EVP_Q_mac(3) and EVP_Q_digest(3)
766
767       •   EVP_RAND(3) and EVP_RAND_do_all_provided(3)
768
769       •   EVP_set_default_properties(3)
770
771       •   EVP_SIGNATURE_fetch(3) and EVP_SIGNATURE_do_all_provided(3)
772
773       •   OSSL_CMP_CTX_new(3) and OSSL_CMP_SRV_CTX_new(3)
774
775       •   OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert(3)
776
777       •   OSSL_CRMF_MSG_create_popo(3) and OSSL_CRMF_MSGS_verify_popo(3)
778
779       •   OSSL_CRMF_pbm_new(3) and OSSL_CRMF_pbmp_new(3)
780
781       •   OSSL_DECODER_CTX_add_extra(3) and OSSL_DECODER_CTX_new_for_pkey(3)
782
783       •   OSSL_DECODER_fetch(3) and OSSL_DECODER_do_all_provided(3)
784
785       •   OSSL_ENCODER_CTX_add_extra(3)
786
787       •   OSSL_ENCODER_fetch(3) and OSSL_ENCODER_do_all_provided(3)
788
789       •   OSSL_LIB_CTX_free(3), OSSL_LIB_CTX_load_config(3) and
790           OSSL_LIB_CTX_set0_default(3)
791
792       •   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
797       •   OSSL_SELF_TEST_get_callback(3) and OSSL_SELF_TEST_set_callback(3)
798
799       •   OSSL_STORE_attach(3)
800
801       •   OSSL_STORE_LOADER_fetch(3) and OSSL_STORE_LOADER_do_all_provided(3)
802
803       •   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
806       Providers
807
808       Providers are described in detail here "Providers" in crypto(7).  See
809       also "OPENSSL PROVIDERS" in crypto(7).
810
811       Fetching algorithms and property queries
812
813       Implicit and Explicit Fetching is described in detail here "ALGORITHM
814       FETCHING" in crypto(7).
815
816       Mapping EVP controls and flags to provider OSSL_PARAM parameters
817
818       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
823       For ciphers see "CONTROLS" in EVP_EncryptInit(3), "FLAGS" in
824       EVP_EncryptInit(3) and "PARAMETERS" in EVP_EncryptInit(3).
825
826       For digests see "CONTROLS" in EVP_DigestInit(3), "FLAGS" in
827       EVP_DigestInit(3) and "PARAMETERS" in EVP_DigestInit(3).
828
829       Deprecation of Low Level Functions
830
831       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
836       Providers are a replacement for engines and low-level method overrides
837
838       Any accessor that uses an ENGINE is deprecated (such as
839       EVP_PKEY_set1_engine()).  Applications using engines should instead use
840       providers.
841
842       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
847       Deprecated i2d and d2i functions for low-level key types
848
849       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
854       Deprecated low-level key object getters and setters
855
856       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
862       Deprecated low-level key parameter getters
863
864       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
876       Deprecated low-level key parameter setters
877
878       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
888       Deprecated low-level object creation
889
890       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
896       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
901       Deprecated low-level encryption functions
902
903       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
910       Deprecated low-level digest functions
911
912       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
918       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
921       Deprecated low-level signing functions
922
923       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
929       Deprecated low-level MAC functions
930
931       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
939       Note that the one-shot method HMAC() is still available for
940       compatability purposes.
941
942       Deprecated low-level validation functions
943
944       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
951       Deprecated low-level key exchange functions
952
953       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
957       Deprecated low-level key generation functions
958
959       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
966       Deprecated low-level key reading and writing functions
967
968       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
974       Deprecated low-level key printing functions
975
976       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
985       Deprecated function mappings
986
987       The following functions have been deprecated in 3.0.
988
989AES_bi_ige_encrypt() and AES_ige_encrypt()
990
991           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
1001AES_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
1006AES_unwrap_key(), AES_wrap_key()
1007
1008           See "Deprecated low-level encryption functions"
1009
1010AES_options()
1011
1012           There is no replacement. It returned a string indicating if the AES
1013           code was unrolled.
1014
1015ASN1_digest(), ASN1_sign(), ASN1_verify()
1016
1017           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
1020ASN1_STRING_length_set()
1021
1022           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
1026BF_encrypt(), BF_decrypt(), BF_set_key(), BF_cbc_encrypt(),
1027           BF_cfb64_encrypt(), BF_ecb_encrypt(), BF_ofb64_encrypt()
1028
1029           See "Deprecated low-level encryption functions".  The Blowfish
1030           algorithm has been moved to the Legacy Provider.
1031
1032BF_options()
1033
1034           There is no replacement. This option returned a constant string.
1035
1036BIO_get_callback(), BIO_set_callback(), BIO_debug_callback()
1037
1038           Use the respective non-deprecated _ex() functions.
1039
1040BN_is_prime_ex(), BN_is_prime_fasttest_ex()
1041
1042           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
1045BN_pseudo_rand(), BN_pseudo_rand_range()
1046
1047           Use BN_rand(3) and BN_rand_range(3).
1048
1049BN_X931_derive_prime_ex(), BN_X931_generate_prime_ex(),
1050           BN_X931_generate_Xpq()
1051
1052           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
1057Camellia_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
1063           See "Deprecated low-level encryption functions".
1064
1065CAST_encrypt(), CAST_decrypt(), CAST_set_key(), CAST_cbc_encrypt(),
1066           CAST_cfb64_encrypt(), CAST_ecb_encrypt(), CAST_ofb64_encrypt()
1067
1068           See "Deprecated low-level encryption functions".  The CAST
1069           algorithm has been moved to the Legacy Provider.
1070
1071CMAC_CTX_new(), CMAC_CTX_cleanup(), CMAC_CTX_copy(),
1072           CMAC_CTX_free(), CMAC_CTX_get0_cipher_ctx()
1073
1074           See "Deprecated low-level MAC functions".
1075
1076CMAC_Init(), CMAC_Update(), CMAC_Final(), CMAC_resume()
1077
1078           See "Deprecated low-level MAC functions".
1079
1080CRYPTO_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
1086           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
1090CRYPTO_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
1095           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
1101d2i_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
1112           See "Deprecated i2d and d2i functions for low-level key types"
1113
1114DES_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
1127           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
1131DH_bits(), DH_security_bits(), DH_size()
1132
1133           Use EVP_PKEY_get_bits(3), EVP_PKEY_get_security_bits(3) and
1134           EVP_PKEY_get_size(3).
1135
1136DH_check(), DH_check_ex(), DH_check_params(), DH_check_params_ex(),
1137           DH_check_pub_key(), DH_check_pub_key_ex()
1138
1139           See "Deprecated low-level validation functions"
1140
1141DH_clear_flags(), DH_test_flags(), DH_set_flags()
1142
1143           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
1148DH_compute_key() DH_compute_key_padded()
1149
1150           See "Deprecated low-level key exchange functions".
1151
1152DH_new(), DH_new_by_nid(), DH_free(), DH_up_ref()
1153
1154           See "Deprecated low-level object creation"
1155
1156DH_generate_key(), DH_generate_parameters_ex()
1157
1158           See "Deprecated low-level key generation functions".
1159
1160DH_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
1164           See "Deprecated low-level key parameter getters"
1165
1166DH_get_1024_160(), DH_get_2048_224(), DH_get_2048_256()
1167
1168           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
1173DH_KDF_X9_42()
1174
1175           Applications should use EVP_PKEY_CTX_set_dh_kdf_type(3) instead.
1176
1177DH_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
1181           See "Providers are a replacement for engines and low-level method
1182           overrides"
1183
1184DHparams_print(), DHparams_print_fp()
1185
1186           See "Deprecated low-level key printing functions"
1187
1188DH_set0_key(), DH_set0_pqg(), DH_set_length()
1189
1190           See "Deprecated low-level key parameter setters"
1191
1192DSA_bits(), DSA_security_bits(), DSA_size()
1193
1194           Use EVP_PKEY_get_bits(3), EVP_PKEY_get_security_bits(3) and
1195           EVP_PKEY_get_size(3).
1196
1197DHparams_dup(), DSA_dup_DH()
1198
1199           There is no direct replacement. Applications may use
1200           EVP_PKEY_copy_parameters(3) and EVP_PKEY_dup(3) instead.
1201
1202DSA_generate_key(), DSA_generate_parameters_ex()
1203
1204           See "Deprecated low-level key generation functions".
1205
1206DSA_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
1210           See "Providers are a replacement for engines and low-level method
1211           overrides".
1212
1213DSA_get0_p(), DSA_get0_q(), DSA_get0_g(), DSA_get0_pqg(),
1214           DSA_get0_key(), DSA_get0_priv_key(), DSA_get0_pub_key()
1215
1216           See "Deprecated low-level key parameter getters".
1217
1218DSA_new(), DSA_free(), DSA_up_ref()
1219
1220           See "Deprecated low-level object creation"
1221
1222DSAparams_dup()
1223
1224           There is no direct replacement. Applications may use
1225           EVP_PKEY_copy_parameters(3) and EVP_PKEY_dup(3) instead.
1226
1227DSAparams_print(), DSAparams_print_fp(), DSA_print(),
1228           DSA_print_fp()
1229
1230           See "Deprecated low-level key printing functions"
1231
1232DSA_set0_key(), DSA_set0_pqg()
1233
1234           See "Deprecated low-level key parameter setters"
1235
1236DSA_set_flags(), DSA_clear_flags(), DSA_test_flags()
1237
1238           The DSA_FLAG_CACHE_MONT_P flag has been deprecated without
1239           replacement.
1240
1241DSA_sign(), DSA_do_sign(), DSA_sign_setup(), DSA_verify(),
1242           DSA_do_verify()
1243
1244           See "Deprecated low-level signing functions".
1245
1246ECDH_compute_key()
1247
1248           See "Deprecated low-level key exchange functions".
1249
1250ECDH_KDF_X9_62()
1251
1252           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
1256ECDSA_sign(), ECDSA_sign_ex(), ECDSA_sign_setup(), ECDSA_do_sign(),
1257           ECDSA_do_sign_ex(), ECDSA_verify(), ECDSA_do_verify()
1258
1259           See "Deprecated low-level signing functions".
1260
1261ECDSA_size()
1262
1263           Applications should use EVP_PKEY_get_size(3).
1264
1265EC_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
1270           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
1274EC_GROUP_clear_free()
1275
1276           Use EC_GROUP_free(3) instead.
1277
1278EC_GROUP_get_curve_GF2m(), EC_GROUP_get_curve_GFp(),
1279           EC_GROUP_set_curve_GF2m(), EC_GROUP_set_curve_GFp()
1280
1281           Applications should use EC_GROUP_get_curve(3) and
1282           EC_GROUP_set_curve(3).
1283
1284EC_GROUP_have_precompute_mult(), EC_GROUP_precompute_mult(),
1285           EC_KEY_precompute_mult()
1286
1287           These functions are not widely used. Applications should instead
1288           switch to named curves which OpenSSL has hardcoded lookup tables
1289           for.
1290
1291EC_GROUP_new(), EC_GROUP_method_of(), EC_POINT_method_of()
1292
1293           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
1297EC_KEY_can_sign()
1298
1299           Applications should use EVP_PKEY_can_sign(3) instead.
1300
1301EC_KEY_check_key()
1302
1303           See "Deprecated low-level validation functions"
1304
1305EC_KEY_set_flags(), EC_KEY_get_flags(), EC_KEY_clear_flags()
1306
1307           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
1314EC_KEY_dup(), EC_KEY_copy()
1315
1316           There is no direct replacement. Applications may use
1317           EVP_PKEY_copy_parameters(3) and EVP_PKEY_dup(3) instead.
1318
1319EC_KEY_decoded_from_explicit_params()
1320
1321           There is no replacement.
1322
1323EC_KEY_generate_key()
1324
1325           See "Deprecated low-level key generation functions".
1326
1327EC_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
1331           See "Deprecated low-level key parameter getters".
1332
1333EC_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
1338           See "Providers are a replacement for engines and low-level method
1339           overrides"
1340
1341EC_METHOD_get_field_type()
1342
1343           Use EC_GROUP_get_field_type(3) instead.  See "Providers are a
1344           replacement for engines and low-level method overrides"
1345
1346EC_KEY_key2buf(), EC_KEY_oct2key(), EC_KEY_oct2priv(),
1347           EC_KEY_priv2buf(), EC_KEY_priv2oct()
1348
1349           There are no replacements for these.
1350
1351EC_KEY_new(), EC_KEY_new_by_curve_name(), EC_KEY_free(),
1352           EC_KEY_up_ref()
1353
1354           See "Deprecated low-level object creation"
1355
1356EC_KEY_print(), EC_KEY_print_fp()
1357
1358           See "Deprecated low-level key printing functions"
1359
1360EC_KEY_set_asn1_flag(), EC_KEY_set_conv_form(),
1361           EC_KEY_set_enc_flags()
1362
1363           See "Deprecated low-level key parameter setters".
1364
1365EC_KEY_set_group(), EC_KEY_set_private_key(),
1366           EC_KEY_set_public_key(), EC_KEY_set_public_key_affine_coordinates()
1367
1368           See "Deprecated low-level key parameter setters".
1369
1370ECParameters_print(), ECParameters_print_fp(),
1371           ECPKParameters_print(), ECPKParameters_print_fp()
1372
1373           See "Deprecated low-level key printing functions"
1374
1375EC_POINT_bn2point(), EC_POINT_point2bn()
1376
1377           These functions were not particularly useful, since EC point
1378           serialization formats are not individual big-endian integers.
1379
1380EC_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
1385           Applications should use EC_POINT_get_affine_coordinates(3) and
1386           EC_POINT_set_affine_coordinates(3) instead.
1387
1388EC_POINT_get_Jprojective_coordinates_GFp(),
1389           EC_POINT_set_Jprojective_coordinates_GFp()
1390
1391           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
1395EC_POINT_make_affine(), EC_POINTs_make_affine()
1396
1397           There is no replacement. These functions were not widely used, and
1398           OpenSSL automatically performs this conversion when needed.
1399
1400EC_POINT_set_compressed_coordinates_GF2m(),
1401           EC_POINT_set_compressed_coordinates_GFp()
1402
1403           Applications should use EC_POINT_set_compressed_coordinates(3)
1404           instead.
1405
1406EC_POINTs_mul()
1407
1408           This function is not widely used. Applications should instead use
1409           the EC_POINT_mul(3) function.
1410
1411ENGINE_*()
1412
1413           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
1417ERR_load_*(), ERR_func_error_string(), ERR_get_error_line(),
1418           ERR_get_error_line_data(), ERR_get_state()
1419
1420           OpenSSL now loads error strings automatically so these functions
1421           are not needed.
1422
1423ERR_peek_error_line_data(), ERR_peek_last_error_line_data()
1424
1425           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
1433EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_iv_noconst(),
1434           EVP_CIPHER_CTX_original_iv()
1435
1436           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
1441EVP_CIPHER_meth_*(), EVP_MD_CTX_set_update_fn(),
1442           EVP_MD_CTX_update_fn(), EVP_MD_meth_*()
1443
1444           See "Providers are a replacement for engines and low-level method
1445           overrides".
1446
1447EVP_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
1451           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
1455EVP_PKEY_CTX_get0_dh_kdf_ukm(), EVP_PKEY_CTX_get0_ecdh_kdf_ukm()
1456
1457           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
1462EVP_PKEY_CTX_set_rsa_keygen_pubexp()
1463
1464           Applications should use EVP_PKEY_CTX_set1_rsa_keygen_pubexp(3)
1465           instead.
1466
1467EVP_PKEY_cmp(), EVP_PKEY_cmp_parameters()
1468
1469           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
1473EVP_PKEY_encrypt_old(), EVP_PKEY_decrypt_old(),
1474
1475           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
1479EVP_PKEY_get0()
1480
1481           This function returns NULL if the key comes from a provider.
1482
1483EVP_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
1488           See "Functions that return an internal key should be treated as
1489           read only".
1490
1491EVP_PKEY_meth_*()
1492
1493           See "Providers are a replacement for engines and low-level method
1494           overrides".
1495
1496EVP_PKEY_new_CMAC_key()
1497
1498           See "Deprecated low-level MAC functions".
1499
1500EVP_PKEY_assign(), EVP_PKEY_set1_DH(), EVP_PKEY_set1_DSA(),
1501           EVP_PKEY_set1_EC_KEY(), EVP_PKEY_set1_RSA()
1502
1503           See "Deprecated low-level key object getters and setters"
1504
1505EVP_PKEY_set1_tls_encodedpoint() EVP_PKEY_get1_tls_encodedpoint()
1506
1507           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
1514EVP_PKEY_set1_engine(), EVP_PKEY_get0_engine()
1515
1516           See "Providers are a replacement for engines and low-level method
1517           overrides".
1518
1519EVP_PKEY_set_alias_type()
1520
1521           This function has been removed. There is no replacement.  See
1522           "EVP_PKEY_set_alias_type() method has been removed"
1523
1524HMAC_Init_ex(), HMAC_Update(), HMAC_Final(), HMAC_size()
1525
1526           See "Deprecated low-level MAC functions".
1527
1528HMAC_CTX_new(), HMAC_CTX_free(), HMAC_CTX_copy(), HMAC_CTX_reset(),
1529           HMAC_CTX_set_flags(), HMAC_CTX_get_md()
1530
1531           See "Deprecated low-level MAC functions".
1532
1533i2d_DHparams(), i2d_DHxparams()
1534
1535           See "Deprecated low-level key reading and writing functions" and
1536           "Migration" in d2i_RSAPrivateKey(3)
1537
1538i2d_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
1542           See "Deprecated low-level key reading and writing functions" and
1543           "Migration" in d2i_RSAPrivateKey(3)
1544
1545i2d_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
1549           See "Deprecated low-level key reading and writing functions" and
1550           "Migration" in d2i_RSAPrivateKey(3)
1551
1552i2d_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
1557           See "Deprecated low-level key reading and writing functions" and
1558           "Migration" in d2i_RSAPrivateKey(3)
1559
1560IDEA_encrypt(), IDEA_set_decrypt_key(), IDEA_set_encrypt_key(),
1561           IDEA_cbc_encrypt(), IDEA_cfb64_encrypt(), IDEA_ecb_encrypt(),
1562           IDEA_ofb64_encrypt()
1563
1564           See "Deprecated low-level encryption functions".  IDEA has been
1565           moved to the Legacy Provider.
1566
1567IDEA_options()
1568
1569           There is no replacement. This function returned a constant string.
1570
1571MD2(), MD2_Init(), MD2_Update(), MD2_Final()
1572
1573           See "Deprecated low-level encryption functions".  MD2 has been
1574           moved to the Legacy Provider.
1575
1576MD2_options()
1577
1578           There is no replacement. This function returned a constant string.
1579
1580MD4(), MD4_Init(), MD4_Update(), MD4_Final(), MD4_Transform()
1581
1582           See "Deprecated low-level encryption functions".  MD4 has been
1583           moved to the Legacy Provider.
1584
1585MDC2(), MDC2_Init(), MDC2_Update(), MDC2_Final()
1586
1587           See "Deprecated low-level encryption functions".  MDC2 has been
1588           moved to the Legacy Provider.
1589
1590MD5(), MD5_Init(), MD5_Update(), MD5_Final(), MD5_Transform()
1591
1592           See "Deprecated low-level encryption functions".
1593
1594NCONF_WIN32()
1595
1596           This undocumented function has no replacement.  See "HISTORY" in
1597           config(5) for more details.
1598
1599OCSP_parse_url()
1600
1601           Use OSSL_HTTP_parse_url(3) instead.
1602
1603OCSP_REQ_CTX type and OCSP_REQ_CTX_*() functions
1604
1605           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
1611OPENSSL_fork_child(), OPENSSL_fork_parent(), OPENSSL_fork_prepare()
1612
1613           There is no replacement for these functions. These pthread fork
1614           support methods were unused by OpenSSL.
1615
1616OSSL_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
1626           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
1630PEM_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
1652           See "Deprecated low-level key reading and writing functions"
1653
1654PKCS1_MGF1()
1655
1656           See "Deprecated low-level encryption functions".
1657
1658RAND_get_rand_method(), RAND_set_rand_method(), RAND_OpenSSL(),
1659           RAND_set_rand_engine()
1660
1661           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
1664RC2_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
1670           See "Deprecated low-level encryption functions".  The Algorithms
1671           "RC2", "RC4" and "RC5" have been moved to the Legacy Provider.
1672
1673RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update(),
1674           RIPEMD160_Final(), RIPEMD160_Transform()
1675
1676           See "Deprecated low-level digest functions".  The RIPE algorithm
1677           has been moved to the Legacy Provider.
1678
1679RSA_bits(), RSA_security_bits(), RSA_size()
1680
1681           Use EVP_PKEY_get_bits(3), EVP_PKEY_get_security_bits(3) and
1682           EVP_PKEY_get_size(3).
1683
1684RSA_check_key(), RSA_check_key_ex()
1685
1686           See "Deprecated low-level validation functions"
1687
1688RSA_clear_flags(), RSA_flags(), RSA_set_flags(), RSA_test_flags(),
1689           RSA_setup_blinding(), RSA_blinding_off(), RSA_blinding_on()
1690
1691           All of these RSA flags have been deprecated without replacement:
1692
1693           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
1697RSA_generate_key_ex(), RSA_generate_multi_prime_key()
1698
1699           See "Deprecated low-level key generation functions".
1700
1701RSA_get0_engine()
1702
1703           See "Providers are a replacement for engines and low-level method
1704           overrides"
1705
1706RSA_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
1713           See "Deprecated low-level key parameter getters"
1714
1715RSA_new(), RSA_free(), RSA_up_ref()
1716
1717           See "Deprecated low-level object creation".
1718
1719RSA_get_default_method(), RSA_get_ex_data and RSA_get_method()
1720
1721           See "Providers are a replacement for engines and low-level method
1722           overrides".
1723
1724RSA_get_version()
1725
1726           There is no replacement.
1727
1728RSA_meth_*(), RSA_new_method(), RSA_null_method and
1729           RSA_PKCS1_OpenSSL()
1730
1731           See "Providers are a replacement for engines and low-level method
1732           overrides".
1733
1734RSA_padding_add_*(), RSA_padding_check_*()
1735
1736           See "Deprecated low-level signing functions" and "Deprecated low-
1737           level encryption functions".
1738
1739RSA_print(), RSA_print_fp()
1740
1741           See "Deprecated low-level key printing functions"
1742
1743RSA_public_encrypt(), RSA_private_decrypt()
1744
1745           See "Deprecated low-level encryption functions"
1746
1747RSA_private_encrypt(), RSA_public_decrypt()
1748
1749           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
1753RSAPrivateKey_dup(), RSAPublicKey_dup()
1754
1755           There is no direct replacement. Applications may use
1756           EVP_PKEY_dup(3).
1757
1758RSAPublicKey_it(), RSAPrivateKey_it()
1759
1760           See "Deprecated low-level key reading and writing functions"
1761
1762RSA_set0_crt_params(), RSA_set0_factors(), RSA_set0_key(),
1763           RSA_set0_multi_prime_params()
1764
1765           See "Deprecated low-level key parameter setters".
1766
1767RSA_set_default_method(), RSA_set_method(), RSA_set_ex_data()
1768
1769           See "Providers are a replacement for engines and low-level method
1770           overrides"
1771
1772RSA_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
1776           See "Deprecated low-level signing functions".
1777
1778RSA_X931_derive_ex(), RSA_X931_generate_key_ex(),
1779           RSA_X931_hash_id()
1780
1781           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
1785SEED_encrypt(), SEED_decrypt(), SEED_set_key(), SEED_cbc_encrypt(),
1786           SEED_cfb128_encrypt(), SEED_ecb_encrypt(), SEED_ofb128_encrypt()
1787
1788           See "Deprecated low-level encryption functions".  The SEED
1789           algorithm has been moved to the Legacy Provider.
1790
1791SHA1_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
1797           See "Deprecated low-level digest functions".
1798
1799SRP_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
1809           There are no replacements for the SRP functions.
1810
1811SSL_CTX_set_tmp_dh_callback(), SSL_set_tmp_dh_callback(),
1812           SSL_CTX_set_tmp_dh(), SSL_set_tmp_dh()
1813
1814           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
1827SSL_CTX_set_tlsext_ticket_key_cb()
1828
1829           Use the new SSL_CTX_set_tlsext_ticket_key_evp_cb(3) function
1830           instead.
1831
1832WHIRLPOOL(), WHIRLPOOL_Init(), WHIRLPOOL_Update(),
1833           WHIRLPOOL_Final(), WHIRLPOOL_BitUpdate()
1834
1835           See "Deprecated low-level digest functions".  The Whirlpool
1836           algorithm has been moved to the Legacy Provider.
1837
1838X509_certificate_type()
1839
1840           This was an undocumented function. Applications can use
1841           X509_get0_pubkey(3) and X509_get0_signature(3) instead.
1842
1843X509_http_nbio(), X509_CRL_http_nbio()
1844
1845           Use X509_load_http(3) and X509_CRL_load_http(3) instead.
1846
1847   Using the FIPS Module in applications
1848       See fips_module(7) and OSSL_PROVIDER-FIPS(7) for details.
1849
1850   OpenSSL command line application changes
1851       New applications
1852
1853       openssl kdf uses the new EVP_KDF(3) API.  openssl kdf uses the new
1854       EVP_MAC(3) API.
1855
1856       Added options
1857
1858       -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
1864       The list app has many new options. See openssl-list(1) for more
1865       information.
1866
1867       -crl_lastupdate and -crl_nextupdate used by openssl ca allows explicit
1868       setting of fields in the generated CRL.
1869
1870       Removed options
1871
1872       Interactive mode is not longer available.
1873
1874       The -crypt option used by openssl passwd.  The -c option used by
1875       openssl x509, openssl dhparam, openssl dsaparam, and openssl ecparam.
1876
1877       Other Changes
1878
1879       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
1886       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
1892       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
1897       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
1901       Default settings
1902
1903       "SHA256" is now the default digest for TS query used by openssl ts.
1904
1905       Deprecated apps
1906
1907       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
1912   TLS Changes
1913       •   TLS 1.3 FFDHE key exchange support added
1914
1915           This uses DH safe prime named groups.
1916
1917       •   Support for fully "pluggable" TLSv1.3 groups.
1918
1919           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
1924       •   SSL and SSL_CTX options are now 64 bit instead of 32 bit.
1925
1926           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
1929           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
1934           See SSL_CTX_get_options(3), SSL_CTX_set_options(3),
1935           SSL_get_options(3) and SSL_set_options(3).
1936
1937SSL_set1_host() and SSL_add1_host() Changes
1938
1939           These functions now take IP literal addresses as well as actual
1940           hostnames.
1941
1942       •   Added SSL option SSL_OP_CLEANSE_PLAINTEXT
1943
1944           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
1949       •   Client-initiated renegotiation is disabled by default.
1950
1951           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
1955       •   Secure renegotiation is now required by default for TLS connections
1956
1957           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
1964       •   Combining the Configure options no-ec and no-dh no longer disables
1965           TLSv1.3
1966
1967           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
1976SSL_CTX_set_ciphersuites() and SSL_set_ciphersuites() changes.
1977
1978           The methods now ignore unknown ciphers.
1979
1980       •   Security callback change.
1981
1982           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
1992       •   New SSL option SSL_OP_IGNORE_UNEXPECTED_EOF
1993
1994           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
1999       •   The security strength of SHA1 and MD5 based signatures in TLS has
2000           been reduced.
2001
2002           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
2013       •   X509 certificates signed using SHA1 are no longer allowed at
2014           security level 1 and above.
2015
2016           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

SEE ALSO

2026       fips_module(7)
2027
2029       Copyright 2021-2022 The OpenSSL Project Authors. All Rights Reserved.
2030
2031       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>.
2035
2036
2037
20383.0.5                             2022-07-05            MIGRATION_GUIDE(7ossl)
Impressum