Update documentation following addition of OSSL_LIB_CTX_new_child()

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

1 files changed, 50 insertions, 3 deletions

diff --git a/doc/internal/man3/ossl_provider_new.pod b/doc/internal/man3/ossl_provider_new.pod
index e83869a9de..ff347bad3f 100644
--- a/doc/internal/man3/ossl_provider_new.pod
+++ b/doc/internal/man3/ossl_provider_new.pod
@@ -5,7 +5,10 @@
 ossl_provider_find, ossl_provider_new, ossl_provider_up_ref,
 ossl_provider_free,
 ossl_provider_set_fallback, ossl_provider_set_module_path,
-ossl_provider_add_parameter,
+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_init_child_providers,
+ossl_provider_init_as_child,
 ossl_provider_activate, ossl_provider_deactivate, ossl_provider_available,
 ossl_provider_ctx,
 ossl_provider_doall_activated,
@@ -37,11 +40,19 @@ ossl_provider_get_capabilities
  int ossl_provider_add_parameter(OSSL_PROVIDER *prov, const char *name,
                                  const char *value);
 
+ /* Child Providers */
+ int ossl_provider_set_child(OSSL_PROVIDER *prov,
+                             const OSSL_CORE_HANDLE *handle);
+ 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);
+
  /*
   * Activate the Provider
   * If the Provider is a module, the module will be loaded
   */
- int ossl_provider_activate(OSSL_PROVIDER *prov, int retain_fallbacks);
+ int ossl_provider_activate(OSSL_PROVIDER *prov, int retain_fallbacks,
+                            int upcalls);
  int ossl_provider_deactivate(OSSL_PROVIDER *prov);
  /* Check if provider is available (activated) */
  int ossl_provider_available(OSSL_PROVIDER *prov);
@@ -49,6 +60,8 @@ ossl_provider_get_capabilities
  /* Return pointer to the provider's context */
  void *ossl_provider_ctx(const OSSL_PROVIDER *prov);
 
+ const OSSL_DISPATCH *ossl_provider_get0_dispatch(const OSSL_PROVIDER *prov);
+
  /* Iterate over all loaded providers */
  int ossl_provider_doall_activated(OSSL_LIB_CTX *,
                                    int (*cb)(OSSL_PROVIDER *provider,
@@ -82,6 +95,12 @@ ossl_provider_get_capabilities
                                       int *result);
  int ossl_provider_clear_all_operation_bits(OSSL_LIB_CTX *libctx);
 
+ int ossl_provider_init_child_providers(OSSL_LIB_CTX *ctx);
+ int ossl_provider_init_as_child(OSSL_LIB_CTX *ctx,
+                                 const OSSL_CORE_HANDLE *handle,
+                                 const OSSL_DISPATCH *in);
+
+
 =head1 DESCRIPTION
 
 I<OSSL_PROVIDER> is a type that holds all the necessary information
@@ -162,6 +181,19 @@ provider will use the name to find the value it wants.
 Only text parameters can be given, and it's up to the provider to
 interpret them.
 
+ossl_provider_set_child() marks this provider as a child of a provider in the
+parent library context. I<handle> is the B<OSSL_CORE_HANDLE> object passed to
+the provider's B<OSSL_provider_init> function.
+
+ossl_provider_get_parent() obtains the handle on the parent provider.
+
+ossl_provider_up_ref_parent() increases the reference count on the parent
+provider. If I<activate> is nonzero then the parent provider is also activated.
+
+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_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.
@@ -184,7 +216,9 @@ be located in that module, and called.
 =back
 
 If I<retain_fallbacks> is zero, fallbacks are disabled.  If it is nonzero,
-fallbacks are left unchanged.
+fallbacks are left unchanged. If I<upcalls> is nonzero then, if this is a child
+provider, upcalls to the parent libctx will be made to inform it of an
+up-ref.
 
 ossl_provider_deactivate() "deactivates" the provider for the given
 provider object I<prov> by decrementing its activation count.  When
@@ -198,6 +232,10 @@ ossl_provider_ctx() returns a context created by the provider.
 Outside of the provider, it's completely opaque, but it needs to be
 passed back to some of the provider functions.
 
+ossl_provider_get0_dispatch() returns the dispatch table that the provider
+initially returned in the I<out> parameter of its B<OSSL_provider_init>
+function.
+
 ossl_provider_doall_activated() iterates over all the currently
 "activated" providers, and calls I<cb> for each of them.
 If no providers have been "activated" yet, it tries to activate all
@@ -253,6 +291,15 @@ I<*result> to 1 or 0 accorddingly.
 ossl_provider_clear_all_operation_bits() clears all of the operation bits
 to (0) for all providers in the library context I<libctx>.
 
+ossl_provider_init_child_providers() registers the callbacks required to
+receive notifications about loading and unloading of providers in the parent
+library context.
+
+ossl_provider_init_as_child() stores in the library context I<ctx> references to
+the necessary upcalls for managing child providers. The I<handle> and I<in>
+parameters are the B<OSSL_CORE_HANDLE> and B<OSSL_DISPATCH> pointers that were
+passed to the provider's B<OSSL_provider_init> function.
+
 =head1 NOTES
 
 Locating a provider module happens as follows: