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 https://github.com/openssl/openssl/pull/17937)

23 files changed, 177 insertions, 84 deletions

diff --git a/CHANGES.md b/CHANGES.md
index 319e576f62..7a4b38cbb4 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -112,6 +112,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
index 14e8dd3886..e796ff4045 100644
--- 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
index 380f4da9c2..e2909d7197 100644
--- 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
index 03a86299cf..ea69a5464e 100644
--- 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
index ba4d4ea897..ea0a3252a6 100644
--- 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
index 4436b799fd..73848a6fbf 100644
--- 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
index c697e6f474..bb555fccc1 100644
--- 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
index fb48022a8f..496940c378 100644
--- a/crypto/property/property.c
+++ b/crypto/property/property.c
@@ -52,7 +52,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
index 3f978c06a3..e06f47a6b7 100644
--- 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
index f73bce32b9..bca6516b04 100644
--- 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
index 13a4b059a0..de34c30fa2 100644
--- 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
index 82beda458b..3ce005b9be 100644
--- 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,6 +56,10 @@ 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
@@ -61,6 +67,12 @@ 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-2021 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man3/OPENSSL_LH_stats.pod b/doc/man3/OPENSSL_LH_stats.pod
index b86de52cb5..5bc69674f8 100644
--- 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
index e220c633f3..a1a49fbb82 100644
--- 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
index 5384cac56e..d821ef2fdd 100644
--- a/include/internal/cryptlib.h
+++ b/include/internal/cryptlib.h
@@ -30,7 +30,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);
 
 void OPENSSL_cpuid_setup(void);
 #if defined(__i386)   || defined(__i386__)   || defined(_M_IX86) || \
diff --git a/include/openssl/lhash.h.in b/include/openssl/lhash.h.in
index e9bb2590a0..97dd3a4b84 100644
--- a/include/openssl/lhash.h.in
+++ b/include/openssl/lhash.h.in
@@ -97,13 +97,17 @@ unsigned long OPENSSL_LH_get_down_load(const OPENSSL_LHASH *lh);
 void OPENSSL_LH_set_down_load(OPENSSL_LHASH *lh, unsigned long down_load);
 
 # ifndef OPENSSL_NO_STDIO
-void OPENSSL_LH_stats(const OPENSSL_LHASH *lh, FILE *fp);
-void OPENSSL_LH_node_stats(const OPENSSL_LHASH *lh, FILE *fp);
-void OPENSSL_LH_node_usage_stats(const OPENSSL_LHASH *lh, FILE *fp);
+#  ifndef OPENSSL_NO_DEPRECATED_3_1
+OSSL_DEPRECATEDIN_3_1 void OPENSSL_LH_stats(const OPENSSL_LHASH *lh, FILE *fp);
+OSSL_DEPRECATEDIN_3_1 void OPENSSL_LH_node_stats(const OPENSSL_LHASH *lh, FILE *fp);
+OSSL_DEPRECATEDIN_3_1 void OPENSSL_LH_node_usage_stats(const OPENSSL_LHASH *lh, FILE *fp);
+#  endif
+# endif
+# ifndef OPENSSL_NO_DEPRECATED_3_1
+OSSL_DEPRECATEDIN_3_1 void OPENSSL_LH_stats_bio(const OPENSSL_LHASH *lh, BIO *out);
+OSSL_DEPRECATEDIN_3_1 void OPENSSL_LH_node_stats_bio(const OPENSSL_LHASH *lh, BIO *out);
+OSSL_DEPRECATEDIN_3_1 void OPENSSL_LH_node_usage_stats_bio(const OPENSSL_LHASH *lh, BIO *out);
 # endif
-void OPENSSL_LH_stats_bio(const OPENSSL_LHASH *lh, BIO *out);
-void OPENSSL_LH_node_stats_bio(const OPENSSL_LHASH *lh, BIO *out);
-void OPENSSL_LH_node_usage_stats_bio(const OPENSSL_LHASH *lh, BIO *out);
 
 # ifndef OPENSSL_NO_DEPRECATED_1_1_0
 #  define _LHASH OPENSSL_LHASH
