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)

3 files changed, 17 insertions, 12 deletions

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<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 307008f7ba..44d385655e 100644
--- 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 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<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> and
 B<OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS>.