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)

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
 -----------
 

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.

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

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 */

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

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);

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)
 {

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;

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 {

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);

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,

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.

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)>

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
 

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) || \

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)
 

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)

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

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);

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

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:

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)

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 *),