Update documentation following updates to the provider code

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

3 files changed, 22 insertions, 18 deletions

diff --git a/doc/internal/man3/ossl_provider_new.pod b/doc/internal/man3/ossl_provider_new.pod
index 0a76135281..928cc9b844 100644
--- a/doc/internal/man3/ossl_provider_new.pod
+++ b/doc/internal/man3/ossl_provider_new.pod
@@ -9,7 +9,7 @@ ossl_provider_add_parameter, ossl_provider_set_child, ossl_provider_get_parent,
 ossl_provider_up_ref_parent, ossl_provider_free_parent,
 ossl_provider_default_props_update, ossl_provider_get0_dispatch,
 ossl_provider_init_as_child,
-ossl_provider_activate, ossl_provider_deactivate,
+ossl_provider_activate, ossl_provider_deactivate, ossl_provider_add_to_store,
 ossl_provider_ctx,
 ossl_provider_doall_activated,
 ossl_provider_name, ossl_provider_dso,
@@ -53,8 +53,9 @@ ossl_provider_get_capabilities
   * Activate the Provider
   * If the Provider is a module, the module will be loaded
   */
- int ossl_provider_activate(OSSL_PROVIDER *prov, int upcalls);
+ int ossl_provider_activate(OSSL_PROVIDER *prov, int upcalls, int aschild);
  int ossl_provider_deactivate(OSSL_PROVIDER *prov);
+ int ossl_provider_add_to_store(OSSL_PROVIDER *prov, int retain_fallbacks);
 
  /* Return pointer to the provider's context */
  void *ossl_provider_ctx(const OSSL_PROVIDER *prov);
@@ -218,12 +219,18 @@ be located in that module, and called.
 =back
 
 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.
+parent libctx will be made to inform it of an up-ref. If I<aschild> is nonzero
+then the provider will only be activated if it is a child provider. Otherwise
+no action is taken and ossl_provider_activate() returns success.
 
 ossl_provider_deactivate() "deactivates" the provider for the given
 provider object I<prov> by decrementing its activation count.  When
 that count reaches zero, the activation flag is cleared.
 
+ossl_provider_add_to_store() adds the provider I<prov> to the provider store and
+makes it available to other threads. This will prevent future automatic loading
+of fallback providers, unless I<retain_fallbacks> is true.
+
 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.
@@ -336,8 +343,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(), ossl_provider_default_props_update() return 1 on
-success, or 0 on error.
+ossl_provider_deactivate(), ossl_provider_add_to_store(),
+ossl_provider_default_props_update() return 1 on success, or 0 on error.
 
 ossl_provider_name(), ossl_provider_dso(),
 ossl_provider_module_name(), and ossl_provider_module_path() return a
diff --git a/doc/man3/OSSL_LIB_CTX.pod b/doc/man3/OSSL_LIB_CTX.pod
index d51816ead7..98a3896fe4 100644
--- a/doc/man3/OSSL_LIB_CTX.pod
+++ b/doc/man3/OSSL_LIB_CTX.pod
@@ -75,19 +75,13 @@ context. If L<EVP_set_default_properties(3)> is called directly on a child
 library context then the new properties will override anything from the parent
 library context and mirroring of the properties will stop.
 
-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.
+When OSSL_LIB_CTX_new_child() is 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.
 
 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
diff --git a/doc/man7/provider.pod b/doc/man7/provider.pod
index 797ef45553..7074a5cad1 100644
--- a/doc/man7/provider.pod
+++ b/doc/man7/provider.pod
@@ -69,6 +69,9 @@ the provider multiple simultaneous uses.
 This pointer will be passed to various operation functions offered by
 the provider.
 
+Note that the provider will not be made available for applications to use until
+the initialization function has completed and returned successfully.
+
 One of the functions the provider offers to the OpenSSL libraries is
 the central mechanism for the OpenSSL libraries to get access to
 operation implementations for diverse algorithms.