From 10e7216e502916f8e7917ac4f21411fffd1fb882 Mon Sep 17 00:00:00 2001
From: Richard Levitte <levitte@openssl.org>
Date: Mon, 11 Nov 2019 18:38:57 +0100
Subject: [PATCH] CORE: Add a generic callback function type

This offers a very generic way to define a callback as well as calling
it.

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10412)
---
 doc/man7/openssl-core.h.pod | 12 ++++++++++++
 include/openssl/core.h      | 15 +++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/doc/man7/openssl-core.h.pod b/doc/man7/openssl-core.h.pod
index a7f209b104..55d53fe262 100644
--- a/doc/man7/openssl-core.h.pod
+++ b/doc/man7/openssl-core.h.pod
@@ -74,6 +74,18 @@ parameters, and to describe parameters.
 
 B<OSSL_PARAM> is further described in L<OSSL_PARAM(3)>
 
+=item B<OSSL_CALLBACK>
+
+This is a function type for a generic callback function:
+
+    typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg);
+
+A function that takes a pointer of this type should also take a
+pointer to caller data.  When calling this callback, the function is
+expected to build an B<OSSL_PARAM> array of data it wants or is
+expected to pass back, and pass that as I<params>, as well as
+the caller data pointer it received, as I<arg>.
+
 =back
 
 =head1 SEE ALSO
diff --git a/include/openssl/core.h b/include/openssl/core.h
index 74a3bfb91e..bed580c811 100644
--- a/include/openssl/core.h
+++ b/include/openssl/core.h
@@ -187,6 +187,21 @@ extern OSSL_provider_init_fn OSSL_provider_init;
 #  pragma names restore
 # endif
 
+/*
+ * Generic callback function signature.
+ *
+ * The expectation is that any provider function that wants to offer
+ * a callback / hook can do so by taking an argument with this type,
+ * as well as a pointer to caller-specific data.  When calling the
+ * callback, the provider function can populate an OSSL_PARAM array
+ * with data of its choice and pass that in the callback call, along
+ * with the caller data argument.
+ *
+ * libcrypto may use the OSSL_PARAM array to create arguments for an
+ * application callback it knows about.
+ */
+typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg);
+
 # ifdef __cplusplus
 }
 # endif
-- 
2.25.1