From 4d49b68504cc494e552bce8e0b82ec8b501d5abe Mon Sep 17 00:00:00 2001 From: "Dr. David von Oheimb" Date: Mon, 29 Mar 2021 19:32:48 +0200 Subject: Crypto: Add deprecation compatibility declarations for SHA* message digest functions Also add hints to SHA256_Init.pod and CHANGES.md how to replace SHA256() etc. Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/14741) --- CHANGES.md | 76 +++++++++++++++++++++++++++++++++----------------------------- 1 file changed, 40 insertions(+), 36 deletions(-) (limited to 'CHANGES.md') diff --git a/CHANGES.md b/CHANGES.md index a2ef2f6b3f..69863b27da 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -240,11 +240,11 @@ OpenSSL 3.0 *Matt Caswell* - * A number of functions handling low level keys or engines were deprecated + * A number of functions handling low-level keys or engines were deprecated including EVP_PKEY_set1_engine(), EVP_PKEY_get0_engine(), EVP_PKEY_assign(), EVP_PKEY_get0(), EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305() and EVP_PKEY_get0_siphash(). Applications using engines should instead use - providers. Applications getting or setting low level keys in an EVP_PKEY + providers. Applications getting or setting low-level keys in an EVP_PKEY should instead use the OSSL_ENCODER or OSSL_DECODER APIs, or alternatively use EVP_PKEY_fromdata() or EVP_PKEY_get_params(). @@ -405,7 +405,7 @@ OpenSSL 3.0 *Dmitry Belyavskiy* - * All of the low level EC_KEY functions have been deprecated including: + * All of the low-level EC_KEY functions have been deprecated including: EC_KEY_OpenSSL, EC_KEY_get_default_method, EC_KEY_set_default_method, EC_KEY_get_method, EC_KEY_set_method, EC_KEY_new_method @@ -823,7 +823,7 @@ OpenSSL 3.0 *David von Oheimb* - * All of the low level RSA functions have been deprecated including: + * All of the low-level RSA functions have been deprecated including: RSA_new_method, RSA_size, RSA_security_bits, RSA_get0_pss_params, RSA_get_version, RSA_get0_engine, RSA_generate_key_ex, @@ -854,12 +854,12 @@ OpenSSL 3.0 RSA_meth_set_verify, RSA_meth_get_keygen, RSA_meth_set_keygen, RSA_meth_get_multi_prime_keygen and RSA_meth_set_multi_prime_keygen. - Use of these low level functions has been informally discouraged for a long + Use of these low-level functions has been informally discouraged for a long time. Instead applications should use L, L, L and L. - All of these low level RSA functions have been deprecated without + All of these low-level RSA functions have been deprecated without replacement: RSA_blinding_off, RSA_blinding_on, RSA_clear_flags, RSA_get_version, @@ -904,7 +904,7 @@ OpenSSL 3.0 *Paul Dale* - * All of the low level DH functions have been deprecated including: + * All of the low-level DH functions have been deprecated including: DH_OpenSSL, DH_set_default_method, DH_get_default_method, DH_set_method, DH_new_method, DH_new, DH_free, DH_up_ref, DH_bits, DH_set0_pqg, DH_size, @@ -920,11 +920,11 @@ OpenSSL 3.0 DH_meth_set_init, DH_meth_get_finish, DH_meth_set_finish, DH_meth_get_generate_params and DH_meth_set_generate_params. - Use of these low level functions has been informally discouraged for a long + Use of these low-level functions has been informally discouraged for a long time. Instead applications should use L and L. - These low level DH functions have been deprecated without replacement: + These low-level DH functions have been deprecated without replacement: DH_clear_flags, DH_get_1024_160, DH_get_2048_224, DH_get_2048_256, DH_set_flags and DH_test_flags. @@ -948,7 +948,7 @@ OpenSSL 3.0 *Paul Dale and Matt Caswell* - * All of the low level DSA functions have been deprecated including: + * All of the low-level DSA functions have been deprecated including: DSA_new, DSA_free, DSA_up_ref, DSA_bits, DSA_get0_pqg, DSA_set0_pqg, DSA_get0_key, DSA_set0_key, DSA_get0_p, DSA_get0_q, DSA_get0_g, @@ -968,11 +968,11 @@ OpenSSL 3.0 DSA_meth_get_finish, DSA_meth_set_finish, DSA_meth_get_paramgen, DSA_meth_set_paramgen, DSA_meth_get_keygen and DSA_meth_set_keygen. - Use of these low level functions has been informally discouraged for a long + Use of these low-level functions has been informally discouraged for a long time. Instead applications should use L, L and L. - These low level DSA functions have been deprecated without replacement: + These low-level DSA functions have been deprecated without replacement: DSA_clear_flags, DSA_dup_DH, DSAparams_dup, DSA_set_flags and DSA_test_flags. @@ -1002,13 +1002,13 @@ OpenSSL 3.0 *Richard Levitte* - * Deprecated low level ECDH and ECDSA functions. These include: + * Deprecated low-level ECDH and ECDSA functions. These include: ECDH_compute_key, ECDSA_do_sign, ECDSA_do_sign_ex, ECDSA_do_verify, ECDSA_sign_setup, ECDSA_sign, ECDSA_sign_ex, ECDSA_verify and ECDSA_size. - Use of these low level functions has been informally discouraged for a long + Use of these low-level functions has been informally discouraged for a long time. Instead applications should use the EVP_PKEY_derive(3), EVP_DigestSign(3) and EVP_DigestVerify(3) functions. @@ -1039,7 +1039,7 @@ OpenSSL 3.0 HMAC_Init_ex, HMAC_Update, HMAC_Final, HMAC_CTX_copy, HMAC_CTX_set_flags and HMAC_CTX_get_md. - Use of these low level functions has been informally discouraged for a long + Use of these low-level functions has been informally discouraged for a long time. Instead applications should use L, L, L, L and L or the single-shot MAC function L. @@ -1058,19 +1058,19 @@ OpenSSL 3.0 *Rich Salz* - * All of the low level CMAC functions have been deprecated including: + * All of the low-level CMAC functions have been deprecated including: CMAC_CTX_new, CMAC_CTX_cleanup, CMAC_CTX_free, CMAC_CTX_get0_cipher_ctx, CMAC_CTX_copy, CMAC_Init, CMAC_Update, CMAC_Final and CMAC_resume. - Use of these low level functions has been informally discouraged for a long + Use of these low-level functions has been informally discouraged for a long time. Instead applications should use L, L, L, L and L. *Paul Dale* - * All of the low level MD2, MD4, MD5, MDC2, RIPEMD160, SHA1, SHA224, SHA256, + * The low-level MD2, MD4, MD5, MDC2, RIPEMD160, SHA1, SHA224, SHA256, SHA384, SHA512 and Whirlpool digest functions have been deprecated. These include: @@ -1079,17 +1079,21 @@ OpenSSL 3.0 MD5_Final, MD5_Transform, MDC2, MDC2_Init, MDC2_Update, MDC2_Final, RIPEMD160, RIPEMD160_Init, RIPEMD160_Update, RIPEMD160_Final, RIPEMD160_Transform, SHA1_Init, SHA1_Update, SHA1_Final, SHA1_Transform, - SHA224_Init, SHA224_Update, SHA224_Final, SHA224_Transform, SHA256_Init, - SHA256_Update, SHA256_Final, SHA256_Transform, SHA384, SHA384_Init, - SHA384_Update, SHA384_Final, SHA512, SHA512_Init, SHA512_Update, - SHA512_Final, SHA512_Transform, WHIRLPOOL, WHIRLPOOL_Init, + SHA224_Init, SHA224_Update, SHA224_Final, SHA224_Transform, + SHA256_Init, SHA256_Update, SHA256_Final, SHA256_Transform, + SHA384_Init, SHA384_Update, SHA384_Final, + SHA512_Init, SHA512_Update, SHA512_Final, SHA512_Transform, + WHIRLPOOL, WHIRLPOOL_Init, WHIRLPOOL_Update, WHIRLPOOL_BitUpdate and WHIRLPOOL_Final. - Use of these low level functions has been informally discouraged - for a long time. Applications should use the EVP_DigestInit_ex(3), - EVP_DigestUpdate(3) and EVP_DigestFinal_ex(3) functions instead. + Use of these low-level functions has been informally discouraged + for a long time. Applications should use the L, + L, and L functions instead. + Alternatively, the quick one-shot function L can be used. + SHA1, SHA224, SHA256, SHA384 and SHA512 have changed from functions to macros + like this: (EVP_Q_digest(NULL, "SHA256", NULL, d, n, md, NULL) ? md : NULL). - *Paul Dale* + *Paul Dale and David von Oheimb* * Corrected the documentation of the return values from the `EVP_DigestSign*` set of functions. The documentation mentioned negative values for some @@ -1101,7 +1105,7 @@ OpenSSL 3.0 *Richard Levitte* - * All of the low level cipher functions have been deprecated including: + * All of the low-level cipher functions have been deprecated including: AES_options, AES_set_encrypt_key, AES_set_decrypt_key, AES_encrypt, AES_decrypt, AES_ecb_encrypt, AES_cbc_encrypt, AES_cfb128_encrypt, @@ -1133,7 +1137,7 @@ OpenSSL 3.0 SEED_set_key, SEED_encrypt, SEED_decrypt, SEED_ecb_encrypt, SEED_cbc_encrypt, SEED_cfb128_encrypt and SEED_ofb128_encrypt. - Use of these low level functions has been informally discouraged for + Use of these low-level functions has been informally discouraged for a long time. Applications should use the high level EVP APIs, e.g. EVP_EncryptInit_ex, EVP_EncryptUpdate, EVP_EncryptFinal_ex, and the equivalently named decrypt functions instead. @@ -1168,7 +1172,7 @@ OpenSSL 3.0 difficult to perform and are not believed likely. Attacks against DH512 are considered just feasible. However, for an attack the target would have to re-use the DH512 private key, which is not recommended anyway. - Also applications directly using the low level API BN_mod_exp may be + Also applications directly using the low-level API BN_mod_exp may be affected if they use BN_FLG_CONSTTIME. ([CVE-2019-1551]) @@ -7652,11 +7656,11 @@ OpenSSL 1.0.1 *Steve Henson* - * Add similar low level API blocking to ciphers. + * Add similar low-level API blocking to ciphers. *Steve Henson* - * Low level digest APIs are not approved in FIPS mode: any attempt + * low-level digest APIs are not approved in FIPS mode: any attempt to use these will cause a fatal error. Applications that *really* want to use them can use the `private_*` version instead. @@ -11044,7 +11048,7 @@ OpenSSL 0.9.8.] * Add new 'medium level' PKCS#12 API. Certificates and keys can be added using this API to created arbitrary PKCS#12 - files while avoiding the low level API. + files while avoiding the low-level API. New options to PKCS12_create(), key or cert can be NULL and will then be omitted from the output file. The encryption @@ -11055,7 +11059,7 @@ OpenSSL 0.9.8.] options work when creating a PKCS#12 file. New option -nomac to omit the mac, NONE can be set for an encryption algorithm. New code is modified to use the enhanced PKCS12_create() - instead of the low level API. + instead of the low-level API. *Steve Henson* @@ -12777,7 +12781,7 @@ s-cbc 3624.96k 5258.21k 5530.91k 5624.30k 5628.26k *Richard Levitte* - * Change all calls to low level digest routines in the library and + * Change all calls to low-level digest routines in the library and applications to use EVP. Add missing calls to HMAC_cleanup() and don't assume HMAC_CTX can be copied using memcpy(). @@ -15360,7 +15364,7 @@ s-cbc 3624.96k 5258.21k 5530.91k 5624.30k 5628.26k *Bodo Moeller* * New openssl application 'rsautl'. This utility can be - used for low level RSA operations. DER public key + used for low-level RSA operations. DER public key BIO/fp routines also added. *Steve Henson* @@ -17240,7 +17244,7 @@ s-cbc 3624.96k 5258.21k 5530.91k 5624.30k 5628.26k provides hooks that allow the default DSA functions or functions on a "per key" basis to be replaced. This allows hardware acceleration and hardware key storage to be handled without major modification to the - library. Also added low level modexp hooks and CRYPTO_EX structure and + library. Also added low-level modexp hooks and CRYPTO_EX structure and associated functions. *Steve Henson* -- cgit v1.2.3