mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-02-17 14:32:04 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation following addition of OSSL_LIB_CTX_new_child()

Browse Source 
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14991)
This commit is contained in:
Matt Caswell 2021-05-05 14:43:19 +01:00
parent fb9b3a7bce
commit 878be71c2d
5 changed files with 167 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
doc/internal/man3/ossl_lib_ctx_get_data.pod
View File

@ -2,7 +2,8 @@
=head1 NAME
ossl_lib_ctx_get_data, ossl_lib_ctx_run_once, ossl_lib_ctx_onfree
ossl_lib_ctx_get_data, ossl_lib_ctx_run_once, ossl_lib_ctx_onfree,
ossl_lib_ctx_is_child
- internal OSSL_LIB_CTX routines
=head1 SYNOPSIS
@ -11,6 +12,7 @@ ossl_lib_ctx_get_data, ossl_lib_ctx_run_once, ossl_lib_ctx_onfree
#include "internal/cryptlib.h"
typedef struct ossl_lib_ctx_method {
int priority;
void *(*new_func)(OSSL_LIB_CTX *ctx);
void (*free_func)(void *);
} OSSL_LIB_CTX_METHOD;
@ -22,6 +24,8 @@ ossl_lib_ctx_get_data, ossl_lib_ctx_run_once, ossl_lib_ctx_onfree
ossl_lib_ctx_run_once_fn run_once_fn);
int ossl_lib_ctx_onfree(OSSL_LIB_CTX *ctx, ossl_lib_ctx_onfree_fn onfreefn);
int ossl_lib_ctx_is_child(OSSL_LIB_CTX *ctx);
=head1 DESCRIPTION
Internally, the OpenSSL library context B<OSSL_LIB_CTX> is implemented
@ -53,6 +57,9 @@ using ossl_lib_ctx_onfree. This associates an "on free" routine I<onfreefn> with
the library context I<ctx>. When I<ctx> is freed all associated "on free"
routines are called.
ossl_lib_ctx_is_child() returns 1 if this library context is a child and 0
otherwise.
=head1 RETURN VALUES
ossl_lib_ctx_get_data() returns a pointer on success, or NULL on
@ -86,8 +93,13 @@ and a destructor to an index.
/*
* Include a reference to this in the methods table in context.c
* OSSL_LIB_CTX_FOO_INDEX should be added to internal/cryptlib.h
* Priorities can be OSSL_LIB_CTX_METHOD_DEFAULT_PRIORITY,
* OSSL_LIB_CTX_METHOD_PRIORITY_1, OSSL_LIB_CTX_METHOD_PRIORITY_2, etc.
* Default priority is low (0). The higher the priority the earlier the
* method's destructor will be called when the library context is cleaned up.
*/
const OSSL_LIB_CTX_METHOD foo_method = {
OSSL_LIB_CTX_METHOD_DEFAULT_PRIORITY,
foo_new,
foo_free
};

53
doc/internal/man3/ossl_provider_new.pod
View File

