diff options
author | Richard Levitte <levitte@openssl.org> | 2019-09-14 16:22:19 +0200 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2019-09-19 14:58:17 +0200 |
commit | f7c16d48a945e80f22f6f02550ee3fe14edb52fa (patch) | |
tree | b6ec900293f5a14213aa1836c916ea4e11f7c260 /doc | |
parent | f8c0218f09e190a2efb28302f6c9737efe151d27 (diff) |
In provider implemented methods, save the name number, not the name string
Multiple names per implementation is already supported in the namemap,
but hasn't been used yet. However, as soon as we have multiple names,
we will get an issue with what name should be saved in the method.
The solution is to not save the name itself, but rather the number
it's associated with. This number is supposed to be unique for each
set of names, and we assume that algorithm names are globally unique,
i.e. there can be no name overlap between different algorithm types.
Incidently, it was also found that the 'get' function used by
ossl_construct_method() doesn't need all the parameters it was given;
most of what it needs, it can now get through the data structure given
by the caller of ossl_construct_method(). As a consequence,
ossl_construct_method() itself doesn't need all the parameters it was
given either.
There are some added internal functions that are expected to disappear
as soon as legacy code is removed, such as evp_first_name() and
ossl_namemap_num2name().
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9897)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/internal/man3/evp_generic_fetch.pod | 49 | ||||
-rw-r--r-- | doc/internal/man3/ossl_method_construct.pod | 26 |
2 files changed, 48 insertions, 27 deletions
diff --git a/doc/internal/man3/evp_generic_fetch.pod b/doc/internal/man3/evp_generic_fetch.pod index b77391e386..6fe7bccba3 100644 --- a/doc/internal/man3/evp_generic_fetch.pod +++ b/doc/internal/man3/evp_generic_fetch.pod @@ -2,7 +2,8 @@ =head1 NAME -evp_generic_fetch - generic algorithm fetcher and method creator for EVP +evp_generic_fetch, evp_generic_fetch_by_number +- generic algorithm fetchers and method creators for EVP =head1 SYNOPSIS @@ -11,7 +12,7 @@ evp_generic_fetch - generic algorithm fetcher and method creator for EVP void *evp_generic_fetch(OPENSSL_CTX *libctx, int operation_id, const char *name, const char *properties, - void *(*new_method)(const char *name, + void *(*new_method)(int name_id, const OSSL_DISPATCH *fns, OSSL_PROVIDER *prov, void *method_data), @@ -19,23 +20,42 @@ evp_generic_fetch - generic algorithm fetcher and method creator for EVP int (*up_ref_method)(void *), void (*free_method)(void *)); + void *evp_generic_fetch_by_number(OPENSSL_CTX *ctx, int operation_id, + int name_id, const char *properties, + void *(*new_method)(int name_id, + const OSSL_DISPATCH *fns, + OSSL_PROVIDER *prov, + void *method_data), + void *method_data, + int (*up_ref_method)(void *), + void (*free_method)(void *)); + =head1 DESCRIPTION evp_generic_fetch() calls ossl_method_construct() with the given -C<libctx>, C<operation_id>, C<name>, and C<properties> and uses +I<libctx>, I<operation_id>, I<name>, and I<properties> and uses it to create an EVP method with the help of the functions -C<new_method>, C<up_ref_method>, and C<free_method>. +I<new_method>, I<up_ref_method>, and I<free_method>. + +evp_generic_fetch_by_number() does the same thing as evp_generic_fetch(), +but takes a I<name_id> instead of a number. +I<name_id> must always be non-zero; as a matter of fact, it being zero +is considered a programming error. +This is meant to be used when one method needs to fetch an associated +other method, and is typically called from inside the given function +I<new_method>. -The three functions are supposed to: +The three functions I<new_method>, I<up_ref_method>, and +I<free_method> are supposed to: =over 4 =item new_method() creates an internal method from function pointers found in the -dispatch table C<fns>. -The algorithm I<name>, provider I<prov>, and I<method_data> are -also passed to be used as new_method() sees fit. +dispatch table I<fns>, with name identity I<name_id>. +The provider I<prov> and I<method_data> are also passed to be used as +new_method() sees fit. =item up_ref_method() @@ -55,10 +75,10 @@ evp_generic_fetch() returns a method on success, or B<NULL> on error. =head1 EXAMPLES This is a short example of the fictitious EVP API and operation called -C<EVP_FOO>. +B<EVP_FOO>. To begin with, let's assume something like this in -C<include/openssl/core_numbers.h>: +F<include/openssl/core_numbers.h>: #define OSSL_OP_FOO 100 @@ -80,6 +100,7 @@ And here's the implementation of the FOO method fetcher: /* typedef struct evp_foo_st EVP_FOO */ struct evp_foo_st { OSSL_PROVIDER *prov; + int name_id; CRYPTO_REF_COUNT refcnt; OSSL_OP_foo_newctx_fn *newctx; OSSL_OP_foo_init_fn *init; @@ -92,14 +113,18 @@ And here's the implementation of the FOO method fetcher: * In this example, we have a public method creator and destructor. * It's not absolutely necessary, but is in the spirit of OpenSSL. */ - EVP_FOO *EVP_FOO_meth_from_dispatch(const OSSL_DISPATCH *fns, - OSSL_PROVIDER *prov) + EVP_FOO *EVP_FOO_meth_from_dispatch(int name_id, + const OSSL_DISPATCH *fns, + OSSL_PROVIDER *prov, + void *data) { EVP_FOO *foo = NULL; if ((foo = OPENSSL_zalloc(sizeof(*foo))) == NULL) return NULL; + foo->name_id = name_id; + for (; fns->function_id != 0; fns++) { switch (fns->function_id) { case OSSL_OP_FOO_NEWCTX_FUNC: diff --git a/doc/internal/man3/ossl_method_construct.pod b/doc/internal/man3/ossl_method_construct.pod index 9beb7942f0..a25ca4cd8c 100644 --- a/doc/internal/man3/ossl_method_construct.pod +++ b/doc/internal/man3/ossl_method_construct.pod @@ -15,13 +15,11 @@ OSSL_METHOD_CONSTRUCT_METHOD, ossl_method_construct /* Remove a store */ void (*dealloc_tmp_store)(void *store); /* Get an already existing method from a store */ - void *(*get)(OPENSSL_CTX *libctx, void *store, - int operation_id, const char *name, const char *propquery, - void *data); + void *(*get)(OPENSSL_CTX *libctx, void *store, void *data); /* Store a method in a store */ int (*put)(OPENSSL_CTX *libctx, void *store, void *method, - int operation_id, const char *name, const char *propdef, - void *data); + const OSSL_PROVIDER *prov, int operation_id, const char *name, + const char *propdef, void *data); /* Construct a new method */ void *(*construct)(const char *name, const OSSL_DISPATCH *fns, OSSL_PROVIDER *prov, void *data); @@ -31,7 +29,6 @@ OSSL_METHOD_CONSTRUCT_METHOD, ossl_method_construct typedef struct ossl_method_construct_method OSSL_METHOD_CONSTRUCT_METHOD; void *ossl_method_construct(OPENSSL_CTX *ctx, int operation_id, - const char *name, const char *properties, int force_cache, OSSL_METHOD_CONSTRUCT_METHOD *mcm, void *mcm_data); @@ -58,11 +55,10 @@ It's important to keep in mind that a method is identified by three things: =head2 Functions ossl_method_construct() creates a method by asking all available -providers for a dispatch table given an I<operation_id>, an algorithm -I<name> and a set of I<properties>, and then calling the appropriate -functions given by the sub-system specific method creator through -I<mcm> and the data in I<mcm_data> (which is passed by -ossl_method_construct()). +providers for a dispatch table given an I<operation_id>, and then +calling the appropriate functions given by the sub-system specific +method creator through I<mcm> and the data in I<mcm_data> (which is +passed by ossl_method_construct()). This function assumes that the sub-system method creator implements reference counting and acts accordingly (i.e. it will call the @@ -98,10 +94,10 @@ B<NULL> is a valid value and means that a sub-system default store must be used. This default store should be stored in the library context I<libctx>. -The method to be looked up should be identified with the given -I<operation_id>, I<name>, the provided property query I<propquery> -and data from I<data> (which is the I<mcm_data> that was passed to -ossl_construct_method()). +The method to be looked up should be identified with data found in I<data> +(which is the I<mcm_data> that was passed to ossl_construct_method()). +In other words, the ossl_method_construct() caller is entirely responsible +for ensuring the necesssary data is made available. This function is expected to increment the method's reference count. |