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