@@ -134,110 +138,145 @@ void OPENSSL_LH_node_usage_stats_bio(const OPENSSL_LHASH *lh, BIO *out);
 
 /* Helper macro for internal use */
 # define DEFINE_LHASH_OF_INTERNAL(type) \
-    LHASH_OF(type) { union lh_##type##_dummy { void* d1; unsigned long d2; int d3; } dummy; }; \
+    LHASH_OF(type) { \
+        union lh_##type##_dummy { void* d1; unsigned long d2; int d3; } dummy; \
+    }; \
     typedef int (*lh_##type##_compfunc)(const type *a, const type *b); \
     typedef unsigned long (*lh_##type##_hashfunc)(const type *a); \
     typedef void (*lh_##type##_doallfunc)(type *a); \
-    static ossl_unused ossl_inline type *ossl_check_##type##_lh_plain_type(type *ptr) \
+    static ossl_unused ossl_inline type *\
+    ossl_check_##type##_lh_plain_type(type *ptr) \
     { \
         return ptr; \
     } \
-    static ossl_unused ossl_inline const type *ossl_check_const_##type##_lh_plain_type(const type *ptr) \
+    static ossl_unused ossl_inline const type * \
+    ossl_check_const_##type##_lh_plain_type(const type *ptr) \
     { \
         return ptr; \
     } \
-    static ossl_unused ossl_inline const OPENSSL_LHASH *ossl_check_const_##type##_lh_type(const LHASH_OF(type) *lh) \
+    static ossl_unused ossl_inline const OPENSSL_LHASH * \
+    ossl_check_const_##type##_lh_type(const LHASH_OF(type) *lh) \
     { \
         return (const OPENSSL_LHASH *)lh; \
     } \
-    static ossl_unused ossl_inline OPENSSL_LHASH *ossl_check_##type##_lh_type(LHASH_OF(type) *lh) \
+    static ossl_unused ossl_inline OPENSSL_LHASH * \
+    ossl_check_##type##_lh_type(LHASH_OF(type) *lh) \
     { \
         return (OPENSSL_LHASH *)lh; \
     } \
-    static ossl_unused ossl_inline OPENSSL_LH_COMPFUNC ossl_check_##type##_lh_compfunc_type(lh_##type##_compfunc cmp) \
+    static ossl_unused ossl_inline OPENSSL_LH_COMPFUNC \
+    ossl_check_##type##_lh_compfunc_type(lh_##type##_compfunc cmp) \
     { \
         return (OPENSSL_LH_COMPFUNC)cmp; \
     } \
-    static ossl_unused ossl_inline OPENSSL_LH_HASHFUNC ossl_check_##type##_lh_hashfunc_type(lh_##type##_hashfunc hfn) \
+    static ossl_unused ossl_inline OPENSSL_LH_HASHFUNC \
+    ossl_check_##type##_lh_hashfunc_type(lh_##type##_hashfunc hfn) \
     { \
         return (OPENSSL_LH_HASHFUNC)hfn; \
     } \
-    static ossl_unused ossl_inline OPENSSL_LH_DOALL_FUNC ossl_check_##type##_lh_doallfunc_type(lh_##type##_doallfunc dfn) \
+    static ossl_unused ossl_inline OPENSSL_LH_DOALL_FUNC \
+    ossl_check_##type##_lh_doallfunc_type(lh_##type##_doallfunc dfn) \
     { \
         return (OPENSSL_LH_DOALL_FUNC)dfn; \
     } \
     LHASH_OF(type)
 
-# define DEFINE_LHASH_OF(type) \
-    LHASH_OF(type) { union lh_##type##_dummy { void* d1; unsigned long d2; int d3; } dummy; }; \
-    static ossl_unused ossl_inline LHASH_OF(type) *lh_##type##_new(unsigned long (*hfn)(const type *), \
-                                                                   int (*cfn)(const type *, const type *)) \
+# ifndef OPENSSL_NO_DEPRECATED_3_1
+#  define DEFINE_LHASH_OF_DEPRECATED(type) \
+    static ossl_unused ossl_inline void \
+    lh_##type##_node_stats_bio(const LHASH_OF(type) *lh, BIO *out) \
+    { \
+        OPENSSL_LH_node_stats_bio((const OPENSSL_LHASH *)lh, out); \
+    } \
+    static ossl_unused ossl_inline void \
+    lh_##type##_node_usage_stats_bio(const LHASH_OF(type) *lh, BIO *out) \
+    { \
+        OPENSSL_LH_node_usage_stats_bio((const OPENSSL_LHASH *)lh, out); \
+    } \
+    static ossl_unused ossl_inline void \
+    lh_##type##_stats_bio(const LHASH_OF(type) *lh, BIO *out) \
+    { \
+        OPENSSL_LH_stats_bio((const OPENSSL_LHASH *)lh, out); \
+    }
+# else
+#  define DEFINE_LHASH_OF_DEPRECATED(type)
+# endif
+
+# define DEFINE_LHASH_OF_EX(type) \
+    LHASH_OF(type) { \
+        union lh_##type##_dummy { void* d1; unsigned long d2; int d3; } dummy; \
+    }; \
+    static ossl_unused ossl_inline LHASH_OF(type) * \
+    lh_##type##_new(unsigned long (*hfn)(const type *), \
+                    int (*cfn)(const type *, const type *)) \
     { \
         return (LHASH_OF(type) *) \
             OPENSSL_LH_new((OPENSSL_LH_HASHFUNC)hfn, (OPENSSL_LH_COMPFUNC)cfn); \
     } \
-    static ossl_unused ossl_inline void lh_##type##_free(LHASH_OF(type) *lh) \
+    static ossl_unused ossl_inline void \
+    lh_##type##_free(LHASH_OF(type) *lh) \
     { \
         OPENSSL_LH_free((OPENSSL_LHASH *)lh); \
     } \
-    static ossl_unused ossl_inline void lh_##type##_flush(LHASH_OF(type) *lh) \
+    static ossl_unused ossl_inline void \
+    lh_##type##_flush(LHASH_OF(type) *lh) \
     { \
         OPENSSL_LH_flush((OPENSSL_LHASH *)lh); \
     } \
-    static ossl_unused ossl_inline type *lh_##type##_insert(LHASH_OF(type) *lh, type *d) \
+    static ossl_unused ossl_inline type * \
+    lh_##type##_insert(LHASH_OF(type) *lh, type *d) \
     { \
         return (type *)OPENSSL_LH_insert((OPENSSL_LHASH *)lh, d); \
     } \
-    static ossl_unused ossl_inline type *lh_##type##_delete(LHASH_OF(type) *lh, const type *d) \
+    static ossl_unused ossl_inline type * \
+    lh_##type##_delete(LHASH_OF(type) *lh, const type *d) \
     { \
         return (type *)OPENSSL_LH_delete((OPENSSL_LHASH *)lh, d); \
     } \
-    static ossl_unused ossl_inline type *lh_##type##_retrieve(LHASH_OF(type) *lh, const type *d) \
+    static ossl_unused ossl_inline type * \
+    lh_##type##_retrieve(LHASH_OF(type) *lh, const type *d) \
     { \
         return (type *)OPENSSL_LH_retrieve((OPENSSL_LHASH *)lh, d); \
     } \
-    static ossl_unused ossl_inline int lh_##type##_error(LHASH_OF(type) *lh) \
+    static ossl_unused ossl_inline int \
+    lh_##type##_error(LHASH_OF(type) *lh) \
     { \
         return OPENSSL_LH_error((OPENSSL_LHASH *)lh); \
     } \
-    static ossl_unused ossl_inline unsigned long lh_##type##_num_items(LHASH_OF(type) *lh) \
+    static ossl_unused ossl_inline unsigned long \
+    lh_##type##_num_items(LHASH_OF(type) *lh) \
     { \
         return OPENSSL_LH_num_items((OPENSSL_LHASH *)lh); \
     } \
-    static ossl_unused ossl_inline void lh_##type##_node_stats_bio(const LHASH_OF(type) *lh, BIO *out) \
-    { \
-        OPENSSL_LH_node_stats_bio((const OPENSSL_LHASH *)lh, out); \
-    } \
-    static ossl_unused ossl_inline void lh_##type##_node_usage_stats_bio(const LHASH_OF(type) *lh, BIO *out) \
-    { \
-        OPENSSL_LH_node_usage_stats_bio((const OPENSSL_LHASH *)lh, out); \
-    } \
-    static ossl_unused ossl_inline void lh_##type##_stats_bio(const LHASH_OF(type) *lh, BIO *out) \
-    { \
-        OPENSSL_LH_stats_bio((const OPENSSL_LHASH *)lh, out); \
-    } \
-    static ossl_unused ossl_inline unsigned long lh_##type##_get_down_load(LHASH_OF(type) *lh) \
+    static ossl_unused ossl_inline unsigned long \
+    lh_##type##_get_down_load(LHASH_OF(type) *lh) \
     { \
         return OPENSSL_LH_get_down_load((OPENSSL_LHASH *)lh); \
     } \
-    static ossl_unused ossl_inline void lh_##type##_set_down_load(LHASH_OF(type) *lh, unsigned long dl) \
+    static ossl_unused ossl_inline void \
+    lh_##type##_set_down_load(LHASH_OF(type) *lh, unsigned long dl) \
     { \
         OPENSSL_LH_set_down_load((OPENSSL_LHASH *)lh, dl); \
     } \
-    static ossl_unused ossl_inline void lh_##type##_doall(LHASH_OF(type) *lh, \
-                                                          void (*doall)(type *)) \
+    static ossl_unused ossl_inline void \
+    lh_##type##_doall(LHASH_OF(type) *lh, void (*doall)(type *)) \
     { \
         OPENSSL_LH_doall((OPENSSL_LHASH *)lh, (OPENSSL_LH_DOALL_FUNC)doall); \
     } \
-    static ossl_unused ossl_inline void lh_##type##_doall_arg(LHASH_OF(type) *lh, \
-                                                              void (*doallarg)(type *, void *), \
-                                                              void *arg) \
+    static ossl_unused ossl_inline void \
+    lh_##type##_doall_arg(LHASH_OF(type) *lh, \
+                          void (*doallarg)(type *, void *), void *arg) \
     { \
         OPENSSL_LH_doall_arg((OPENSSL_LHASH *)lh, \
                              (OPENSSL_LH_DOALL_FUNCARG)doallarg, arg); \
     } \
     LHASH_OF(type)
 
