From 3bbec1afed1c65b6f7f645b27808b070e6e7a509 Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Thu, 20 Jun 2019 17:55:36 +0200 Subject: [PATCH] Enhance and update the docs of the internal ossl_provider API Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/9200) --- .../man3/ossl_provider_add_conf_module.pod | 41 +++++ doc/internal/man3/ossl_provider_new.pod | 159 +++++++++++------- 2 files changed, 136 insertions(+), 64 deletions(-) create mode 100644 doc/internal/man3/ossl_provider_add_conf_module.pod diff --git a/doc/internal/man3/ossl_provider_add_conf_module.pod b/doc/internal/man3/ossl_provider_add_conf_module.pod new file mode 100644 index 0000000000..7e4d5097f6 --- /dev/null +++ b/doc/internal/man3/ossl_provider_add_conf_module.pod @@ -0,0 +1,41 @@ +=pod + +=head1 NAME + +ossl_provider_add_conf_module - internal standard configuration module + +=head1 SYNOPSIS + + #include "internal/provider.h" + + /* Configuration */ + void ossl_provider_add_conf_module(void); + +=head1 DESCRIPTION + +ossl_provider_add_conf_module() adds the standard configuration module +for providers. +This allows providers to be configured with an OpenSSL L file. + +=head1 RETURN VALUES + +ossl_provider_add_conf_module() doesn't return any value. + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +The functions described here were all added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/doc/internal/man3/ossl_provider_new.pod b/doc/internal/man3/ossl_provider_new.pod index 9e96c7203c..5a8e97b1c2 100644 --- a/doc/internal/man3/ossl_provider_new.pod +++ b/doc/internal/man3/ossl_provider_new.pod @@ -3,9 +3,12 @@ =head1 NAME ossl_provider_find, ossl_provider_new, ossl_provider_upref, -ossl_provider_free, ossl_provider_add_module_location, -ossl_provider_set_fallback, ossl_provider_activate, -ossl_provider_ctx, ossl_provider_forall_loaded, +ossl_provider_free, +ossl_provider_set_fallback, ossl_provider_set_module_path, +ossl_provider_add_parameter, +ossl_provider_activate, +ossl_provider_ctx, +ossl_provider_forall_loaded, ossl_provider_name, ossl_provider_dso, ossl_provider_module_name, ossl_provider_module_path, ossl_provider_teardown, ossl_provider_get_param_types, @@ -23,8 +26,10 @@ ossl_provider_get_params, ossl_provider_query_operation void ossl_provider_free(OSSL_PROVIDER *prov); /* Setters */ - int ossl_provider_add_module_location(OSSL_PROVIDER *prov, const char *loc); int ossl_provider_set_fallback(OSSL_PROVIDER *prov); + int ossl_provider_set_module_path(OSSL_PROVIDER *prov, const char *path); + int ossl_provider_add_parameter(OSSL_PROVIDER *prov, const char *name, + const char *value); /* Load and initialize the Provider */ int ossl_provider_activate(OSSL_PROVIDER *prov); @@ -54,57 +59,77 @@ ossl_provider_get_params, ossl_provider_query_operation =head1 DESCRIPTION -C is a type that holds all the necessary information +I is a type that holds all the necessary information to handle a provider, regardless of if it's built in to the application or the OpenSSL libraries, or if it's a loadable provider module. -Instances of this type are commonly refered to as Is. +Instances of this type are commonly referred to as "provider objects". -A I is always stored in a set of Is +A provider object is always stored in a set of provider objects in the library context. -Is are reference counted. +Provider objects are reference counted. -Is are initially inactive, i.e. they are only -recorded in the store, but are not used. +Provider objects are initially inactive, i.e. they are only recorded +in the store, but are not used. They are activated with the first call to ossl_provider_activate(), and are inactivated when ossl_provider_free() has been called as many times as ossl_provider_activate() has. =head2 Functions -ossl_provider_find() finds an existing I in the -I store by C. -The I it finds gets its reference count -incremented. - -ossl_provider_new() creates a new I and stores it in -the I store, unless there already is one there with -the same name. -The reference counter of a newly created I will -always be 2; one for being added to the store, and one for the -returned reference. -To indicate a built-in provider, the C argument must -point at the provider initialization function for that provider. - -ossl_provider_free() decrements a I's reference -counter; if it drops below 2, the I is assumed to -have fallen out of use and will be inactivated (its teardown function -is called); if it drops down to zero, the I is -assumed to have been taken out of the store, and the associated module -will be unloaded if one was loaded, and the I will be -freed. - -ossl_provider_add_module_location() adds a location to look for a -provider module. - -ossl_provider_set_fallback() marks an available provider as fallback. -Note that after this call, the I pointer that was +ossl_provider_find() finds an existing provider object in the provider +object store by I. +The provider object it finds has its reference count incremented. + +ossl_provider_new() creates a new provider object named I and +stores it in the provider object store, unless there already is one +there with the same name. +If there already is one with the same name, it's returned with its +reference count incremented. +The reference count of a newly created provider object will always +be 2; one for being added to the store, and one for the returned +reference. +If I is NULL, the provider is assumed to be a +dynamically loadable module, with the symbol B as +its initialisation function. +If I isn't NULL, the provider is assumed to be built +in, with I being the pointer to its initialisation +function. +For further description of the initialisation function, see the +description of ossl_provider_activate() below. + +ossl_provider_upref() increments the provider object I's +reference count. + +ossl_provider_free() decrements the provider object I's +reference count; if it drops below 2, the provider object is assumed +to have fallen out of use and will be deactivated (its I +function is called); if it drops down to zero, I is assumed to +have been taken out of the store, and the associated module will be +unloaded if one was loaded, and I itself will be freed. + +ossl_provider_set_fallback() marks an available provider I as +fallback. +Note that after this call, the provider object pointer that was used can simply be dropped, but not freed. +ossl_provider_set_module_path() sets the module path to load the +provider module given the provider object I. +This will be used in preference to automatically trying to figure out +the path from the provider name and the default module directory (more +on this in L). + +ossl_provider_add_parameter() adds a global parameter for the provider +to retrieve as it sees fit. +The parameters are a combination of I and I, and the +provider will use the name to find the value it wants. +Only text parameters can be given, and it's up to the provider to +interpret them. + ossl_provider_activate() "activates" the provider for the given -I. -What "activates" means depends on what type of I it +provider object I. +What "activates" means depends on what type of provider object it is: =over 4 @@ -117,8 +142,8 @@ function will get called. =item * If no intialization function was given with ossl_provider_new(), a -loadable module with the C that was given to ossl_provider_new() -will be located and loaded, then the symbol C will +loadable module with the I that was given to ossl_provider_new() +will be located and loaded, then the symbol B will be located in that module, and called. =back @@ -128,7 +153,7 @@ Outside of the provider, it's completely opaque, but it needs to be passed back to some of the provider functions. ossl_provider_forall_loaded() iterates over all the currently -"activated" providers, and calls C for each of them. +"activated" providers, and calls I for each of them. If no providers have been "activated" yet, it tries to activate all available fallback providers and tries another iteration. @@ -144,23 +169,23 @@ providers that come in the form of loadable modules. ossl_provider_module_path() returns the full path of the module file, for providers that come in the form of loadable modules. -ossl_provider_teardown() calls the provider's C function, if +ossl_provider_teardown() calls the provider's I function, if the provider has one. -ossl_provider_get_param_types() calls the provider's C +ossl_provider_get_param_types() calls the provider's I function, if the provider has one. -It should return an array of C to describe all the -parameters that the provider has for the I. +It should return an array of I to describe all the +parameters that the provider has for the provider object. ossl_provider_get_params() calls the provider's parameter request responder. -It should treat the given C array as described in +It should treat the given I array as described in L. ossl_provider_query_operation() calls the provider's -C function, if the provider has one. -It should return an array of C for the given -C. +I function, if the provider has one. +It should return an array of I for the given +I. =head1 NOTES @@ -170,50 +195,56 @@ Locating a provider module happens as follows: =item 1. -Look in each directory given by ossl_provider_add_module_location(). +If a path was given with ossl_provider_set_module_path(), use that as +module path. +Otherwise, use the provider object's name as module path, with +platform specific standard extensions added. =item 2. -Look in the directory given by the environment variable -B. +If the environment variable B is defined, assume its +value is a directory specification and merge it with the module path. +Otherwise, merge the value of the OpenSSL built in macro B +with the module path. -=item 3. +=back -Look in the directory given by the OpenSSL built in macro -B. +When this process is done, the result is used when trying to load the +provider module. -=back +The command C can be used to find out the value +of the built in macro B. =head1 RETURN VALUES ossl_provider_find() and ossl_provider_new() return a pointer to a -I (C) on success, or B on error. +provider object (I) on success, or NULL on error. -ossl_provider_upref() returns the value of the reference counter after +ossl_provider_upref() returns the value of the reference count after it has been incremented. ossl_provider_free() doesn't return any value. -ossl_provider_add_module_location(), ossl_provider_set_fallback() and +ossl_provider_set_module_path(), ossl_provider_set_fallback() and ossl_provider_activate() 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 -pointer to their respective data if it's available, otherwise B +pointer to their respective data if it's available, otherwise NULL is returned. ossl_provider_teardown() doesnt't return any value. -ossl_provider_get_param_types() returns a pointer to an C +ossl_provider_get_param_types() returns a pointer to an I array if this function is available in the provider, otherwise -B. +NULL. ossl_provider_get_params() returns 1 on success, or 0 on error. If this function isn't available in the provider, 0 is returned. =head1 SEE ALSO -L, L +L, L, L =head1 HISTORY -- 2.25.1