diff options
author | Michael Baentsch <info@baentsch.ch> | 2021-01-13 11:06:13 +0100 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2021-01-14 17:33:47 +0000 |
commit | 3bc061eb0a990a95d35c462b9206bdf74905cfa2 (patch) | |
tree | e5a8ac7d81994ec627be81768639dae24546d675 | |
parent | b11ba50fd9bd3c33e1627ca5c64f08b403e88173 (diff) |
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)
-rw-r--r-- | doc/man3/OSSL_PROVIDER.pod | 15 | ||||
-rw-r--r-- | doc/man7/OSSL_PROVIDER-default.pod | 15 | ||||
-rw-r--r-- | 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 |