From c85c5e1a5327379306f4c3f8248ace740c64c338 Mon Sep 17 00:00:00 2001 From: Shane Lontis Date: Fri, 23 Apr 2021 10:53:03 +1000 Subject: [PATCH] Deprecate EVP_PKEY_cmp() and EVP_PKEY_cmp_parameters(). The replacement functions EVP_PKEY_eq() and EVP_PKEY_parameters_eq() already exist. Reviewed-by: Richard Levitte Reviewed-by: David von Oheimb (Merged from https://github.com/openssl/openssl/pull/14997) --- CHANGES.md | 13 ++++++------- crypto/evp/p_lib.c | 4 ++++ doc/man3/EVP_PKEY_copy_parameters.pod | 25 +++++++++++++++---------- doc/man7/evp.pod | 2 +- doc/man7/provider-keymgmt.pod | 2 +- include/openssl/evp.h | 8 ++++++-- test/evp_extra_test.c | 2 +- util/libcrypto.num | 4 ++-- 8 files changed, 36 insertions(+), 24 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 480c4091a9..a7420d6d5a 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -567,14 +567,13 @@ OpenSSL 3.0 *Richard Levitte* - * Renamed `EVP_PKEY_cmp()` to `EVP_PKEY_eq()` and - `EVP_PKEY_cmp_parameters()` to `EVP_PKEY_parameters_eq()`. - While the old function names have been retained for backward compatibility - they should not be used in new developments - because their return values are confusing: Unlike other `_cmp()` functions - they do not return 0 in case their arguments are equal. + * Deprecated `EVP_PKEY_cmp()` and `EVP_PKEY_cmp_parameters()` since their + return values were confusing: Unlike other `_cmp()` functions + they do not return 0 when their arguments are equal. + The new replacement functions `EVP_PKEY_eq()` and `EVP_PKEY_parameters_eq()` + should be used. - *David von Oheimb* + *David von Oheimb and Shane Lontis* * Deprecated `EC_METHOD_get_field_type()`. Applications should switch to `EC_GROUP_get_field_type()`. diff --git a/crypto/evp/p_lib.c b/crypto/evp/p_lib.c index 3af7e17bee..5cfc7405f3 100644 --- a/crypto/evp/p_lib.c +++ b/crypto/evp/p_lib.c @@ -292,10 +292,12 @@ static int evp_pkey_cmp_any(const EVP_PKEY *a, const EVP_PKEY *b, return evp_keymgmt_match(keymgmt1, keydata1, keydata2, selection); } +# ifndef OPENSSL_NO_DEPRECATED_3_0 int EVP_PKEY_cmp_parameters(const EVP_PKEY *a, const EVP_PKEY *b) { return EVP_PKEY_parameters_eq(a, b); } +#endif int EVP_PKEY_parameters_eq(const EVP_PKEY *a, const EVP_PKEY *b) { @@ -315,10 +317,12 @@ int EVP_PKEY_parameters_eq(const EVP_PKEY *a, const EVP_PKEY *b) return -2; } +# ifndef OPENSSL_NO_DEPRECATED_3_0 int EVP_PKEY_cmp(const EVP_PKEY *a, const EVP_PKEY *b) { return EVP_PKEY_eq(a, b); } +#endif int EVP_PKEY_eq(const EVP_PKEY *a, const EVP_PKEY *b) { diff --git a/doc/man3/EVP_PKEY_copy_parameters.pod b/doc/man3/EVP_PKEY_copy_parameters.pod index 742418cf10..1ca38f8ae9 100644 --- a/doc/man3/EVP_PKEY_copy_parameters.pod +++ b/doc/man3/EVP_PKEY_copy_parameters.pod @@ -14,8 +14,13 @@ EVP_PKEY_cmp - public key parameter and comparison functions int EVP_PKEY_copy_parameters(EVP_PKEY *to, const EVP_PKEY *from); int EVP_PKEY_parameters_eq(const EVP_PKEY *a, const EVP_PKEY *b); - int EVP_PKEY_cmp_parameters(const EVP_PKEY *a, const EVP_PKEY *b); int EVP_PKEY_eq(const EVP_PKEY *a, const EVP_PKEY *b); + +Deprecated since OpenSSL 3.0, can be hidden entirely by defining +B with a suitable version value, see +L: + + int EVP_PKEY_cmp_parameters(const EVP_PKEY *a, const EVP_PKEY *b); int EVP_PKEY_cmp(const EVP_PKEY *a, const EVP_PKEY *b); =head1 DESCRIPTION @@ -46,10 +51,9 @@ Since OpenSSL private keys contain public key components too the function EVP_PKEY_eq() can also be used to determine if a private key matches a public key. -EVP_PKEY_cmp() and EVP_PKEY_cmp_parameters() differ in their return values -compared to other _cmp() functions. They are aliases for EVP_PKEY_eq() and -EVP_PKEY_parameters_eq() functions provided for backwards compatibility -with existing applications. +The deprecated functions EVP_PKEY_cmp() and EVP_PKEY_cmp_parameters() differ in +their return values compared to other _cmp() functions. They are aliases for +EVP_PKEY_eq() and EVP_PKEY_parameters_eq(). =head1 RETURN VALUES @@ -72,14 +76,15 @@ L =head1 HISTORY -EVP_PKEY_eq() and EVP_PKEY_parameters_eq() were added in OpenSSL 3.0 to -avoid confusion on the return values of EVP_PKEY_cmp() and -EVP_PKEY_cmp_parameters() which unlike other _cmp() -functions do not return 0 in case their arguments are equal. +The EVP_PKEY_cmp() and EVP_PKEY_cmp_parameters() functions were deprecated in +OpenSSL 3.0. + +The EVP_PKEY_eq() and EVP_PKEY_parameters_eq() were added in OpenSSL 3.0 to +replace EVP_PKEY_cmp() and EVP_PKEY_cmp_parameters(). =head1 COPYRIGHT -Copyright 2006-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2006-2021 The OpenSSL Project Authors. All Rights Reserved. Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/doc/man7/evp.pod b/doc/man7/evp.pod index 307008f7ba..44d385655e 100644 --- a/doc/man7/evp.pod +++ b/doc/man7/evp.pod @@ -31,7 +31,7 @@ L. EVP_PKEYs can be associated with a private key of a particular algorithm by using the functions described on the L page, or new keys can be generated using L. -EVP_PKEYs can be compared using L, or printed using +EVP_PKEYs can be compared using L, or printed using L. L can be used to convert a key back into an L array. diff --git a/doc/man7/provider-keymgmt.pod b/doc/man7/provider-keymgmt.pod index c9280bc8ef..000c8cab3f 100644 --- a/doc/man7/provider-keymgmt.pod +++ b/doc/man7/provider-keymgmt.pod @@ -175,7 +175,7 @@ Indicating that all key object parameters should be considered, regardless of their more granular classification. =for comment This should used by EVP functions such as -EVP_PKEY_copy_parameters() and EVP_PKEY_cmp_parameters() +EVP_PKEY_copy_parameters() and EVP_PKEY_parameters_eq() This is a combination of B and B. diff --git a/include/openssl/evp.h b/include/openssl/evp.h index 5d493f171e..a9a9662370 100644 --- a/include/openssl/evp.h +++ b/include/openssl/evp.h @@ -1356,11 +1356,15 @@ EVP_PKEY *d2i_KeyParams_bio(int type, EVP_PKEY **a, BIO *in); int EVP_PKEY_copy_parameters(EVP_PKEY *to, const EVP_PKEY *from); int EVP_PKEY_missing_parameters(const EVP_PKEY *pkey); int EVP_PKEY_save_parameters(EVP_PKEY *pkey, int mode); -int EVP_PKEY_cmp_parameters(const EVP_PKEY *a, const EVP_PKEY *b); int EVP_PKEY_parameters_eq(const EVP_PKEY *a, const EVP_PKEY *b); +int EVP_PKEY_eq(const EVP_PKEY *a, const EVP_PKEY *b); +# ifndef OPENSSL_NO_DEPRECATED_3_0 +OSSL_DEPRECATEDIN_3_0 +int EVP_PKEY_cmp_parameters(const EVP_PKEY *a, const EVP_PKEY *b); +OSSL_DEPRECATEDIN_3_0 int EVP_PKEY_cmp(const EVP_PKEY *a, const EVP_PKEY *b); -int EVP_PKEY_eq(const EVP_PKEY *a, const EVP_PKEY *b); +# endif int EVP_PKEY_print_public(BIO *out, const EVP_PKEY *pkey, int indent, ASN1_PCTX *pctx); diff --git a/test/evp_extra_test.c b/test/evp_extra_test.c index 3d63482f64..f8fdc7287d 100644 --- a/test/evp_extra_test.c +++ b/test/evp_extra_test.c @@ -2758,7 +2758,7 @@ static int test_ecpub(int idx) if (!TEST_ptr(d2i_PublicKey(EVP_PKEY_EC, &pkey2, &q, savelen))) goto done; /* The keys should match. */ - if (!TEST_int_eq(EVP_PKEY_cmp(pkey, pkey2), 1)) + if (!TEST_int_eq(EVP_PKEY_eq(pkey, pkey2), 1)) goto done; # endif diff --git a/util/libcrypto.num b/util/libcrypto.num index 720f28edea..b938f11d1e 100644 --- a/util/libcrypto.num +++ b/util/libcrypto.num @@ -190,7 +190,7 @@ EVP_DigestInit 193 3_0_0 EXIST::FUNCTION: EVP_PKEY_meth_find 194 3_0_0 EXIST::FUNCTION:DEPRECATEDIN_3_0 X509_VERIFY_PARAM_get_count 195 3_0_0 EXIST::FUNCTION: ASN1_BIT_STRING_get_bit 196 3_0_0 EXIST::FUNCTION: -EVP_PKEY_cmp 197 3_0_0 EXIST::FUNCTION: +EVP_PKEY_cmp 197 3_0_0 EXIST::FUNCTION:DEPRECATEDIN_3_0 d2i_X509_ALGORS 198 3_0_0 EXIST::FUNCTION: EVP_PKEY2PKCS8 199 3_0_0 EXIST::FUNCTION: BN_nist_mod_256 200 3_0_0 EXIST::FUNCTION: @@ -3460,7 +3460,7 @@ ERR_print_errors_cb 3531 3_0_0 EXIST::FUNCTION: ENGINE_set_default_string 3532 3_0_0 EXIST::FUNCTION:DEPRECATEDIN_3_0,ENGINE BIO_number_read 3533 3_0_0 EXIST::FUNCTION: CRYPTO_zalloc 3534 3_0_0 EXIST::FUNCTION: -EVP_PKEY_cmp_parameters 3535 3_0_0 EXIST::FUNCTION: +EVP_PKEY_cmp_parameters 3535 3_0_0 EXIST::FUNCTION:DEPRECATEDIN_3_0 EVP_PKEY_CTX_new_id 3537 3_0_0 EXIST::FUNCTION: TLS_FEATURE_free 3538 3_0_0 EXIST::FUNCTION: d2i_BASIC_CONSTRAINTS 3539 3_0_0 EXIST::FUNCTION: -- 2.34.1