diff options
Diffstat (limited to 'doc/internal/man3/evp_generic_fetch.pod')
| -rw-r--r-- | doc/internal/man3/evp_generic_fetch.pod | 49 |
1 files changed, 37 insertions, 12 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: |