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)

2 files changed, 63 insertions, 4 deletions

diff --git a/doc/internal/man3/ossl_lib_ctx_get_data.pod b/doc/internal/man3/ossl_lib_ctx_get_data.pod
index b79e93d848..6b80aa011e 100644
--- a/doc/internal/man3/ossl_lib_ctx_get_data.pod
+++ b/doc/internal/man3/ossl_lib_ctx_get_data.pod
@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-ossl_lib_ctx_get_data, ossl_lib_ctx_run_once, ossl_lib_ctx_onfree
+ossl_lib_ctx_get_data, ossl_lib_ctx_run_once, ossl_lib_ctx_onfree,
+ossl_lib_ctx_is_child
 - internal OSSL_LIB_CTX routines
 
 =head1 SYNOPSIS
@@ -11,6 +12,7 @@ ossl_lib_ctx_get_data, ossl_lib_ctx_run_once, ossl_lib_ctx_onfree
  #include "internal/cryptlib.h"
 
  typedef struct ossl_lib_ctx_method {
+     int priority;
      void *(*new_func)(OSSL_LIB_CTX *ctx);
      void (*free_func)(void *);
  } OSSL_LIB_CTX_METHOD;
@@ -22,6 +24,8 @@ ossl_lib_ctx_get_data, ossl_lib_ctx_run_once, ossl_lib_ctx_onfree
                            ossl_lib_ctx_run_once_fn run_once_fn);
  int ossl_lib_ctx_onfree(OSSL_LIB_CTX *ctx, ossl_lib_ctx_onfree_fn onfreefn);
 
+ int ossl_lib_ctx_is_child(OSSL_LIB_CTX *ctx);
+
 =head1 DESCRIPTION
 
 Internally, the OpenSSL library context B<OSSL_LIB_CTX> is implemented
@@ -53,6 +57,9 @@ using ossl_lib_ctx_onfree. This associates an "on free" routine I<onfreefn> with
 the library context I<ctx>. When I<ctx> is freed all associated "on free"
 routines are called.
 
+ossl_lib_ctx_is_child() returns 1 if this library context is a child and 0
+otherwise.
+
 =head1 RETURN VALUES
 
 ossl_lib_ctx_get_data() returns a pointer on success, or NULL on
@@ -86,8 +93,13 @@ and a destructor to an index.
  /*
   * Include a reference to this in the methods table in context.c 
   * OSSL_LIB_CTX_FOO_INDEX should be added to internal/cryptlib.h
+  * Priorities can be OSSL_LIB_CTX_METHOD_DEFAULT_PRIORITY,
+  * OSSL_LIB_CTX_METHOD_PRIORITY_1, OSSL_LIB_CTX_METHOD_PRIORITY_2, etc.
+  * Default priority is low (0). The higher the priority the earlier the
+  * method's destructor will be called when the library context is cleaned up.
   */
  const OSSL_LIB_CTX_METHOD foo_method = {
+     OSSL_LIB_CTX_METHOD_DEFAULT_PRIORITY,
      foo_new,
      foo_free
  };
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: