Update documentation for global properties mirroring

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

3 files changed, 20 insertions, 8 deletions

diff --git a/crypto/provider_core.c b/crypto/provider_core.c
index 3c2d142775..512a16ee66 100644
--- 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 7ab60eb3a5..ed2d6993b3 100644
--- 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 19cd4e445b..10ad301fb4 100644
--- 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