mirror of
https://github.com/QuasarApp/openssl.git
synced 2025-05-02 20:49:39 +00:00
9e11fe0d85
This queries the provider for its available functionality (unless a matching method structured is already cached, in which case that's used instead), and creates method structure with the help of a passed constructor. The result is cached if the provider allows it (or if caching is forced). Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/8340)
134 lines
4.1 KiB
Plaintext
134 lines
4.1 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
OSSL_METHOD_CONSTRUCT_METHOD, ossl_method_construct
|
|
- generic method constructor
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include "internal/core.h"
|
|
|
|
struct ossl_method_construct_method_st {
|
|
/* Create store */
|
|
void *(*alloc_tmp_store)(void);
|
|
/* Remove a store */
|
|
void (*dealloc_tmp_store)(void *store);
|
|
/* Get an already existing method from a store */
|
|
void *(*get)(OPENSSL_CTX *libctx, void *store, const char *propquery,
|
|
void *data);
|
|
/* Store a method in a store */
|
|
int (*put)(OPENSSL_CTX *libctx, void *store, const char *propdef,
|
|
void *method, void *data);
|
|
/* Construct a new method */
|
|
void *(*construct)(const OSSL_DISPATCH *fns, OSSL_PROVIDER *prov,
|
|
void *data);
|
|
/* Destruct a method */
|
|
void (*destruct)(void *method);
|
|
};
|
|
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);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
All libcrypto sub-systems that want to create their own methods based
|
|
on provider dispatch tables need to do so in exactly the same way.
|
|
ossl_method_construct() does this while leaving it to the sub-systems
|
|
to define more precisely how the methods are created, stored, etc.
|
|
|
|
=head2 Functions
|
|
|
|
ossl_method_construct() creates a method by asking all available
|
|
providers for a dispatch table given an C<operation_id>, an algorithm
|
|
C<name> and a set of C<properties>, and then calling appropriate
|
|
functions given by the sub-system specific method creator through
|
|
C<mcm> and the data in C<mcm_data> (which is passed by
|
|
ossl_method_construct()).
|
|
|
|
=head2 Structures
|
|
|
|
A central part of constructing a sub-system specific method is to give
|
|
ossl_method_construct a set of functions, all in the
|
|
C<OSSL_METHOD_CONSTRUCT_METHOD> structure, which holds the following
|
|
function pointers:
|
|
|
|
=over 4
|
|
|
|
=item alloc_tmp_store()
|
|
|
|
Create a temporary method store.
|
|
This store is used to temporarily store methods for easier lookup, for
|
|
when the provider doesn't want its dispatch table stored in a longer
|
|
term cache.
|
|
|
|
=item dealloc_tmp_store()
|
|
|
|
Remove a temporary store.
|
|
|
|
=item get()
|
|
|
|
Look up an already existing method from a store.
|
|
|
|
The store may be given with C<store>.
|
|
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 C<libctx>.
|
|
|
|
The method to be looked up should be identified with data from C<data>
|
|
(which is the C<mcm_data> that was passed to ossl_construct_method())
|
|
and the provided property query C<propquery>.
|
|
|
|
=item put()
|
|
|
|
Places the C<method> created by the construct() function (see below)
|
|
in a store.
|
|
|
|
The store may be given with C<store>.
|
|
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 C<libctx>.
|
|
|
|
The method should be associated with the given property definition
|
|
C<propdef> and any identification data given through C<data> (which is
|
|
the C<mcm_data> that was passed to ossl_construct_method()).
|
|
|
|
=item construct()
|
|
|
|
Constructs a sub-system method given a dispatch table C<fns>.
|
|
|
|
The associated I<provider object> C<prov> is passed as well, to make
|
|
it possible for the sub-system constructor to keep a reference, which
|
|
is recommended.
|
|
If such a reference is kept, the I<provider object> reference counter
|
|
must be incremented, using ossl_provider_upref().
|
|
|
|
=item desctruct()
|
|
|
|
Destruct the given C<method>.
|
|
|
|
=back
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
ossl_method_construct() returns a constructed method on success, or
|
|
B<NULL> on error.
|
|
|
|
=head1 HISTORY
|
|
|
|
This functionality was added to OpenSSL 3.0.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<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|