From 3bc061eb0a990a95d35c462b9206bdf74905cfa2 Mon Sep 17 00:00:00 2001 From: Michael Baentsch Date: Wed, 13 Jan 2021 11:06:13 +0100 Subject: Enhance default provider documentation Bring Wiki and man page documentation in line regarding default provider fall-back behaviour. Fixes #13844 Reviewed-by: Tomas Mraz Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/openssl/pull/13859) --- 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_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 for each one, with the current provider in I and the -I that comes from the caller. +I 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 for more information on this fallback +behaviour. OSSL_PROVIDER_gettable_params() is used to get a provider parameter descriptor set as a constant B 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 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) 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). =item An identifier -- cgit v1.2.3