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 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 B<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://github.com/openssl/openssl/wiki/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://github.com/openssl/openssl/wiki/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: 1062L<EVP_PKEY_get_bn_param(3)>, 1063L<EVP_PKEY_get_int_param(3)>, 1064L<EVP_PKEY_get_size_t_param(3)>, 1065L<EVP_PKEY_get_utf8_string_param(3)>, 1066L<EVP_PKEY_get_octet_string_param(3)>, or 1067L<EVP_PKEY_get_params(3)>, 1068to access fields from an EVP_PKEY. 1069Gettable parameters are listed in: 1070L<EVP_PKEY-RSA(7)/Common RSA parameters>, 1071L<EVP_PKEY-EC(7)/Common EC parameters>, 1072L<EVP_PKEY-DSA(7)/DSA parameters>, 1073L<EVP_PKEY-DH(7)/DH parameters>, 1074L<EVP_PKEY-FFC(7)/FFC parameters>, 1075L<EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>, 1076L<EVP_PKEY-ML-DSA(7)/Common parameters>, 1077and 1078L<EVP_PKEY-ML-KEM(7)/Common parameters>. 1079Applications may also use L<EVP_PKEY_todata(3)> to return all fields. 1080 1081=head4 Deprecated low-level key parameter setters 1082 1083Functions that access low-level objects directly such as L<RSA_set0_crt_params(3)> 1084are now deprecated. Applications should use L<EVP_PKEY_fromdata(3)> to create 1085new keys from user provided key data. Keys should be immutable once they are 1086created, so if required the user may use L<EVP_PKEY_todata(3)>, L<OSSL_PARAM_merge(3)>, 1087and L<EVP_PKEY_fromdata(3)> to create a modified key. 1088See L<EVP_PKEY-DH(7)/Examples> for more information. 1089See L</Deprecated low-level key generation functions> for information on 1090generating a key using parameters. 1091 1092=head4 Deprecated low-level object creation 1093 1094Low-level objects were created using methods such as L<RSA_new(3)>, 1095L<RSA_up_ref(3)> and L<RSA_free(3)>. Applications should instead use the 1096high-level EVP_PKEY APIs, e.g. L<EVP_PKEY_new(3)>, L<EVP_PKEY_up_ref(3)> and 1097L<EVP_PKEY_free(3)>. 1098See also L<EVP_PKEY_CTX_new_from_name(3)> and L<EVP_PKEY_CTX_new_from_pkey(3)>. 1099 1100EVP_PKEYs may be created in a variety of ways: 1101See also L</Deprecated low-level key generation functions>, 1102L</Deprecated low-level key reading and writing functions> and 1103L</Deprecated low-level key parameter setters>. 1104 1105=head4 Deprecated low-level encryption functions 1106 1107Low-level encryption functions such as L<AES_encrypt(3)> and L<AES_decrypt(3)> 1108have been informally discouraged from use for a long time. Applications should 1109instead use the high level EVP APIs L<EVP_EncryptInit_ex(3)>, 1110L<EVP_EncryptUpdate(3)>, and L<EVP_EncryptFinal_ex(3)> or 1111L<EVP_DecryptInit_ex(3)>, L<EVP_DecryptUpdate(3)> and L<EVP_DecryptFinal_ex(3)>. 1112 1113=head4 Deprecated low-level digest functions 1114 1115Use of low-level digest functions such as L<SHA1_Init(3)> have been 1116informally discouraged from use for a long time. Applications should instead 1117use the high level EVP APIs L<EVP_DigestInit_ex(3)>, L<EVP_DigestUpdate(3)> 1118and L<EVP_DigestFinal_ex(3)>, or the quick one-shot L<EVP_Q_digest(3)>. 1119 1120Note that the functions L<SHA1(3)>, L<SHA224(3)>, L<SHA256(3)>, L<SHA384(3)> 1121and L<SHA512(3)> have changed to macros that use L<EVP_Q_digest(3)>. 1122 1123=head4 Deprecated low-level signing functions 1124 1125Use of low-level signing functions such as L<DSA_sign(3)> have been 1126informally discouraged for a long time. Instead applications should use 1127L<EVP_DigestSign(3)> and L<EVP_DigestVerify(3)>. 1128See also L<EVP_SIGNATURE-RSA(7)>, L<EVP_SIGNATURE-DSA(7)>, 1129L<EVP_SIGNATURE-ECDSA(7)> and L<EVP_SIGNATURE-ED25519(7)>. 1130 1131=head4 Deprecated low-level MAC functions 1132 1133Low-level mac functions such as L<CMAC_Init(3)> are deprecated. 1134Applications should instead use the new L<EVP_MAC(3)> interface, using 1135L<EVP_MAC_CTX_new(3)>, L<EVP_MAC_CTX_free(3)>, L<EVP_MAC_init(3)>, 1136L<EVP_MAC_update(3)> and L<EVP_MAC_final(3)> or the single-shot MAC function 1137L<EVP_Q_mac(3)>. 1138See L<EVP_MAC(3)>, L<EVP_MAC-HMAC(7)>, L<EVP_MAC-CMAC(7)>, L<EVP_MAC-GMAC(7)>, 1139L<EVP_MAC-KMAC(7)>, L<EVP_MAC-BLAKE2(7)>, L<EVP_MAC-Poly1305(7)> and 1140L<EVP_MAC-Siphash(7)> for additional information. 1141 1142Note that the one-shot method HMAC() is still available for compatibility purposes, 1143but this can also be replaced by using EVP_Q_MAC if a library context is required. 1144 1145=head4 Deprecated low-level validation functions 1146 1147Low-level validation functions such as L<DH_check(3)> have been informally 1148discouraged from use for a long time. Applications should instead use the high-level 1149EVP_PKEY APIs such as L<EVP_PKEY_check(3)>, L<EVP_PKEY_param_check(3)>, 1150L<EVP_PKEY_param_check_quick(3)>, L<EVP_PKEY_public_check(3)>, 1151L<EVP_PKEY_public_check_quick(3)>, L<EVP_PKEY_private_check(3)>, 1152and L<EVP_PKEY_pairwise_check(3)>. 1153 1154=head4 Deprecated low-level key exchange functions 1155 1156Many low-level functions have been informally discouraged from use for a long 1157time. Applications should instead use L<EVP_PKEY_derive(3)>. 1158See L<EVP_KEYEXCH-DH(7)>, L<EVP_KEYEXCH-ECDH(7)> and L<EVP_KEYEXCH-X25519(7)>. 1159 1160=head4 Deprecated low-level key generation functions 1161 1162Many low-level functions have been informally discouraged from use for a long 1163time. Applications should instead use L<EVP_PKEY_keygen_init(3)> and 1164L<EVP_PKEY_generate(3)> as described in L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>, 1165L<EVP_PKEY-RSA(7)>, L<EVP_PKEY-EC(7)> and L<EVP_PKEY-X25519(7)>. 1166The 'quick' one-shot function L<EVP_PKEY_Q_keygen(3)> and macros for the most 1167common cases: <EVP_RSA_gen(3)> and L<EVP_EC_gen(3)> may also be used. 1168 1169=head4 Deprecated low-level key reading and writing functions 1170 1171Use of low-level objects (such as DSA) has been informally discouraged from use 1172for a long time. Functions to read and write these low-level objects (such as 1173PEM_read_DSA_PUBKEY()) should be replaced. Applications should instead use 1174L<OSSL_ENCODER_to_bio(3)> and L<OSSL_DECODER_from_bio(3)>. 1175 1176=head4 Deprecated low-level key printing functions 1177 1178Use of low-level objects (such as DSA) has been informally discouraged from use 1179for a long time. Functions to print these low-level objects such as 1180DSA_print() should be replaced with the equivalent EVP_PKEY functions. 1181Application should use one of L<EVP_PKEY_print_public(3)>, 1182L<EVP_PKEY_print_private(3)>, L<EVP_PKEY_print_params(3)>, 1183L<EVP_PKEY_print_public_fp(3)>, L<EVP_PKEY_print_private_fp(3)> or 1184L<EVP_PKEY_print_params_fp(3)>. Note that internally these use 1185L<OSSL_ENCODER_to_bio(3)> and L<OSSL_DECODER_from_bio(3)>. 1186 1187=head3 Deprecated function mappings 1188 1189The following functions have been deprecated in 3.0. 1190 1191=over 4 1192 1193=item * 1194 1195AES_bi_ige_encrypt() and AES_ige_encrypt() 1196 1197There is no replacement for the IGE functions. New code should not use these modes. 1198These undocumented functions were never integrated into the EVP layer. 1199They implemented the AES Infinite Garble Extension (IGE) mode and AES 1200Bi-directional IGE mode. These modes were never formally standardised and 1201usage of these functions is believed to be very small. In particular 1202AES_bi_ige_encrypt() has a known bug. It accepts 2 AES keys, but only one 1203is ever used. The security implications are believed to be minimal, but 1204this issue was never fixed for backwards compatibility reasons. 1205 1206=item * 1207 1208AES_encrypt(), AES_decrypt(), AES_set_encrypt_key(), AES_set_decrypt_key(), 1209AES_cbc_encrypt(), AES_cfb128_encrypt(), AES_cfb1_encrypt(), AES_cfb8_encrypt(), 1210AES_ecb_encrypt(), AES_ofb128_encrypt() 1211 1212=item * 1213 1214AES_unwrap_key(), AES_wrap_key() 1215 1216See L</Deprecated low-level encryption functions> 1217 1218=item * 1219 1220AES_options() 1221 1222There is no replacement. It returned a string indicating if the AES code was unrolled. 1223 1224=item * 1225 1226ASN1_digest(), ASN1_sign(), ASN1_verify() 1227 1228There are no replacements. These old functions are not used, and could be 1229disabled with the macro NO_ASN1_OLD since OpenSSL 0.9.7. 1230 1231=item * 1232 1233ASN1_STRING_length_set() 1234 1235Use L<ASN1_STRING_set(3)> or L<ASN1_STRING_set0(3)> instead. 1236This was a potentially unsafe function that could change the bounds of a 1237previously passed in pointer. 1238 1239=item * 1240 1241BF_encrypt(), BF_decrypt(), BF_set_key(), BF_cbc_encrypt(), BF_cfb64_encrypt(), 1242BF_ecb_encrypt(), BF_ofb64_encrypt() 1243 1244See L</Deprecated low-level encryption functions>. 1245The Blowfish algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>. 1246 1247=item * 1248 1249BF_options() 1250 1251There is no replacement. This option returned a constant string. 1252 1253=item * 1254 1255BIO_get_callback(), BIO_set_callback(), BIO_debug_callback() 1256 1257Use the respective non-deprecated _ex() functions. 1258 1259=item * 1260 1261BN_is_prime_ex(), BN_is_prime_fasttest_ex() 1262 1263Use L<BN_check_prime(3)> which avoids possible misuse and always uses at least 126464 rounds of the Miller-Rabin primality test. 1265 1266=item * 1267 1268BN_pseudo_rand(), BN_pseudo_rand_range() 1269 1270Use L<BN_rand(3)> and L<BN_rand_range(3)>. 1271 1272=item * 1273 1274BN_X931_derive_prime_ex(), BN_X931_generate_prime_ex(), BN_X931_generate_Xpq() 1275 1276There are no replacements for these low-level functions. They were used internally 1277by RSA_X931_derive_ex() and RSA_X931_generate_key_ex() which are also deprecated. 1278Use L<EVP_PKEY_keygen(3)> instead. 1279 1280=item * 1281 1282Camellia_encrypt(), Camellia_decrypt(), Camellia_set_key(), 1283Camellia_cbc_encrypt(), Camellia_cfb128_encrypt(), Camellia_cfb1_encrypt(), 1284Camellia_cfb8_encrypt(), Camellia_ctr128_encrypt(), Camellia_ecb_encrypt(), 1285Camellia_ofb128_encrypt() 1286 1287See L</Deprecated low-level encryption functions>. 1288 1289=item * 1290 1291CAST_encrypt(), CAST_decrypt(), CAST_set_key(), CAST_cbc_encrypt(), 1292CAST_cfb64_encrypt(), CAST_ecb_encrypt(), CAST_ofb64_encrypt() 1293 1294See L</Deprecated low-level encryption functions>. 1295The CAST algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>. 1296 1297=item * 1298 1299CMAC_CTX_new(), CMAC_CTX_cleanup(), CMAC_CTX_copy(), CMAC_CTX_free(), 1300CMAC_CTX_get0_cipher_ctx() 1301 1302See L</Deprecated low-level MAC functions>. 1303 1304=item * 1305 1306CMAC_Init(), CMAC_Update(), CMAC_Final(), CMAC_resume() 1307 1308See L</Deprecated low-level MAC functions>. 1309 1310=item * 1311 1312CRYPTO_mem_ctrl(), CRYPTO_mem_debug_free(), CRYPTO_mem_debug_malloc(), 1313CRYPTO_mem_debug_pop(), CRYPTO_mem_debug_push(), CRYPTO_mem_debug_realloc(), 1314CRYPTO_mem_leaks(), CRYPTO_mem_leaks_cb(), CRYPTO_mem_leaks_fp(), 1315CRYPTO_set_mem_debug() 1316 1317Memory-leak checking has been deprecated in favor of more modern development 1318tools, such as compiler memory and leak sanitizers or Valgrind. 1319 1320=item * 1321 1322CRYPTO_cts128_encrypt_block(), CRYPTO_cts128_encrypt(), 1323CRYPTO_cts128_decrypt_block(), CRYPTO_cts128_decrypt(), 1324CRYPTO_nistcts128_encrypt_block(), CRYPTO_nistcts128_encrypt(), 1325CRYPTO_nistcts128_decrypt_block(), CRYPTO_nistcts128_decrypt() 1326 1327Use the higher level functions EVP_CipherInit_ex2(), EVP_CipherUpdate() and 1328EVP_CipherFinal_ex() instead. 1329See the "cts_mode" parameter in 1330L<EVP_EncryptInit(3)/Gettable and Settable EVP_CIPHER_CTX parameters>. 1331See L<EVP_EncryptInit(3)/EXAMPLES> for a AES-256-CBC-CTS example. 1332 1333=item * 1334 1335d2i_DHparams(), d2i_DHxparams(), d2i_DSAparams(), d2i_DSAPrivateKey(), 1336d2i_DSAPrivateKey_bio(), d2i_DSAPrivateKey_fp(), d2i_DSA_PUBKEY(), 1337d2i_DSA_PUBKEY_bio(), d2i_DSA_PUBKEY_fp(), d2i_DSAPublicKey(), 1338d2i_ECParameters(), d2i_ECPrivateKey(), d2i_ECPrivateKey_bio(), 1339d2i_ECPrivateKey_fp(), d2i_EC_PUBKEY(), d2i_EC_PUBKEY_bio(), 1340d2i_EC_PUBKEY_fp(), d2i_RSAPrivateKey(), 1341d2i_RSAPrivateKey_bio(), d2i_RSAPrivateKey_fp(), d2i_RSA_PUBKEY(), 1342d2i_RSA_PUBKEY_bio(), d2i_RSA_PUBKEY_fp(), d2i_RSAPublicKey(), 1343d2i_RSAPublicKey_bio(), d2i_RSAPublicKey_fp() 1344 1345See L</Deprecated i2d and d2i functions for low-level key types> 1346 1347=item * 1348 1349o2i_ECPublicKey() 1350 1351Use L<EVP_PKEY_set1_encoded_public_key(3)>. 1352See L</Deprecated low-level key parameter setters> 1353 1354=item * 1355 1356DES_crypt(), DES_fcrypt(), DES_encrypt1(), DES_encrypt2(), DES_encrypt3(), 1357DES_decrypt3(), DES_ede3_cbc_encrypt(), DES_ede3_cfb64_encrypt(), 1358DES_ede3_cfb_encrypt(),DES_ede3_ofb64_encrypt(), 1359DES_ecb_encrypt(), DES_ecb3_encrypt(), DES_ofb64_encrypt(), DES_ofb_encrypt(), 1360DES_cfb64_encrypt DES_cfb_encrypt(), DES_cbc_encrypt(), DES_ncbc_encrypt(), 1361DES_pcbc_encrypt(), DES_xcbc_encrypt(), DES_cbc_cksum(), DES_quad_cksum(), 1362DES_check_key_parity(), DES_is_weak_key(), DES_key_sched(), DES_options(), 1363DES_random_key(), DES_set_key(), DES_set_key_checked(), DES_set_key_unchecked(), 1364DES_set_odd_parity(), DES_string_to_2keys(), DES_string_to_key() 1365 1366See L</Deprecated low-level encryption functions>. 1367Algorithms for "DESX-CBC", "DES-ECB", "DES-CBC", "DES-OFB", "DES-CFB", 1368"DES-CFB1" and "DES-CFB8" have been moved to the L<Legacy Provider|/Legacy Algorithms>. 1369 1370=item * 1371 1372DH_bits(), DH_security_bits(), DH_size() 1373 1374Use L<EVP_PKEY_get_bits(3)>, L<EVP_PKEY_get_security_bits(3)> and 1375L<EVP_PKEY_get_size(3)>. 1376 1377=item * 1378 1379DH_check(), DH_check_ex(), DH_check_params(), DH_check_params_ex(), 1380DH_check_pub_key(), DH_check_pub_key_ex() 1381 1382See L</Deprecated low-level validation functions> 1383 1384=item * 1385 1386DH_clear_flags(), DH_test_flags(), DH_set_flags() 1387 1388The B<DH_FLAG_CACHE_MONT_P> flag has been deprecated without replacement. 1389The B<DH_FLAG_TYPE_DH> and B<DH_FLAG_TYPE_DHX> have been deprecated. 1390Use EVP_PKEY_is_a() to determine the type of a key. 1391There is no replacement for setting these flags. 1392 1393=item * 1394 1395DH_compute_key() DH_compute_key_padded() 1396 1397See L</Deprecated low-level key exchange functions>. 1398 1399=item * 1400 1401DH_new(), DH_new_by_nid(), DH_free(), DH_up_ref() 1402 1403See L</Deprecated low-level object creation> 1404 1405=item * 1406 1407DH_generate_key(), DH_generate_parameters_ex() 1408 1409See L</Deprecated low-level key generation functions>. 1410 1411=item * 1412 1413DH_get0_pqg(), DH_get0_p(), DH_get0_q(), DH_get0_g(), DH_get0_key(), 1414DH_get0_priv_key(), DH_get0_pub_key(), DH_get_length(), DH_get_nid() 1415 1416See L</Deprecated low-level key parameter getters> 1417 1418=item * 1419 1420DH_get_1024_160(), DH_get_2048_224(), DH_get_2048_256() 1421 1422Applications should instead set the B<OSSL_PKEY_PARAM_GROUP_NAME> as specified in 1423L<EVP_PKEY-DH(7)/DH parameters>) to one of "dh_1024_160", "dh_2048_224" or 1424"dh_2048_256" when generating a DH key. 1425 1426=item * 1427 1428DH_KDF_X9_42() 1429 1430Applications should use L<EVP_PKEY_CTX_set_dh_kdf_type(3)> instead. 1431 1432=item * 1433 1434DH_get_default_method(), DH_get0_engine(), DH_meth_*(), DH_new_method(), 1435DH_OpenSSL(), DH_get_ex_data(), DH_set_default_method(), DH_set_method(), 1436DH_set_ex_data() 1437 1438See L</Providers are a replacement for engines and low-level method overrides> 1439 1440=item * 1441 1442DHparams_print(), DHparams_print_fp() 1443 1444See L</Deprecated low-level key printing functions> 1445 1446=item * 1447 1448DH_set0_key(), DH_set0_pqg(), DH_set_length() 1449 1450See L</Deprecated low-level key parameter setters> 1451 1452=item * 1453 1454DSA_bits(), DSA_security_bits(), DSA_size() 1455 1456Use L<EVP_PKEY_get_bits(3)>, L<EVP_PKEY_get_security_bits(3)> and 1457L<EVP_PKEY_get_size(3)>. 1458 1459=item * 1460 1461DHparams_dup(), DSA_dup_DH() 1462 1463There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)> 1464and L<EVP_PKEY_dup(3)> instead. 1465 1466=item * 1467 1468DSA_generate_key(), DSA_generate_parameters_ex() 1469 1470See L</Deprecated low-level key generation functions>. 1471 1472=item * 1473 1474DSA_get0_engine(), DSA_get_default_method(), DSA_get_ex_data(), 1475DSA_get_method(), DSA_meth_*(), DSA_new_method(), DSA_OpenSSL(), 1476DSA_set_default_method(), DSA_set_ex_data(), DSA_set_method() 1477 1478See L</Providers are a replacement for engines and low-level method overrides>. 1479 1480=item * 1481 1482DSA_get0_p(), DSA_get0_q(), DSA_get0_g(), DSA_get0_pqg(), DSA_get0_key(), 1483DSA_get0_priv_key(), DSA_get0_pub_key() 1484 1485See L</Deprecated low-level key parameter getters>. 1486 1487=item * 1488 1489DSA_new(), DSA_free(), DSA_up_ref() 1490 1491See L</Deprecated low-level object creation> 1492 1493=item * 1494 1495DSAparams_dup() 1496 1497There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)> 1498and L<EVP_PKEY_dup(3)> instead. 1499 1500=item * 1501 1502DSAparams_print(), DSAparams_print_fp(), DSA_print(), DSA_print_fp() 1503 1504See L</Deprecated low-level key printing functions> 1505 1506=item * 1507 1508DSA_set0_key(), DSA_set0_pqg() 1509 1510See L</Deprecated low-level key parameter setters> 1511 1512=item * 1513 1514DSA_set_flags(), DSA_clear_flags(), DSA_test_flags() 1515 1516The B<DSA_FLAG_CACHE_MONT_P> flag has been deprecated without replacement. 1517 1518=item * 1519 1520DSA_sign(), DSA_do_sign(), DSA_sign_setup(), DSA_verify(), DSA_do_verify() 1521 1522See L</Deprecated low-level signing functions>. 1523 1524=item * 1525 1526ECDH_compute_key() 1527 1528See L</Deprecated low-level key exchange functions>. 1529 1530=item * 1531 1532ECDH_KDF_X9_62() 1533 1534Applications may either set this using the helper function 1535L<EVP_PKEY_CTX_set_ecdh_kdf_type(3)> or by setting an L<OSSL_PARAM(3)> using the 1536"kdf-type" as shown in L<EVP_KEYEXCH-ECDH(7)/EXAMPLES> 1537 1538=item * 1539 1540ECDSA_sign(), ECDSA_sign_ex(), ECDSA_sign_setup(), ECDSA_do_sign(), 1541ECDSA_do_sign_ex(), ECDSA_verify(), ECDSA_do_verify() 1542 1543See L</Deprecated low-level signing functions>. 1544 1545=item * 1546 1547ECDSA_size() 1548 1549Applications should use L<EVP_PKEY_get_size(3)>. 1550 1551=item * 1552 1553EC_GF2m_simple_method(), EC_GFp_mont_method(), EC_GFp_nist_method(), 1554EC_GFp_nistp224_method(), EC_GFp_nistp256_method(), EC_GFp_nistp521_method(), 1555EC_GFp_simple_method() 1556 1557There are no replacements for these functions. Applications should rely on the 1558library automatically assigning a suitable method internally when an EC_GROUP 1559is constructed. 1560 1561=item * 1562 1563EC_GROUP_clear_free() 1564 1565Use L<EC_GROUP_free(3)> instead. 1566 1567=item * 1568 1569EC_GROUP_get_curve_GF2m(), EC_GROUP_get_curve_GFp(), EC_GROUP_set_curve_GF2m(), 1570EC_GROUP_set_curve_GFp() 1571 1572Applications should use L<EC_GROUP_get_curve(3)> and L<EC_GROUP_set_curve(3)>. 1573 1574=item * 1575 1576EC_GROUP_have_precompute_mult(), EC_GROUP_precompute_mult(), 1577EC_KEY_precompute_mult() 1578 1579These functions are not widely used. Applications should instead switch to 1580named curves which OpenSSL has hardcoded lookup tables for. 1581 1582=item * 1583 1584EC_GROUP_new(), EC_GROUP_method_of(), EC_POINT_method_of() 1585 1586EC_METHOD is now an internal-only concept and a suitable EC_METHOD is assigned 1587internally without application intervention. 1588Users of EC_GROUP_new() should switch to a different suitable constructor. 1589 1590=item * 1591 1592EC_KEY_can_sign() 1593 1594Applications should use L<EVP_PKEY_can_sign(3)> instead. 1595 1596=item * 1597 1598EC_KEY_check_key() 1599 1600See L</Deprecated low-level validation functions> 1601 1602=item * 1603 1604EC_KEY_set_flags(), EC_KEY_get_flags(), EC_KEY_clear_flags() 1605 1606See L<EVP_PKEY-EC(7)/Common EC parameters> which handles flags as separate 1607parameters for B<OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT>, 1608B<OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE>, B<OSSL_PKEY_PARAM_EC_ENCODING>, 1609B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH> and 1610B<OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC>. 1611See also L<EVP_PKEY-EC(7)/EXAMPLES> 1612 1613=item * 1614 1615EC_KEY_dup(), EC_KEY_copy() 1616 1617There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)> 1618and L<EVP_PKEY_dup(3)> instead. 1619 1620=item * 1621 1622EC_KEY_decoded_from_explicit_params() 1623 1624There is no replacement. 1625 1626=item * 1627 1628EC_KEY_generate_key() 1629 1630See L</Deprecated low-level key generation functions>. 1631 1632=item * 1633 1634EC_KEY_get0_group(), EC_KEY_get0_private_key(), EC_KEY_get0_public_key(), 1635EC_KEY_get_conv_form(), EC_KEY_get_enc_flags() 1636 1637See L</Deprecated low-level key parameter getters>. 1638 1639=item * 1640 1641EC_KEY_get0_engine(), EC_KEY_get_default_method(), EC_KEY_get_method(), 1642EC_KEY_new_method(), EC_KEY_get_ex_data(), EC_KEY_OpenSSL(), 1643EC_KEY_set_ex_data(), EC_KEY_set_default_method(), EC_KEY_METHOD_*(), 1644EC_KEY_set_method() 1645 1646See L</Providers are a replacement for engines and low-level method overrides> 1647 1648=item * 1649 1650EC_METHOD_get_field_type() 1651 1652Use L<EC_GROUP_get_field_type(3)> instead. 1653See L</Providers are a replacement for engines and low-level method overrides> 1654 1655=item * 1656 1657EC_KEY_key2buf(), EC_KEY_oct2key(), EC_KEY_oct2priv(), EC_KEY_priv2buf(), 1658EC_KEY_priv2oct() 1659 1660There are no replacements for these. 1661 1662=item * 1663 1664EC_KEY_new(), EC_KEY_new_by_curve_name(), EC_KEY_free(), EC_KEY_up_ref() 1665 1666See L</Deprecated low-level object creation> 1667 1668=item * 1669 1670EC_KEY_print(), EC_KEY_print_fp() 1671 1672See L</Deprecated low-level key printing functions> 1673 1674=item * 1675 1676EC_KEY_set_asn1_flag(), EC_KEY_set_conv_form(), EC_KEY_set_enc_flags() 1677 1678See L</Deprecated low-level key parameter setters>. 1679 1680=item * 1681 1682EC_KEY_set_group(), EC_KEY_set_private_key(), EC_KEY_set_public_key(), 1683EC_KEY_set_public_key_affine_coordinates() 1684 1685See L</Deprecated low-level key parameter setters>. 1686 1687=item * 1688 1689ECParameters_print(), ECParameters_print_fp(), ECPKParameters_print(), 1690ECPKParameters_print_fp() 1691 1692See L</Deprecated low-level key printing functions> 1693 1694=item * 1695 1696EC_POINT_bn2point(), EC_POINT_point2bn() 1697 1698These functions were not particularly useful, since EC point serialization 1699formats are not individual big-endian integers. 1700 1701=item * 1702 1703EC_POINT_get_affine_coordinates_GF2m(), EC_POINT_get_affine_coordinates_GFp(), 1704EC_POINT_set_affine_coordinates_GF2m(), EC_POINT_set_affine_coordinates_GFp() 1705 1706Applications should use L<EC_POINT_get_affine_coordinates(3)> and 1707L<EC_POINT_set_affine_coordinates(3)> instead. 1708 1709=item * 1710 1711EC_POINT_get_Jprojective_coordinates_GFp(), EC_POINT_set_Jprojective_coordinates_GFp() 1712 1713These functions are not widely used. Applications should instead use the 1714L<EC_POINT_set_affine_coordinates(3)> and L<EC_POINT_get_affine_coordinates(3)> 1715functions. 1716 1717=item * 1718 1719EC_POINT_make_affine(), EC_POINTs_make_affine() 1720 1721There is no replacement. These functions were not widely used, and OpenSSL 1722automatically performs this conversion when needed. 1723 1724=item * 1725 1726EC_POINT_set_compressed_coordinates_GF2m(), EC_POINT_set_compressed_coordinates_GFp() 1727 1728Applications should use L<EC_POINT_set_compressed_coordinates(3)> instead. 1729 1730=item * 1731 1732EC_POINTs_mul() 1733 1734This function is not widely used. Applications should instead use the 1735L<EC_POINT_mul(3)> function. 1736 1737=item * 1738 1739B<ENGINE_*()> 1740 1741All engine functions are deprecated. An engine should be rewritten as a provider. 1742See L</Providers are a replacement for engines and low-level method overrides>. 1743 1744=item * 1745 1746B<ERR_load_*()>, ERR_func_error_string(), ERR_get_error_line(), 1747ERR_get_error_line_data(), ERR_get_state() 1748 1749OpenSSL now loads error strings automatically so these functions are not needed. 1750 1751=item * 1752 1753ERR_peek_error_line_data(), ERR_peek_last_error_line_data() 1754 1755The new functions are L<ERR_peek_error_func(3)>, L<ERR_peek_last_error_func(3)>, 1756L<ERR_peek_error_data(3)>, L<ERR_peek_last_error_data(3)>, L<ERR_get_error_all(3)>, 1757L<ERR_peek_error_all(3)> and L<ERR_peek_last_error_all(3)>. 1758Applications should use L<ERR_get_error_all(3)>, or pick information 1759with ERR_peek functions and finish off with getting the error code by using 1760L<ERR_get_error(3)>. 1761 1762=item * 1763 1764EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_iv_noconst(), EVP_CIPHER_CTX_original_iv() 1765 1766Applications should instead use L<EVP_CIPHER_CTX_get_updated_iv(3)>, 1767L<EVP_CIPHER_CTX_get_updated_iv(3)> and L<EVP_CIPHER_CTX_get_original_iv(3)> 1768respectively. 1769See L<EVP_CIPHER_CTX_get_original_iv(3)> for further information. 1770 1771=item * 1772 1773B<EVP_CIPHER_meth_*()>, EVP_MD_CTX_set_update_fn(), EVP_MD_CTX_update_fn(), 1774B<EVP_MD_meth_*()> 1775 1776See L</Providers are a replacement for engines and low-level method overrides>. 1777 1778=item * 1779 1780EVP_PKEY_CTRL_PKCS7_ENCRYPT(), EVP_PKEY_CTRL_PKCS7_DECRYPT(), 1781EVP_PKEY_CTRL_PKCS7_SIGN(), EVP_PKEY_CTRL_CMS_ENCRYPT(), 1782EVP_PKEY_CTRL_CMS_DECRYPT(), and EVP_PKEY_CTRL_CMS_SIGN() 1783 1784These control operations are not invoked by the OpenSSL library anymore and 1785are replaced by direct checks of the key operation against the key type 1786when the operation is initialized. 1787 1788=item * 1789 1790EVP_PKEY_CTX_get0_dh_kdf_ukm(), EVP_PKEY_CTX_get0_ecdh_kdf_ukm() 1791 1792See the "kdf-ukm" item in L<EVP_KEYEXCH-DH(7)/DH key exchange parameters> and 1793L<EVP_KEYEXCH-ECDH(7)/ECDH Key Exchange parameters>. 1794These functions are obsolete and should not be required. 1795 1796=item * 1797 1798EVP_PKEY_CTX_set_rsa_keygen_pubexp() 1799 1800Applications should use L<EVP_PKEY_CTX_set1_rsa_keygen_pubexp(3)> instead. 1801 1802=item * 1803 1804EVP_PKEY_cmp(), EVP_PKEY_cmp_parameters() 1805 1806Applications should use L<EVP_PKEY_eq(3)> and L<EVP_PKEY_parameters_eq(3)> instead. 1807See L<EVP_PKEY_copy_parameters(3)> for further details. 1808 1809=item * 1810 1811EVP_PKEY_encrypt_old(), EVP_PKEY_decrypt_old(), 1812 1813Applications should use L<EVP_PKEY_encrypt_init(3)> and L<EVP_PKEY_encrypt(3)> or 1814L<EVP_PKEY_decrypt_init(3)> and L<EVP_PKEY_decrypt(3)> instead. 1815 1816=item * 1817 1818EVP_PKEY_get0() 1819 1820This function returns NULL if the key comes from a provider. 1821 1822=item * 1823 1824EVP_PKEY_get0_DH(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_EC_KEY(), EVP_PKEY_get0_RSA(), 1825EVP_PKEY_get1_DH(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_EC_KEY and EVP_PKEY_get1_RSA(), 1826EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash() 1827 1828See L</Functions that return an internal key should be treated as read only>. 1829 1830=item * 1831 1832B<EVP_PKEY_meth_*()> 1833 1834See L</Providers are a replacement for engines and low-level method overrides>. 1835 1836=item * 1837 1838EVP_PKEY_new_CMAC_key() 1839 1840See L</Deprecated low-level MAC functions>. 1841 1842=item * 1843 1844EVP_PKEY_assign(), EVP_PKEY_set1_DH(), EVP_PKEY_set1_DSA(), 1845EVP_PKEY_set1_EC_KEY(), EVP_PKEY_set1_RSA() 1846 1847See L</Deprecated low-level key object getters and setters> 1848 1849=item * 1850 1851EVP_PKEY_set1_tls_encodedpoint() EVP_PKEY_get1_tls_encodedpoint() 1852 1853These functions were previously used by libssl to set or get an encoded public 1854key into/from an EVP_PKEY object. With OpenSSL 3.0 these are replaced by the more 1855generic functions L<EVP_PKEY_set1_encoded_public_key(3)> and 1856L<EVP_PKEY_get1_encoded_public_key(3)>. 1857The old versions have been converted to deprecated macros that just call the 1858new functions. 1859 1860=item * 1861 1862EVP_PKEY_set1_engine(), EVP_PKEY_get0_engine() 1863 1864See L</Providers are a replacement for engines and low-level method overrides>. 1865 1866=item * 1867 1868EVP_PKEY_set_alias_type() 1869 1870This function has been removed. There is no replacement. 1871See L</EVP_PKEY_set_alias_type() method has been removed> 1872 1873=item * 1874 1875HMAC_Init_ex(), HMAC_Update(), HMAC_Final(), HMAC_size() 1876 1877See L</Deprecated low-level MAC functions>. 1878 1879=item * 1880 1881HMAC_CTX_new(), HMAC_CTX_free(), HMAC_CTX_copy(), HMAC_CTX_reset(), 1882HMAC_CTX_set_flags(), HMAC_CTX_get_md() 1883 1884See L</Deprecated low-level MAC functions>. 1885 1886=item * 1887 1888i2d_DHparams(), i2d_DHxparams() 1889 1890See L</Deprecated low-level key reading and writing functions> 1891and L<d2i_RSAPrivateKey(3)/Migration> 1892 1893=item * 1894 1895i2d_DSAparams(), i2d_DSAPrivateKey(), i2d_DSAPrivateKey_bio(), 1896i2d_DSAPrivateKey_fp(), i2d_DSA_PUBKEY(), i2d_DSA_PUBKEY_bio(), 1897i2d_DSA_PUBKEY_fp(), i2d_DSAPublicKey() 1898 1899See L</Deprecated low-level key reading and writing functions> 1900and L<d2i_RSAPrivateKey(3)/Migration> 1901 1902=item * 1903 1904i2d_ECParameters(), i2d_ECPrivateKey(), i2d_ECPrivateKey_bio(), 1905i2d_ECPrivateKey_fp(), i2d_EC_PUBKEY(), i2d_EC_PUBKEY_bio(), 1906i2d_EC_PUBKEY_fp() 1907 1908See L</Deprecated low-level key reading and writing functions> 1909and L<d2i_RSAPrivateKey(3)/Migration> 1910 1911=item * 1912 1913i2o_ECPublicKey() 1914 1915Use L<EVP_PKEY_get1_encoded_public_key(3)>. 1916See L</Deprecated low-level key parameter getters> 1917 1918=item * 1919 1920i2d_RSAPrivateKey(), i2d_RSAPrivateKey_bio(), i2d_RSAPrivateKey_fp(), 1921i2d_RSA_PUBKEY(), i2d_RSA_PUBKEY_bio(), i2d_RSA_PUBKEY_fp(), 1922i2d_RSAPublicKey(), i2d_RSAPublicKey_bio(), i2d_RSAPublicKey_fp() 1923 1924See L</Deprecated low-level key reading and writing functions> 1925and L<d2i_RSAPrivateKey(3)/Migration> 1926 1927=item * 1928 1929IDEA_encrypt(), IDEA_set_decrypt_key(), IDEA_set_encrypt_key(), 1930IDEA_cbc_encrypt(), IDEA_cfb64_encrypt(), IDEA_ecb_encrypt(), 1931IDEA_ofb64_encrypt() 1932 1933See L</Deprecated low-level encryption functions>. 1934IDEA has been moved to the L<Legacy Provider|/Legacy Algorithms>. 1935 1936=item * 1937 1938IDEA_options() 1939 1940There is no replacement. This function returned a constant string. 1941 1942=item * 1943 1944MD2(), MD2_Init(), MD2_Update(), MD2_Final() 1945 1946See L</Deprecated low-level encryption functions>. 1947MD2 has been moved to the L<Legacy Provider|/Legacy Algorithms>. 1948 1949=item * 1950 1951MD2_options() 1952 1953There is no replacement. This function returned a constant string. 1954 1955=item * 1956 1957MD4(), MD4_Init(), MD4_Update(), MD4_Final(), MD4_Transform() 1958 1959See L</Deprecated low-level encryption functions>. 1960MD4 has been moved to the L<Legacy Provider|/Legacy Algorithms>. 1961 1962=item * 1963 1964MDC2(), MDC2_Init(), MDC2_Update(), MDC2_Final() 1965 1966See L</Deprecated low-level encryption functions>. 1967MDC2 has been moved to the L<Legacy Provider|/Legacy Algorithms>. 1968 1969=item * 1970 1971MD5(), MD5_Init(), MD5_Update(), MD5_Final(), MD5_Transform() 1972 1973See L</Deprecated low-level encryption functions>. 1974 1975=item * 1976 1977NCONF_WIN32() 1978 1979This undocumented function has no replacement. 1980See L<config(5)/HISTORY> for more details. 1981 1982=item * 1983 1984OCSP_parse_url() 1985 1986Use L<OSSL_HTTP_parse_url(3)> instead. 1987 1988=item * 1989 1990B<OCSP_REQ_CTX> type and B<OCSP_REQ_CTX_*()> functions 1991 1992These methods were used to collect all necessary data to form a HTTP request, 1993and to perform the HTTP transfer with that request. With OpenSSL 3.0, the 1994type is B<OSSL_HTTP_REQ_CTX>, and the deprecated functions are replaced 1995with B<OSSL_HTTP_REQ_CTX_*()>. See L<OSSL_HTTP_REQ_CTX(3)> for additional 1996details. 1997 1998=item * 1999 2000OPENSSL_fork_child(), OPENSSL_fork_parent(), OPENSSL_fork_prepare() 2001 2002There is no replacement for these functions. These pthread fork support methods 2003were unused by OpenSSL. 2004 2005=item * 2006 2007OSSL_STORE_ctrl(), OSSL_STORE_do_all_loaders(), OSSL_STORE_LOADER_get0_engine(), 2008OSSL_STORE_LOADER_get0_scheme(), OSSL_STORE_LOADER_new(), 2009OSSL_STORE_LOADER_set_attach(), OSSL_STORE_LOADER_set_close(), 2010OSSL_STORE_LOADER_set_ctrl(), OSSL_STORE_LOADER_set_eof(), 2011OSSL_STORE_LOADER_set_error(), OSSL_STORE_LOADER_set_expect(), 2012OSSL_STORE_LOADER_set_find(), OSSL_STORE_LOADER_set_load(), 2013OSSL_STORE_LOADER_set_open(), OSSL_STORE_LOADER_set_open_ex(), 2014OSSL_STORE_register_loader(), OSSL_STORE_unregister_loader(), 2015OSSL_STORE_vctrl() 2016 2017These functions helped applications and engines create loaders for 2018schemes they supported. These are all deprecated and discouraged in favour of 2019provider implementations, see L<provider-storemgmt(7)>. 2020 2021=item * 2022 2023PEM_read_DHparams(), PEM_read_bio_DHparams(), 2024PEM_read_DSAparams(), PEM_read_bio_DSAparams(), 2025PEM_read_DSAPrivateKey(), PEM_read_DSA_PUBKEY(), 2026PEM_read_bio_DSAPrivateKey and PEM_read_bio_DSA_PUBKEY(), 2027PEM_read_ECPKParameters(), PEM_read_ECPrivateKey(), PEM_read_EC_PUBKEY(), 2028PEM_read_bio_ECPKParameters(), PEM_read_bio_ECPrivateKey(), PEM_read_bio_EC_PUBKEY(), 2029PEM_read_RSAPrivateKey(), PEM_read_RSA_PUBKEY(), PEM_read_RSAPublicKey(), 2030PEM_read_bio_RSAPrivateKey(), PEM_read_bio_RSA_PUBKEY(), PEM_read_bio_RSAPublicKey(), 2031PEM_write_bio_DHparams(), PEM_write_bio_DHxparams(), PEM_write_DHparams(), PEM_write_DHxparams(), 2032PEM_write_DSAparams(), PEM_write_DSAPrivateKey(), PEM_write_DSA_PUBKEY(), 2033PEM_write_bio_DSAparams(), PEM_write_bio_DSAPrivateKey(), PEM_write_bio_DSA_PUBKEY(), 2034PEM_write_ECPKParameters(), PEM_write_ECPrivateKey(), PEM_write_EC_PUBKEY(), 2035PEM_write_bio_ECPKParameters(), PEM_write_bio_ECPrivateKey(), PEM_write_bio_EC_PUBKEY(), 2036PEM_write_RSAPrivateKey(), PEM_write_RSA_PUBKEY(), PEM_write_RSAPublicKey(), 2037PEM_write_bio_RSAPrivateKey(), PEM_write_bio_RSA_PUBKEY(), 2038PEM_write_bio_RSAPublicKey(), 2039 2040See L</Deprecated low-level key reading and writing functions> 2041 2042=item * 2043 2044PKCS1_MGF1() 2045 2046See L</Deprecated low-level encryption functions>. 2047 2048=item * 2049 2050RAND_get_rand_method(), RAND_set_rand_method(), RAND_OpenSSL(), 2051RAND_set_rand_engine() 2052 2053Applications should instead use L<RAND_set_DRBG_type(3)>, 2054L<EVP_RAND(3)> and L<EVP_RAND(7)>. 2055See L<RAND_set_rand_method(3)> for more details. 2056 2057=item * 2058 2059RC2_encrypt(), RC2_decrypt(), RC2_set_key(), RC2_cbc_encrypt(), RC2_cfb64_encrypt(), 2060RC2_ecb_encrypt(), RC2_ofb64_encrypt(), 2061RC4(), RC4_set_key(), RC4_options(), 2062RC5_32_encrypt(), RC5_32_set_key(), RC5_32_decrypt(), RC5_32_cbc_encrypt(), 2063RC5_32_cfb64_encrypt(), RC5_32_ecb_encrypt(), RC5_32_ofb64_encrypt() 2064 2065See L</Deprecated low-level encryption functions>. 2066The Algorithms "RC2", "RC4" and "RC5" have been moved to the L<Legacy Provider|/Legacy Algorithms>. 2067 2068=item * 2069 2070RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update(), RIPEMD160_Final(), 2071RIPEMD160_Transform() 2072 2073See L</Deprecated low-level digest functions>. 2074The RIPE algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>. 2075 2076=item * 2077 2078RSA_bits(), RSA_security_bits(), RSA_size() 2079 2080Use L<EVP_PKEY_get_bits(3)>, L<EVP_PKEY_get_security_bits(3)> and 2081L<EVP_PKEY_get_size(3)>. 2082 2083=item * 2084 2085RSA_check_key(), RSA_check_key_ex() 2086 2087See L</Deprecated low-level validation functions> 2088 2089=item * 2090 2091RSA_clear_flags(), RSA_flags(), RSA_set_flags(), RSA_test_flags(), 2092RSA_setup_blinding(), RSA_blinding_off(), RSA_blinding_on() 2093 2094All of these RSA flags have been deprecated without replacement: 2095 2096B<RSA_FLAG_BLINDING>, B<RSA_FLAG_CACHE_PRIVATE>, B<RSA_FLAG_CACHE_PUBLIC>, 2097B<RSA_FLAG_EXT_PKEY>, B<RSA_FLAG_NO_BLINDING>, B<RSA_FLAG_THREAD_SAFE> 2098B<RSA_METHOD_FLAG_NO_CHECK> 2099 2100=item * 2101 2102RSA_generate_key_ex(), RSA_generate_multi_prime_key() 2103 2104See L</Deprecated low-level key generation functions>. 2105 2106=item * 2107 2108RSA_get0_engine() 2109 2110See L</Providers are a replacement for engines and low-level method overrides> 2111 2112=item * 2113 2114RSA_get0_crt_params(), RSA_get0_d(), RSA_get0_dmp1(), RSA_get0_dmq1(), 2115RSA_get0_e(), RSA_get0_factors(), RSA_get0_iqmp(), RSA_get0_key(), 2116RSA_get0_multi_prime_crt_params(), RSA_get0_multi_prime_factors(), RSA_get0_n(), 2117RSA_get0_p(), RSA_get0_pss_params(), RSA_get0_q(), 2118RSA_get_multi_prime_extra_count() 2119 2120See L</Deprecated low-level key parameter getters> 2121 2122=item * 2123 2124RSA_new(), RSA_free(), RSA_up_ref() 2125 2126See L</Deprecated low-level object creation>. 2127 2128=item * 2129 2130RSA_get_default_method(), RSA_get_ex_data and RSA_get_method() 2131 2132See L</Providers are a replacement for engines and low-level method overrides>. 2133 2134=item * 2135 2136RSA_get_version() 2137 2138There is no replacement. 2139 2140=item * 2141 2142B<RSA_meth_*()>, RSA_new_method(), RSA_null_method and RSA_PKCS1_OpenSSL() 2143 2144See L</Providers are a replacement for engines and low-level method overrides>. 2145 2146=item * 2147 2148B<RSA_padding_add_*()>, B<RSA_padding_check_*()> 2149 2150See L</Deprecated low-level signing functions> and 2151L</Deprecated low-level encryption functions>. 2152 2153=item * 2154 2155RSA_print(), RSA_print_fp() 2156 2157See L</Deprecated low-level key printing functions> 2158 2159=item * 2160 2161RSA_public_encrypt(), RSA_private_decrypt() 2162 2163See L</Deprecated low-level encryption functions> 2164 2165=item * 2166 2167RSA_private_encrypt(), RSA_public_decrypt() 2168 2169This is equivalent to doing sign and verify recover operations (with a padding 2170mode of none). See L</Deprecated low-level signing functions>. 2171 2172=item * 2173 2174RSAPrivateKey_dup(), RSAPublicKey_dup() 2175 2176There is no direct replacement. Applications may use L<EVP_PKEY_dup(3)>. 2177 2178=item * 2179 2180RSAPublicKey_it(), RSAPrivateKey_it() 2181 2182See L</Deprecated low-level key reading and writing functions> 2183 2184=item * 2185 2186RSA_set0_crt_params(), RSA_set0_factors(), RSA_set0_key(), 2187RSA_set0_multi_prime_params() 2188 2189See L</Deprecated low-level key parameter setters>. 2190 2191=item * 2192 2193RSA_set_default_method(), RSA_set_method(), RSA_set_ex_data() 2194 2195See L</Providers are a replacement for engines and low-level method overrides> 2196 2197=item * 2198 2199RSA_sign(), RSA_sign_ASN1_OCTET_STRING(), RSA_verify(), 2200RSA_verify_ASN1_OCTET_STRING(), RSA_verify_PKCS1_PSS(), 2201RSA_verify_PKCS1_PSS_mgf1() 2202 2203See L</Deprecated low-level signing functions>. 2204 2205=item * 2206 2207RSA_X931_derive_ex(), RSA_X931_generate_key_ex(), RSA_X931_hash_id() 2208 2209There are no replacements for these functions. 2210X931 padding can be set using L<EVP_SIGNATURE-RSA(7)/Signature Parameters>. 2211See B<OSSL_SIGNATURE_PARAM_PAD_MODE>. 2212 2213=item * 2214 2215SEED_encrypt(), SEED_decrypt(), SEED_set_key(), SEED_cbc_encrypt(), 2216SEED_cfb128_encrypt(), SEED_ecb_encrypt(), SEED_ofb128_encrypt() 2217 2218See L</Deprecated low-level encryption functions>. 2219The SEED algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>. 2220 2221=item * 2222 2223SHA1_Init(), SHA1_Update(), SHA1_Final(), SHA1_Transform(), 2224SHA224_Init(), SHA224_Update(), SHA224_Final(), 2225SHA256_Init(), SHA256_Update(), SHA256_Final(), SHA256_Transform(), 2226SHA384_Init(), SHA384_Update(), SHA384_Final(), 2227SHA512_Init(), SHA512_Update(), SHA512_Final(), SHA512_Transform() 2228 2229See L</Deprecated low-level digest functions>. 2230 2231=item * 2232 2233SRP_Calc_A(), SRP_Calc_B(), SRP_Calc_client_key(), SRP_Calc_server_key(), 2234SRP_Calc_u(), SRP_Calc_x(), SRP_check_known_gN_param(), SRP_create_verifier(), 2235SRP_create_verifier_BN(), SRP_get_default_gN(), SRP_user_pwd_free(), SRP_user_pwd_new(), 2236SRP_user_pwd_set0_sv(), SRP_user_pwd_set1_ids(), SRP_user_pwd_set_gN(), 2237SRP_VBASE_add0_user(), SRP_VBASE_free(), SRP_VBASE_get1_by_user(), SRP_VBASE_init(), 2238SRP_VBASE_new(), SRP_Verify_A_mod_N(), SRP_Verify_B_mod_N() 2239 2240There are no replacements for the SRP functions. 2241 2242=item * 2243 2244SSL_CTX_set_tmp_dh_callback(), SSL_set_tmp_dh_callback(), 2245SSL_CTX_set_tmp_dh(), SSL_set_tmp_dh() 2246 2247These are used to set the Diffie-Hellman (DH) parameters that are to be used by 2248servers requiring ephemeral DH keys. Instead applications should consider using 2249the built-in DH parameters that are available by calling L<SSL_CTX_set_dh_auto(3)> 2250or L<SSL_set_dh_auto(3)>. If custom parameters are necessary then applications can 2251use the alternative functions L<SSL_CTX_set0_tmp_dh_pkey(3)> and 2252L<SSL_set0_tmp_dh_pkey(3)>. There is no direct replacement for the "callback" 2253functions. The callback was originally useful in order to have different 2254parameters for export and non-export ciphersuites. Export ciphersuites are no 2255longer supported by OpenSSL. Use of the callback functions should be replaced 2256by one of the other methods described above. 2257 2258=item * 2259 2260SSL_CTX_set_tlsext_ticket_key_cb() 2261 2262Use the new L<SSL_CTX_set_tlsext_ticket_key_evp_cb(3)> function instead. 2263 2264=item * 2265 2266WHIRLPOOL(), WHIRLPOOL_Init(), WHIRLPOOL_Update(), WHIRLPOOL_Final(), 2267WHIRLPOOL_BitUpdate() 2268 2269See L</Deprecated low-level digest functions>. 2270The Whirlpool algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>. 2271 2272=item * 2273 2274X509_certificate_type() 2275 2276This was an undocumented function. Applications can use L<X509_get0_pubkey(3)> 2277and L<X509_get0_signature(3)> instead. 2278 2279=item * 2280 2281X509_http_nbio(), X509_CRL_http_nbio() 2282 2283Use L<X509_load_http(3)> and L<X509_CRL_load_http(3)> instead. 2284 2285=back 2286 2287=head3 NID handling for provided keys and algorithms 2288 2289The following functions for NID (numeric id) handling have changed semantics. 2290 2291=over 4 2292 2293=item * 2294 2295EVP_PKEY_id(), EVP_PKEY_get_id() 2296 2297This function was previously used to reliably return the NID of 2298an EVP_PKEY object, e.g., to look up the name of the algorithm of 2299such EVP_PKEY by calling L<OBJ_nid2sn(3)>. With the introduction 2300of L<provider(7)>s EVP_PKEY_id() or its new equivalent 2301L<EVP_PKEY_get_id(3)> might now also return the value -1 2302(B<EVP_PKEY_KEYMGMT>) indicating the use of a provider to 2303implement the EVP_PKEY object. Therefore, the use of 2304L<EVP_PKEY_get0_type_name(3)> is recommended for retrieving 2305the name of the EVP_PKEY algorithm. 2306 2307=back 2308 2309=head2 Using the FIPS Module in applications 2310 2311See L<fips_module(7)> and L<OSSL_PROVIDER-FIPS(7)> for details. 2312 2313=head2 OpenSSL command line application changes 2314 2315=head3 New applications 2316 2317L<B<openssl kdf>|openssl-kdf(1)> uses the new L<EVP_KDF(3)> API. 2318L<B<openssl kdf>|openssl-mac(1)> uses the new L<EVP_MAC(3)> API. 2319 2320=head3 Added options 2321 2322B<-provider_path> and B<-provider> are available to all apps and can be used 2323multiple times to load any providers, such as the 'legacy' provider or third 2324party providers. If used then the 'default' provider would also need to be 2325specified if required. The B<-provider_path> must be specified before the 2326B<-provider> option. 2327 2328The B<list> app has many new options. See L<openssl-list(1)> for more 2329information. 2330 2331B<-crl_lastupdate> and B<-crl_nextupdate> used by B<openssl ca> allows 2332explicit setting of fields in the generated CRL. 2333 2334=head3 Removed options 2335 2336Interactive mode is not longer available. 2337 2338The B<-crypt> option used by B<openssl passwd>. 2339The B<-c> option used by B<openssl x509>, B<openssl dhparam>, 2340B<openssl dsaparam>, and B<openssl ecparam>. 2341 2342=head3 Other Changes 2343 2344The output of Command line applications may have minor changes. 2345These are primarily changes in capitalisation and white space. However, in some 2346cases, there are additional differences. 2347For example, the DH parameters output from B<openssl dhparam> now lists 'P', 2348'Q', 'G' and 'pcounter' instead of 'prime', 'generator', 'subgroup order' and 2349'counter' respectively. 2350 2351The B<openssl> commands that read keys, certificates, and CRLs now 2352automatically detect the PEM or DER format of the input files so it is not 2353necessary to explicitly specify the input format anymore. However if the 2354input format option is used the specified format will be required. 2355 2356B<openssl speed> no longer uses low-level API calls. 2357This implies some of the performance numbers might not be comparable with the 2358previous releases due to higher overhead. This applies particularly to 2359measuring performance on smaller data chunks. 2360 2361b<openssl dhparam>, B<openssl dsa>, B<openssl gendsa>, B<openssl dsaparam>, 2362B<openssl genrsa> and B<openssl rsa> have been modified to use PKEY APIs. 2363B<openssl genrsa> and B<openssl rsa> now write PKCS #8 keys by default. 2364 2365=head3 Default settings 2366 2367"SHA256" is now the default digest for TS query used by B<openssl ts>. 2368 2369=head3 Deprecated apps 2370 2371B<openssl rsautl> is deprecated, use B<openssl pkeyutl> instead. 2372B<openssl dhparam>, B<openssl dsa>, B<openssl gendsa>, B<openssl dsaparam>, 2373B<openssl genrsa>, B<openssl rsa>, B<openssl genrsa> and B<openssl rsa> are 2374now in maintenance mode and no new features will be added to them. 2375 2376=head2 TLS Changes 2377 2378=over 4 2379 2380=item * 2381 2382TLS 1.3 FFDHE key exchange support added 2383 2384This uses DH safe prime named groups. 2385 2386=item * 2387 2388Support for fully "pluggable" TLSv1.3 groups. 2389 2390This means that providers may supply their own group implementations (using 2391either the "key exchange" or the "key encapsulation" methods) which will 2392automatically be detected and used by libssl. 2393 2394=item * 2395 2396SSL and SSL_CTX options are now 64 bit instead of 32 bit. 2397 2398The signatures of the functions to get and set options on SSL and 2399SSL_CTX objects changed from "unsigned long" to "uint64_t" type. 2400 2401This may require source code changes. For example it is no longer possible 2402to use the B<SSL_OP_> macro values in preprocessor C<#if> conditions. 2403However it is still possible to test whether these macros are defined or not. 2404 2405See L<SSL_CTX_get_options(3)>, L<SSL_CTX_set_options(3)>, 2406L<SSL_get_options(3)> and L<SSL_set_options(3)>. 2407 2408=item * 2409 2410SSL_set1_host() and SSL_add1_host() Changes 2411 2412These functions now take IP literal addresses as well as actual hostnames. 2413 2414=item * 2415 2416Added SSL option SSL_OP_CLEANSE_PLAINTEXT 2417 2418If the option is set, openssl cleanses (zeroizes) plaintext bytes from 2419internal buffers after delivering them to the application. Note, 2420the application is still responsible for cleansing other copies 2421(e.g.: data received by L<SSL_read(3)>). 2422 2423=item * 2424 2425Client-initiated renegotiation is disabled by default. 2426 2427To allow it, use the B<-client_renegotiation> option, 2428the B<SSL_OP_ALLOW_CLIENT_RENEGOTIATION> flag, or the C<ClientRenegotiation> 2429config parameter as appropriate. 2430 2431=item * 2432 2433Secure renegotiation is now required by default for TLS connections 2434 2435Support for RFC 5746 secure renegotiation is now required by default for 2436SSL or TLS connections to succeed. Applications that require the ability 2437to connect to legacy peers will need to explicitly set 2438SSL_OP_LEGACY_SERVER_CONNECT. Accordingly, SSL_OP_LEGACY_SERVER_CONNECT 2439is no longer set as part of SSL_OP_ALL. 2440 2441=item * 2442 2443Combining the Configure options no-ec and no-dh no longer disables TLSv1.3 2444 2445Typically if OpenSSL has no EC or DH algorithms then it cannot support 2446connections with TLSv1.3. However OpenSSL now supports "pluggable" groups 2447through providers. Therefore third party providers may supply group 2448implementations even where there are no built-in ones. Attempting to create 2449TLS connections in such a build without also disabling TLSv1.3 at run time or 2450using third party provider groups may result in handshake failures. TLSv1.3 2451can be disabled at compile time using the "no-tls1_3" Configure option. 2452 2453=item * 2454 2455SSL_CTX_set_ciphersuites() and SSL_set_ciphersuites() changes. 2456 2457The methods now ignore unknown ciphers. 2458 2459=item * 2460 2461Security callback change. 2462 2463The security callback, which can be customised by application code, supports 2464the security operation SSL_SECOP_TMP_DH. This is defined to take an EVP_PKEY 2465in the "other" parameter. In most places this is what is passed. All these 2466places occur server side. However there was one client side call of this 2467security operation and it passed a DH object instead. This is incorrect 2468according to the definition of SSL_SECOP_TMP_DH, and is inconsistent with all 2469of the other locations. Therefore this client side call has been changed to 2470pass an EVP_PKEY instead. 2471 2472=item * 2473 2474New SSL option SSL_OP_IGNORE_UNEXPECTED_EOF 2475 2476The SSL option SSL_OP_IGNORE_UNEXPECTED_EOF is introduced. If that option 2477is set, an unexpected EOF is ignored, it pretends a close notify was received 2478instead and so the returned error becomes SSL_ERROR_ZERO_RETURN. 2479 2480=item * 2481 2482The security strength of SHA1 and MD5 based signatures in TLS has been reduced. 2483 2484This results in SSL 3, TLS 1.0, TLS 1.1 and DTLS 1.0 no longer 2485working at the default security level of 1 and instead requires security 2486level 0. The security level can be changed either using the cipher string 2487with C<@SECLEVEL>, or calling L<SSL_CTX_set_security_level(3)>. This also means 2488that where the signature algorithms extension is missing from a ClientHello 2489then the handshake will fail in TLS 1.2 at security level 1. This is because, 2490although this extension is optional, failing to provide one means that 2491OpenSSL will fallback to a default set of signature algorithms. This default 2492set requires the availability of SHA1. 2493 2494=item * 2495 2496X509 certificates signed using SHA1 are no longer allowed at security level 1 and above. 2497 2498In TLS/SSL the default security level is 1. It can be set either using the cipher 2499string with C<@SECLEVEL>, or calling L<SSL_CTX_set_security_level(3)>. If the 2500leaf certificate is signed with SHA-1, a call to L<SSL_CTX_use_certificate(3)> 2501will fail if the security level is not lowered first. 2502Outside TLS/SSL, the default security level is -1 (effectively 0). It can 2503be set using L<X509_VERIFY_PARAM_set_auth_level(3)> or using the B<-auth_level> 2504options of the commands. 2505 2506=back 2507 2508=head1 SEE ALSO 2509 2510L<fips_module(7)> 2511 2512=head1 HISTORY 2513 2514The migration guide was created for OpenSSL 3.0. 2515 2516=head1 COPYRIGHT 2517 2518Copyright 2021-2025 The OpenSSL Project Authors. All Rights Reserved. 2519 2520Licensed under the Apache License 2.0 (the "License"). You may not use 2521this file except in compliance with the License. You can obtain a copy 2522in the file LICENSE in the source distribution or at 2523L<https://www.openssl.org/source/license.html>. 2524 2525=cut 2526