@ -5,7 +5,10 @@
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_add_parameter, ossl_provider_set_child, ossl_provider_get_parent,
ossl_provider_up_ref_parent, ossl_provider_free_parent,
ossl_provider_get0_dispatch, ossl_provider_init_child_providers,
ossl_provider_init_as_child,
ossl_provider_activate, ossl_provider_deactivate, ossl_provider_available,
ossl_provider_ctx,
ossl_provider_doall_activated,
@ -37,11 +40,19 @@ ossl_provider_get_capabilities
int ossl_provider_add_parameter(OSSL_PROVIDER *prov, const char *name,
const char *value);
/* Child Providers */
int ossl_provider_set_child(OSSL_PROVIDER *prov,
const OSSL_CORE_HANDLE *handle);
const OSSL_CORE_HANDLE *ossl_provider_get_parent(OSSL_PROVIDER *prov);
int ossl_provider_up_ref_parent(OSSL_PROVIDER *prov, int activate);
int ossl_provider_free_parent(OSSL_PROVIDER *prov, int deactivate);
/*
* Activate the Provider
* If the Provider is a module, the module will be loaded
*/
int ossl_provider_activate(OSSL_PROVIDER *prov, int retain_fallbacks);
int ossl_provider_activate(OSSL_PROVIDER *prov, int retain_fallbacks,
int upcalls);
int ossl_provider_deactivate(OSSL_PROVIDER *prov);
/* Check if provider is available (activated) */
int ossl_provider_available(OSSL_PROVIDER *prov);
@ -49,6 +60,8 @@ ossl_provider_get_capabilities
/* Return pointer to the provider's context */
void *ossl_provider_ctx(const OSSL_PROVIDER *prov);
const OSSL_DISPATCH *ossl_provider_get0_dispatch(const OSSL_PROVIDER *prov);
/* Iterate over all loaded providers */
int ossl_provider_doall_activated(OSSL_LIB_CTX *,
int (*cb)(OSSL_PROVIDER *provider,
@ -82,6 +95,12 @@ ossl_provider_get_capabilities
int *result);
int ossl_provider_clear_all_operation_bits(OSSL_LIB_CTX *libctx);
int ossl_provider_init_child_providers(OSSL_LIB_CTX *ctx);
int ossl_provider_init_as_child(OSSL_LIB_CTX *ctx,
const OSSL_CORE_HANDLE *handle,
const OSSL_DISPATCH *in);
=head1 DESCRIPTION
I<OSSL_PROVIDER> is a type that holds all the necessary information
@ -162,6 +181,19 @@ 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_set_child() marks this provider as a child of a provider in the
parent library context. I<handle> is the B<OSSL_CORE_HANDLE> object passed to
the provider's B<OSSL_provider_init> function.
ossl_provider_get_parent() obtains the handle on the parent provider.
ossl_provider_up_ref_parent() increases the reference count on the parent
provider. If I<activate> is nonzero then the parent provider is also activated.
ossl_provider_free_parent() decreases the reference count on the parent
provider. If I<deactivate> is nonzero then the parent provider is also
deactivated.
ossl_provider_activate() "activates" the provider for the given
provider object I<prov> by incrementing its activation count, flagging
it as activated, and initializing it if it isn't already initialized.
@ -184,7 +216,9 @@ be located in that module, and called.
=back
If I<retain_fallbacks> is zero, fallbacks are disabled. If it is nonzero,
fallbacks are left unchanged.
fallbacks are left unchanged. If I<upcalls> is nonzero then, if this is a child
provider, upcalls to the parent libctx will be made to inform it of an
up-ref.
ossl_provider_deactivate() "deactivates" the provider for the given
provider object I<prov> by decrementing its activation count. When
@ -198,6 +232,10 @@ 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_get0_dispatch() returns the dispatch table that the provider
initially returned in the I<out> parameter of its B<OSSL_provider_init>
function.
ossl_provider_doall_activated() iterates over all the currently
"activated" providers, and calls I<cb> for each of them.
If no providers have been "activated" yet, it tries to activate all
@ -253,6 +291,15 @@ I<*result> to 1 or 0 accorddingly.
ossl_provider_clear_all_operation_bits() clears all of the operation bits
to (0) for all providers in the library context I<libctx>.
ossl_provider_init_child_providers() registers the callbacks required to
receive notifications about loading and unloading of providers in the parent
library context.
ossl_provider_init_as_child() stores in the library context I<ctx> references to
the necessary upcalls for managing child providers. The I<handle> and I<in>
parameters are the B<OSSL_CORE_HANDLE> and B<OSSL_DISPATCH> pointers that were
passed to the provider's B<OSSL_provider_init> function.
=head1 NOTES
Locating a provider module happens as follows:

44
doc/man3/OSSL_LIB_CTX.pod
View File

@ -3,8 +3,8 @@
=head1 NAME
OSSL_LIB_CTX, OSSL_LIB_CTX_new, OSSL_LIB_CTX_new_from_dispatch,
OSSL_LIB_CTX_free, OSSL_LIB_CTX_load_config, OSSL_LIB_CTX_get0_global_default,
OSSL_LIB_CTX_set0_default
OSSL_LIB_CTX_new_child, OSSL_LIB_CTX_free, OSSL_LIB_CTX_load_config,
OSSL_LIB_CTX_get0_global_default, OSSL_LIB_CTX_set0_default
- OpenSSL library context
=head1 SYNOPSIS
@ -16,6 +16,8 @@ OSSL_LIB_CTX_set0_default
OSSL_LIB_CTX *OSSL_LIB_CTX_new(void);
OSSL_LIB_CTX *OSSL_LIB_CTX_new_from_dispatch(const OSSL_CORE_HANDLE *handle,
const OSSL_DISPATCH *in);
OSSL_LIB_CTX *OSSL_LIB_CTX_new_child(const OSSL_CORE_HANDLE *handle,
const OSSL_DISPATCH *in);
int OSSL_LIB_CTX_load_config(OSSL_LIB_CTX *ctx, const char *config_file);
void OSSL_LIB_CTX_free(OSSL_LIB_CTX *ctx);
OSSL_LIB_CTX *OSSL_LIB_CTX_get0_global_default(void);
@ -43,6 +45,44 @@ OSSL_provider_init function. Some OpenSSL functions, such as
L<BIO_new_from_core_bio(3)>, require the library context to be created in this
way in order to work.
OSSL_LIB_CTX_new_child() is only useful to provider authors and does the same
thing as OSSL_LIB_CTX_new_from_dispatch() except that it additionally links the
new library context to the application library context. The new library context
is a full library context in its own right, but will have all the same providers
available to it that are available in the application library context (without
having to reload them). If the application loads or unloads providers from the
application library context then this will be automatically mirrored in the
child library context.
In addition providers that are not loaded in the parent library context can be
explicitly loaded into the child library context independently from the parent
library context. Providers loaded independently in this way will not be mirrored
in the parent library context and will not be affected if the parent library
context subsequently loads the same provider.
A provider may call the function L<OSSL_PROVIDER_load(3)> with the child library
context as required. If the provider already exists due to it being mirrored
from the parent library context then it will remain available and its reference
count will be increased. If L<OSSL_PROVIDER_load(3)> is called in this way then
L<OSSL_PROVIDER_unload(3)> should be subsequently called to decrement the
reference count. L<OSSL_PROVIDER_unload(3)> must not be called for a provider in
the child library context that did not have an earlier L<OSSL_PROVIDER_load(3)>
call for that provider in that child library context.
OSSL_LIB_CTX_new_child() must only be called from within the scope of a
provider's B<OSSL_provider_init> function (see L<provider-base(7)>). Calling it
outside of that function may succeed but may not correctly mirror all providers
and is considered undefined behaviour. When called from within the scope of a
provider's B<OSSL_provider_init> function the currently initialising provider is
not yet available in the application's library context and therefore will
similarly not yet be available in the newly constructed child library context.
As soon as the B<OSSL_provider_init> function returns then the new provider is
available in the application's library context and will be similarly mirrored in
the child library context. Since the current provider is still initialising
the provider should not attempt to perform fetches, or call any function that
performs a fetch using the child library context until after the initialisation
function has completed.
OSSL_LIB_CTX_load_config() loads a configuration file using the given C<ctx>.
This can be used to associate a library context with providers that are loaded
from a configuration.

10
doc/man3/OSSL_PROVIDER.pod
View File

@ -7,8 +7,9 @@ OSSL_PROVIDER, OSSL_PROVIDER_load, OSSL_PROVIDER_try_load, OSSL_PROVIDER_unload,
OSSL_PROVIDER_available, OSSL_PROVIDER_do_all,
OSSL_PROVIDER_gettable_params, OSSL_PROVIDER_get_params,
OSSL_PROVIDER_query_operation, OSSL_PROVIDER_unquery_operation,
OSSL_PROVIDER_get0_provider_ctx, OSSL_PROVIDER_add_builtin, OSSL_PROVIDER_name,
OSSL_PROVIDER_get_capabilities, OSSL_PROVIDER_self_test
OSSL_PROVIDER_get0_provider_ctx, OSSL_PROVIDER_get0_dispatch,
OSSL_PROVIDER_add_builtin, OSSL_PROVIDER_name, OSSL_PROVIDER_get_capabilities,
OSSL_PROVIDER_self_test
- provider routines
=head1 SYNOPSIS
@ -39,6 +40,7 @@ OSSL_PROVIDER_get_capabilities, OSSL_PROVIDER_self_test
int operation_id,
const OSSL_ALGORITHM *algs);
void *OSSL_PROVIDER_get0_provider_ctx(const OSSL_PROVIDER *prov);
const OSSL_DISPATCH *OSSL_PROVIDER_get0_dispatch(const OSSL_PROVIDER *prov);
int OSSL_PROVIDER_add_builtin(OSSL_LIB_CTX *libctx, const char *name,
ossl_provider_init_fn *init_fn);
@ -130,6 +132,10 @@ OSSL_PROVIDER_get0_provider_ctx() returns the provider context for the given
provider. The provider context is an opaque handle set by the provider itself
and is passed back to the provider by libcrypto in various function calls.
OSSL_PROVIDER_get0_dispatch() returns the provider's dispatch table as it was
returned in the I<out> parameter from the provider's init function. See
L<provider-base(7)>.
If it is permissible to cache references to this array then I<*no_store> is set
to 0 or 1 otherwise. If the array is not cacheable then it is assumed to
have a short lifetime.

54
doc/man7/provider-base.pod
View File

@ -80,6 +80,21 @@ provider-base
void cleanup_nonce(const OSSL_CORE_HANDLE *handle,
unsigned char *buf, size_t len);
/* Functions for querying the providers in the application library context */
int provider_register_child_cb(const OSSL_CORE_HANDLE *handle,
int (*create_cb)(const OSSL_CORE_HANDLE *provider,
void *cbdata),
int (*remove_cb)(const OSSL_CORE_HANDLE *provider,
void *cbdata),
void *cbdata);
void provider_deregister_child_cb(const OSSL_CORE_HANDLE *handle);
const char *provider_name(const OSSL_CORE_HANDLE *prov);
void *provider_get0_provider_ctx(const OSSL_CORE_HANDLE *prov);
const OSSL_DISPATCH *provider_get0_dispatch(const OSSL_CORE_HANDLE *prov);
int provider_up_ref(const OSSL_CORE_HANDLE *prov, int activate);
int provider_free(const OSSL_CORE_HANDLE *prov, int deactivate);
/* Functions offered by the provider to libcrypto */
void provider_teardown(void *provctx);
const OSSL_ITEM *provider_gettable_params(void *provctx);
@ -260,6 +275,45 @@ cleanup_nonce() is used to clean up and free the buffer returned by
get_nonce(). The nonce pointer returned by get_nonce() is passed in
B<buf> and its length in B<len>.
provider_register_child_cb() registers callbacks for being informed about the
loading and unloading of providers in the application's library context.
I<handle> is this provider's handle and I<cbdata> is this provider's data
that will be passed back to the callbacks. It returns 1 on success or 0
otherwise.
I<create_cb> is a callback that will be called when a new provider is loaded
into the application's library context. It is also called for any providers that
are already loaded at the point that this callback is registered. The callback
is passed the handle being used for the new provider being loadded and this
provider's data in I<cbdata>. It should return 1 on success or 0 on failure.
I<remove_cb> is a callback that will be called when a new provider is unloaded
from the application's library context. It is passed the handle being used for
the provider being unloaded and this provider's data in I<cbdata>. It should
return 1 on success or 0 on failure.
provider_deregister_child_cb() unregisters callbacks previously registered via
provider_register_child_cb(). If provider_register_child_cb() has been called
then provider_deregister_child_cb() should be called at or before the point that
this provider's teardown function is called.
provider_name() returns a string giving the name of the provider identified by
I<handle>.
provider_get0_provider_ctx() returns the provider context that is associated
with the provider identified by I<prov>.
provider_get0_dispatch() gets the dispatch table registered by the provider
identified by I<prov> when it initialised.
provider_up_ref() increments the reference count on the provider I<prov>. If
I<activate> is nonzero then the provider is also loaded if it is not already
loaded. It returns 1 on success or 0 on failure.
provider_free() decrements the reference count on the provider I<prov>. If
I<deactivate> is nonzero then the provider is also unloaded if it is not
already loaded. It returns 1 on success or 0 on failure.
=head2 Provider functions
provider_teardown() is called when a provider is shut down and removed