xref: /freebsd/crypto/openssl/doc/man7/migration_guide.pod (revision 535af610a4fdace6d50960c0ad9be0597eea7a1b)
1=pod
2
3=head1 NAME
4
5migration_guide - OpenSSL migration guide
6
7=head1 SYNOPSIS
8
9See the individual manual pages for details.
10
11=head1 DESCRIPTION
12
13This guide details the changes required to migrate to new versions of OpenSSL.
14Currently this covers OpenSSL 3.0. For earlier versions refer to
15L<https://github.com/openssl/openssl/blob/master/CHANGES.md>.
16For an overview of some of the key concepts introduced in OpenSSL 3.0 see
17L<crypto(7)>.
18
19=head1 OPENSSL 3.0
20
21=head2 Main Changes from OpenSSL 1.1.1
22
23=head3 Major Release
24
25OpenSSL 3.0 is a major release and consequently any application that currently
26uses an older version of OpenSSL will at the very least need to be recompiled in
27order to work with the new version. It is the intention that the large majority
28of applications will work unchanged with OpenSSL 3.0 if those applications
29previously worked with OpenSSL 1.1.1. However this is not guaranteed and some
30changes may be required in some cases. Changes may also be required if
31applications need to take advantage of some of the new features available in
32OpenSSL 3.0 such as the availability of the FIPS module.
33
34=head3 License Change
35
36In previous versions, OpenSSL was licensed under the L<dual OpenSSL and SSLeay
37licenses|https://www.openssl.org/source/license-openssl-ssleay.txt>
38(both licenses apply). From OpenSSL 3.0 this is replaced by the
39L<Apache License v2|https://www.openssl.org/source/apache-license-2.0.txt>.
40
41=head3 Providers and FIPS support
42
43One of the key changes from OpenSSL 1.1.1 is the introduction of the Provider
44concept. Providers collect together and make available algorithm implementations.
45With OpenSSL 3.0 it is possible to specify, either programmatically or via a
46config file, which providers you want to use for any given application.
47OpenSSL 3.0 comes with 5 different providers as standard. Over time third
48parties may distribute additional providers that can be plugged into OpenSSL.
49All algorithm implementations available via providers are accessed through the
50"high level" APIs (for example those functions prefixed with C<EVP>). They cannot
51be accessed using the L</Low Level APIs>.
52
53One of the standard providers available is the FIPS provider. This makes
54available FIPS validated cryptographic algorithms.
55The FIPS provider is disabled by default and needs to be enabled explicitly
56at configuration time using the C<enable-fips> option. If it is enabled,
57the FIPS provider gets built and installed in addition to the other standard
58providers. No separate installation procedure is necessary.
59There is however a dedicated C<install_fips> make target, which serves the
60special purpose of installing only the FIPS provider into an existing
61OpenSSL installation.
62
63Not all algorithms may be available for the application at a particular moment.
64If the application code uses any digest or cipher algorithm via the EVP interface,
65the application should verify the result of the L<EVP_EncryptInit(3)>,
66L<EVP_EncryptInit_ex(3)>, and L<EVP_DigestInit(3)> functions. In case when
67the requested algorithm is not available, these functions will fail.
68
69See also L</Legacy Algorithms> for information on the legacy provider.
70
71See also L</Completing the installation of the FIPS Module> and
72L</Using the FIPS Module in applications>.
73
74=head3 Low Level APIs
75
76OpenSSL has historically provided two sets of APIs for invoking cryptographic
77algorithms: the "high level" APIs (such as the C<EVP> APIs) and the "low level"
78APIs. The high level APIs are typically designed to work across all algorithm
79types. The "low level" APIs are targeted at a specific algorithm implementation.
80For example, the EVP APIs provide the functions L<EVP_EncryptInit_ex(3)>,
81L<EVP_EncryptUpdate(3)> and L<EVP_EncryptFinal(3)> to perform symmetric
82encryption. Those functions can be used with the algorithms AES, CHACHA, 3DES etc.
83On the other hand, to do AES encryption using the low level APIs you would have
84to call AES specific functions such as L<AES_set_encrypt_key(3)>,
85L<AES_encrypt(3)>, and so on. The functions for 3DES are different.
86Use of the low level APIs has been informally discouraged by the OpenSSL
87development team for a long time. However in OpenSSL 3.0 this is made more
88formal. All such low level APIs have been deprecated. You may still use them in
89your applications, but you may start to see deprecation warnings during
90compilation (dependent on compiler support for this). Deprecated APIs may be
91removed from future versions of OpenSSL so you are strongly encouraged to update
92your code to use the high level APIs instead.
93
94This is described in more detail in L</Deprecation of Low Level Functions>
95
96=head3 Legacy Algorithms
97
98Some cryptographic algorithms such as B<MD2> and B<DES> that were available via
99the EVP APIs are now considered legacy and their use is strongly discouraged.
100These legacy EVP algorithms are still available in OpenSSL 3.0 but not by
101default. If you want to use them then you must load the legacy provider.
102This can be as simple as a config file change, or can be done programmatically.
103See L<OSSL_PROVIDER-legacy(7)> for a complete list of algorithms.
104Applications using the EVP APIs to access these algorithms should instead use
105more modern algorithms. If that is not possible then these applications
106should ensure that the legacy provider has been loaded. This can be achieved
107either programmatically or via configuration. See L<crypto(7)> man page for
108more information about providers.
109
110=head3 Engines and "METHOD" APIs
111
112The refactoring to support Providers conflicts internally with the APIs used to
113support engines, including the ENGINE API and any function that creates or
114modifies custom "METHODS" (for example L<EVP_MD_meth_new(3)>,
115L<EVP_CIPHER_meth_new(3)>, L<EVP_PKEY_meth_new(3)>, L<RSA_meth_new(3)>,
116L<EC_KEY_METHOD_new(3)>, etc.). These functions are being deprecated in
117OpenSSL 3.0, and users of these APIs should know that their use can likely
118bypass provider selection and configuration, with unintended consequences.
119This is particularly relevant for applications written to use the OpenSSL 3.0
120FIPS module, as detailed below. Authors and maintainers of external engines are
121strongly encouraged to refactor their code transforming engines into providers
122using the new Provider API and avoiding deprecated methods.
123
124=head3 Support of legacy engines
125
126If openssl is not built without engine support or deprecated API support, engines
127will still work. However, their applicability will be limited.
128
129New algorithms provided via engines will still work.
130
131Engine-backed keys can be loaded via custom B<OSSL_STORE> implementation.
132In this case the B<EVP_PKEY> objects created via L<ENGINE_load_private_key(3)>
133will be considered legacy and will continue to work.
134
135To ensure the future compatibility, the engines should be turned to providers.
136To prefer the provider-based hardware offload, you can specify the default
137properties to prefer your provider.
138
139=head3 Versioning Scheme
140
141The OpenSSL versioning scheme has changed with the OpenSSL 3.0 release. The new
142versioning scheme has this format:
143
144MAJOR.MINOR.PATCH
145
146For OpenSSL 1.1.1 and below, different patch levels were indicated by a letter
147at the end of the release version number. This will no longer be used and
148instead the patch level is indicated by the final number in the version. A
149change in the second (MINOR) number indicates that new features may have been
150added. OpenSSL versions with the same major number are API and ABI compatible.
151If the major number changes then API and ABI compatibility is not guaranteed.
152
153For more information, see L<OpenSSL_version(3)>.
154
155=head3 Other major new features
156
157=head4 Certificate Management Protocol (CMP, RFC 4210)
158
159This also covers CRMF (RFC 4211) and HTTP transfer (RFC 6712)
160See L<openssl-cmp(1)> and L<OSSL_CMP_exec_certreq(3)> as starting points.
161
162=head4 HTTP(S) client
163
164A proper HTTP(S) client that supports GET and POST, redirection, plain and
165ASN.1-encoded contents, proxies, and timeouts.
166
167=head4 Key Derivation Function API (EVP_KDF)
168
169This simplifies the process of adding new KDF and PRF implementations.
170
171Previously KDF algorithms had been shoe-horned into using the EVP_PKEY object
172which was not a logical mapping.
173Existing applications that use KDF algorithms using EVP_PKEY
174(scrypt, TLS1 PRF and HKDF) may be slower as they use an EVP_KDF bridge
175internally.
176All new applications should use the new L<EVP_KDF(3)> interface.
177See also L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)> and
178L<OSSL_PROVIDER-FIPS(7)/Key Derivation Function (KDF)>.
179
180=head4 Message Authentication Code API (EVP_MAC)
181
182This simplifies the process of adding MAC implementations.
183
184This includes a generic EVP_PKEY to EVP_MAC bridge, to facilitate the continued
185use of MACs through raw private keys in functionality such as
186L<EVP_DigestSign(3)> and L<EVP_DigestVerify(3)>.
187
188All new applications should use the new L<EVP_MAC(3)> interface.
189See also L<OSSL_PROVIDER-default(7)/Message Authentication Code (MAC)>
190and L<OSSL_PROVIDER-FIPS(7)/Message Authentication Code (MAC)>.
191
192=head4 Algorithm Fetching
193
194Using calls to convenience functions such as EVP_sha256() and EVP_aes_256_gcm() may
195incur a performance penalty when using providers.
196Retrieving algorithms from providers involves searching for an algorithm by name.
197This is much slower than directly accessing a method table.
198It is recommended to prefetch algorithms if an algorithm is used many times.
199See L<crypto(7)/Performance>, L<crypto(7)/Explicit fetching> and L<crypto(7)/Implicit fetching>.
200
201=head4 Support for Linux Kernel TLS
202
203In order to use KTLS, support for it must be compiled in using the
204C<enable-ktls> configuration option. It must also be enabled at run time using
205the B<SSL_OP_ENABLE_KTLS> option.
206
207=head4 New Algorithms
208
209=over 4
210
211=item *
212
213KDF algorithms "SINGLE STEP" and "SSH"
214
215See L<EVP_KDF-SS(7)> and L<EVP_KDF-SSHKDF(7)>
216
217=item *
218
219MAC Algorithms "GMAC" and "KMAC"
220
221See L<EVP_MAC-GMAC(7)> and L<EVP_MAC-KMAC(7)>.
222
223=item *
224
225KEM Algorithm "RSASVE"
226
227See L<EVP_KEM-RSA(7)>.
228
229=item *
230
231Cipher Algorithm "AES-SIV"
232
233See L<EVP_EncryptInit(3)/SIV Mode>.
234
235=item *
236
237AES Key Wrap inverse ciphers supported by EVP layer.
238
239The inverse ciphers use AES decryption for wrapping, and AES encryption for
240unwrapping. The algorithms are: "AES-128-WRAP-INV", "AES-192-WRAP-INV",
241"AES-256-WRAP-INV", "AES-128-WRAP-PAD-INV", "AES-192-WRAP-PAD-INV" and
242"AES-256-WRAP-PAD-INV".
243
244=item *
245
246CTS ciphers added to EVP layer.
247
248The algorithms are "AES-128-CBC-CTS", "AES-192-CBC-CTS", "AES-256-CBC-CTS",
249"CAMELLIA-128-CBC-CTS", "CAMELLIA-192-CBC-CTS" and "CAMELLIA-256-CBC-CTS".
250CS1, CS2 and CS3 variants are supported.
251
252=back
253
254=head4 CMS and PKCS#7 updates
255
256=over 4
257
258=item *
259
260Added CAdES-BES signature verification support.
261
262=item *
263
264Added CAdES-BES signature scheme and attributes support (RFC 5126) to CMS API.
265
266=item *
267
268Added AuthEnvelopedData content type structure (RFC 5083) using AES_GCM
269
270This uses the AES-GCM parameter (RFC 5084) for the Cryptographic Message Syntax.
271Its purpose is to support encryption and decryption of a digital envelope that
272is both authenticated and encrypted using AES GCM mode.
273
274=item *
275
276L<PKCS7_get_octet_string(3)> and L<PKCS7_type_is_other(3)> were made public.
277
278=back
279
280=head4 PKCS#12 API updates
281
282The default algorithms for pkcs12 creation with the PKCS12_create() function
283were changed to more modern PBKDF2 and AES based algorithms. The default
284MAC iteration count was changed to PKCS12_DEFAULT_ITER to make it equal
285with the password-based encryption iteration count. The default digest
286algorithm for the MAC computation was changed to SHA-256. The pkcs12
287application now supports -legacy option that restores the previous
288default algorithms to support interoperability with legacy systems.
289
290Added enhanced PKCS#12 APIs which accept a library context B<OSSL_LIB_CTX>
291and (where relevant) a property query. Other APIs which handle PKCS#7 and
292PKCS#8 objects have also been enhanced where required. This includes:
293
294L<PKCS12_add_key_ex(3)>, L<PKCS12_add_safe_ex(3)>, L<PKCS12_add_safes_ex(3)>,
295L<PKCS12_create_ex(3)>, L<PKCS12_decrypt_skey_ex(3)>, L<PKCS12_init_ex(3)>,
296L<PKCS12_item_decrypt_d2i_ex(3)>, L<PKCS12_item_i2d_encrypt_ex(3)>,
297L<PKCS12_key_gen_asc_ex(3)>, L<PKCS12_key_gen_uni_ex(3)>, L<PKCS12_key_gen_utf8_ex(3)>,
298L<PKCS12_pack_p7encdata_ex(3)>, L<PKCS12_pbe_crypt_ex(3)>, L<PKCS12_PBE_keyivgen_ex(3)>,
299L<PKCS12_SAFEBAG_create_pkcs8_encrypt_ex(3)>, L<PKCS5_pbe2_set_iv_ex(3)>,
300L<PKCS5_pbe_set0_algor_ex(3)>, L<PKCS5_pbe_set_ex(3)>, L<PKCS5_pbkdf2_set_ex(3)>,
301L<PKCS5_v2_PBE_keyivgen_ex(3)>, L<PKCS5_v2_scrypt_keyivgen_ex(3)>,
302L<PKCS8_decrypt_ex(3)>, L<PKCS8_encrypt_ex(3)>, L<PKCS8_set0_pbe_ex(3)>.
303
304As part of this change the EVP_PBE_xxx APIs can also accept a library
305context and property query and will call an extended version of the key/IV
306derivation function which supports these parameters. This includes
307L<EVP_PBE_CipherInit_ex(3)>, L<EVP_PBE_find_ex(3)> and L<EVP_PBE_scrypt_ex(3)>.
308
309=head4 Windows thread synchronization changes
310
311Windows thread synchronization uses read/write primitives (SRWLock) when
312supported by the OS, otherwise CriticalSection continues to be used.
313
314=head4 Trace API
315
316A new generic trace API has been added which provides support for enabling
317instrumentation through trace output. This feature is mainly intended as an aid
318for developers and is disabled by default. To utilize it, OpenSSL needs to be
319configured with the C<enable-trace> option.
320
321If the tracing API is enabled, the application can activate trace output by
322registering BIOs as trace channels for a number of tracing and debugging
323categories. See L<OSSL_trace_enabled(3)>.
324
325=head4 Key validation updates
326
327L<EVP_PKEY_public_check(3)> and L<EVP_PKEY_param_check(3)> now work for
328more key types. This includes RSA, DSA, ED25519, X25519, ED448 and X448.
329Previously (in 1.1.1) they would return -2. For key types that do not have
330parameters then L<EVP_PKEY_param_check(3)> will always return 1.
331
332=head3 Other notable deprecations and changes
333
334=head4 The function code part of an OpenSSL error code is no longer relevant
335
336This code is now always set to zero. Related functions are deprecated.
337
338=head4 STACK and HASH macros have been cleaned up
339
340The type-safe wrappers are declared everywhere and implemented once.
341See L<DEFINE_STACK_OF(3)> and L<DECLARE_LHASH_OF(3)>.
342
343=head4 The RAND_DRBG subsystem has been removed
344
345The new L<EVP_RAND(3)> is a partial replacement: the DRBG callback framework is
346absent. The RAND_DRBG API did not fit well into the new provider concept as
347implemented by EVP_RAND and EVP_RAND_CTX.
348
349=head4 Removed FIPS_mode() and FIPS_mode_set()
350
351These functions are legacy APIs that are not applicable to the new provider
352model. Applications should instead use
353L<EVP_default_properties_is_fips_enabled(3)> and
354L<EVP_default_properties_enable_fips(3)>.
355
356=head4 Key generation is slower
357
358The Miller-Rabin test now uses 64 rounds, which is used for all prime generation,
359including RSA key generation. This affects the time for larger keys sizes.
360
361The default key generation method for the regular 2-prime RSA keys was changed
362to the FIPS186-4 B.3.6 method (Generation of Probable Primes with Conditions
363Based on Auxiliary Probable Primes). This method is slower than the original
364method.
365
366=head4 Change PBKDF2 to conform to SP800-132 instead of the older PKCS5 RFC2898
367
368This checks that the salt length is at least 128 bits, the derived key length is
369at least 112 bits, and that the iteration count is at least 1000.
370For backwards compatibility these checks are disabled by default in the
371default provider, but are enabled by default in the FIPS provider.
372
373To enable or disable the checks see B<OSSL_KDF_PARAM_PKCS5> in
374L<EVP_KDF-PBKDF2(7)>. The parameter can be set using L<EVP_KDF_derive(3)>.
375
376=head4 Enforce a minimum DH modulus size of 512 bits
377
378Smaller sizes now result in an error.
379
380=head4 SM2 key changes
381
382EC EVP_PKEYs with the SM2 curve have been reworked to automatically become
383EVP_PKEY_SM2 rather than EVP_PKEY_EC.
384
385Unlike in previous OpenSSL versions, this means that applications cannot
386call C<EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2)> to get SM2 computations.
387
388Parameter and key generation is also reworked to make it possible
389to generate EVP_PKEY_SM2 parameters and keys. Applications must now generate
390SM2 keys directly and must not create an EVP_PKEY_EC key first. It is no longer
391possible to import an SM2 key with domain parameters other than the SM2 elliptic
392curve ones.
393
394Validation of SM2 keys has been separated from the validation of regular EC
395keys, allowing to improve the SM2 validation process to reject loaded private
396keys that are not conforming to the SM2 ISO standard.
397In particular, a private scalar I<k> outside the range I<< 1 <= k < n-1 >> is
398now correctly rejected.
399
400=head4 EVP_PKEY_set_alias_type() method has been removed
401
402This function made a B<EVP_PKEY> object mutable after it had been set up. In
403OpenSSL 3.0 it was decided that a provided key should not be able to change its
404type, so this function has been removed.
405
406=head4 Functions that return an internal key should be treated as read only
407
408Functions such as L<EVP_PKEY_get0_RSA(3)> behave slightly differently in
409OpenSSL 3.0. Previously they returned a pointer to the low-level key used
410internally by libcrypto. From OpenSSL 3.0 this key may now be held in a
411provider. Calling these functions will only return a handle on the internal key
412where the EVP_PKEY was constructed using this key in the first place, for
413example using a function or macro such as L<EVP_PKEY_assign_RSA(3)>,
414L<EVP_PKEY_set1_RSA(3)>, etc.
415Where the EVP_PKEY holds a provider managed key, then these functions now return
416a cached copy of the key. Changes to the internal provider key that take place
417after the first time the cached key is accessed will not be reflected back in
418the cached copy. Similarly any changes made to the cached copy by application
419code will not be reflected back in the internal provider key.
420
421For the above reasons the keys returned from these functions should typically be
422treated as read-only. To emphasise this the value returned from
423L<EVP_PKEY_get0_RSA(3)>, L<EVP_PKEY_get0_DSA(3)>, L<EVP_PKEY_get0_EC_KEY(3)> and
424L<EVP_PKEY_get0_DH(3)> have been made const. This may break some existing code.
425Applications broken by this change should be modified. The preferred solution is
426to refactor the code to avoid the use of these deprecated functions. Failing
427this the code should be modified to use a const pointer instead.
428The L<EVP_PKEY_get1_RSA(3)>, L<EVP_PKEY_get1_DSA(3)>, L<EVP_PKEY_get1_EC_KEY(3)>
429and L<EVP_PKEY_get1_DH(3)> functions continue to return a non-const pointer to
430enable them to be "freed". However they should also be treated as read-only.
431
432=head4 The public key check has moved from EVP_PKEY_derive() to EVP_PKEY_derive_set_peer()
433
434This may mean result in an error in L<EVP_PKEY_derive_set_peer(3)> rather than
435during L<EVP_PKEY_derive(3)>.
436To disable this check use EVP_PKEY_derive_set_peer_ex(dh, peer, 0).
437
438=head4 The print format has cosmetic changes for some functions
439
440The output from numerous "printing" functions such as L<X509_signature_print(3)>,
441L<X509_print_ex(3)>, L<X509_CRL_print_ex(3)>, and other similar functions has been
442amended such that there may be cosmetic differences between the output
443observed in 1.1.1 and 3.0. This also applies to the B<-text> output from the
444B<openssl x509> and B<openssl crl> applications.
445
446=head4 Interactive mode from the B<openssl> program has been removed
447
448From now on, running it without arguments is equivalent to B<openssl help>.
449
450=head4 The error return values from some control calls (ctrl) have changed
451
452One significant change is that controls which used to return -2 for
453invalid inputs, now return -1 indicating a generic error condition instead.
454
455=head4 DH and DHX key types have different settable parameters
456
457Previously (in 1.1.1) these conflicting parameters were allowed, but will now
458result in errors. See L<EVP_PKEY-DH(7)> for further details. This affects the
459behaviour of L<openssl-genpkey(1)> for DH parameter generation.
460
461=head4 EVP_CIPHER_CTX_set_flags() ordering change
462
463If using a cipher from a provider the B<EVP_CIPH_FLAG_LENGTH_BITS> flag can only
464be set B<after> the cipher has been assigned to the cipher context.
465See L<EVP_EncryptInit(3)/FLAGS> for more information.
466
467=head4 Validation of operation context parameters
468
469Due to move of the implementation of cryptographic operations to the
470providers, validation of various operation parameters can be postponed until
471the actual operation is executed where previously it happened immediately
472when an operation parameter was set.
473
474For example when setting an unsupported curve with
475EVP_PKEY_CTX_set_ec_paramgen_curve_nid() this function call will not fail
476but later keygen operations with the EVP_PKEY_CTX will fail.
477
478=head4 Removal of function code from the error codes
479
480The function code part of the error code is now always set to 0. For that
481reason the ERR_GET_FUNC() macro was removed. Applications must resolve
482the error codes only using the library number and the reason code.
483
484=head4 ChaCha20-Poly1305 cipher does not allow a truncated IV length to be used
485
486In OpenSSL 3.0 setting the IV length to any value other than 12 will result in an
487error.
488Prior to OpenSSL 3.0 the ivlen could be smaller that the required 12 byte length,
489using EVP_CIPHER_CTX_ctrl(ctx, EVP_CRTL_AEAD_SET_IVLEN, ivlen, NULL). This resulted
490in an IV that had leading zero padding.
491
492=head2 Installation and Compilation
493
494Please refer to the INSTALL.md file in the top of the distribution for
495instructions on how to build and install OpenSSL 3.0. Please also refer to the
496various platform specific NOTES files for your specific platform.
497
498=head2 Upgrading from OpenSSL 1.1.1
499
500Upgrading to OpenSSL 3.0 from OpenSSL 1.1.1 should be relatively straight
501forward in most cases. The most likely area where you will encounter problems
502is if you have used low level APIs in your code (as discussed above). In that
503case you are likely to start seeing deprecation warnings when compiling your
504application. If this happens you have 3 options:
505
506=over 4
507
508=item 1.
509
510Ignore the warnings. They are just warnings. The deprecated functions are still present and you may still use them. However be aware that they may be removed from a future version of OpenSSL.
511
512=item 2.
513
514Suppress the warnings. Refer to your compiler documentation on how to do this.
515
516=item 3.
517
518Remove your usage of the low level APIs. In this case you will need to rewrite your code to use the high level APIs instead
519
520=back
521
522=head3 Error code changes
523
524As OpenSSL 3.0 provides a brand new Encoder/Decoder mechanism for working with
525widely used file formats, application code that checks for particular error
526reason codes on key loading failures might need an update.
527
528Password-protected keys may deserve special attention. If only some errors
529are treated as an indicator that the user should be asked about the password again,
530it's worth testing these scenarios and processing the newly relevant codes.
531
532There may be more cases to treat specially, depending on the calling application code.
533
534=head2 Upgrading from OpenSSL 1.0.2
535
536Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 is likely to be significantly more
537difficult. In addition to the issues discussed above in the section about
538L</Upgrading from OpenSSL 1.1.1>, the main things to be aware of are:
539
540=over 4
541
542=item 1.
543
544The build and installation procedure has changed significantly.
545
546Check the file INSTALL.md in the top of the installation for instructions on how
547to build and install OpenSSL for your platform. Also read the various NOTES
548files in the same directory, as applicable for your platform.
549
550=item 2.
551
552Many structures have been made opaque in OpenSSL 3.0.
553
554The structure definitions have been removed from the public header files and
555moved to internal header files. In practice this means that you can no longer
556stack allocate some structures. Instead they must be heap allocated through some
557function call (typically those function names have a C<_new> suffix to them).
558Additionally you must use "setter" or "getter" functions to access the fields
559within those structures.
560
561For example code that previously looked like this:
562
563 EVP_MD_CTX md_ctx;
564
565 /* This line will now generate compiler errors */
566 EVP_MD_CTX_init(&md_ctx);
567
568The code needs to be amended to look like this:
569
570 EVP_MD_CTX *md_ctx;
571
572 md_ctx = EVP_MD_CTX_new();
573 ...
574 ...
575 EVP_MD_CTX_free(md_ctx);
576
577=item 3.
578
579Support for TLSv1.3 has been added.
580
581This has a number of implications for SSL/TLS applications. See the
582L<TLS1.3 page|https://wiki.openssl.org/index.php/TLS1.3> for further details.
583
584=back
585
586More details about the breaking changes between OpenSSL versions 1.0.2 and 1.1.0
587can be found on the
588L<OpenSSL 1.1.0 Changes page|https://wiki.openssl.org/index.php/OpenSSL_1.1.0_Changes>.
589
590=head3 Upgrading from the OpenSSL 2.0 FIPS Object Module
591
592The OpenSSL 2.0 FIPS Object Module was a separate download that had to be built
593separately and then integrated into your main OpenSSL 1.0.2 build.
594In OpenSSL 3.0 the FIPS support is fully integrated into the mainline version of
595OpenSSL and is no longer a separate download. For further information see
596L</Completing the installation of the FIPS Module>.
597
598The function calls FIPS_mode() and FIPS_mode_set() have been removed
599from OpenSSL 3.0. You should rewrite your application to not use them.
600See L<fips_module(7)> and L<OSSL_PROVIDER-FIPS(7)> for details.
601
602=head2 Completing the installation of the FIPS Module
603
604The FIPS Module will be built and installed automatically if FIPS support has
605been configured. The current documentation can be found in the
606L<README-FIPS|https://github.com/openssl/openssl/blob/master/README-FIPS.md> file.
607
608=head2 Programming
609
610Applications written to work with OpenSSL 1.1.1 will mostly just work with
611OpenSSL 3.0. However changes will be required if you want to take advantage of
612some of the new features that OpenSSL 3.0 makes available. In order to do that
613you need to understand some new concepts introduced in OpenSSL 3.0.
614Read L<crypto(7)/Library contexts> for further information.
615
616=head3 Library Context
617
618A library context allows different components of a complex application to each
619use a different library context and have different providers loaded with
620different configuration settings.
621See L<crypto(7)/Library contexts> for further info.
622
623If the user creates an B<OSSL_LIB_CTX> via L<OSSL_LIB_CTX_new(3)> then many
624functions may need to be changed to pass additional parameters to handle the
625library context.
626
627=head4 Using a Library Context - Old functions that should be changed
628
629If a library context is needed then all EVP_* digest functions that return a
630B<const EVP_MD *> such as EVP_sha256() should be replaced with a call to
631L<EVP_MD_fetch(3)>. See L<crypto(7)/ALGORITHM FETCHING>.
632
633If a library context is needed then all EVP_* cipher functions that return a
634B<const EVP_CIPHER *> such as EVP_aes_128_cbc() should be replaced vith a call to
635L<EVP_CIPHER_fetch(3)>. See L<crypto(7)/ALGORITHM FETCHING>.
636
637Some functions can be passed an object that has already been set up with a library
638context such as L<d2i_X509(3)>, L<d2i_X509_CRL(3)>, L<d2i_X509_REQ(3)> and
639L<d2i_X509_PUBKEY(3)>. If NULL is passed instead then the created object will be
640set up with the default library context. Use L<X509_new_ex(3)>,
641L<X509_CRL_new_ex(3)>, L<X509_REQ_new_ex(3)> and L<X509_PUBKEY_new_ex(3)> if a
642library context is required.
643
644All functions listed below with a I<NAME> have a replacement function I<NAME_ex>
645that takes B<OSSL_LIB_CTX> as an additional argument. Functions that have other
646mappings are listed along with the respective name.
647
648=over 4
649
650=item *
651
652L<ASN1_item_new(3)>, L<ASN1_item_d2i(3)>, L<ASN1_item_d2i_fp(3)>,
653L<ASN1_item_d2i_bio(3)>, L<ASN1_item_sign(3)> and L<ASN1_item_verify(3)>
654
655=item *
656
657L<BIO_new(3)>
658
659=item *
660
661b2i_RSA_PVK_bio() and i2b_PVK_bio()
662
663=item *
664
665L<BN_CTX_new(3)> and L<BN_CTX_secure_new(3)>
666
667=item *
668
669L<CMS_AuthEnvelopedData_create(3)>, L<CMS_ContentInfo_new(3)>, L<CMS_data_create(3)>,
670L<CMS_digest_create(3)>, L<CMS_EncryptedData_encrypt(3)>, L<CMS_encrypt(3)>,
671L<CMS_EnvelopedData_create(3)>, L<CMS_ReceiptRequest_create0(3)> and L<CMS_sign(3)>
672
673=item *
674
675L<CONF_modules_load_file(3)>
676
677=item *
678
679L<CTLOG_new(3)>, L<CTLOG_new_from_base64(3)> and L<CTLOG_STORE_new(3)>
680
681=item *
682
683L<CT_POLICY_EVAL_CTX_new(3)>
684
685=item *
686
687L<d2i_AutoPrivateKey(3)>, L<d2i_PrivateKey(3)> and L<d2i_PUBKEY(3)>
688
689=item *
690
691L<d2i_PrivateKey_bio(3)> and L<d2i_PrivateKey_fp(3)>
692
693Use L<d2i_PrivateKey_ex_bio(3)> and L<d2i_PrivateKey_ex_fp(3)>
694
695=item *
696
697L<EC_GROUP_new(3)>
698
699Use L<EC_GROUP_new_by_curve_name_ex(3)> or L<EC_GROUP_new_from_params(3)>.
700
701=item *
702
703L<EVP_DigestSignInit(3)> and L<EVP_DigestVerifyInit(3)>
704
705=item *
706
707L<EVP_PBE_CipherInit(3)>, L<EVP_PBE_find(3)> and L<EVP_PBE_scrypt(3)>
708
709=item *
710
711L<PKCS5_PBE_keyivgen(3)>
712
713=item *
714
715L<EVP_PKCS82PKEY(3)>
716
717=item *
718
719L<EVP_PKEY_CTX_new_id(3)>
720
721Use L<EVP_PKEY_CTX_new_from_name(3)>
722
723=item *
724
725L<EVP_PKEY_derive_set_peer(3)>, L<EVP_PKEY_new_raw_private_key(3)>
726and L<EVP_PKEY_new_raw_public_key(3)>
727
728=item *
729
730L<EVP_SignFinal(3)> and L<EVP_VerifyFinal(3)>
731
732=item *
733
734L<NCONF_new(3)>
735
736=item *
737
738L<OCSP_RESPID_match(3)> and L<OCSP_RESPID_set_by_key(3)>
739
740=item *
741
742L<OPENSSL_thread_stop(3)>
743
744=item *
745
746L<OSSL_STORE_open(3)>
747
748=item *
749
750L<PEM_read_bio_Parameters(3)>, L<PEM_read_bio_PrivateKey(3)>, L<PEM_read_bio_PUBKEY(3)>,
751L<PEM_read_PrivateKey(3)> and L<PEM_read_PUBKEY(3)>
752
753=item *
754
755L<PEM_write_bio_PrivateKey(3)>, L<PEM_write_bio_PUBKEY(3)>, L<PEM_write_PrivateKey(3)>
756and L<PEM_write_PUBKEY(3)>
757
758=item *
759
760L<PEM_X509_INFO_read_bio(3)> and L<PEM_X509_INFO_read(3)>
761
762=item *
763
764L<PKCS12_add_key(3)>, L<PKCS12_add_safe(3)>, L<PKCS12_add_safes(3)>,
765L<PKCS12_create(3)>, L<PKCS12_decrypt_skey(3)>, L<PKCS12_init(3)>, L<PKCS12_item_decrypt_d2i(3)>,
766L<PKCS12_item_i2d_encrypt(3)>, L<PKCS12_key_gen_asc(3)>, L<PKCS12_key_gen_uni(3)>,
767L<PKCS12_key_gen_utf8(3)>, L<PKCS12_pack_p7encdata(3)>, L<PKCS12_pbe_crypt(3)>,
768L<PKCS12_PBE_keyivgen(3)>, L<PKCS12_SAFEBAG_create_pkcs8_encrypt(3)>
769
770=item *
771
772L<PKCS5_pbe_set0_algor(3)>, L<PKCS5_pbe_set(3)>, L<PKCS5_pbe2_set_iv(3)>,
773L<PKCS5_pbkdf2_set(3)> and L<PKCS5_v2_scrypt_keyivgen(3)>
774
775=item *
776
777L<PKCS7_encrypt(3)>, L<PKCS7_new(3)> and L<PKCS7_sign(3)>
778
779=item *
780
781L<PKCS8_decrypt(3)>, L<PKCS8_encrypt(3)> and L<PKCS8_set0_pbe(3)>
782
783=item *
784
785L<RAND_bytes(3)> and L<RAND_priv_bytes(3)>
786
787=item *
788
789L<SMIME_write_ASN1(3)>
790
791=item *
792
793L<SSL_load_client_CA_file(3)>
794
795=item *
796
797L<SSL_CTX_new(3)>
798
799=item *
800
801L<TS_RESP_CTX_new(3)>
802
803=item *
804
805L<X509_CRL_new(3)>
806
807=item *
808
809L<X509_load_cert_crl_file(3)> and L<X509_load_cert_file(3)>
810
811=item *
812
813L<X509_LOOKUP_by_subject(3)> and L<X509_LOOKUP_ctrl(3)>
814
815=item *
816
817L<X509_NAME_hash(3)>
818
819=item *
820
821L<X509_new(3)>
822
823=item *
824
825L<X509_REQ_new(3)> and L<X509_REQ_verify(3)>
826
827=item *
828
829L<X509_STORE_CTX_new(3)>, L<X509_STORE_set_default_paths(3)>, L<X509_STORE_load_file(3)>,
830L<X509_STORE_load_locations(3)> and L<X509_STORE_load_store(3)>
831
832=back
833
834=head4 New functions that use a Library context
835
836The following functions can be passed a library context if required.
837Passing NULL will use the default library context.
838
839=over 4
840
841=item *
842
843L<BIO_new_from_core_bio(3)>
844
845=item *
846
847L<EVP_ASYM_CIPHER_fetch(3)> and L<EVP_ASYM_CIPHER_do_all_provided(3)>
848
849=item *
850
851L<EVP_CIPHER_fetch(3)> and L<EVP_CIPHER_do_all_provided(3)>
852
853=item *
854
855L<EVP_default_properties_enable_fips(3)> and
856L<EVP_default_properties_is_fips_enabled(3)>
857
858=item *
859
860L<EVP_KDF_fetch(3)> and L<EVP_KDF_do_all_provided(3)>
861
862=item *
863
864L<EVP_KEM_fetch(3)> and L<EVP_KEM_do_all_provided(3)>
865
866=item *
867
868L<EVP_KEYEXCH_fetch(3)> and L<EVP_KEYEXCH_do_all_provided(3)>
869
870=item *
871
872L<EVP_KEYMGMT_fetch(3)> and L<EVP_KEYMGMT_do_all_provided(3)>
873
874=item *
875
876L<EVP_MAC_fetch(3)> and L<EVP_MAC_do_all_provided(3)>
877
878=item *
879
880L<EVP_MD_fetch(3)> and L<EVP_MD_do_all_provided(3)>
881
882=item *
883
884L<EVP_PKEY_CTX_new_from_pkey(3)>
885
886=item *
887
888L<EVP_PKEY_Q_keygen(3)>
889
890=item *
891
892L<EVP_Q_mac(3)> and L<EVP_Q_digest(3)>
893
894=item *
895
896L<EVP_RAND(3)> and L<EVP_RAND_do_all_provided(3)>
897
898=item *
899
900L<EVP_set_default_properties(3)>
901
902=item *
903
904L<EVP_SIGNATURE_fetch(3)> and L<EVP_SIGNATURE_do_all_provided(3)>
905
906=item *
907
908L<OSSL_CMP_CTX_new(3)> and L<OSSL_CMP_SRV_CTX_new(3)>
909
910=item *
911
912L<OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert(3)>
913
914=item *
915
916L<OSSL_CRMF_MSG_create_popo(3)> and L<OSSL_CRMF_MSGS_verify_popo(3)>
917
918=item *
919
920L<OSSL_CRMF_pbm_new(3)> and L<OSSL_CRMF_pbmp_new(3)>
921
922=item *
923
924L<OSSL_DECODER_CTX_add_extra(3)> and L<OSSL_DECODER_CTX_new_for_pkey(3)>
925
926=item *
927
928L<OSSL_DECODER_fetch(3)> and L<OSSL_DECODER_do_all_provided(3)>
929
930=item *
931
932L<OSSL_ENCODER_CTX_add_extra(3)>
933
934=item *
935
936L<OSSL_ENCODER_fetch(3)> and L<OSSL_ENCODER_do_all_provided(3)>
937
938=item *
939
940L<OSSL_LIB_CTX_free(3)>, L<OSSL_LIB_CTX_load_config(3)> and L<OSSL_LIB_CTX_set0_default(3)>
941
942=item *
943
944L<OSSL_PROVIDER_add_builtin(3)>, L<OSSL_PROVIDER_available(3)>,
945L<OSSL_PROVIDER_do_all(3)>, L<OSSL_PROVIDER_load(3)>,
946L<OSSL_PROVIDER_set_default_search_path(3)> and L<OSSL_PROVIDER_try_load(3)>
947
948=item *
949
950L<OSSL_SELF_TEST_get_callback(3)> and L<OSSL_SELF_TEST_set_callback(3)>
951
952=item *
953
954L<OSSL_STORE_attach(3)>
955
956=item *
957
958L<OSSL_STORE_LOADER_fetch(3)> and L<OSSL_STORE_LOADER_do_all_provided(3)>
959
960=item *
961
962L<RAND_get0_primary(3)>, L<RAND_get0_private(3)>, L<RAND_get0_public(3)>,
963L<RAND_set_DRBG_type(3)> and L<RAND_set_seed_source_type(3)>
964
965=back
966
967=head3 Providers
968
969Providers are described in detail here L<crypto(7)/Providers>.
970See also L<crypto(7)/OPENSSL PROVIDERS>.
971
972=head3 Fetching algorithms and property queries
973
974Implicit and Explicit Fetching is described in detail here
975L<crypto(7)/ALGORITHM FETCHING>.
976
977=head3 Mapping EVP controls and flags to provider L<OSSL_PARAM(3)> parameters
978
979The existing functions for controls (such as L<EVP_CIPHER_CTX_ctrl(3)>) and
980manipulating flags (such as L<EVP_MD_CTX_set_flags(3)>)internally use
981B<OSSL_PARAMS> to pass information to/from provider objects.
982See L<OSSL_PARAM(3)> for additional information related to parameters.
983
984For ciphers see L<EVP_EncryptInit(3)/CONTROLS>, L<EVP_EncryptInit(3)/FLAGS> and
985L<EVP_EncryptInit(3)/PARAMETERS>.
986
987For digests see L<EVP_DigestInit(3)/CONTROLS>, L<EVP_DigestInit(3)/FLAGS> and
988L<EVP_DigestInit(3)/PARAMETERS>.
989
990=head3 Deprecation of Low Level Functions
991
992A significant number of APIs have been deprecated in OpenSSL 3.0.
993This section describes some common categories of deprecations.
994See L</Deprecated function mappings> for the list of deprecated functions
995that refer to these categories.
996
997=head4 Providers are a replacement for engines and low-level method overrides
998
999Any accessor that uses an ENGINE is deprecated (such as EVP_PKEY_set1_engine()).
1000Applications using engines should instead use providers.
1001
1002Before providers were added algorithms were overridden by changing the methods
1003used by algorithms. All these methods such as RSA_new_method() and RSA_meth_new()
1004are now deprecated and can be replaced by using providers instead.
1005
1006=head4 Deprecated i2d and d2i functions for low-level key types
1007
1008Any i2d and d2i functions such as d2i_DHparams() that take a low-level key type
1009have been deprecated. Applications should instead use the L<OSSL_DECODER(3)> and
1010L<OSSL_ENCODER(3)> APIs to read and write files.
1011See L<d2i_RSAPrivateKey(3)/Migration> for further details.
1012
1013=head4 Deprecated low-level key object getters and setters
1014
1015Applications that set or get low-level key objects (such as EVP_PKEY_set1_DH()
1016or EVP_PKEY_get0()) should instead use the OSSL_ENCODER
1017(See L<OSSL_ENCODER_to_bio(3)>) or OSSL_DECODER (See L<OSSL_DECODER_from_bio(3)>)
1018APIs, or alternatively use L<EVP_PKEY_fromdata(3)> or L<EVP_PKEY_todata(3)>.
1019
1020=head4 Deprecated low-level key parameter getters
1021
1022Functions that access low-level objects directly such as L<RSA_get0_n(3)> are now
1023deprecated. Applications should use one of L<EVP_PKEY_get_bn_param(3)>,
1024L<EVP_PKEY_get_int_param(3)>, l<EVP_PKEY_get_size_t_param(3)>,
1025L<EVP_PKEY_get_utf8_string_param(3)>, L<EVP_PKEY_get_octet_string_param(3)> or
1026L<EVP_PKEY_get_params(3)> to access fields from an EVP_PKEY.
1027Gettable parameters are listed in L<EVP_PKEY-RSA(7)/Common RSA parameters>,
1028L<EVP_PKEY-DH(7)/DH parameters>, L<EVP_PKEY-DSA(7)/DSA parameters>,
1029L<EVP_PKEY-FFC(7)/FFC parameters>, L<EVP_PKEY-EC(7)/Common EC parameters> and
1030L<EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>.
1031Applications may also use L<EVP_PKEY_todata(3)> to return all fields.
1032
1033=head4 Deprecated low-level key parameter setters
1034
1035Functions that access low-level objects directly such as L<RSA_set0_crt_params(3)>
1036are now deprecated. Applications should use L<EVP_PKEY_fromdata(3)> to create
1037new keys from user provided key data. Keys should be immutable once they are
1038created, so if required the user may use L<EVP_PKEY_todata(3)>, L<OSSL_PARAM_merge(3)>,
1039and L<EVP_PKEY_fromdata(3)> to create a modified key.
1040See L<EVP_PKEY-DH(7)/Examples> for more information.
1041See L</Deprecated low-level key generation functions> for information on
1042generating a key using parameters.
1043
1044=head4 Deprecated low-level object creation
1045
1046Low-level objects were created using methods such as L<RSA_new(3)>,
1047L<RSA_up_ref(3)> and L<RSA_free(3)>. Applications should instead use the
1048high-level EVP_PKEY APIs, e.g. L<EVP_PKEY_new(3)>, L<EVP_PKEY_up_ref(3)> and
1049L<EVP_PKEY_free(3)>.
1050See also L<EVP_PKEY_CTX_new_from_name(3)> and L<EVP_PKEY_CTX_new_from_pkey(3)>.
1051
1052EVP_PKEYs may be created in a variety of ways:
1053See also L</Deprecated low-level key generation functions>,
1054L</Deprecated low-level key reading and writing functions> and
1055L</Deprecated low-level key parameter setters>.
1056
1057=head4 Deprecated low-level encryption functions
1058
1059Low-level encryption functions such as L<AES_encrypt(3)> and L<AES_decrypt(3)>
1060have been informally discouraged from use for a long time. Applications should
1061instead use the high level EVP APIs L<EVP_EncryptInit_ex(3)>,
1062L<EVP_EncryptUpdate(3)>, and L<EVP_EncryptFinal_ex(3)> or
1063L<EVP_DecryptInit_ex(3)>, L<EVP_DecryptUpdate(3)> and L<EVP_DecryptFinal_ex(3)>.
1064
1065=head4 Deprecated low-level digest functions
1066
1067Use of low-level digest functions such as L<SHA1_Init(3)> have been
1068informally discouraged from use for a long time.  Applications should instead
1069use the the high level EVP APIs L<EVP_DigestInit_ex(3)>, L<EVP_DigestUpdate(3)>
1070and L<EVP_DigestFinal_ex(3)>, or the quick one-shot L<EVP_Q_digest(3)>.
1071
1072Note that the functions L<SHA1(3)>, L<SHA224(3)>, L<SHA256(3)>, L<SHA384(3)>
1073and L<SHA512(3)> have changed to macros that use L<EVP_Q_digest(3)>.
1074
1075=head4 Deprecated low-level signing functions
1076
1077Use of low-level signing functions such as L<DSA_sign(3)> have been
1078informally discouraged for a long time. Instead applications should use
1079L<EVP_DigestSign(3)> and L<EVP_DigestVerify(3)>.
1080See also L<EVP_SIGNATURE-RSA(7)>, L<EVP_SIGNATURE-DSA(7)>,
1081L<EVP_SIGNATURE-ECDSA(7)> and L<EVP_SIGNATURE-ED25519(7)>.
1082
1083=head4 Deprecated low-level MAC functions
1084
1085Low-level mac functions such as L<CMAC_Init(3)> are deprecated.
1086Applications should instead use the new L<EVP_MAC(3)> interface, using
1087L<EVP_MAC_CTX_new(3)>, L<EVP_MAC_CTX_free(3)>, L<EVP_MAC_init(3)>,
1088L<EVP_MAC_update(3)> and L<EVP_MAC_final(3)> or the single-shot MAC function
1089L<EVP_Q_mac(3)>.
1090See L<EVP_MAC(3)>, L<EVP_MAC-HMAC(7)>, L<EVP_MAC-CMAC(7)>, L<EVP_MAC-GMAC(7)>,
1091L<EVP_MAC-KMAC(7)>, L<EVP_MAC-BLAKE2(7)>, L<EVP_MAC-Poly1305(7)> and
1092L<EVP_MAC-Siphash(7)> for additional information.
1093
1094Note that the one-shot method HMAC() is still available for compatibility purposes,
1095but this can also be replaced by using EVP_Q_MAC if a library context is required.
1096
1097=head4 Deprecated low-level validation functions
1098
1099Low-level validation functions such as L<DH_check(3)> have been informally
1100discouraged from use for a long time. Applications should instead use the high-level
1101EVP_PKEY APIs such as L<EVP_PKEY_check(3)>, L<EVP_PKEY_param_check(3)>,
1102L<EVP_PKEY_param_check_quick(3)>, L<EVP_PKEY_public_check(3)>,
1103L<EVP_PKEY_public_check_quick(3)>, L<EVP_PKEY_private_check(3)>,
1104and L<EVP_PKEY_pairwise_check(3)>.
1105
1106=head4 Deprecated low-level key exchange functions
1107
1108Many low-level functions have been informally discouraged from use for a long
1109time. Applications should instead use L<EVP_PKEY_derive(3)>.
1110See L<EVP_KEYEXCH-DH(7)>, L<EVP_KEYEXCH-ECDH(7)> and L<EVP_KEYEXCH-X25519(7)>.
1111
1112=head4 Deprecated low-level key generation functions
1113
1114Many low-level functions have been informally discouraged from use for a long
1115time. Applications should instead use L<EVP_PKEY_keygen_init(3)> and
1116L<EVP_PKEY_generate(3)> as described in L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>,
1117L<EVP_PKEY-RSA(7)>, L<EVP_PKEY-EC(7)> and L<EVP_PKEY-X25519(7)>.
1118The 'quick' one-shot function L<EVP_PKEY_Q_keygen(3)> and macros for the most
1119common cases: <EVP_RSA_gen(3)> and L<EVP_EC_gen(3)> may also be used.
1120
1121=head4 Deprecated low-level key reading and writing functions
1122
1123Use of low-level objects (such as DSA) has been informally discouraged from use
1124for a long time. Functions to read and write these low-level objects (such as
1125PEM_read_DSA_PUBKEY()) should be replaced. Applications should instead use
1126L<OSSL_ENCODER_to_bio(3)> and L<OSSL_DECODER_from_bio(3)>.
1127
1128=head4 Deprecated low-level key printing functions
1129
1130Use of low-level objects (such as DSA) has been informally discouraged from use
1131for a long time. Functions to print these low-level objects such as
1132DSA_print() should be replaced with the equivalent EVP_PKEY functions.
1133Application should use one of L<EVP_PKEY_print_public(3)>,
1134L<EVP_PKEY_print_private(3)>, L<EVP_PKEY_print_params(3)>,
1135L<EVP_PKEY_print_public_fp(3)>, L<EVP_PKEY_print_private_fp(3)> or
1136L<EVP_PKEY_print_params_fp(3)>. Note that internally these use
1137L<OSSL_ENCODER_to_bio(3)> and L<OSSL_DECODER_from_bio(3)>.
1138
1139=head3 Deprecated function mappings
1140
1141The following functions have been deprecated in 3.0.
1142
1143=over 4
1144
1145=item *
1146
1147AES_bi_ige_encrypt() and AES_ige_encrypt()
1148
1149There is no replacement for the IGE functions. New code should not use these modes.
1150These undocumented functions were never integrated into the EVP layer.
1151They implemented the AES Infinite Garble Extension (IGE) mode and AES
1152Bi-directional IGE mode. These modes were never formally standardised and
1153usage of these functions is believed to be very small. In particular
1154AES_bi_ige_encrypt() has a known bug. It accepts 2 AES keys, but only one
1155is ever used. The security implications are believed to be minimal, but
1156this issue was never fixed for backwards compatibility reasons.
1157
1158=item *
1159
1160AES_encrypt(), AES_decrypt(), AES_set_encrypt_key(), AES_set_decrypt_key(),
1161AES_cbc_encrypt(), AES_cfb128_encrypt(), AES_cfb1_encrypt(), AES_cfb8_encrypt(),
1162AES_ecb_encrypt(), AES_ofb128_encrypt()
1163
1164=item *
1165
1166AES_unwrap_key(), AES_wrap_key()
1167
1168See L</Deprecated low-level encryption functions>
1169
1170=item *
1171
1172AES_options()
1173
1174There is no replacement. It returned a string indicating if the AES code was unrolled.
1175
1176=item *
1177
1178ASN1_digest(), ASN1_sign(), ASN1_verify()
1179
1180There are no replacements. These old functions are not used, and could be
1181disabled with the macro NO_ASN1_OLD since OpenSSL 0.9.7.
1182
1183=item *
1184
1185ASN1_STRING_length_set()
1186
1187Use L<ASN1_STRING_set(3)> or L<ASN1_STRING_set0(3)> instead.
1188This was a potentially unsafe function that could change the bounds of a
1189previously passed in pointer.
1190
1191=item *
1192
1193BF_encrypt(), BF_decrypt(), BF_set_key(), BF_cbc_encrypt(), BF_cfb64_encrypt(),
1194BF_ecb_encrypt(), BF_ofb64_encrypt()
1195
1196See L</Deprecated low-level encryption functions>.
1197The Blowfish algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1198
1199=item *
1200
1201BF_options()
1202
1203There is no replacement. This option returned a constant string.
1204
1205=item *
1206
1207BIO_get_callback(), BIO_set_callback(), BIO_debug_callback()
1208
1209Use the respective non-deprecated _ex() functions.
1210
1211=item *
1212
1213BN_is_prime_ex(), BN_is_prime_fasttest_ex()
1214
1215Use L<BN_check_prime(3)> which avoids possible misuse and always uses at least
121664 rounds of the Miller-Rabin primality test.
1217
1218=item *
1219
1220BN_pseudo_rand(), BN_pseudo_rand_range()
1221
1222Use L<BN_rand(3)> and L<BN_rand_range(3)>.
1223
1224=item *
1225
1226BN_X931_derive_prime_ex(), BN_X931_generate_prime_ex(), BN_X931_generate_Xpq()
1227
1228There are no replacements for these low-level functions. They were used internally
1229by RSA_X931_derive_ex() and RSA_X931_generate_key_ex() which are also deprecated.
1230Use L<EVP_PKEY_keygen(3)> instead.
1231
1232=item *
1233
1234Camellia_encrypt(), Camellia_decrypt(), Camellia_set_key(),
1235Camellia_cbc_encrypt(), Camellia_cfb128_encrypt(), Camellia_cfb1_encrypt(),
1236Camellia_cfb8_encrypt(), Camellia_ctr128_encrypt(), Camellia_ecb_encrypt(),
1237Camellia_ofb128_encrypt()
1238
1239See L</Deprecated low-level encryption functions>.
1240
1241=item *
1242
1243CAST_encrypt(), CAST_decrypt(), CAST_set_key(), CAST_cbc_encrypt(),
1244CAST_cfb64_encrypt(), CAST_ecb_encrypt(), CAST_ofb64_encrypt()
1245
1246See L</Deprecated low-level encryption functions>.
1247The CAST algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1248
1249=item *
1250
1251CMAC_CTX_new(), CMAC_CTX_cleanup(), CMAC_CTX_copy(), CMAC_CTX_free(),
1252CMAC_CTX_get0_cipher_ctx()
1253
1254See L</Deprecated low-level MAC functions>.
1255
1256=item *
1257
1258CMAC_Init(), CMAC_Update(), CMAC_Final(), CMAC_resume()
1259
1260See L</Deprecated low-level MAC functions>.
1261
1262=item *
1263
1264CRYPTO_mem_ctrl(), CRYPTO_mem_debug_free(), CRYPTO_mem_debug_malloc(),
1265CRYPTO_mem_debug_pop(), CRYPTO_mem_debug_push(), CRYPTO_mem_debug_realloc(),
1266CRYPTO_mem_leaks(), CRYPTO_mem_leaks_cb(), CRYPTO_mem_leaks_fp(),
1267CRYPTO_set_mem_debug()
1268
1269Memory-leak checking has been deprecated in favor of more modern development
1270tools, such as compiler memory and leak sanitizers or Valgrind.
1271
1272=item *
1273
1274CRYPTO_cts128_encrypt_block(), CRYPTO_cts128_encrypt(),
1275CRYPTO_cts128_decrypt_block(), CRYPTO_cts128_decrypt(),
1276CRYPTO_nistcts128_encrypt_block(), CRYPTO_nistcts128_encrypt(),
1277CRYPTO_nistcts128_decrypt_block(), CRYPTO_nistcts128_decrypt()
1278
1279Use the higher level functions EVP_CipherInit_ex2(), EVP_CipherUpdate() and
1280EVP_CipherFinal_ex() instead.
1281See the "cts_mode" parameter in
1282L<EVP_EncryptInit(3)/Gettable and Settable EVP_CIPHER_CTX parameters>.
1283See L<EVP_EncryptInit(3)/EXAMPLES> for a AES-256-CBC-CTS example.
1284
1285=item *
1286
1287d2i_DHparams(), d2i_DHxparams(), d2i_DSAparams(), d2i_DSAPrivateKey(),
1288d2i_DSAPrivateKey_bio(), d2i_DSAPrivateKey_fp(), d2i_DSA_PUBKEY(),
1289d2i_DSA_PUBKEY_bio(), d2i_DSA_PUBKEY_fp(), d2i_DSAPublicKey(),
1290d2i_ECParameters(), d2i_ECPrivateKey(), d2i_ECPrivateKey_bio(),
1291d2i_ECPrivateKey_fp(), d2i_EC_PUBKEY(), d2i_EC_PUBKEY_bio(),
1292d2i_EC_PUBKEY_fp(), o2i_ECPublicKey(), d2i_RSAPrivateKey(),
1293d2i_RSAPrivateKey_bio(), d2i_RSAPrivateKey_fp(), d2i_RSA_PUBKEY(),
1294d2i_RSA_PUBKEY_bio(), d2i_RSA_PUBKEY_fp(), d2i_RSAPublicKey(),
1295d2i_RSAPublicKey_bio(), d2i_RSAPublicKey_fp()
1296
1297See L</Deprecated i2d and d2i functions for low-level key types>
1298
1299=item *
1300
1301DES_crypt(), DES_fcrypt(), DES_encrypt1(), DES_encrypt2(), DES_encrypt3(),
1302DES_decrypt3(), DES_ede3_cbc_encrypt(), DES_ede3_cfb64_encrypt(),
1303DES_ede3_cfb_encrypt(),DES_ede3_ofb64_encrypt(),
1304DES_ecb_encrypt(), DES_ecb3_encrypt(), DES_ofb64_encrypt(), DES_ofb_encrypt(),
1305DES_cfb64_encrypt DES_cfb_encrypt(), DES_cbc_encrypt(), DES_ncbc_encrypt(),
1306DES_pcbc_encrypt(), DES_xcbc_encrypt(), DES_cbc_cksum(), DES_quad_cksum(),
1307DES_check_key_parity(), DES_is_weak_key(), DES_key_sched(), DES_options(),
1308DES_random_key(), DES_set_key(), DES_set_key_checked(), DES_set_key_unchecked(),
1309DES_set_odd_parity(), DES_string_to_2keys(), DES_string_to_key()
1310
1311See L</Deprecated low-level encryption functions>.
1312Algorithms for "DESX-CBC", "DES-ECB", "DES-CBC", "DES-OFB", "DES-CFB",
1313"DES-CFB1" and "DES-CFB8" have been moved to the L<Legacy Provider|/Legacy Algorithms>.
1314
1315=item *
1316
1317DH_bits(), DH_security_bits(), DH_size()
1318
1319Use L<EVP_PKEY_get_bits(3)>, L<EVP_PKEY_get_security_bits(3)> and
1320L<EVP_PKEY_get_size(3)>.
1321
1322=item *
1323
1324DH_check(), DH_check_ex(), DH_check_params(), DH_check_params_ex(),
1325DH_check_pub_key(), DH_check_pub_key_ex()
1326
1327See L</Deprecated low-level validation functions>
1328
1329=item *
1330
1331DH_clear_flags(), DH_test_flags(), DH_set_flags()
1332
1333The B<DH_FLAG_CACHE_MONT_P> flag has been deprecated without replacement.
1334The B<DH_FLAG_TYPE_DH> and B<DH_FLAG_TYPE_DHX> have been deprecated.
1335Use EVP_PKEY_is_a() to determine the type of a key.
1336There is no replacement for setting these flags.
1337
1338=item *
1339
1340DH_compute_key() DH_compute_key_padded()
1341
1342See L</Deprecated low-level key exchange functions>.
1343
1344=item *
1345
1346DH_new(), DH_new_by_nid(), DH_free(), DH_up_ref()
1347
1348See L</Deprecated low-level object creation>
1349
1350=item *
1351
1352DH_generate_key(), DH_generate_parameters_ex()
1353
1354See L</Deprecated low-level key generation functions>.
1355
1356=item *
1357
1358DH_get0_pqg(), DH_get0_p(), DH_get0_q(), DH_get0_g(), DH_get0_key(),
1359DH_get0_priv_key(), DH_get0_pub_key(), DH_get_length(), DH_get_nid()
1360
1361See L</Deprecated low-level key parameter getters>
1362
1363=item *
1364
1365DH_get_1024_160(), DH_get_2048_224(), DH_get_2048_256()
1366
1367Applications should instead set the B<OSSL_PKEY_PARAM_GROUP_NAME> as specified in
1368L<EVP_PKEY-DH(7)/DH parameters>) to one of "dh_1024_160", "dh_2048_224" or
1369"dh_2048_256" when generating a DH key.
1370
1371=item *
1372
1373DH_KDF_X9_42()
1374
1375Applications should use L<EVP_PKEY_CTX_set_dh_kdf_type(3)> instead.
1376
1377=item *
1378
1379DH_get_default_method(), DH_get0_engine(), DH_meth_*(), DH_new_method(),
1380DH_OpenSSL(), DH_get_ex_data(), DH_set_default_method(), DH_set_method(),
1381DH_set_ex_data()
1382
1383See L</Providers are a replacement for engines and low-level method overrides>
1384
1385=item *
1386
1387DHparams_print(), DHparams_print_fp()
1388
1389See L</Deprecated low-level key printing functions>
1390
1391=item *
1392
1393DH_set0_key(), DH_set0_pqg(), DH_set_length()
1394
1395See L</Deprecated low-level key parameter setters>
1396
1397=item *
1398
1399DSA_bits(), DSA_security_bits(), DSA_size()
1400
1401Use L<EVP_PKEY_get_bits(3)>, L<EVP_PKEY_get_security_bits(3)> and
1402L<EVP_PKEY_get_size(3)>.
1403
1404=item *
1405
1406DHparams_dup(), DSA_dup_DH()
1407
1408There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)>
1409and L<EVP_PKEY_dup(3)> instead.
1410
1411=item *
1412
1413DSA_generate_key(), DSA_generate_parameters_ex()
1414
1415See L</Deprecated low-level key generation functions>.
1416
1417=item *
1418
1419DSA_get0_engine(), DSA_get_default_method(), DSA_get_ex_data(),
1420DSA_get_method(), DSA_meth_*(), DSA_new_method(), DSA_OpenSSL(),
1421DSA_set_default_method(), DSA_set_ex_data(), DSA_set_method()
1422
1423See L</Providers are a replacement for engines and low-level method overrides>.
1424
1425=item *
1426
1427DSA_get0_p(), DSA_get0_q(), DSA_get0_g(), DSA_get0_pqg(), DSA_get0_key(),
1428DSA_get0_priv_key(), DSA_get0_pub_key()
1429
1430See L</Deprecated low-level key parameter getters>.
1431
1432=item *
1433
1434DSA_new(), DSA_free(), DSA_up_ref()
1435
1436See L</Deprecated low-level object creation>
1437
1438=item *
1439
1440DSAparams_dup()
1441
1442There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)>
1443and L<EVP_PKEY_dup(3)> instead.
1444
1445=item *
1446
1447DSAparams_print(), DSAparams_print_fp(), DSA_print(), DSA_print_fp()
1448
1449See L</Deprecated low-level key printing functions>
1450
1451=item *
1452
1453DSA_set0_key(), DSA_set0_pqg()
1454
1455See L</Deprecated low-level key parameter setters>
1456
1457=item *
1458
1459DSA_set_flags(), DSA_clear_flags(), DSA_test_flags()
1460
1461The B<DSA_FLAG_CACHE_MONT_P> flag has been deprecated without replacement.
1462
1463=item *
1464
1465DSA_sign(), DSA_do_sign(), DSA_sign_setup(), DSA_verify(), DSA_do_verify()
1466
1467See L</Deprecated low-level signing functions>.
1468
1469=item *
1470
1471ECDH_compute_key()
1472
1473See L</Deprecated low-level key exchange functions>.
1474
1475=item *
1476
1477ECDH_KDF_X9_62()
1478
1479Applications may either set this using the helper function
1480L<EVP_PKEY_CTX_set_ecdh_kdf_type(3)> or by setting an L<OSSL_PARAM(3)> using the
1481"kdf-type" as shown in L<EVP_KEYEXCH-ECDH(7)/EXAMPLES>
1482
1483=item *
1484
1485ECDSA_sign(), ECDSA_sign_ex(), ECDSA_sign_setup(), ECDSA_do_sign(),
1486ECDSA_do_sign_ex(), ECDSA_verify(), ECDSA_do_verify()
1487
1488See L</Deprecated low-level signing functions>.
1489
1490=item *
1491
1492ECDSA_size()
1493
1494Applications should use L<EVP_PKEY_get_size(3)>.
1495
1496=item *
1497
1498EC_GF2m_simple_method(), EC_GFp_mont_method(), EC_GFp_nist_method(),
1499EC_GFp_nistp224_method(), EC_GFp_nistp256_method(), EC_GFp_nistp521_method(),
1500EC_GFp_simple_method()
1501
1502There are no replacements for these functions. Applications should rely on the
1503library automatically assigning a suitable method internally when an EC_GROUP
1504is constructed.
1505
1506=item *
1507
1508EC_GROUP_clear_free()
1509
1510Use L<EC_GROUP_free(3)> instead.
1511
1512=item *
1513
1514EC_GROUP_get_curve_GF2m(), EC_GROUP_get_curve_GFp(), EC_GROUP_set_curve_GF2m(),
1515EC_GROUP_set_curve_GFp()
1516
1517Applications should use L<EC_GROUP_get_curve(3)> and L<EC_GROUP_set_curve(3)>.
1518
1519=item *
1520
1521EC_GROUP_have_precompute_mult(), EC_GROUP_precompute_mult(),
1522EC_KEY_precompute_mult()
1523
1524These functions are not widely used. Applications should instead switch to
1525named curves which OpenSSL has hardcoded lookup tables for.
1526
1527=item *
1528
1529EC_GROUP_new(), EC_GROUP_method_of(), EC_POINT_method_of()
1530
1531EC_METHOD is now an internal-only concept and a suitable EC_METHOD is assigned
1532internally without application intervention.
1533Users of EC_GROUP_new() should switch to a different suitable constructor.
1534
1535=item *
1536
1537EC_KEY_can_sign()
1538
1539Applications should use L<EVP_PKEY_can_sign(3)> instead.
1540
1541=item *
1542
1543EC_KEY_check_key()
1544
1545See L</Deprecated low-level validation functions>
1546
1547=item *
1548
1549EC_KEY_set_flags(), EC_KEY_get_flags(), EC_KEY_clear_flags()
1550
1551See L<EVP_PKEY-EC(7)/Common EC parameters> which handles flags as separate
1552parameters for B<OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT>,
1553B<OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE>, B<OSSL_PKEY_PARAM_EC_ENCODING>,
1554B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH> and
1555B<OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC>.
1556See also L<EVP_PKEY-EC(7)/EXAMPLES>
1557
1558=item *
1559
1560EC_KEY_dup(), EC_KEY_copy()
1561
1562There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)>
1563and L<EVP_PKEY_dup(3)> instead.
1564
1565=item *
1566
1567EC_KEY_decoded_from_explicit_params()
1568
1569There is no replacement.
1570
1571=item *
1572
1573EC_KEY_generate_key()
1574
1575See L</Deprecated low-level key generation functions>.
1576
1577=item *
1578
1579EC_KEY_get0_group(), EC_KEY_get0_private_key(), EC_KEY_get0_public_key(),
1580EC_KEY_get_conv_form(), EC_KEY_get_enc_flags()
1581
1582See L</Deprecated low-level key parameter getters>.
1583
1584=item *
1585
1586EC_KEY_get0_engine(), EC_KEY_get_default_method(), EC_KEY_get_method(),
1587EC_KEY_new_method(), EC_KEY_get_ex_data(), EC_KEY_OpenSSL(),
1588EC_KEY_set_ex_data(), EC_KEY_set_default_method(), EC_KEY_METHOD_*(),
1589EC_KEY_set_method()
1590
1591See L</Providers are a replacement for engines and low-level method overrides>
1592
1593=item *
1594
1595EC_METHOD_get_field_type()
1596
1597Use L<EC_GROUP_get_field_type(3)> instead.
1598See L</Providers are a replacement for engines and low-level method overrides>
1599
1600=item *
1601
1602EC_KEY_key2buf(), EC_KEY_oct2key(), EC_KEY_oct2priv(), EC_KEY_priv2buf(),
1603EC_KEY_priv2oct()
1604
1605There are no replacements for these.
1606
1607=item *
1608
1609EC_KEY_new(), EC_KEY_new_by_curve_name(), EC_KEY_free(), EC_KEY_up_ref()
1610
1611See L</Deprecated low-level object creation>
1612
1613=item *
1614
1615EC_KEY_print(), EC_KEY_print_fp()
1616
1617See L</Deprecated low-level key printing functions>
1618
1619=item *
1620
1621EC_KEY_set_asn1_flag(), EC_KEY_set_conv_form(), EC_KEY_set_enc_flags()
1622
1623See L</Deprecated low-level key parameter setters>.
1624
1625=item *
1626
1627EC_KEY_set_group(), EC_KEY_set_private_key(), EC_KEY_set_public_key(),
1628EC_KEY_set_public_key_affine_coordinates()
1629
1630See L</Deprecated low-level key parameter setters>.
1631
1632=item *
1633
1634ECParameters_print(), ECParameters_print_fp(), ECPKParameters_print(),
1635ECPKParameters_print_fp()
1636
1637See L</Deprecated low-level key printing functions>
1638
1639=item *
1640
1641EC_POINT_bn2point(), EC_POINT_point2bn()
1642
1643These functions were not particularly useful, since EC point serialization
1644formats are not individual big-endian integers.
1645
1646=item *
1647
1648EC_POINT_get_affine_coordinates_GF2m(), EC_POINT_get_affine_coordinates_GFp(),
1649EC_POINT_set_affine_coordinates_GF2m(), EC_POINT_set_affine_coordinates_GFp()
1650
1651Applications should use L<EC_POINT_get_affine_coordinates(3)> and
1652L<EC_POINT_set_affine_coordinates(3)> instead.
1653
1654=item *
1655
1656EC_POINT_get_Jprojective_coordinates_GFp(), EC_POINT_set_Jprojective_coordinates_GFp()
1657
1658These functions are not widely used. Applications should instead use the
1659L<EC_POINT_set_affine_coordinates(3)> and L<EC_POINT_get_affine_coordinates(3)>
1660functions.
1661
1662=item *
1663
1664EC_POINT_make_affine(), EC_POINTs_make_affine()
1665
1666There is no replacement. These functions were not widely used, and OpenSSL
1667automatically performs this conversion when needed.
1668
1669=item *
1670
1671EC_POINT_set_compressed_coordinates_GF2m(), EC_POINT_set_compressed_coordinates_GFp()
1672
1673Applications should use L<EC_POINT_set_compressed_coordinates(3)> instead.
1674
1675=item *
1676
1677EC_POINTs_mul()
1678
1679This function is not widely used. Applications should instead use the
1680L<EC_POINT_mul(3)> function.
1681
1682=item *
1683
1684B<ENGINE_*()>
1685
1686All engine functions are deprecated. An engine should be rewritten as a provider.
1687See L</Providers are a replacement for engines and low-level method overrides>.
1688
1689=item *
1690
1691B<ERR_load_*()>, ERR_func_error_string(), ERR_get_error_line(),
1692ERR_get_error_line_data(), ERR_get_state()
1693
1694OpenSSL now loads error strings automatically so these functions are not needed.
1695
1696=item *
1697
1698ERR_peek_error_line_data(), ERR_peek_last_error_line_data()
1699
1700The new functions are L<ERR_peek_error_func(3)>, L<ERR_peek_last_error_func(3)>,
1701L<ERR_peek_error_data(3)>, L<ERR_peek_last_error_data(3)>, L<ERR_get_error_all(3)>,
1702L<ERR_peek_error_all(3)> and L<ERR_peek_last_error_all(3)>.
1703Applications should use L<ERR_get_error_all(3)>, or pick information
1704with ERR_peek functions and finish off with getting the error code by using
1705L<ERR_get_error(3)>.
1706
1707=item *
1708
1709EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_iv_noconst(), EVP_CIPHER_CTX_original_iv()
1710
1711Applications should instead use L<EVP_CIPHER_CTX_get_updated_iv(3)>,
1712L<EVP_CIPHER_CTX_get_updated_iv(3)> and L<EVP_CIPHER_CTX_get_original_iv(3)>
1713respectively.
1714See L<EVP_CIPHER_CTX_get_original_iv(3)> for further information.
1715
1716=item *
1717
1718B<EVP_CIPHER_meth_*()>, EVP_MD_CTX_set_update_fn(), EVP_MD_CTX_update_fn(),
1719B<EVP_MD_meth_*()>
1720
1721See L</Providers are a replacement for engines and low-level method overrides>.
1722
1723=item *
1724
1725EVP_PKEY_CTRL_PKCS7_ENCRYPT(), EVP_PKEY_CTRL_PKCS7_DECRYPT(),
1726EVP_PKEY_CTRL_PKCS7_SIGN(), EVP_PKEY_CTRL_CMS_ENCRYPT(),
1727EVP_PKEY_CTRL_CMS_DECRYPT(), and EVP_PKEY_CTRL_CMS_SIGN()
1728
1729These control operations are not invoked by the OpenSSL library anymore and
1730are replaced by direct checks of the key operation against the key type
1731when the operation is initialized.
1732
1733=item *
1734
1735EVP_PKEY_CTX_get0_dh_kdf_ukm(), EVP_PKEY_CTX_get0_ecdh_kdf_ukm()
1736
1737See the "kdf-ukm" item in L<EVP_KEYEXCH-DH(7)/DH key exchange parameters> and
1738L<EVP_KEYEXCH-ECDH(7)/ECDH Key Exchange parameters>.
1739These functions are obsolete and should not be required.
1740
1741=item *
1742
1743EVP_PKEY_CTX_set_rsa_keygen_pubexp()
1744
1745Applications should use L<EVP_PKEY_CTX_set1_rsa_keygen_pubexp(3)> instead.
1746
1747=item *
1748
1749EVP_PKEY_cmp(), EVP_PKEY_cmp_parameters()
1750
1751Applications should use L<EVP_PKEY_eq(3)> and L<EVP_PKEY_parameters_eq(3)> instead.
1752See L<EVP_PKEY_copy_parameters(3)> for further details.
1753
1754=item *
1755
1756EVP_PKEY_encrypt_old(), EVP_PKEY_decrypt_old(),
1757
1758Applications should use L<EVP_PKEY_encrypt_init(3)> and L<EVP_PKEY_encrypt(3)> or
1759L<EVP_PKEY_decrypt_init(3)> and L<EVP_PKEY_decrypt(3)> instead.
1760
1761=item *
1762
1763EVP_PKEY_get0()
1764
1765This function returns NULL if the key comes from a provider.
1766
1767=item *
1768
1769EVP_PKEY_get0_DH(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_EC_KEY(), EVP_PKEY_get0_RSA(),
1770EVP_PKEY_get1_DH(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_EC_KEY and EVP_PKEY_get1_RSA(),
1771EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash()
1772
1773See L</Functions that return an internal key should be treated as read only>.
1774
1775=item *
1776
1777B<EVP_PKEY_meth_*()>
1778
1779See L</Providers are a replacement for engines and low-level method overrides>.
1780
1781=item *
1782
1783EVP_PKEY_new_CMAC_key()
1784
1785See L</Deprecated low-level MAC functions>.
1786
1787=item *
1788
1789EVP_PKEY_assign(), EVP_PKEY_set1_DH(), EVP_PKEY_set1_DSA(),
1790EVP_PKEY_set1_EC_KEY(), EVP_PKEY_set1_RSA()
1791
1792See L</Deprecated low-level key object getters and setters>
1793
1794=item *
1795
1796EVP_PKEY_set1_tls_encodedpoint() EVP_PKEY_get1_tls_encodedpoint()
1797
1798These functions were previously used by libssl to set or get an encoded public
1799key into/from an EVP_PKEY object. With OpenSSL 3.0 these are replaced by the more
1800generic functions L<EVP_PKEY_set1_encoded_public_key(3)> and
1801L<EVP_PKEY_get1_encoded_public_key(3)>.
1802The old versions have been converted to deprecated macros that just call the
1803new functions.
1804
1805=item *
1806
1807EVP_PKEY_set1_engine(), EVP_PKEY_get0_engine()
1808
1809See L</Providers are a replacement for engines and low-level method overrides>.
1810
1811=item *
1812
1813EVP_PKEY_set_alias_type()
1814
1815This function has been removed. There is no replacement.
1816See L</EVP_PKEY_set_alias_type() method has been removed>
1817
1818=item *
1819
1820HMAC_Init_ex(), HMAC_Update(), HMAC_Final(), HMAC_size()
1821
1822See L</Deprecated low-level MAC functions>.
1823
1824=item *
1825
1826HMAC_CTX_new(), HMAC_CTX_free(), HMAC_CTX_copy(), HMAC_CTX_reset(),
1827HMAC_CTX_set_flags(), HMAC_CTX_get_md()
1828
1829See L</Deprecated low-level MAC functions>.
1830
1831=item *
1832
1833i2d_DHparams(), i2d_DHxparams()
1834
1835See L</Deprecated low-level key reading and writing functions>
1836and L<d2i_RSAPrivateKey(3)/Migration>
1837
1838=item *
1839
1840i2d_DSAparams(), i2d_DSAPrivateKey(), i2d_DSAPrivateKey_bio(),
1841i2d_DSAPrivateKey_fp(), i2d_DSA_PUBKEY(), i2d_DSA_PUBKEY_bio(),
1842i2d_DSA_PUBKEY_fp(), i2d_DSAPublicKey()
1843
1844See L</Deprecated low-level key reading and writing functions>
1845and L<d2i_RSAPrivateKey(3)/Migration>
1846
1847=item *
1848
1849i2d_ECParameters(), i2d_ECPrivateKey(), i2d_ECPrivateKey_bio(),
1850i2d_ECPrivateKey_fp(), i2d_EC_PUBKEY(), i2d_EC_PUBKEY_bio(),
1851i2d_EC_PUBKEY_fp(), i2o_ECPublicKey()
1852
1853See L</Deprecated low-level key reading and writing functions>
1854and L<d2i_RSAPrivateKey(3)/Migration>
1855
1856=item *
1857
1858i2d_RSAPrivateKey(), i2d_RSAPrivateKey_bio(), i2d_RSAPrivateKey_fp(),
1859i2d_RSA_PUBKEY(), i2d_RSA_PUBKEY_bio(), i2d_RSA_PUBKEY_fp(),
1860i2d_RSAPublicKey(), i2d_RSAPublicKey_bio(), i2d_RSAPublicKey_fp()
1861
1862See L</Deprecated low-level key reading and writing functions>
1863and L<d2i_RSAPrivateKey(3)/Migration>
1864
1865=item *
1866
1867IDEA_encrypt(), IDEA_set_decrypt_key(), IDEA_set_encrypt_key(),
1868IDEA_cbc_encrypt(), IDEA_cfb64_encrypt(), IDEA_ecb_encrypt(),
1869IDEA_ofb64_encrypt()
1870
1871See L</Deprecated low-level encryption functions>.
1872IDEA has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1873
1874=item *
1875
1876IDEA_options()
1877
1878There is no replacement. This function returned a constant string.
1879
1880=item *
1881
1882MD2(), MD2_Init(), MD2_Update(), MD2_Final()
1883
1884See L</Deprecated low-level encryption functions>.
1885MD2 has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1886
1887=item *
1888
1889MD2_options()
1890
1891There is no replacement. This function returned a constant string.
1892
1893=item *
1894
1895MD4(), MD4_Init(), MD4_Update(), MD4_Final(), MD4_Transform()
1896
1897See L</Deprecated low-level encryption functions>.
1898MD4 has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1899
1900=item *
1901
1902MDC2(), MDC2_Init(), MDC2_Update(), MDC2_Final()
1903
1904See L</Deprecated low-level encryption functions>.
1905MDC2 has been moved to the L<Legacy Provider|/Legacy Algorithms>.
1906
1907=item *
1908
1909MD5(), MD5_Init(), MD5_Update(), MD5_Final(), MD5_Transform()
1910
1911See L</Deprecated low-level encryption functions>.
1912
1913=item *
1914
1915NCONF_WIN32()
1916
1917This undocumented function has no replacement.
1918See L<config(5)/HISTORY> for more details.
1919
1920=item *
1921
1922OCSP_parse_url()
1923
1924Use L<OSSL_HTTP_parse_url(3)> instead.
1925
1926=item *
1927
1928B<OCSP_REQ_CTX> type and B<OCSP_REQ_CTX_*()> functions
1929
1930These methods were used to collect all necessary data to form a HTTP request,
1931and to perform the HTTP transfer with that request.  With OpenSSL 3.0, the
1932type is B<OSSL_HTTP_REQ_CTX>, and the deprecated functions are replaced
1933with B<OSSL_HTTP_REQ_CTX_*()>. See L<OSSL_HTTP_REQ_CTX(3)> for additional
1934details.
1935
1936=item *
1937
1938OPENSSL_fork_child(), OPENSSL_fork_parent(), OPENSSL_fork_prepare()
1939
1940There is no replacement for these functions. These pthread fork support methods
1941were unused by OpenSSL.
1942
1943=item *
1944
1945OSSL_STORE_ctrl(), OSSL_STORE_do_all_loaders(), OSSL_STORE_LOADER_get0_engine(),
1946OSSL_STORE_LOADER_get0_scheme(), OSSL_STORE_LOADER_new(),
1947OSSL_STORE_LOADER_set_attach(), OSSL_STORE_LOADER_set_close(),
1948OSSL_STORE_LOADER_set_ctrl(), OSSL_STORE_LOADER_set_eof(),
1949OSSL_STORE_LOADER_set_error(), OSSL_STORE_LOADER_set_expect(),
1950OSSL_STORE_LOADER_set_find(), OSSL_STORE_LOADER_set_load(),
1951OSSL_STORE_LOADER_set_open(), OSSL_STORE_LOADER_set_open_ex(),
1952OSSL_STORE_register_loader(), OSSL_STORE_unregister_loader(),
1953OSSL_STORE_vctrl()
1954
1955These functions helped applications and engines create loaders for
1956schemes they supported.  These are all deprecated and discouraged in favour of
1957provider implementations, see L<provider-storemgmt(7)>.
1958
1959=item *
1960
1961PEM_read_DHparams(), PEM_read_bio_DHparams(),
1962PEM_read_DSAparams(), PEM_read_bio_DSAparams(),
1963PEM_read_DSAPrivateKey(), PEM_read_DSA_PUBKEY(),
1964PEM_read_bio_DSAPrivateKey and PEM_read_bio_DSA_PUBKEY(),
1965PEM_read_ECPKParameters(), PEM_read_ECPrivateKey(), PEM_read_EC_PUBKEY(),
1966PEM_read_bio_ECPKParameters(), PEM_read_bio_ECPrivateKey(), PEM_read_bio_EC_PUBKEY(),
1967PEM_read_RSAPrivateKey(), PEM_read_RSA_PUBKEY(), PEM_read_RSAPublicKey(),
1968PEM_read_bio_RSAPrivateKey(), PEM_read_bio_RSA_PUBKEY(), PEM_read_bio_RSAPublicKey(),
1969PEM_write_bio_DHparams(), PEM_write_bio_DHxparams(), PEM_write_DHparams(), PEM_write_DHxparams(),
1970PEM_write_DSAparams(), PEM_write_DSAPrivateKey(), PEM_write_DSA_PUBKEY(),
1971PEM_write_bio_DSAparams(), PEM_write_bio_DSAPrivateKey(), PEM_write_bio_DSA_PUBKEY(),
1972PEM_write_ECPKParameters(), PEM_write_ECPrivateKey(), PEM_write_EC_PUBKEY(),
1973PEM_write_bio_ECPKParameters(), PEM_write_bio_ECPrivateKey(), PEM_write_bio_EC_PUBKEY(),
1974PEM_write_RSAPrivateKey(), PEM_write_RSA_PUBKEY(), PEM_write_RSAPublicKey(),
1975PEM_write_bio_RSAPrivateKey(), PEM_write_bio_RSA_PUBKEY(),
1976PEM_write_bio_RSAPublicKey(),
1977
1978See L</Deprecated low-level key reading and writing functions>
1979
1980=item *
1981
1982PKCS1_MGF1()
1983
1984See L</Deprecated low-level encryption functions>.
1985
1986=item *
1987
1988RAND_get_rand_method(), RAND_set_rand_method(), RAND_OpenSSL(),
1989RAND_set_rand_engine()
1990
1991Applications should instead use L<RAND_set_DRBG_type(3)>,
1992L<EVP_RAND(3)> and L<EVP_RAND(7)>.
1993See L<RAND_set_rand_method(3)> for more details.
1994
1995=item *
1996
1997RC2_encrypt(), RC2_decrypt(), RC2_set_key(), RC2_cbc_encrypt(), RC2_cfb64_encrypt(),
1998RC2_ecb_encrypt(), RC2_ofb64_encrypt(),
1999RC4(), RC4_set_key(), RC4_options(),
2000RC5_32_encrypt(), RC5_32_set_key(), RC5_32_decrypt(), RC5_32_cbc_encrypt(),
2001RC5_32_cfb64_encrypt(), RC5_32_ecb_encrypt(), RC5_32_ofb64_encrypt()
2002
2003See L</Deprecated low-level encryption functions>.
2004The Algorithms "RC2", "RC4" and "RC5" have been moved to the L<Legacy Provider|/Legacy Algorithms>.
2005
2006=item *
2007
2008RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update(), RIPEMD160_Final(),
2009RIPEMD160_Transform()
2010
2011See L</Deprecated low-level digest functions>.
2012The RIPE algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
2013
2014=item *
2015
2016RSA_bits(), RSA_security_bits(), RSA_size()
2017
2018Use L<EVP_PKEY_get_bits(3)>, L<EVP_PKEY_get_security_bits(3)> and
2019L<EVP_PKEY_get_size(3)>.
2020
2021=item *
2022
2023RSA_check_key(), RSA_check_key_ex()
2024
2025See L</Deprecated low-level validation functions>
2026
2027=item *
2028
2029RSA_clear_flags(), RSA_flags(), RSA_set_flags(), RSA_test_flags(),
2030RSA_setup_blinding(), RSA_blinding_off(), RSA_blinding_on()
2031
2032All of these RSA flags have been deprecated without replacement:
2033
2034B<RSA_FLAG_BLINDING>, B<RSA_FLAG_CACHE_PRIVATE>, B<RSA_FLAG_CACHE_PUBLIC>,
2035B<RSA_FLAG_EXT_PKEY>, B<RSA_FLAG_NO_BLINDING>, B<RSA_FLAG_THREAD_SAFE>
2036B<RSA_METHOD_FLAG_NO_CHECK>
2037
2038=item *
2039
2040RSA_generate_key_ex(), RSA_generate_multi_prime_key()
2041
2042See L</Deprecated low-level key generation functions>.
2043
2044=item *
2045
2046RSA_get0_engine()
2047
2048See L</Providers are a replacement for engines and low-level method overrides>
2049
2050=item *
2051
2052RSA_get0_crt_params(), RSA_get0_d(), RSA_get0_dmp1(), RSA_get0_dmq1(),
2053RSA_get0_e(), RSA_get0_factors(), RSA_get0_iqmp(), RSA_get0_key(),
2054RSA_get0_multi_prime_crt_params(), RSA_get0_multi_prime_factors(), RSA_get0_n(),
2055RSA_get0_p(), RSA_get0_pss_params(), RSA_get0_q(),
2056RSA_get_multi_prime_extra_count()
2057
2058See L</Deprecated low-level key parameter getters>
2059
2060=item *
2061
2062RSA_new(), RSA_free(), RSA_up_ref()
2063
2064See L</Deprecated low-level object creation>.
2065
2066=item *
2067
2068RSA_get_default_method(), RSA_get_ex_data and RSA_get_method()
2069
2070See L</Providers are a replacement for engines and low-level method overrides>.
2071
2072=item *
2073
2074RSA_get_version()
2075
2076There is no replacement.
2077
2078=item *
2079
2080B<RSA_meth_*()>, RSA_new_method(), RSA_null_method and RSA_PKCS1_OpenSSL()
2081
2082See L</Providers are a replacement for engines and low-level method overrides>.
2083
2084=item *
2085
2086B<RSA_padding_add_*()>, B<RSA_padding_check_*()>
2087
2088See L</Deprecated low-level signing functions> and
2089L</Deprecated low-level encryption functions>.
2090
2091=item *
2092
2093RSA_print(), RSA_print_fp()
2094
2095See L</Deprecated low-level key printing functions>
2096
2097=item *
2098
2099RSA_public_encrypt(), RSA_private_decrypt()
2100
2101See L</Deprecated low-level encryption functions>
2102
2103=item *
2104
2105RSA_private_encrypt(), RSA_public_decrypt()
2106
2107This is equivalent to doing sign and verify recover operations (with a padding
2108mode of none). See L</Deprecated low-level signing functions>.
2109
2110=item *
2111
2112RSAPrivateKey_dup(), RSAPublicKey_dup()
2113
2114There is no direct replacement. Applications may use L<EVP_PKEY_dup(3)>.
2115
2116=item *
2117
2118RSAPublicKey_it(), RSAPrivateKey_it()
2119
2120See L</Deprecated low-level key reading and writing functions>
2121
2122=item *
2123
2124RSA_set0_crt_params(), RSA_set0_factors(), RSA_set0_key(),
2125RSA_set0_multi_prime_params()
2126
2127See L</Deprecated low-level key parameter setters>.
2128
2129=item *
2130
2131RSA_set_default_method(), RSA_set_method(), RSA_set_ex_data()
2132
2133See L</Providers are a replacement for engines and low-level method overrides>
2134
2135=item *
2136
2137RSA_sign(), RSA_sign_ASN1_OCTET_STRING(), RSA_verify(),
2138RSA_verify_ASN1_OCTET_STRING(), RSA_verify_PKCS1_PSS(),
2139RSA_verify_PKCS1_PSS_mgf1()
2140
2141See L</Deprecated low-level signing functions>.
2142
2143=item *
2144
2145RSA_X931_derive_ex(), RSA_X931_generate_key_ex(), RSA_X931_hash_id()
2146
2147There are no replacements for these functions.
2148X931 padding can be set using L<EVP_SIGNATURE-RSA(7)/Signature Parameters>.
2149See B<OSSL_SIGNATURE_PARAM_PAD_MODE>.
2150
2151=item *
2152
2153SEED_encrypt(), SEED_decrypt(), SEED_set_key(), SEED_cbc_encrypt(),
2154SEED_cfb128_encrypt(), SEED_ecb_encrypt(), SEED_ofb128_encrypt()
2155
2156See L</Deprecated low-level encryption functions>.
2157The SEED algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
2158
2159=item *
2160
2161SHA1_Init(), SHA1_Update(), SHA1_Final(), SHA1_Transform(),
2162SHA224_Init(), SHA224_Update(), SHA224_Final(),
2163SHA256_Init(), SHA256_Update(), SHA256_Final(), SHA256_Transform(),
2164SHA384_Init(), SHA384_Update(), SHA384_Final(),
2165SHA512_Init(), SHA512_Update(), SHA512_Final(), SHA512_Transform()
2166
2167See L</Deprecated low-level digest functions>.
2168
2169=item *
2170
2171SRP_Calc_A(), SRP_Calc_B(), SRP_Calc_client_key(), SRP_Calc_server_key(),
2172SRP_Calc_u(), SRP_Calc_x(), SRP_check_known_gN_param(), SRP_create_verifier(),
2173SRP_create_verifier_BN(), SRP_get_default_gN(), SRP_user_pwd_free(), SRP_user_pwd_new(),
2174SRP_user_pwd_set0_sv(), SRP_user_pwd_set1_ids(), SRP_user_pwd_set_gN(),
2175SRP_VBASE_add0_user(), SRP_VBASE_free(), SRP_VBASE_get1_by_user(), SRP_VBASE_init(),
2176SRP_VBASE_new(), SRP_Verify_A_mod_N(), SRP_Verify_B_mod_N()
2177
2178There are no replacements for the SRP functions.
2179
2180=item *
2181
2182SSL_CTX_set_tmp_dh_callback(), SSL_set_tmp_dh_callback(),
2183SSL_CTX_set_tmp_dh(), SSL_set_tmp_dh()
2184
2185These are used to set the Diffie-Hellman (DH) parameters that are to be used by
2186servers requiring ephemeral DH keys. Instead applications should consider using
2187the built-in DH parameters that are available by calling L<SSL_CTX_set_dh_auto(3)>
2188or L<SSL_set_dh_auto(3)>. If custom parameters are necessary then applications can
2189use the alternative functions L<SSL_CTX_set0_tmp_dh_pkey(3)> and
2190L<SSL_set0_tmp_dh_pkey(3)>. There is no direct replacement for the "callback"
2191functions. The callback was originally useful in order to have different
2192parameters for export and non-export ciphersuites. Export ciphersuites are no
2193longer supported by OpenSSL. Use of the callback functions should be replaced
2194by one of the other methods described above.
2195
2196=item *
2197
2198SSL_CTX_set_tlsext_ticket_key_cb()
2199
2200Use the new L<SSL_CTX_set_tlsext_ticket_key_evp_cb(3)> function instead.
2201
2202=item *
2203
2204WHIRLPOOL(), WHIRLPOOL_Init(), WHIRLPOOL_Update(), WHIRLPOOL_Final(),
2205WHIRLPOOL_BitUpdate()
2206
2207See L</Deprecated low-level digest functions>.
2208The Whirlpool algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>.
2209
2210=item *
2211
2212X509_certificate_type()
2213
2214This was an undocumented function. Applications can use L<X509_get0_pubkey(3)>
2215and L<X509_get0_signature(3)> instead.
2216
2217=item *
2218
2219X509_http_nbio(), X509_CRL_http_nbio()
2220
2221Use L<X509_load_http(3)> and L<X509_CRL_load_http(3)> instead.
2222
2223=back
2224
2225=head3 NID handling for provided keys and algorithms
2226
2227The following functions for NID (numeric id) handling have changed semantics.
2228
2229=over 4
2230
2231=item *
2232
2233EVP_PKEY_id(), EVP_PKEY_get_id()
2234
2235This function was previously used to reliably return the NID of
2236an EVP_PKEY object, e.g., to look up the name of the algorithm of
2237such EVP_PKEY by calling L<OBJ_nid2sn(3)>. With the introduction
2238of L<provider(7)>s EVP_PKEY_id() or its new equivalent
2239L<EVP_PKEY_get_id(3)> might now also return the value -1
2240(B<EVP_PKEY_KEYMGMT>) indicating the use of a provider to
2241implement the EVP_PKEY object. Therefore, the use of
2242L<EVP_PKEY_get0_type_name(3)> is recommended for retrieving
2243the name of the EVP_PKEY algorithm.
2244
2245=back
2246
2247=head2 Using the FIPS Module in applications
2248
2249See L<fips_module(7)> and L<OSSL_PROVIDER-FIPS(7)> for details.
2250
2251=head2 OpenSSL command line application changes
2252
2253=head3 New applications
2254
2255L<B<openssl kdf>|openssl-kdf(1)> uses the new L<EVP_KDF(3)> API.
2256L<B<openssl kdf>|openssl-mac(1)> uses the new L<EVP_MAC(3)> API.
2257
2258=head3 Added options
2259
2260B<-provider_path> and B<-provider> are available to all apps and can be used
2261multiple times to load any providers, such as the 'legacy' provider or third
2262party providers. If used then the 'default' provider would also need to be
2263specified if required. The B<-provider_path> must be specified before the
2264B<-provider> option.
2265
2266The B<list> app has many new options. See L<openssl-list(1)> for more
2267information.
2268
2269B<-crl_lastupdate> and B<-crl_nextupdate> used by B<openssl ca> allows
2270explicit setting of fields in the generated CRL.
2271
2272=head3 Removed options
2273
2274Interactive mode is not longer available.
2275
2276The B<-crypt> option used by B<openssl passwd>.
2277The B<-c> option used by B<openssl x509>, B<openssl dhparam>,
2278B<openssl dsaparam>, and B<openssl ecparam>.
2279
2280=head3 Other Changes
2281
2282The output of Command line applications may have minor changes.
2283These are primarily changes in capitalisation and white space.  However, in some
2284cases, there are additional differences.
2285For example, the DH parameters output from B<openssl dhparam> now lists 'P',
2286'Q', 'G' and 'pcounter' instead of 'prime', 'generator', 'subgroup order' and
2287'counter' respectively.
2288
2289The B<openssl> commands that read keys, certificates, and CRLs now
2290automatically detect the PEM or DER format of the input files so it is not
2291necessary to explicitly specify the input format anymore. However if the
2292input format option is used the specified format will be required.
2293
2294B<openssl speed> no longer uses low-level API calls.
2295This implies some of the performance numbers might not be comparable with the
2296previous releases due to higher overhead. This applies particularly to
2297measuring performance on smaller data chunks.
2298
2299b<openssl dhparam>, B<openssl dsa>, B<openssl gendsa>, B<openssl dsaparam>,
2300B<openssl genrsa> and B<openssl rsa> have been modified to use PKEY APIs.
2301B<openssl genrsa> and B<openssl rsa> now write PKCS #8 keys by default.
2302
2303=head3 Default settings
2304
2305"SHA256" is now the default digest for TS query used by B<openssl ts>.
2306
2307=head3 Deprecated apps
2308
2309B<openssl rsautl> is deprecated, use B<openssl pkeyutl> instead.
2310B<openssl dhparam>, B<openssl dsa>, B<openssl gendsa>, B<openssl dsaparam>,
2311B<openssl genrsa>, B<openssl rsa>, B<openssl genrsa> and B<openssl rsa> are
2312now in maintenance mode and no new features will be added to them.
2313
2314=head2 TLS Changes
2315
2316=over 4
2317
2318=item *
2319
2320TLS 1.3 FFDHE key exchange support added
2321
2322This uses DH safe prime named groups.
2323
2324=item *
2325
2326Support for fully "pluggable" TLSv1.3 groups.
2327
2328This means that providers may supply their own group implementations (using
2329either the "key exchange" or the "key encapsulation" methods) which will
2330automatically be detected and used by libssl.
2331
2332=item *
2333
2334SSL and SSL_CTX options are now 64 bit instead of 32 bit.
2335
2336The signatures of the functions to get and set options on SSL and
2337SSL_CTX objects changed from "unsigned long" to "uint64_t" type.
2338
2339This may require source code changes. For example it is no longer possible
2340to use the B<SSL_OP_> macro values in preprocessor C<#if> conditions.
2341However it is still possible to test whether these macros are defined or not.
2342
2343See L<SSL_CTX_get_options(3)>, L<SSL_CTX_set_options(3)>,
2344L<SSL_get_options(3)> and L<SSL_set_options(3)>.
2345
2346=item *
2347
2348SSL_set1_host() and SSL_add1_host() Changes
2349
2350These functions now take IP literal addresses as well as actual hostnames.
2351
2352=item *
2353
2354Added SSL option SSL_OP_CLEANSE_PLAINTEXT
2355
2356If the option is set, openssl cleanses (zeroizes) plaintext bytes from
2357internal buffers after delivering them to the application. Note,
2358the application is still responsible for cleansing other copies
2359(e.g.: data received by L<SSL_read(3)>).
2360
2361=item *
2362
2363Client-initiated renegotiation is disabled by default.
2364
2365To allow it, use the B<-client_renegotiation> option,
2366the B<SSL_OP_ALLOW_CLIENT_RENEGOTIATION> flag, or the C<ClientRenegotiation>
2367config parameter as appropriate.
2368
2369=item *
2370
2371Secure renegotiation is now required by default for TLS connections
2372
2373Support for RFC 5746 secure renegotiation is now required by default for
2374SSL or TLS connections to succeed.  Applications that require the ability
2375to connect to legacy peers will need to explicitly set
2376SSL_OP_LEGACY_SERVER_CONNECT.  Accordingly, SSL_OP_LEGACY_SERVER_CONNECT
2377is no longer set as part of SSL_OP_ALL.
2378
2379=item *
2380
2381Combining the Configure options no-ec and no-dh no longer disables TLSv1.3
2382
2383Typically if OpenSSL has no EC or DH algorithms then it cannot support
2384connections with TLSv1.3. However OpenSSL now supports "pluggable" groups
2385through providers. Therefore third party providers may supply group
2386implementations even where there are no built-in ones. Attempting to create
2387TLS connections in such a build without also disabling TLSv1.3 at run time or
2388using third party provider groups may result in handshake failures. TLSv1.3
2389can be disabled at compile time using the "no-tls1_3" Configure option.
2390
2391=item *
2392
2393SSL_CTX_set_ciphersuites() and SSL_set_ciphersuites() changes.
2394
2395The methods now ignore unknown ciphers.
2396
2397=item *
2398
2399Security callback change.
2400
2401The security callback, which can be customised by application code, supports
2402the security operation SSL_SECOP_TMP_DH. This is defined to take an EVP_PKEY
2403in the "other" parameter. In most places this is what is passed. All these
2404places occur server side. However there was one client side call of this
2405security operation and it passed a DH object instead. This is incorrect
2406according to the definition of SSL_SECOP_TMP_DH, and is inconsistent with all
2407of the other locations. Therefore this client side call has been changed to
2408pass an EVP_PKEY instead.
2409
2410=item *
2411
2412New SSL option SSL_OP_IGNORE_UNEXPECTED_EOF
2413
2414The SSL option SSL_OP_IGNORE_UNEXPECTED_EOF is introduced. If that option
2415is set, an unexpected EOF is ignored, it pretends a close notify was received
2416instead and so the returned error becomes SSL_ERROR_ZERO_RETURN.
2417
2418=item *
2419
2420The security strength of SHA1 and MD5 based signatures in TLS has been reduced.
2421
2422This results in SSL 3, TLS 1.0, TLS 1.1 and DTLS 1.0 no longer
2423working at the default security level of 1 and instead requires security
2424level 0. The security level can be changed either using the cipher string
2425with C<@SECLEVEL>, or calling L<SSL_CTX_set_security_level(3)>. This also means
2426that where the signature algorithms extension is missing from a ClientHello
2427then the handshake will fail in TLS 1.2 at security level 1. This is because,
2428although this extension is optional, failing to provide one means that
2429OpenSSL will fallback to a default set of signature algorithms. This default
2430set requires the availability of SHA1.
2431
2432=item *
2433
2434X509 certificates signed using SHA1 are no longer allowed at security level 1 and above.
2435
2436In TLS/SSL the default security level is 1. It can be set either using the cipher
2437string with C<@SECLEVEL>, or calling L<SSL_CTX_set_security_level(3)>. If the
2438leaf certificate is signed with SHA-1, a call to L<SSL_CTX_use_certificate(3)>
2439will fail if the security level is not lowered first.
2440Outside TLS/SSL, the default security level is -1 (effectively 0). It can
2441be set using L<X509_VERIFY_PARAM_set_auth_level(3)> or using the B<-auth_level>
2442options of the commands.
2443
2444=back
2445
2446=head1 SEE ALSO
2447
2448L<fips_module(7)>
2449
2450=head1 HISTORY
2451
2452The migration guide was created for OpenSSL 3.0.
2453
2454=head1 COPYRIGHT
2455
2456Copyright 2021-2023 The OpenSSL Project Authors. All Rights Reserved.
2457
2458Licensed under the Apache License 2.0 (the "License").  You may not use
2459this file except in compliance with the License.  You can obtain a copy
2460in the file LICENSE in the source distribution or at
2461L<https://www.openssl.org/source/license.html>.
2462
2463=cut
2464