Add deprecation macro for 3.1 and deprecate OPENSSL_LH_stats

Reviewed-by: Paul Dale <pauli@openssl.org> Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from #17937) (cherry picked from commit 5317b6e)
openssl · Nov 21, 2022 · 4334710 · 4334710
1 parent 2adb790
commit 4334710
Show file tree

Hide file tree

Showing 23 changed files with 177 additions and 84 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -49,6 +49,23 @@ OpenSSL 3.1
 
    *Sergey Kirillov, Andrey Matyukov (Intel Corp)*
 
+ * The functions `OPENSSL_LH_stats`, `OPENSSL_LH_node_stats`,
+   `OPENSSL_LH_node_usage_stats`, `OPENSSL_LH_stats_bio`,
+   `OPENSSL_LH_node_stats_bio` and `OPENSSL_LH_node_usage_stats_bio` are now
+   marked deprecated from OpenSSL 3.1 onwards and can be disabled by defining
+   `OPENSSL_NO_DEPRECATED_3_1`.
+
+   The macro `DEFINE_LHASH_OF` is now deprecated in favour of the macro
+   `DEFINE_LHASH_OF_EX`, which omits the corresponding type-specific function
+   definitions for these functions regardless of whether
+   `OPENSSL_NO_DEPRECATED_3_1` is defined.
+
+   Users of `DEFINE_LHASH_OF` may start receiving deprecation warnings for these
+   functions regardless of whether they are using them. It is recommended that
+   users transition to the new macro, `DEFINE_LHASH_OF_EX`.
+
+   *Hugo Landau*
+
 OpenSSL 3.0
 -----------
 

diff --git a/apps/include/function.h b/apps/include/function.h
@@ -29,7 +29,7 @@ typedef struct function_st {
     const char *deprecated_version;
 } FUNCTION;
 
-DEFINE_LHASH_OF(FUNCTION);
+DEFINE_LHASH_OF_EX(FUNCTION);
 
 /* Structure to hold the number of columns to be displayed and the
  * field width used to display them.

diff --git a/crypto/core_namemap.c b/crypto/core_namemap.c
@@ -23,7 +23,7 @@ typedef struct {
     int number;
 } NAMENUM_ENTRY;
 
-DEFINE_LHASH_OF(NAMENUM_ENTRY);
+DEFINE_LHASH_OF_EX(NAMENUM_ENTRY);
 
 /*-
  * The namemap itself

diff --git a/crypto/engine/eng_local.h b/crypto/engine/eng_local.h
@@ -156,6 +156,6 @@ struct engine_st {
 
 typedef struct st_engine_pile ENGINE_PILE;
 
-DEFINE_LHASH_OF(ENGINE_PILE);
+DEFINE_LHASH_OF_EX(ENGINE_PILE);
 
 #endif                          /* OSSL_CRYPTO_ENGINE_ENG_LOCAL_H */
diff --git a/crypto/lhash/lh_stats.c b/crypto/lhash/lh_stats.c
@@ -7,6 +7,8 @@
  * https://www.openssl.org/source/license.html
  */
 
+#define OPENSSL_SUPPRESS_DEPRECATED
+
 #include <stdio.h>
 #include <string.h>
 #include <stdlib.h>
@@ -21,6 +23,7 @@
 #include "lhash_local.h"
 
 # ifndef OPENSSL_NO_STDIO
+#  ifndef OPENSSL_NO_DEPRECATED_3_1
 void OPENSSL_LH_stats(const OPENSSL_LHASH *lh, FILE *fp)
 {
     BIO *bp;
@@ -56,9 +59,15 @@ void OPENSSL_LH_node_usage_stats(const OPENSSL_LHASH *lh, FILE *fp)
     OPENSSL_LH_node_usage_stats_bio(lh, bp);
     BIO_free(bp);
 }
-
+#  endif
 # endif
 
+# ifndef OPENSSL_NO_DEPRECATED_3_1
+/*
+ * These functions are implemented as separate static functions as they are
+ * called from the stdio functions above and calling deprecated functions will
+ * generate a warning.
+ */
 void OPENSSL_LH_stats_bio(const OPENSSL_LHASH *lh, BIO *out)
 {
     BIO_printf(out, "num_items             = %lu\n", lh->num_items);
@@ -115,3 +124,4 @@ void OPENSSL_LH_node_usage_stats_bio(const OPENSSL_LHASH *lh, BIO *out)
                (int)((total % lh->num_nodes) * 100 / lh->num_nodes),
                (int)(total / n_used), (int)((total % n_used) * 100 / n_used));
 }
