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 <levitte@openssl.org>
Reviewed-by: David von Oheimb <david.von.oheimb@siemens.com>
(Merged from https://github.com/openssl/openssl/pull/14997)

diff --git a/CHANGES.md b/CHANGES.md
index 480c4091a9f8d0b58077cc650995d5ff9d1ff1ba..a7420d6d5a3823159ab1d22bb2b6a90ac1699323 100644 (file)
--- 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 3af7e17bee14654c917d4df937770f30aa320f0e..5cfc7405f3fd54fc8fd710b5425b9a03050027bb 100644 (file)
--- 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 742418cf104f91b0e408a2dcd22511811ee1c556..1ca38f8ae93c4df6df21c68b4123a8a206573a64 100644 (file)
--- 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<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
+ 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<EVP_PKEY_keygen(3)>
 
 =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 307008f7ba1af3748e4f9997b85e0e72a015da61..44d385655e5f8d4860e592984dfe948211132070 100644 (file)
--- a/doc/man7/evp.pod
+++ b/doc/man7/evp.pod
@@ -31,7 +31,7 @@ L<EVP_PKEY_new(3)>. EVP_PKEYs can be associated
 with a private key of a particular algorithm by using the functions
 described on the L<EVP_PKEY_fromdata(3)> page, or
 new keys can be generated using L<EVP_PKEY_keygen(3)>.
-EVP_PKEYs can be compared using L<EVP_PKEY_cmp(3)>, or printed using
+EVP_PKEYs can be compared using L<EVP_PKEY_eq(3)>, or printed using
 L<EVP_PKEY_print_private(3)>. L<EVP_PKEY_todata(3)> can be used to convert a
 key back into an L<OSSL_PARAM(3)> array.
 

diff --git a/doc/man7/provider-keymgmt.pod b/doc/man7/provider-keymgmt.pod
index c9280bc8ef4562057ca9747118040f6876dac057..000c8cab3fe18ce1802a80b0681296b48a49b848 100644 (file)
--- 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<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> and
 B<OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS>.

diff --git a/include/openssl/evp.h b/include/openssl/evp.h
index 5d493f171eed6d6fa88a8138175f932c753edcb7..a9a9662370f3a1aad67ff61fb4095f1c0f20051d 100644 (file)
--- 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 3d63482f64530cf42bbdf70211921c53fd63d7b0..f8fdc7287df3a09259c4443d273e363e4a78eba4 100644 (file)
--- 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 720f28edea3d3ea1f53529ad329b373604da050c..b938f11d1ebf6dda9a263bdf468d8d2ceec61a9b 100644 (file)
--- 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: