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