+# define DEFINE_LHASH_OF(type) \
+    DEFINE_LHASH_OF_EX(type); \
+    DEFINE_LHASH_OF_DEPRECATED(type) \
+    LHASH_OF(type)
+
 #define IMPLEMENT_LHASH_DOALL_ARG_CONST(type, argtype) \
     int_implement_lhash_doall(type, argtype, const type)
 
@@ -250,7 +289,8 @@ void OPENSSL_LH_node_usage_stats_bio(const OPENSSL_LHASH *lh, BIO *out);
                                    void (*fn)(cbargtype *, argtype *), \
                                    argtype *arg) \
     { \
-        OPENSSL_LH_doall_arg((OPENSSL_LHASH *)lh, (OPENSSL_LH_DOALL_FUNCARG)fn, (void *)arg); \
+        OPENSSL_LH_doall_arg((OPENSSL_LHASH *)lh, \
+                             (OPENSSL_LH_DOALL_FUNCARG)fn, (void *)arg); \
     } \
     LHASH_OF(type)
 
diff --git a/include/openssl/macros.h b/include/openssl/macros.h
index a6bc3f1feb..42e35ed9d3 100644
--- a/include/openssl/macros.h
+++ b/include/openssl/macros.h
@@ -177,6 +177,17 @@
 # undef OPENSSL_NO_DEPRECATED_1_0_0
 # undef OPENSSL_NO_DEPRECATED_0_9_8
 
