Replace OSSL_ITEM with OSSL_PARAM as parameter descriptor, everywhere

[openssl.git] / include / openssl / core.h

diff --git a/include/openssl/core.h b/include/openssl/core.h
index 98b58bea6963e69053dc8c94d8afd306aca59384..43e9d0a6bce2c625c8e19c6e3d335f1e3bb39ece 100644 (file)
--- a/include/openssl/core.h
+++ b/include/openssl/core.h
@@ -43,7 +43,7 @@ struct ossl_dispatch_st {
  * tables remain tables with function pointers only.
  *
  * This is used whenever we need to pass things like a table of error reason
- * codes <-> reason string maps, parameter name <-> parameter type maps, ...
+ * codes <-> reason string maps, ...
  *
  * Usage determines which field works as key if any, rather than field order.
  *
@@ -75,9 +75,9 @@ struct ossl_algorithm_st {
 struct ossl_param_st {
     const char *key;             /* the name of the parameter */
     unsigned int data_type;      /* declare what kind of content is in buffer */
-    void *buffer;                /* value being passed in or out */
-    size_t buffer_size;          /* buffer size */
-    size_t *return_size;         /* OPTIONAL: address to content size */
+    void *data;                  /* value being passed in or out */
+    size_t data_size;            /* data size */
+    size_t return_size;          /* returned content size */
 };
 
 /* Currently supported OSSL_PARAM data types */
@@ -111,13 +111,28 @@ struct ossl_param_st {
  * printed as a hexdump.
  */
 # define OSSL_PARAM_OCTET_STRING         5
-
 /*-
- * Pointer flag
+ * OSSL_PARAM_UTF8_PTR
+ * is a pointer to a printable string.  Is expteced to be printed as it is.
+ *
+ * The difference between this and OSSL_PARAM_UTF8_STRING is that only pointers
+ * are manipulated for this type.
+ *
+ * This is more relevant for parameter requests, where the responding
+ * function doesn't need to copy the data to the provided buffer, but
+ * sets the provided buffer to point at the actual data instead.
+ *
+ * WARNING!  Using these is FRAGILE, as it assumes that the actual
+ * data and its location are constant.
+ */
+# define OSSL_PARAM_UTF8_PTR             6
+/*-
+ * OSSL_PARAM_OCTET_PTR
+ * is a pointer to a string of bytes with no further specification.  It is
+ * expected to be printed as a hexdump.
  *
- * This flag can be added to any type to signify that the buffer
- * pointer is set to point at a pointer to the data instead of
- * pointing directly at the data.
+ * The difference between this and OSSL_PARAM_OCTET_STRING is that only pointers
+ * are manipulated for this type.
  *
  * This is more relevant for parameter requests, where the responding
  * function doesn't need to copy the data to the provided buffer, but
@@ -126,15 +141,51 @@ struct ossl_param_st {
  * WARNING!  Using these is FRAGILE, as it assumes that the actual
  * data and its location are constant.
  */
-# define OSSL_PARAM_POINTER_FLAG    0x80000000UL
+# define OSSL_PARAM_OCTET_PTR            7
 
 /*
- * Convenience pointer types for strings.
+ * Typedef for the thread stop handling callback. Used both internally and by
+ * providers.
+ *
+ * Providers may register for notifications about threads stopping by
+ * registering a callback to hear about such events. Providers register the
+ * callback using the OSSL_FUNC_CORE_THREAD_START function in the |in| dispatch
+ * table passed to OSSL_provider_init(). The arg passed back to a provider will
+ * be the provider side context object.
+ */
+typedef void (*OSSL_thread_stop_handler_fn)(void *arg);
+
+
+/*-
+ * Provider entry point
+ * --------------------
+ *
+ * This function is expected to be present in any dynamically loadable
+ * provider module.  By definition, if this function doesn't exist in a
+ * module, that module is not an OpenSSL provider module.
+ */
+/*-
+ * |provider|   pointer to opaque type OSSL_PROVIDER.  This can be used
+ *              together with some functions passed via |in| to query data.
+ * |in|         is the array of functions that the Core passes to the provider.
+ * |out|        will be the array of base functions that the provider passes
+ *              back to the Core.
+ * |provctx|    a provider side context object, optionally created if the
+ *              provider needs it.  This value is passed to other provider
+ *              functions, notably other context constructors.
  */
-# define OSSL_PARAM_UTF8_STRING_PTR                     \
-    (OSSL_PARAM_UTF8_STRING|OSSL_PARAM_POINTER_FLAG)
-# define OSSL_PARAM_OCTET_STRING_PTR                    \
-    (OSSL_PARAM_OCTET_STRING|OSSL_PARAM_POINTER_FLAG)
+typedef int (OSSL_provider_init_fn)(const OSSL_PROVIDER *provider,
+                                    const OSSL_DISPATCH *in,
+                                    const OSSL_DISPATCH **out,
+                                    void **provctx);
+# ifdef __VMS
+#  pragma names save
+#  pragma names uppercase,truncated
+# endif
+extern OSSL_provider_init_fn OSSL_provider_init;
+# ifdef __VMS
+#  pragma names restore
+# endif
 
 # ifdef __cplusplus
 }