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