+# if OPENSSL_API_LEVEL >= 30100
+#  ifndef OPENSSL_NO_DEPRECATED
+#   define OSSL_DEPRECATEDIN_3_1                OSSL_DEPRECATED(3.1)
+#   define OSSL_DEPRECATEDIN_3_1_FOR(msg)       OSSL_DEPRECATED_FOR(3.1, msg)
+#  else
+#   define OPENSSL_NO_DEPRECATED_3_1
+#  endif
+# else
+#  define OSSL_DEPRECATEDIN_3_1
+#  define OSSL_DEPRECATEDIN_3_1_FOR(msg)
+# endif
 # if OPENSSL_API_LEVEL >= 30000
 #  ifndef OPENSSL_NO_DEPRECATED
 #   define OSSL_DEPRECATEDIN_3_0                OSSL_DEPRECATED(3.0)
diff --git a/ssl/ssl_local.h b/ssl/ssl_local.h
index 1db7eb2ff0..6274b2e228 100644
--- a/ssl/ssl_local.h
+++ b/ssl/ssl_local.h
@@ -772,9 +772,9 @@ typedef enum tlsext_index_en {
     TLSEXT_IDX_num_builtins
 } TLSEXT_INDEX;
 
-DEFINE_LHASH_OF(SSL_SESSION);
+DEFINE_LHASH_OF_EX(SSL_SESSION);
 /* Needed in ssl_cert.c */
