Deprecate EC_GROUP_clear_free()

There is nothing confidential in `EC_GROUP` so really having a
`EC_GROUP_clear_free` function at all does not make much sense anymore.

See https://github.com/openssl/openssl/issues/9822

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9874)

diff --git a/crypto/ec/ec_lib.c b/crypto/ec/ec_lib.c
index 69b3c7fca58ca892c6fbc352a41fafe0a6cb7de9..08d018c4e669dfc23da5f6b8d4de98ef2695dd14 100644 (file)
--- a/crypto/ec/ec_lib.c
+++ b/crypto/ec/ec_lib.c
@@ -116,6 +116,7 @@ void EC_GROUP_free(EC_GROUP *group)
     OPENSSL_free(group);
 }
 
+#if !OPENSSL_API_3
 void EC_GROUP_clear_free(EC_GROUP *group)
 {
     if (!group)
@@ -134,6 +135,7 @@ void EC_GROUP_clear_free(EC_GROUP *group)
     OPENSSL_clear_free(group->seed, group->seed_len);
     OPENSSL_clear_free(group, sizeof(*group));
 }
+#endif
 
 int EC_GROUP_copy(EC_GROUP *dest, const EC_GROUP *src)
 {

diff --git a/doc/man3/EC_GROUP_new.pod b/doc/man3/EC_GROUP_new.pod
index 17284e12c068d541159156054e88ec7c07976a40..2d85e91d19d6ea6802b76186338655da9cb6364c 100644 (file)
--- a/doc/man3/EC_GROUP_new.pod
+++ b/doc/man3/EC_GROUP_new.pod
@@ -32,7 +32,6 @@ objects
  EC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params)
  EC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params)
  void EC_GROUP_free(EC_GROUP *group);
- void EC_GROUP_clear_free(EC_GROUP *group);
 
  EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a,
                                   const BIGNUM *b, BN_CTX *ctx);
@@ -59,6 +58,12 @@ objects
 
  size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems);
 
+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)>:
+
+ void EC_GROUP_clear_free(EC_GROUP *group);
+
 =head1 DESCRIPTION
 
 Within the library there are two forms of elliptic curve that are of interest. The first form is those defined over the
@@ -129,7 +134,10 @@ that the default library context is always used.
 EC_GROUP_free frees the memory associated with the EC_GROUP.
 If B<group> is NULL nothing is done.
 
-EC_GROUP_clear_free destroys any sensitive data held within the EC_GROUP and then frees its memory.
+EC_GROUP_clear_free is deprecated: it was meant to destroy any sensitive data
+held within the EC_GROUP and then free its memory, but since all the data stored
+in the EC_GROUP is public anyway, this function is unnecessary.
+Its use can be safely replaced with EC_GROUP_free.
 If B<group> is NULL nothing is done.
 
 =head1 RETURN VALUES
@@ -149,8 +157,18 @@ L<OPENSSL_CTX(3)>
 
 =head1 HISTORY
 
+=over 2
+
+=item *
+
 EC_GROUP_new_ex and EC_GROUP_new_by_curve_name_ex were added in OpenSSL 3.0.
 
+=item *
+
+EC_GROUP_clear_free() was deprecated in OpenSSL 3.0; use EC_GROUP_free() instead.
+
+=back
+
 =head1 COPYRIGHT
 
 Copyright 2013-2018 The OpenSSL Project Authors. All Rights Reserved.

diff --git a/include/openssl/ec.h b/include/openssl/ec.h
index 11999b41fc2b0bd761785b33fa3f7e605fc14827..b4c50ecfc70df3369025b76b2d741e0f3a92dcc1 100644 (file)
--- a/include/openssl/ec.h
+++ b/include/openssl/ec.h
@@ -131,7 +131,7 @@ void EC_GROUP_free(EC_GROUP *group);
 /** Clears and frees a EC_GROUP object
  *  \param  group  EC_GROUP object to be cleared and freed.
  */
-void EC_GROUP_clear_free(EC_GROUP *group);
+DEPRECATEDIN_3(void EC_GROUP_clear_free(EC_GROUP *group))
 
 /** Copies EC_GROUP objects. Note: both EC_GROUPs must use the same EC_METHOD.
  *  \param  dst  destination EC_GROUP object

diff --git a/util/libcrypto.num b/util/libcrypto.num
index 3f76771b4d63b5c257e228c8a17f2cc10e71e009..644b27cdeeef9f11bd4c8a32a9e79bd40a007de5 100644 (file)
--- a/util/libcrypto.num
+++ b/util/libcrypto.num
@@ -2577,7 +2577,7 @@ PKCS7_ENVELOPE_it                       2632      3_0_0   EXIST::FUNCTION:
 ASIdentifierChoice_it                   2633   3_0_0   EXIST::FUNCTION:RFC3779
 CMS_RecipientEncryptedKey_cert_cmp      2634   3_0_0   EXIST::FUNCTION:CMS
 EVP_PKEY_CTX_get_app_data               2635   3_0_0   EXIST::FUNCTION:
-EC_GROUP_clear_free                     2636   3_0_0   EXIST::FUNCTION:EC
+EC_GROUP_clear_free                     2636   3_0_0   EXIST::FUNCTION:DEPRECATEDIN_3,EC
 BN_get_rfc2409_prime_1024               2637   3_0_0   EXIST::FUNCTION:
 CRYPTO_set_mem_functions                2638   3_0_0   EXIST::FUNCTION:
 i2d_ASN1_VISIBLESTRING                  2639   3_0_0   EXIST::FUNCTION: