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