-DEFINE_LHASH_OF(X509_NAME);
+DEFINE_LHASH_OF_EX(X509_NAME);
 
 # define TLSEXT_KEYNAME_LENGTH  16
 # define TLSEXT_TICK_KEY_LENGTH 32
diff --git a/test/lhash_test.c b/test/lhash_test.c
index 537ae1876c..38dbff0748 100644
--- a/test/lhash_test.c
+++ b/test/lhash_test.c
@@ -27,7 +27,7 @@
 #pragma clang diagnostic ignored "-Wunused-function"
 #endif
 
-DEFINE_LHASH_OF(int);
+DEFINE_LHASH_OF_EX(int);
 
 static int int_tests[] = { 65537, 13, 1, 3, -5, 6, 7, 4, -10, -12, -14, 22, 9,
                            -17, 16, 17, -23, 35, 37, 173, 11 };
@@ -210,11 +210,6 @@ static int test_stress(void)
     if (!TEST_int_eq(lh_int_num_items(h), n))
             goto end;
 
-    TEST_info("hash full statistics:");
-    OPENSSL_LH_stats_bio((OPENSSL_LHASH *)h, bio_err);
-    TEST_note("hash full node usage:");
-    OPENSSL_LH_node_usage_stats_bio((OPENSSL_LHASH *)h, bio_err);
-
     /* delete in a different order */
     for (i = 0; i < n; i++) {
         const int j = (7 * i + 4) % n * 3 + 1;
@@ -230,11 +225,6 @@ static int test_stress(void)
         OPENSSL_free(p);
     }
 
-    TEST_info("hash empty statistics:");
-    OPENSSL_LH_stats_bio((OPENSSL_LHASH *)h, bio_err);
-    TEST_note("hash empty node usage:");
-    OPENSSL_LH_node_usage_stats_bio((OPENSSL_LHASH *)h, bio_err);
-
     testresult = 1;
 end:
     lh_int_free(h);
diff --git a/util/find-doc-nits b/util/find-doc-nits
index 7244c589e8..04911fae51 100755
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -105,7 +105,7 @@ my $ignored = qr/(?| ^i2d_
                  |   ^sk_
                  |   ^SKM_DEFINE_STACK_OF_INTERNAL
                  |   ^lh_
-                 |   ^DEFINE_LHASH_OF_INTERNAL
+                 |   ^DEFINE_LHASH_OF_(INTERNAL|DEPRECATED)
                  )/x;
 
 # A common regexp for C symbol names
