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)

diff --git a/doc/man7/openssl-core.h.pod b/doc/man7/openssl-core.h.pod
index a7f209b10482e75530ea54bf5ffcfffafbc0c4a8..55d53fe262551b39b757f07e44084d0b2aaf7efc 100644 (file)
--- 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 74a3bfb91ea5476d84d923b6e26b98c1bc752192..bed580c811f8a2a1faf1d64e69581c131d0279d4 100644 (file)
--- 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