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