diff --git a/util/libcrypto.num b/util/libcrypto.num
index f2426bc8cd..dcd9d02924 100644
--- a/util/libcrypto.num
+++ b/util/libcrypto.num
@@ -1178,7 +1178,7 @@ OPENSSL_uni2asc                         1205	3_0_0	EXIST::FUNCTION:
 SCT_validation_status_string            1206	3_0_0	EXIST::FUNCTION:CT
 PKCS7_add_attribute                     1207	3_0_0	EXIST::FUNCTION:
 ENGINE_register_DSA                     1208	3_0_0	EXIST::FUNCTION:DEPRECATEDIN_3_0,ENGINE
-OPENSSL_LH_node_stats                   1209	3_0_0	EXIST::FUNCTION:STDIO
+OPENSSL_LH_node_stats                   1209	3_0_0	EXIST::FUNCTION:DEPRECATEDIN_3_1,STDIO
 X509_policy_tree_free                   1210	3_0_0	EXIST::FUNCTION:
 EC_GFp_simple_method                    1211	3_0_0	EXIST::FUNCTION:DEPRECATEDIN_3_0,EC
 X509_it                                 1212	3_0_0	EXIST::FUNCTION:
@@ -1317,7 +1317,7 @@ BIO_f_linebuffer                        1346	3_0_0	EXIST::FUNCTION:
 ASN1_item_d2i_bio                       1347	3_0_0	EXIST::FUNCTION:
 ENGINE_get_flags                        1348	3_0_0	EXIST::FUNCTION:DEPRECATEDIN_3_0,ENGINE
 OCSP_resp_find                          1349	3_0_0	EXIST::FUNCTION:OCSP
-OPENSSL_LH_node_usage_stats_bio         1350	3_0_0	EXIST::FUNCTION:
+OPENSSL_LH_node_usage_stats_bio         1350	3_0_0	EXIST::FUNCTION:DEPRECATEDIN_3_1
 EVP_PKEY_encrypt                        1351	3_0_0	EXIST::FUNCTION:
 CRYPTO_cfb128_8_encrypt                 1352	3_0_0	EXIST::FUNCTION:
 SXNET_get_id_INTEGER                    1353	3_0_0	EXIST::FUNCTION:
@@ -1790,7 +1790,7 @@ X509V3_EXT_REQ_add_conf                 1832	3_0_0	EXIST::FUNCTION:
 ASN1_STRING_to_UTF8                     1833	3_0_0	EXIST::FUNCTION:
 EVP_MD_meth_set_update                  1835	3_0_0	EXIST::FUNCTION:DEPRECATEDIN_3_0
 EVP_camellia_192_cbc                    1836	3_0_0	EXIST::FUNCTION:CAMELLIA
-OPENSSL_LH_stats_bio                    1837	3_0_0	EXIST::FUNCTION:
+OPENSSL_LH_stats_bio                    1837	3_0_0	EXIST::FUNCTION:DEPRECATEDIN_3_1
 PKCS7_set_signed_attributes             1838	3_0_0	EXIST::FUNCTION:
 EC_KEY_priv2buf                         1839	3_0_0	EXIST::FUNCTION:DEPRECATEDIN_3_0,EC
 BN_BLINDING_free                        1840	3_0_0	EXIST::FUNCTION:
@@ -1973,7 +1973,7 @@ i2d_TS_REQ_fp                           2019	3_0_0	EXIST::FUNCTION:STDIO,TS
 i2d_OTHERNAME                           2020	3_0_0	EXIST::FUNCTION:
 EC_KEY_get0_private_key                 2021	3_0_0	EXIST::FUNCTION:DEPRECATEDIN_3_0,EC
 SCT_get0_extensions                     2022	3_0_0	EXIST::FUNCTION:CT
