=head1 NAME
-ossl_provider_find, ossl_provider_new, ossl_provider_upref,
-ossl_provider_free, ossl_provider_add_module_location,
-ossl_provider_activate, ossl_provider_forall_loaded,
+ossl_provider_find, ossl_provider_new, ossl_provider_up_ref,
+ossl_provider_free,
+ossl_provider_set_fallback, ossl_provider_set_module_path,
+ossl_provider_add_parameter,
+ossl_provider_activate, ossl_provider_available,
+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,
-ossl_provider_get_params, ossl_provider_query_operation
+ossl_provider_library_context,
+ossl_provider_teardown, ossl_provider_gettable_params,
+ossl_provider_get_params, ossl_provider_query_operation,
+ossl_provider_set_operation_bit, ossl_provider_test_operation_bit,
+ossl_provider_get_capabilities
- internal provider routines
=head1 SYNOPSIS
#include "internal/provider.h"
- OSSL_PROVIDER *ossl_provider_find(OPENSSL_CTX *libctx, const char *name);
+ OSSL_PROVIDER *ossl_provider_find(OPENSSL_CTX *libctx, const char *name,
+ int noconfig);
OSSL_PROVIDER *ossl_provider_new(OPENSSL_CTX *libctx, const char *name,
- ossl_provider_init_fn *init_function);
- int ossl_provider_upref(OSSL_PROVIDER *prov);
+ ossl_provider_init_fn *init_function
+ int noconfig);
+ int ossl_provider_up_ref(OSSL_PROVIDER *prov);
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);
+ /* Check if provider is available */
+ int ossl_provider_available(OSSL_PROVIDER *prov);
+
+ /* Return pointer to the provider's context */
+ void *ossl_provider_ctx(const OSSL_PROVIDER *prov);
/* Iterate over all loaded providers */
int ossl_provider_forall_loaded(OPENSSL_CTX *,
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);
+ OPENSSL_CTX *ossl_provider_library_context(const 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[]);
+ const OSSL_PARAM *ossl_provider_gettable_params(const OSSL_PROVIDER *prov);
+ int ossl_provider_get_params(const OSSL_PROVIDER *prov, OSSL_PARAM params[]);
+ int ossl_provider_get_capabilities(const OSSL_PROVIDER *prov,
+ const char *capability,
+ OSSL_CALLBACK *cb,
+ void *arg);
const OSSL_ALGORITHM *ossl_provider_query_operation(const OSSL_PROVIDER *prov,
int operation_id,
int *no_cache);
+ int ossl_provider_set_operation_bit(OSSL_PROVIDER *provider, size_t bitnum);
+ int ossl_provider_test_operation_bit(OSSL_PROVIDER *provider, size_t bitnum,
+ int *result);
+
=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 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_find() finds an existing provider object in the provider
+object store by I<name>.
+The config file will be automatically loaded unless I<noconfig> is set.
+Typically I<noconfig> should be 0.
+We set I<noconfig> to 1 only when calling these functions while processing a
+config file in order to avoid recursively attempting to load the file.
+The provider object it finds has its reference count incremented.
+
+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 config file will be automatically loaded unless I<noconfig> is set.
+Typically I<noconfig> should be 0.
+We set I<noconfig> to 1 only when calling these functions while processing a
+config file in order to avoid recursively attempting to load the file.
+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_up_ref() increments the provider object I<prov>'s
+reference count.
+
+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 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_library_context() returns the library context the given
+provider I<prov> is registered in.
+
+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
=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
+If no initialization function was given with ossl_provider_new(), a
+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
+ossl_provider_available() activates all fallbacks if no provider is
+activated yet, then checks if given provider object I<prov> is
+activated.
+
+ossl_provider_ctx() returns a context created by the provider.
+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.
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
+ossl_provider_module_name() returns the filename 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
+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_gettable_params() calls the provider's I<gettable_params>
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_PARAM> 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_get_capabilities() calls the provider's I<get_capabilities> function,
+if the provider has one. It provides the name of the I<capability> and a
+callback I<cb> parameter to call for each capability that has a matching name in
+the provider. The callback gets passed OSSL_PARAM details about the capability as
+well as the caller supplied argument I<arg>.
+
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>.
+
+ossl_provider_set_operation_bit() registers a 1 for operation I<bitnum>
+in a bitstring that's internal to I<provider>.
+
+ossl_provider_tests_operation_bit() checks if the bit operation I<bitnum>
+is set (1) or not (0) in the internal I<provider> bitstring, and sets
+I<*result> to 1 or 0 accorddingly.
=head1 NOTES
=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>.
+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.
-=item 3.
+=back
-Look in the directory given by the OpenSSL built in macro
-B<MODULESDIR>.
+When this process is done, the result is used when trying to load the
+provider module.
-=back
+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_up_ref() 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() and ossl_provider_activate()
-return 1 on success, or 0 on error.
+ossl_provider_set_module_path(), ossl_provider_set_fallback() and
+ossl_provider_activate() return 1 on success, or 0 on error.
+
+ossl_provider_available() return 1 if the provider is available,
+otherwise 0.
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_library_context() return a pointer to the library context.
+This may be NULL, and is perfectly valid, as it denotes the default
+global library context.
-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_teardown() doesn't return any value.
+
+ossl_provider_gettable_params() returns a pointer to a constant
+I<OSSL_PARAM> array if this function is available in the provider,
+otherwise 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.
+ossl_provider_set_operation_bit() and ossl_provider_test_operation_bit()
+return 1 on success, or 0 on error.
+
+ossl_provider_get_capabilities() returns 1 on success, or 0 on error.
+If this function isn't available in the provider or the provider does not
+support the requested capability then 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
=head1 COPYRIGHT
-Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2019-2020 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
projects / openssl.git / blobdiff