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