-OPENSSL_LH_node_stats_bio               2023	3_0_0	EXIST::FUNCTION:
+OPENSSL_LH_node_stats_bio               2023	3_0_0	EXIST::FUNCTION:DEPRECATEDIN_3_1
 i2d_DIRECTORYSTRING                     2024	3_0_0	EXIST::FUNCTION:
 BN_X931_derive_prime_ex                 2025	3_0_0	EXIST::FUNCTION:DEPRECATEDIN_3_0
 ENGINE_get_pkey_asn1_meth_str           2026	3_0_0	EXIST::FUNCTION:DEPRECATEDIN_3_0,ENGINE
@@ -2553,7 +2553,7 @@ EVP_DecodeUpdate                        2609	3_0_0	EXIST::FUNCTION:
 ENGINE_get_default_RAND                 2610	3_0_0	EXIST::FUNCTION:DEPRECATEDIN_3_0,ENGINE
 ERR_peek_last_error_line                2611	3_0_0	EXIST::FUNCTION:
 ENGINE_get_ssl_client_cert_function     2612	3_0_0	EXIST::FUNCTION:DEPRECATEDIN_3_0,ENGINE
-OPENSSL_LH_node_usage_stats             2613	3_0_0	EXIST::FUNCTION:STDIO
+OPENSSL_LH_node_usage_stats             2613	3_0_0	EXIST::FUNCTION:DEPRECATEDIN_3_1,STDIO
 DIRECTORYSTRING_it                      2614	3_0_0	EXIST::FUNCTION:
 BIO_write                               2615	3_0_0	EXIST::FUNCTION:
 OCSP_ONEREQ_get_ext_by_OBJ              2616	3_0_0	EXIST::FUNCTION:OCSP
@@ -3073,7 +3073,7 @@ TXT_DB_free                             3139	3_0_0	EXIST::FUNCTION:
 ASN1_STRING_set                         3140	3_0_0	EXIST::FUNCTION:
 d2i_ESS_CERT_ID                         3141	3_0_0	EXIST::FUNCTION:
 EVP_PKEY_meth_set_derive                3142	3_0_0	EXIST::FUNCTION:DEPRECATEDIN_3_0
-OPENSSL_LH_stats                        3143	3_0_0	EXIST::FUNCTION:STDIO
+OPENSSL_LH_stats                        3143	3_0_0	EXIST::FUNCTION:DEPRECATEDIN_3_1,STDIO
 NCONF_dump_fp                           3144	3_0_0	EXIST::FUNCTION:STDIO
 TS_STATUS_INFO_print_bio                3145	3_0_0	EXIST::FUNCTION:TS
 OPENSSL_sk_dup                          3146	3_0_0	EXIST::FUNCTION:
diff --git a/util/missingmacro.txt b/util/missingmacro.txt
index 8e02bb7b83..ad03758ba3 100644
--- a/util/missingmacro.txt
+++ b/util/missingmacro.txt
@@ -86,8 +86,6 @@ OPENSSL_add_all_algorithms_noconf(3)
 LHASH_HASH_FN(3)
 LHASH_COMP_FN(3)
 LHASH_DOALL_ARG_FN(3)
-LHASH_OF(3)
-DEFINE_LHASH_OF(3)
 int_implement_lhash_doall(3)
 OBJ_create_and_add_object(3)
 OBJ_bsearch(3)
diff --git a/util/perl/OpenSSL/ParseC.pm b/util/perl/OpenSSL/ParseC.pm
index e3cfe07827..3f14cac9cd 100644
--- a/util/perl/OpenSSL/ParseC.pm
+++ b/util/perl/OpenSSL/ParseC.pm
@@ -292,7 +292,7 @@ EOF
     { regexp   => qr/(.*)\bLHASH_OF<<<\((.*?)\)>>>(.*)/,
       massager => sub { return ("$1struct lhash_st_$2$3"); }
     },
-    { regexp   => qr/DEFINE_LHASH_OF(?:_INTERNAL)?<<<\((.*)\)>>>/,
+    { regexp   => qr/DEFINE_LHASH_OF(?:_INTERNAL|_EX)?<<<\((.*)\)>>>/,
       massager => sub {
           return (<<"EOF");
 static ossl_inline LHASH_OF($1) * lh_$1_new(unsigned long (*hfn)(const $1 *),