[openssl] master update

[Richard Levitte]

The branch master has been updated
       via  10e7216e502916f8e7917ac4f21411fffd1fb882 (commit)
      from  c31950b964a2f3f7b9e6ad98076954178ee1e77d (commit)


- Log -----------------------------------------------------------------
commit 10e7216e502916f8e7917ac4f21411fffd1fb882
Author: Richard Levitte <levitte at openssl.org>
Date:   Mon Nov 11 18:38:57 2019 +0100

    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 at openssl.org>
    (Merged from https://github.com/openssl/openssl/pull/10412)

-----------------------------------------------------------------------

Summary of changes:
 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