Update documentation for global properties mirroring

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/15242)

diff --git a/crypto/provider_core.c b/crypto/provider_core.c
index 3c2d14277581c50ed3463d45fb4aef8595f150d7..512a16ee6627f6649cde4a86ba5057df6952ca27 100644 (file)
--- a/crypto/provider_core.c
+++ b/crypto/provider_core.c
@@ -46,8 +46,8 @@ DEFINE_STACK_OF(INFOPAIR)
 typedef struct {
     OSSL_PROVIDER *prov;
     int (*create_cb)(const OSSL_CORE_HANDLE *provider, void *cbdata);
-    void (*remove_cb)(const OSSL_CORE_HANDLE *provider, void *cbdata);
-    void (*global_props_cb)(const char *props, void *cbdata);
+    int (*remove_cb)(const OSSL_CORE_HANDLE *provider, void *cbdata);
+    int (*global_props_cb)(const char *props, void *cbdata);
     void *cbdata;
 } OSSL_PROVIDER_CHILD_CB;
 DEFINE_STACK_OF(OSSL_PROVIDER_CHILD_CB)
@@ -1392,10 +1392,10 @@ static int ossl_provider_register_child_cb(const OSSL_CORE_HANDLE *handle,
                                            int (*create_cb)(
                                                const OSSL_CORE_HANDLE *provider,
                                                void *cbdata),
-                                           void (*remove_cb)(
+                                           int (*remove_cb)(
                                                const OSSL_CORE_HANDLE *provider,
                                                void *cbdata),
-                                           void (*global_props_cb)(
+                                           int (*global_props_cb)(
                                                const char *props,
                                                void *cbdata),
                                            void *cbdata)

diff --git a/doc/internal/man3/ossl_provider_new.pod b/doc/internal/man3/ossl_provider_new.pod
index 7ab60eb3a5ad720d4c08139fe177c169c5e25434..ed2d6993b3092de6d3c9272b91b61f4e2de79b00 100644 (file)
--- a/doc/internal/man3/ossl_provider_new.pod
+++ b/doc/internal/man3/ossl_provider_new.pod
@@ -7,7 +7,7 @@ ossl_provider_free,
 ossl_provider_set_fallback, ossl_provider_set_module_path,
 ossl_provider_add_parameter, ossl_provider_set_child, ossl_provider_get_parent,
 ossl_provider_up_ref_parent, ossl_provider_free_parent,
-ossl_provider_get0_dispatch,
+ossl_provider_default_props_update, ossl_provider_get0_dispatch,
 ossl_provider_init_as_child,
 ossl_provider_activate, ossl_provider_deactivate, ossl_provider_available,
 ossl_provider_ctx,
@@ -46,6 +46,8 @@ ossl_provider_get_capabilities
  const OSSL_CORE_HANDLE *ossl_provider_get_parent(OSSL_PROVIDER *prov);
  int ossl_provider_up_ref_parent(OSSL_PROVIDER *prov, int activate);
  int ossl_provider_free_parent(OSSL_PROVIDER *prov, int deactivate);
+ int ossl_provider_default_props_update(OSSL_LIB_CTX *libctx,
+                                        const char *props);
 
  /*
   * Activate the Provider
@@ -193,6 +195,10 @@ ossl_provider_free_parent() decreases the reference count on the parent
 provider. If I<deactivate> is nonzero then the parent provider is also
 deactivated.
 
+ossl_provider_default_props_update() is responsible for informing any child
+providers of an update to the default properties. The new properties are
+supplied in the I<props> string.
+
 ossl_provider_activate() "activates" the provider for the given
 provider object I<prov> by incrementing its activation count, flagging
 it as activated, and initializing it if it isn't already initialized.
@@ -339,7 +345,8 @@ called for any activated providers.
 
 ossl_provider_set_module_path(), ossl_provider_set_fallback(),
 ossl_provider_activate(), ossl_provider_activate_leave_fallbacks() and
-ossl_provider_deactivate() return 1 on success, or 0 on error.
+ossl_provider_deactivate(), ossl_provider_default_props_update() return 1 on
+success, or 0 on error.
 
 ossl_provider_available() return 1 if the provider is available,
 otherwise 0.

diff --git a/doc/man7/provider-base.pod b/doc/man7/provider-base.pod
index 19cd4e445b5ca1cd95579d509bc15672f62c4154..10ad301fb49c85059e20e280633c0d6ef74d44d8 100644 (file)
--- a/doc/man7/provider-base.pod
+++ b/doc/man7/provider-base.pod
@@ -89,6 +89,7 @@ provider-base
                                       void *cbdata),
                      int (*remove_cb)(const OSSL_CORE_HANDLE *provider,
                                       void *cbdata),
+                     int (*global_props_cb)(const char *props, void *cbdata),
                      void *cbdata);
  void provider_deregister_child_cb(const OSSL_CORE_HANDLE *handle);
  const char *provider_name(const OSSL_CORE_HANDLE *prov);
@@ -289,12 +290,16 @@ I<create_cb> is a callback that will be called when a new provider is loaded
 into the application's library context. It is also called for any providers that
 are already loaded at the point that this callback is registered. The callback
 is passed the handle being used for the new provider being loadded and this
-provider's data in I<cbdata>. It should return 1 on success  or 0 on failure.
+provider's data in I<cbdata>. It should return 1 on success or 0 on failure.
 
 I<remove_cb> is a callback that will be called when a new provider is unloaded
 from the application's library context. It is passed the handle being used for
 the provider being unloaded and this provider's data in I<cbdata>. It should
-return 1 on success  or 0 on failure.
+return 1 on success or 0 on failure.
+
+I<global_props_cb> is a callback that will be called when the global properties
+from the parent library context are changed. It should return 1 on success
+or 0 on failure.
 
 provider_deregister_child_cb() unregisters callbacks previously registered via
 provider_register_child_cb(). If provider_register_child_cb() has been called