[openssl] master update

[Matt Caswell]

The branch master has been updated
       via  3bc061eb0a990a95d35c462b9206bdf74905cfa2 (commit)
      from  b11ba50fd9bd3c33e1627ca5c64f08b403e88173 (commit)


- Log -----------------------------------------------------------------
commit 3bc061eb0a990a95d35c462b9206bdf74905cfa2
Author: Michael Baentsch <info at baentsch.ch>
Date:   Wed Jan 13 11:06:13 2021 +0100

    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 at fedoraproject.org>
    Reviewed-by: Matt Caswell <matt at openssl.org>
    (Merged from https://github.com/openssl/openssl/pull/13859)

-----------------------------------------------------------------------

Summary of changes:
 doc/man3/OSSL_PROVIDER.pod         | 15 ++++++++++++---
 doc/man7/OSSL_PROVIDER-default.pod | 15 +++++++++++++--
 doc/man7/provider.pod              |  4 +++-
 3 files changed, 28 insertions(+), 6 deletions(-)

diff --git a/doc/man3/OSSL_PROVIDER.pod b/doc/man3/OSSL_PROVIDER.pod
index 2baccfffaf..dbae09334f 100644
--- 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 96144e2260..472bff65fd 100644
--- 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 18a80eff5a..65bbda5063 100644
--- 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