Enhance and update the docs of the internal ossl_provider API
Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/9200)
This commit is contained in:
parent
4e7991b497
commit
3bbec1afed
2 changed files with 133 additions and 61 deletions
41
doc/internal/man3/ossl_provider_add_conf_module.pod
Normal file
41
doc/internal/man3/ossl_provider_add_conf_module.pod
Normal file
|
@ -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<config(5)> file.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
ossl_provider_add_conf_module() doesn't return any value.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<OSSL_PROVIDER(3)>, L<ossl_provider_new(3)>
|
||||
|
||||
=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
|
|
@ -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<OSSL_PROVIDER> is a type that holds all the necessary information
|
||||
I<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.
|
||||
Instances of this type are commonly referred to as "provider objects".
|
||||
|
||||
A I<provider object> is always stored in a set of I<provider object>s
|
||||
A provider object is always stored in a set of provider objects
|
||||
in the library context.
|
||||
|
||||
I<provider object>s are reference counted.
|
||||
Provider objects are reference counted.
|
||||
|
||||
I<provider object>s 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<provider object> in the
|
||||
I<provider object> store by C<name>.
|
||||
The I<provider object> it finds gets its reference count
|
||||
incremented.
|
||||
ossl_provider_find() finds an existing provider object in the provider
|
||||
object store by I<name>.
|
||||
The provider object it finds has its 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_new() creates a new provider object named I<name> 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<init_function> is NULL, the provider is assumed to be a
|
||||
dynamically loadable module, with the symbol B<OSSL_provider_init> as
|
||||
its initialisation function.
|
||||
If I<init_function> isn't NULL, the provider is assumed to be built
|
||||
in, with I<init_function> being the pointer to its initialisation
|
||||
function.
|
||||
For further description of the initialisation function, see the
|
||||
description of ossl_provider_activate() below.
|
||||
|
||||
ossl_provider_free() decrements a I<provider object>'s reference
|
||||
counter; if it drops below 2, the I<provider object> 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<provider object> is
|
||||
assumed to have been taken out of the store, and the associated module
|
||||
will be unloaded if one was loaded, and the I<provider object> will be
|
||||
freed.
|
||||
ossl_provider_upref() increments the provider object I<prov>'s
|
||||
reference count.
|
||||
|
||||
ossl_provider_add_module_location() adds a location to look for a
|
||||
provider module.
|
||||
ossl_provider_free() decrements the provider object I<prov>'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<teardown>
|
||||
function is called); if it drops down to zero, I<prov> is assumed to
|
||||
have been taken out of the store, and the associated module will be
|
||||
unloaded if one was loaded, and I<prov> itself will be freed.
|
||||
|
||||
ossl_provider_set_fallback() marks an available provider as fallback.
|
||||
Note that after this call, the I<provider object> pointer that was
|
||||
ossl_provider_set_fallback() marks an available provider I<prov> 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<prov>.
|
||||
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</NOTES>).
|
||||
|
||||
ossl_provider_add_parameter() adds a global parameter for the provider
|
||||
to retrieve as it sees fit.
|
||||
The parameters are a combination of I<name> and I<value>, 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<provider object>.
|
||||
What "activates" means depends on what type of I<provider object> it
|
||||
provider object I<prov>.
|
||||
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<name> that was given to ossl_provider_new()
|
||||
will be located and loaded, then the symbol C<OSSL_provider_init> will
|
||||
loadable module with the I<name> that was given to ossl_provider_new()
|
||||
will be located and loaded, then the symbol B<OSSL_provider_init> 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<cb> for each of them.
|
||||
"activated" providers, and calls I<cb> 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<teardown> function, if
|
||||
ossl_provider_teardown() calls the provider's I<teardown> function, if
|
||||
the provider has one.
|
||||
|
||||
ossl_provider_get_param_types() calls the provider's C<get_param_types>
|
||||
ossl_provider_get_param_types() calls the provider's I<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>.
|
||||
It should return an array of I<OSSL_ITEM> 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<OSSL_PARAM> array as described in
|
||||
It should treat the given I<OSSL_PARAM> array as described in
|
||||
L<OSSL_PARAM(3)>.
|
||||
|
||||
ossl_provider_query_operation() calls the provider's
|
||||
C<query_operation> function, if the provider has one.
|
||||
It should return an array of C<OSSL_ALGORITHM> for the given
|
||||
C<operation_id>.
|
||||
I<query_operation> function, if the provider has one.
|
||||
It should return an array of I<OSSL_ALGORITHM> for the given
|
||||
I<operation_id>.
|
||||
|
||||
=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<OPENSSL_MODULES>.
|
||||
|
||||
=item 3.
|
||||
|
||||
Look in the directory given by the OpenSSL built in macro
|
||||
B<MODULESDIR>.
|
||||
If the environment variable B<OPENSSL_MODULES> 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<MODULESDIR>
|
||||
with the module path.
|
||||
|
||||
=back
|
||||
|
||||
When this process is done, the result is used when trying to load the
|
||||
provider module.
|
||||
|
||||
The command C<openssl version -m> can be used to find out the value
|
||||
of the built in macro B<MODULESDIR>.
|
||||
|
||||
=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.
|
||||
provider object (I<OSSL_PROVIDER>) 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<NULL>
|
||||
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_ITEM>
|
||||
ossl_provider_get_param_types() returns a pointer to an I<OSSL_ITEM>
|
||||
array if this function is available in the provider, otherwise
|
||||
B<NULL>.
|
||||
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)>
|
||||
L<OSSL_PROVIDER(3)>, L<provider(7)>, L<openssl(1)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
|
|
Loading…
Reference in a new issue