+# endif
diff --git a/crypto/objects/obj_local.h b/crypto/objects/obj_local.h
@@ -9,6 +9,6 @@
 
 typedef struct name_funcs_st NAME_FUNCS;
 DEFINE_STACK_OF(NAME_FUNCS)
-DEFINE_LHASH_OF(OBJ_NAME);
+DEFINE_LHASH_OF_EX(OBJ_NAME);
 typedef struct added_obj_st ADDED_OBJ;
-DEFINE_LHASH_OF(ADDED_OBJ);
+DEFINE_LHASH_OF_EX(ADDED_OBJ);
diff --git a/crypto/property/defn_cache.c b/crypto/property/defn_cache.c
@@ -29,7 +29,7 @@ typedef struct {
     char body[1];
 } PROPERTY_DEFN_ELEM;
 
-DEFINE_LHASH_OF(PROPERTY_DEFN_ELEM);
+DEFINE_LHASH_OF_EX(PROPERTY_DEFN_ELEM);
 
 static unsigned long property_defn_hash(const PROPERTY_DEFN_ELEM *a)
 {

diff --git a/crypto/property/property.c b/crypto/property/property.c
@@ -53,7 +53,7 @@ typedef struct {
     char body[1];
 } QUERY;
 
-DEFINE_LHASH_OF(QUERY);
+DEFINE_LHASH_OF_EX(QUERY);
 
 typedef struct {
     int nid;

diff --git a/crypto/property/property_string.c b/crypto/property/property_string.c
@@ -32,7 +32,7 @@ typedef struct {
     char body[1];
 } PROPERTY_STRING;
 
-DEFINE_LHASH_OF(PROPERTY_STRING);
+DEFINE_LHASH_OF_EX(PROPERTY_STRING);
 typedef LHASH_OF(PROPERTY_STRING) PROP_TABLE;
 
 typedef struct {

diff --git a/crypto/store/store_local.h b/crypto/store/store_local.h
@@ -114,7 +114,7 @@ struct ossl_store_loader_st {
     OSSL_FUNC_store_close_fn *p_close;
     OSSL_FUNC_store_export_object_fn *p_export_object;
 };
-DEFINE_LHASH_OF(OSSL_STORE_LOADER);
+DEFINE_LHASH_OF_EX(OSSL_STORE_LOADER);
 
 const OSSL_STORE_LOADER *ossl_store_get0_loader_int(const char *scheme);
 void ossl_store_destroy_loaders_int(void);

diff --git a/doc/internal/man7/deprecation.pod b/doc/internal/man7/deprecation.pod
@@ -2,6 +2,7 @@
 
 =head1 NAME
 
+OPENSSL_NO_DEPRECATED_3_1, OSSL_DEPRECATEDIN_3_1,
 OPENSSL_NO_DEPRECATED_3_0, OSSL_DEPRECATEDIN_3_0,
 OPENSSL_NO_DEPRECATED_1_1_1, OSSL_DEPRECATEDIN_1_1_1,
 OPENSSL_NO_DEPRECATED_1_1_0, OSSL_DEPRECATEDIN_1_1_0,

diff --git a/doc/man3/OPENSSL_LH_COMPFUNC.pod b/doc/man3/OPENSSL_LH_COMPFUNC.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-LHASH, DECLARE_LHASH_OF,
+LHASH, LHASH_OF, DEFINE_LHASH_OF_EX, DEFINE_LHASH_OF,
 OPENSSL_LH_COMPFUNC, OPENSSL_LH_HASHFUNC, OPENSSL_LH_DOALL_FUNC,
 LHASH_DOALL_ARG_FN_TYPE,
 IMPLEMENT_LHASH_HASH_FN, IMPLEMENT_LHASH_COMP_FN,
@@ -20,7 +20,9 @@ OPENSSL_LH_doall, OPENSSL_LH_doall_arg, OPENSSL_LH_error
 
  #include <openssl/lhash.h>
 
- DECLARE_LHASH_OF(TYPE);
+ LHASH_OF(TYPE)
+
+ DEFINE_LHASH_OF_EX(TYPE);
 
  LHASH_OF(TYPE) *lh_TYPE_new(OPENSSL_LH_HASHFUNC hash, OPENSSL_LH_COMPFUNC compare);
  void lh_TYPE_free(LHASH_OF(TYPE) *table);
@@ -54,13 +56,23 @@ OPENSSL_LH_doall, OPENSSL_LH_doall_arg, OPENSSL_LH_error
 
  int OPENSSL_LH_error(OPENSSL_LHASH *lh);
 
+The following macro is deprecated:
+
+ DEFINE_LHASH_OF(TYPE);
+
 =head1 DESCRIPTION
 
 This library implements type-checked dynamic hash tables. The hash
 table entries can be arbitrary structures. Usually they consist of key
 and value fields.  In the description here, B<I<TYPE>> is used a placeholder
 for any of the OpenSSL datatypes, such as I<SSL_SESSION>.
 
+To define a new type-checked dynamic hash table, use B<DEFINE_LHASH_OF_EX>().
+B<DEFINE_LHASH_OF>() was previously used for this purpose, but is now
+deprecated. The B<DEFINE_LHASH_OF_EX>() macro provides all functionality of
+B<DEFINE_LHASH_OF>() except for certain deprecated statistics functions (see
+OPENSSL_LH_stats(3)).
+
 B<lh_I<TYPE>_new>() creates a new B<LHASH_OF>(B<I<TYPE>>) structure to store
 arbitrary data entries, and specifies the 'hash' and 'compare'
 callbacks to be used in organising the table's entries.  The I<hash>
@@ -268,6 +280,9 @@ L<OPENSSL_LH_stats(3)>
 In OpenSSL 1.0.0, the lhash interface was revamped for better
 type checking.
 
+In OpenSSL 3.1, B<DEFINE_LHASH_OF_EX>() was introduced and B<DEFINE_LHASH_OF>()
+was deprecated.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved.

diff --git a/doc/man3/OPENSSL_LH_stats.pod b/doc/man3/OPENSSL_LH_stats.pod
@@ -10,14 +10,19 @@ OPENSSL_LH_node_stats_bio, OPENSSL_LH_node_usage_stats_bio - LHASH statistics
 
  #include <openssl/lhash.h>
 
- void OPENSSL_LH_stats(LHASH *table, FILE *out);
  void OPENSSL_LH_node_stats(LHASH *table, FILE *out);
  void OPENSSL_LH_node_usage_stats(LHASH *table, FILE *out);
 
- void OPENSSL_LH_stats_bio(LHASH *table, BIO *out);
  void OPENSSL_LH_node_stats_bio(LHASH *table, BIO *out);
  void OPENSSL_LH_node_usage_stats_bio(LHASH *table, BIO *out);
 
+The following functions have been deprecated since OpenSSL 3.1, and can be
+hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
+see L<openssl_user_macros(7)>:
+
+ void OPENSSL_LH_stats(LHASH *table, FILE *out);
+ void OPENSSL_LH_stats_bio(LHASH *table, BIO *out);
+
 =head1 DESCRIPTION
 
 The B<LHASH> structure records statistics about most aspects of
@@ -43,6 +48,9 @@ record a miss.
 OPENSSL_LH_stats_bio(), OPENSSL_LH_node_stats_bio() and OPENSSL_LH_node_usage_stats_bio()
 are the same as the above, except that the output goes to a B<BIO>.
 
+OPENSSH_LH_stats() and OPENSSH_LH_stats_bio() are deprecated and should no
+longer be used.
+
 =head1 RETURN VALUES
 
 These functions do not return values.
@@ -53,6 +61,9 @@ These calls should be made under a read lock. Refer to
 L<OPENSSL_LH_COMPFUNC(3)/NOTE> for more details about the locks required
 when using the LHASH data structure.
 
+The functions OPENSSH_LH_stats() and OPENSSH_LH_stats_bio() were deprecated in
+version 3.1.
+
 =head1 SEE ALSO
 
 L<bio(7)>, L<OPENSSL_LH_COMPFUNC(3)>

diff --git a/doc/man7/migration_guide.pod b/doc/man7/migration_guide.pod
@@ -329,7 +329,7 @@ This code is now always set to zero. Related functions are deprecated.
 =head4 STACK and HASH macros have been cleaned up
 
 The type-safe wrappers are declared everywhere and implemented once.
-See L<DEFINE_STACK_OF(3)> and L<DECLARE_LHASH_OF(3)>.
+See L<DEFINE_STACK_OF(3)> and L<DEFINE_LHASH_OF_EX(3)>.
 
 =head4 The RAND_DRBG subsystem has been removed
 

diff --git a/include/internal/cryptlib.h b/include/internal/cryptlib.h
@@ -59,7 +59,7 @@ typedef struct ex_callback_st EX_CALLBACK;
 DEFINE_STACK_OF(EX_CALLBACK)
 
 typedef struct mem_st MEM;
-DEFINE_LHASH_OF(MEM);
+DEFINE_LHASH_OF_EX(MEM);
 
 # define OPENSSL_CONF             "openssl.cnf"