Enhance default provider documentation

Bring Wiki and man page documentation in line regarding default provider
fall-back behaviour.

Fixes #13844

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13859)

diff --git a/doc/man3/OSSL_PROVIDER.pod b/doc/man3/OSSL_PROVIDER.pod
index 2baccfffaffbcb6080e1b6cb3e073c77d784fdbd..dbae09334f1d0bf5202d279466895acda924a643 100644 (file)
--- a/doc/man3/OSSL_PROVIDER.pod
+++ b/doc/man3/OSSL_PROVIDER.pod
@@ -78,9 +78,9 @@ or load a provider module with the given name and run its provider
 entry point, C<OSSL_provider_init>.
 
 OSSL_PROVIDER_try_load() functions like OSSL_PROVIDER_load(), except that
-it does not disable the fall-back providers if the provider cannot be
+it does not disable the fallback providers if the provider cannot be
 loaded and initialized.
-If the provider loads successfully, however, the fall-back providers are
+If the provider loads successfully, however, the fallback providers are
 disabled.
 
 OSSL_PROVIDER_unload() unloads the given provider.
@@ -92,7 +92,11 @@ for use.
 
 OSSL_PROVIDER_do_all() iterates over all loaded providers, calling
 I<cb> for each one, with the current provider in I<provider> and the
-I<cbdata> that comes from the caller.
+I<cbdata> that comes from the caller. If no other provider has been loaded
+before calling this function, the default provider is still available as
+fallback.
+See L<OSSL_PROVIDER-default(7)> for more information on this fallback
+behaviour.
 
 OSSL_PROVIDER_gettable_params() is used to get a provider parameter
 descriptor set as a constant B<OSSL_PARAM> array.
@@ -140,6 +144,11 @@ OSSL_PROVIDER_get_capabilities() return 1 on success, or 0 on error.
 OSSL_PROVIDER_load() and OSSL_PROVIDER_try_load() return a pointer to a
 provider object on success, or NULL on error.
 
+OSSL_PROVIDER_do_all() returns 1 if the callback I<cb> returns 1 for every
+provider it is called with, or 0 if any provider callback invocation returns 0;
+callback processing stops at the first callback invocation on a provider
+that returns 0.
+
 OSSL_PROVIDER_available() returns 1 if the named provider is available,
 otherwise 0.
 

diff --git a/doc/man7/OSSL_PROVIDER-default.pod b/doc/man7/OSSL_PROVIDER-default.pod
index 96144e22602fd162d0c43615b85004957925164e..472bff65fdcaf9c9662ced16b7db54f80f3ccb32 100644 (file)
--- a/doc/man7/OSSL_PROVIDER-default.pod
+++ b/doc/man7/OSSL_PROVIDER-default.pod
@@ -7,8 +7,19 @@ OSSL_PROVIDER-default - OpenSSL default provider
 =head1 DESCRIPTION
 
 The OpenSSL default provider supplies the majority of OpenSSL's diverse
-algorithm implementations.  It also acts as a fallback when no other
-provider has been loaded.
+algorithm implementations. If an application doesn't specify anything else
+explicitly (e.g. in the application or via config), then this is the
+provider that will be used as fallback: It is loaded automatically the
+first time that an algorithm is fetched from a provider or a function
+acting on providers is called and no other provider has been loaded yet.
+
+If an attempt to load a provider has already been made (whether successful
+or not) then the default provider won't be loaded automatically. Therefore
+if the default provider is to be used in conjunction with other providers
+then it must be loaded explicitly. Automatic loading of the default
+provider only occurs a maximum of once; if the default provider is
+explicitly unloaded then the default provider will not be automatically
+loaded again.
 
 =head2 Properties
 

diff --git a/doc/man7/provider.pod b/doc/man7/provider.pod
index 18a80eff5ab03d96a3b5970416b24636be2f4592..65bbda5063b75cbd8ccf847170ff8e74c020877b 100644 (file)
--- a/doc/man7/provider.pod
+++ b/doc/man7/provider.pod
@@ -196,7 +196,9 @@ This may be NULL to signify the default (global) library context, or a
 context created by the user.
 Only providers loaded in this library context (see
 L<OSSL_PROVIDER_load(3)>) will be considered by the fetching
-function.
+function. In case no provider has been loaded in this library context
+the default provider will be loaded as fallback (see
+L<OSSL_PROVIDER-default(7)>).
 
 =item An identifier