diff options
author | Richard Levitte <levitte@openssl.org> | 2019-02-21 21:20:53 +0100 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2019-03-11 20:40:13 +0100 |
commit | c453283421299b7f8e0db6d6069c68369294a9f7 (patch) | |
tree | 65cc85db68a09836c965dbf34af779d5c438ee44 /doc/internal | |
parent | 021a65527735af2ddc063d9300138660e3782a15 (diff) |
Add documentation
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/8287)
Diffstat (limited to 'doc/internal')
-rw-r--r-- | doc/internal/man3/ossl_provider_new.pod | 196 |
1 files changed, 196 insertions, 0 deletions
diff --git a/doc/internal/man3/ossl_provider_new.pod b/doc/internal/man3/ossl_provider_new.pod new file mode 100644 index 0000000000..79964d6548 --- /dev/null +++ b/doc/internal/man3/ossl_provider_new.pod @@ -0,0 +1,196 @@ +=pod + +=head1 NAME + +ossl_provider_find, ossl_provider_new, ossl_provider_upref, +ossl_provider_free, ossl_provider_add_module_location, +ossl_provider_activate, ossl_provider_name, ossl_provider_dso, +ossl_provider_module_name, ossl_provider_module_path, +ossl_provider_teardown, ossl_provider_get_param_types, +ossl_provider_get_params - internal provider routines + +=head1 SYNOPSIS + + #include "internal/provider.h" + + OSSL_PROVIDER *ossl_provider_find(OPENSSL_CTX *libctx, const char *name); + OSSL_PROVIDER *ossl_provider_new(OPENSSL_CTX *libctx, const char *name, + ossl_provider_init_fn *init_function); + int ossl_provider_upref(OSSL_PROVIDER *prov); + void ossl_provider_free(OSSL_PROVIDER *prov); + + /* Setters */ + int ossl_provider_add_module_location(OSSL_PROVIDER *prov, const char *loc); + + /* Load and initialize the Provider */ + int ossl_provider_activate(OSSL_PROVIDER *prov); + + /* Getters for other library functions */ + const char *ossl_provider_name(OSSL_PROVIDER *prov); + const DSO *ossl_provider_dso(OSSL_PROVIDER *prov); + const char *ossl_provider_module_name(OSSL_PROVIDER *prov); + const char *ossl_provider_module_path(OSSL_PROVIDER *prov); + + /* Thin wrappers around calls to the provider */ + void ossl_provider_teardown(const OSSL_PROVIDER *prov); + const OSSL_ITEM *ossl_provider_get_param_types(const OSSL_PROVIDER *prov); + int ossl_provider_get_params(const OSSL_PROVIDER *prov, + const OSSL_PARAM params[]); + +=head1 DESCRIPTION + +C<OSSL_PROVIDER> 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 I<provider object>s. + +A I<provider object> is always stored in a set of I<provider object>s +in the library context. + +I<provider object>s are reference counted. + +I<provider object>s 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<provider object> in the +I<provider object> store by C<name>. +The I<provider object> it finds gets it's reference count +incremented. + +ossl_provider_new() creates a new I<provider object> and stores it in +the I<provider object> store, unless there already is one there with +the same name. +The reference counter of a newly created I<provider object> 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<init_function> argument must +point at the provider initialization function for that provider. + +ossl_provider_free() decrements a I<provider object>'s reference +counter; if it drops to one, the I<provider object> will be +inactivated (it's teardown function is called) but kept in the store; +if it drops down to zero, the associated module will be unloaded if +one was loaded, and the I<provider object> will be freed. + +ossl_provider_add_module_location() adds a location to look for a +provider module. + +ossl_provider_activate() "activates" the provider for the given +I<provider object>. +What "activates" means depends on what type of I<provider object> it +is: + +=over 4 + +=item * + +If an initialization function was given with ossl_provider_new(), that +function will get called. + +=item * + +If no intialization function was given with ossl_provider_new(), a +loadable module with the C<name> that was given to ossl_provider_new() +will be located and loaded, then the symbol C<OSSL_provider_init> will +be located in that module, and called. + +=back + +ossl_provider_name() returns the name that was given with +ossl_provider_new(). + +ossl_provider_dso() returns a reference to the module, for providers +that come in the form of loadable modules. + +ossl_provider_module_name() returns the file name of the module, for +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<teardown> function, if +the provider has one. + +ossl_provider_get_param_types() calls the provider's C<get_param_types> +function, if the provider has one. +It should return an array of C<OSSL_ITEM> to describe all the +parameters that the provider has for the I<provider object>. + +ossl_provider_get_params() calls the provider's parameter request +responder. +It should treat the given C<OSSL_PARAM> array as described in +L<OSSL_PARAM(3)>. + +=head1 NOTES + +Locating a provider module happens as follows: + +=over 4 + +=item 1. + +Look in each directory given by ossl_provider_add_module_location(). + +=item 2. + +Look in the directory given by the environment variable +B<OPENSSL_MODULES>. + +=item 3. + +Look in the directory given by the OpenSSL built in macro +B<MODULESDIR>. + +=back + +=head1 RETURN VALUES + +ossl_provider_find() and ossl_provider_new() return a pointer to a +I<provider object> (C<OSSL_PROVIDER>) on success, or B<NULL> on error. + +ossl_provider_upref() returns the value of the reference counter after +it has been incremented. + +ossl_provider_free() doesn't return any value. + +ossl_provider_add_module_location() 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<NULL> +is returned. + +ossl_provider_teardown() doesnt't return any value. + +ossl_provider_get_param_types() returns a pointer to an C<OSSL_ITEM> +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<OSSL_PROVIDER(3)>, L<provider(7)> + +=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<https://www.openssl.org/source/license.html>. + +=cut |