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 480c409..a7420d6 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -567,14 +567,13 @@
*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 3af7e17..5cfc740 100644
--- a/crypto/evp/p_lib.c
+++ b/crypto/evp/p_lib.c
@@ -292,10 +292,12 @@
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 @@
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 742418c..1ca38f8 100644
--- a/doc/man3/EVP_PKEY_copy_parameters.pod
+++ b/doc/man3/EVP_PKEY_copy_parameters.pod
@@ -14,8 +14,13 @@
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 @@
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 @@
=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 307008f..44d3856 100644
--- a/doc/man7/evp.pod
+++ b/doc/man7/evp.pod
@@ -31,7 +31,7 @@
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 c9280bc..000c8ca 100644
--- a/doc/man7/provider-keymgmt.pod
+++ b/doc/man7/provider-keymgmt.pod
@@ -175,7 +175,7 @@
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 5d493f1..a9a9662 100644
--- a/include/openssl/evp.h
+++ b/include/openssl/evp.h
@@ -1356,12 +1356,16 @@
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_cmp(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);
+# endif
+
int EVP_PKEY_print_public(BIO *out, const EVP_PKEY *pkey,
int indent, ASN1_PCTX *pctx);
int EVP_PKEY_print_private(BIO *out, const EVP_PKEY *pkey,
diff --git a/test/evp_extra_test.c b/test/evp_extra_test.c
index 3d63482..f8fdc72 100644
--- a/test/evp_extra_test.c
+++ b/test/evp_extra_test.c
@@ -2758,7 +2758,7 @@
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 720f28e..b938f11 100644
--- a/util/libcrypto.num
+++ b/util/libcrypto.num
@@ -190,7 +190,7 @@
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 @@
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:
