diff options
author | Matt Caswell <matt@openssl.org> | 2021-05-05 14:43:19 +0100 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2021-05-11 15:03:13 +0100 |
commit | 878be71c2d284d1fc4d591fdbbfb14eed63da10f (patch) | |
tree | 03a6de8d4324f7f7c593699c131d585406ec0f48 /doc/internal | |
parent | fb9b3a7bce236c96d8db37e52db83997b4cb18db (diff) |
Update documentation following addition of OSSL_LIB_CTX_new_child()
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14991)
Diffstat (limited to 'doc/internal')
-rw-r--r-- | doc/internal/man3/ossl_lib_ctx_get_data.pod | 14 | ||||
-rw-r--r-- | doc/internal/man3/ossl_provider_new.pod | 53 |
2 files changed, 63 insertions, 4 deletions
diff --git a/doc/internal/man3/ossl_lib_ctx_get_data.pod b/doc/internal/man3/ossl_lib_ctx_get_data.pod index b79e93d848..6b80aa011e 100644 --- a/doc/internal/man3/ossl_lib_ctx_get_data.pod +++ b/doc/internal/man3/ossl_lib_ctx_get_data.pod @@ -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 }; diff --git a/doc/internal/man3/ossl_provider_new.pod b/doc/internal/man3/ossl_provider_new.pod index e83869a9de..ff347bad3f 100644 --- a/doc/internal/man3/ossl_provider_new.pod +++ b/doc/internal/man3/ossl_provider_new.pod @@ -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: |