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, 50 insertions, 4 deletions

diff --git a/doc/man3/OSSL_LIB_CTX.pod b/doc/man3/OSSL_LIB_CTX.pod
index 1af8e53d7b..57037e2ba6 100644
--- a/doc/man3/OSSL_LIB_CTX.pod
+++ b/doc/man3/OSSL_LIB_CTX.pod
@@ -3,8 +3,8 @@
 =head1 NAME
 
 OSSL_LIB_CTX, OSSL_LIB_CTX_new, OSSL_LIB_CTX_new_from_dispatch,
-OSSL_LIB_CTX_free, OSSL_LIB_CTX_load_config, OSSL_LIB_CTX_get0_global_default,
-OSSL_LIB_CTX_set0_default
+OSSL_LIB_CTX_new_child, OSSL_LIB_CTX_free, OSSL_LIB_CTX_load_config,
+OSSL_LIB_CTX_get0_global_default, OSSL_LIB_CTX_set0_default
 - OpenSSL library context
 
 =head1 SYNOPSIS
@@ -16,6 +16,8 @@ OSSL_LIB_CTX_set0_default
  OSSL_LIB_CTX *OSSL_LIB_CTX_new(void);
  OSSL_LIB_CTX *OSSL_LIB_CTX_new_from_dispatch(const OSSL_CORE_HANDLE *handle,
                                               const OSSL_DISPATCH *in);
+ OSSL_LIB_CTX *OSSL_LIB_CTX_new_child(const OSSL_CORE_HANDLE *handle,
+                                      const OSSL_DISPATCH *in);
  int OSSL_LIB_CTX_load_config(OSSL_LIB_CTX *ctx, const char *config_file);
  void OSSL_LIB_CTX_free(OSSL_LIB_CTX *ctx);
  OSSL_LIB_CTX *OSSL_LIB_CTX_get0_global_default(void);
@@ -43,6 +45,44 @@ OSSL_provider_init function. Some OpenSSL functions, such as
 L<BIO_new_from_core_bio(3)>, require the library context to be created in this
 way in order to work.
 
+OSSL_LIB_CTX_new_child() is only useful to provider authors and does the same
+thing as OSSL_LIB_CTX_new_from_dispatch() except that it additionally links the
+new library context to the application library context. The new library context
+is a full library context in its own right, but will have all the same providers
+available to it that are available in the application library context (without
+having to reload them). If the application loads or unloads providers from the
+application library context then this will be automatically mirrored in the
+child library context.
+
+In addition providers that are not loaded in the parent library context can be
+explicitly loaded into the child library context independently from the parent
+library context. Providers loaded independently in this way will not be mirrored
+in the parent library context and will not be affected if the parent library
+context subsequently loads the same provider.
+
+A provider may call the function L<OSSL_PROVIDER_load(3)> with the child library
+context as required. If the provider already exists due to it being mirrored
+from the parent library context then it will remain available and its reference
+count will be increased. If L<OSSL_PROVIDER_load(3)> is called in this way then
+L<OSSL_PROVIDER_unload(3)> should be subsequently called to decrement the
+reference count. L<OSSL_PROVIDER_unload(3)> must not be called for a provider in
+the child library context that did not have an earlier L<OSSL_PROVIDER_load(3)>
+call for that provider in that child library context.
+
+OSSL_LIB_CTX_new_child() must only be called from within the scope of a
+provider's B<OSSL_provider_init> function (see L<provider-base(7)>). Calling it
+outside of that function may succeed but may not correctly mirror all providers
+and is considered undefined behaviour. When called from within the scope of a
+provider's B<OSSL_provider_init> function the currently initialising provider is
+not yet available in the application's library context and therefore will
+similarly not yet be available in the newly constructed child library context.
+As soon as the B<OSSL_provider_init> function returns then the new provider is
+available in the application's library context and will be similarly mirrored in
+the child library context. Since the current provider is still initialising
+the provider should not attempt to perform fetches, or call any function that
+performs a fetch using the child library context until after the initialisation
+function has completed.
+
 OSSL_LIB_CTX_load_config() loads a configuration file using the given C<ctx>.
 This can be used to associate a library context with providers that are loaded
 from a configuration.
diff --git a/doc/man3/OSSL_PROVIDER.pod b/doc/man3/OSSL_PROVIDER.pod
index d5317ee3f5..391084e68e 100644
--- a/doc/man3/OSSL_PROVIDER.pod
+++ b/doc/man3/OSSL_PROVIDER.pod
@@ -7,8 +7,9 @@ OSSL_PROVIDER, OSSL_PROVIDER_load, OSSL_PROVIDER_try_load, OSSL_PROVIDER_unload,
 OSSL_PROVIDER_available, OSSL_PROVIDER_do_all,
 OSSL_PROVIDER_gettable_params, OSSL_PROVIDER_get_params,
 OSSL_PROVIDER_query_operation, OSSL_PROVIDER_unquery_operation,
-OSSL_PROVIDER_get0_provider_ctx, OSSL_PROVIDER_add_builtin, OSSL_PROVIDER_name,
-OSSL_PROVIDER_get_capabilities, OSSL_PROVIDER_self_test
+OSSL_PROVIDER_get0_provider_ctx, OSSL_PROVIDER_get0_dispatch,
+OSSL_PROVIDER_add_builtin, OSSL_PROVIDER_name, OSSL_PROVIDER_get_capabilities,
+OSSL_PROVIDER_self_test
 - provider routines
 
 =head1 SYNOPSIS
@@ -39,6 +40,7 @@ OSSL_PROVIDER_get_capabilities, OSSL_PROVIDER_self_test
                                       int operation_id,
                                       const OSSL_ALGORITHM *algs);
  void *OSSL_PROVIDER_get0_provider_ctx(const OSSL_PROVIDER *prov);
+ const OSSL_DISPATCH *OSSL_PROVIDER_get0_dispatch(const OSSL_PROVIDER *prov);
 
  int OSSL_PROVIDER_add_builtin(OSSL_LIB_CTX *libctx, const char *name,
                                ossl_provider_init_fn *init_fn);
@@ -130,6 +132,10 @@ OSSL_PROVIDER_get0_provider_ctx() returns the provider context for the given
 provider. The provider context is an opaque handle set by the provider itself
 and is passed back to the provider by libcrypto in various function calls.
 
+OSSL_PROVIDER_get0_dispatch() returns the provider's dispatch table as it was
+returned in the I<out> parameter from the provider's init function. See
+L<provider-base(7)>.
+
 If it is permissible to cache references to this array then I<*no_store> is set
 to 0 or 1 otherwise. If the array is not cacheable then it is assumed to
 have a short lifetime.