From c453283421299b7f8e0db6d6069c68369294a9f7 Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Thu, 21 Feb 2019 21:20:53 +0100 Subject: [PATCH] Add documentation Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/openssl/pull/8287) --- doc/internal/man3/ossl_provider_new.pod | 196 ++++++++++++++++++++++++ doc/man3/OSSL_PROVIDER.pod | 112 ++++++++++++++ util/private.num | 1 + 3 files changed, 309 insertions(+) create mode 100644 doc/internal/man3/ossl_provider_new.pod create mode 100644 doc/man3/OSSL_PROVIDER.pod 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 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 Is. + +A I is always stored in a set of Is +in the library context. + +Is are reference counted. + +Is 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 in the +I store by C. +The I it finds gets it's reference count +incremented. + +ossl_provider_new() creates a new I and stores it in +the I store, unless there already is one there with +the same name. +The reference counter of a newly created I 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 argument must +point at the provider initialization function for that provider. + +ossl_provider_free() decrements a I's reference +counter; if it drops to one, the I 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 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. +What "activates" means depends on what type of I 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 that was given to ossl_provider_new() +will be located and loaded, then the symbol C 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 function, if +the provider has one. + +ossl_provider_get_param_types() calls the provider's C +function, if the provider has one. +It should return an array of C to describe all the +parameters that the provider has for the I. + +ossl_provider_get_params() calls the provider's parameter request +responder. +It should treat the given C array as described in +L. + +=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. + +=item 3. + +Look in the directory given by the OpenSSL built in macro +B. + +=back + +=head1 RETURN VALUES + +ossl_provider_find() and ossl_provider_new() return a pointer to a +I (C) on success, or B 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 +is returned. + +ossl_provider_teardown() doesnt't return any value. + +ossl_provider_get_param_types() returns a pointer to an C +array if this function is available in the provider, otherwise +B. + +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, L + +=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. + +=cut diff --git a/doc/man3/OSSL_PROVIDER.pod b/doc/man3/OSSL_PROVIDER.pod new file mode 100644 index 0000000000..e3653663b2 --- /dev/null +++ b/doc/man3/OSSL_PROVIDER.pod @@ -0,0 +1,112 @@ +=pod + +=head1 NAME + +OSSL_PROVIDER, OSSL_PROVIDER_load, OSSL_PROVIDER_unload, +OSSL_PROVIDER_get_param_types, OSSL_PROVIDER_get_params, +OSSL_PROVIDER_add_builtin - provider routines + +=head1 SYNOPSIS + + #include + + typedef struct ossl_provider_st OSSL_PROVIDER; + + OSSL_PROVIDER *OSSL_PROVIDER_load(OPENSSL_CTX *, const char *name); + int OSSL_PROVIDER_unload(OSSL_PROVIDER *prov); + + const OSSL_ITEM *OSSL_PROVIDER_get_param_types(OSSL_PROVIDER *prov); + int OSSL_PROVIDER_get_params(OSSL_PROVIDER *prov, const OSSL_PARAM params[]); + + int OSSL_PROVIDER_add_builtin(OPENSSL_CTX *, const char *name, + ossl_provider_init_fn *init_fn); + +=head1 DESCRIPTION + +B is a type that holds internal information about +implementation providers (see L for information on what a +provider is). +A provider can be built in to the application or the OpenSSL +libraries, or can be a loadable module. +The functions described here handle both forms. + +=head2 Functions + +OSSL_PROVIDER_add_builtin() is used to add a built in provider to +B store in the given library context, by associating a +provider name with a provider initialization function. +This name can then be used with OSSL_PROVIDER_load(). + +OSSL_PROVIDER_load() loads and initializes a provider. +This may simply initialize a provider that was previously added with +OSSL_PROVIDER_add_builtin() and run its given initialization function, +or load a provider module with the given name and run its provider +entry point, C. + +OSSL_PROVIDER_unload() unloads the given provider. +For a provider added with OSSL_PROVIDER_add_builtin(), this simply +runs its teardown function. + +OSSL_PROVIDER_get_param_types() is used to get a provider parameter +descriptor set as an B array. +Each element is a tuple of an B parameter type and a name +in form of a C string. +See L for more information on B and +parameter types. + +OSSL_PROVIDER_get_params() is used to get provider parameter values. +The caller must prepare the B array before calling this +function, and the variables acting as buffers for this parameter array +should be filled with data when it returns successfully. + +=head1 RETURN VALUES + +OSSL_PROVIDER_add() returns 1 on success, or 0 on error. + +OSSL_PROVIDER_load() returns a pointer to a provider object on +success, or B on error. + +OSSL_PROVIDER_unload() returns 1 on success, or 0 on error. + +OSSL_PROVIDER_get_param_types() returns a pointer to a constant array +of B, or NULL if none is provided. + +OSSL_PROVIDER_get_params() returns 1 on success, or 0 on error. + +=head1 EXAMPLES + +This demonstrates how to load the provider module "foo" and ask for +its build number. + + OSSL_PROVIDER *prov = NULL; + const char *build = NULL; + size_t built_l = 0; + const OSSL_PARAM request[] = { + { "build", OSSL_PARAM_UTF8_STRING_PTR, &build, 0, &build_l }, + { NULL, 0, NULL, 0, NULL } + }; + + if ((prov = OSSL_PROVIDER_load(NULL, "foo")) != NULL + && OSSL_PROVIDER_get_params(prov, request)) + printf("Provider 'foo' build %s\n", build); + else + ERR_print_errors_fp(stderr); + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +The type and functions described here were 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. + +=cut diff --git a/util/private.num b/util/private.num index ad1865f049..cb1997a005 100644 --- a/util/private.num +++ b/util/private.num @@ -33,6 +33,7 @@ OPENSSL_Applink external OPENSSL_CTX datatype NAMING_AUTHORITY datatype OSSL_PARAM datatype +OSSL_PROVIDER datatype OSSL_STORE_CTX datatype OSSL_STORE_INFO datatype OSSL_STORE_LOADER datatype -- 2.25.1