2e49c05472
We didn't deal very well with names that didn't have pre-defined NIDs, as the NID zero travelled through the full process and resulted in an inaccessible method. By consequence, we need to refactor the method construction callbacks to rely more on algorithm names. We must, however, still store the legacy NID with the method, for the sake of other code that depend on it (for example, CMS). Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/8878)
148 lines
4.8 KiB
Text
148 lines
4.8 KiB
Text
=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)(OPENSSL_CTX *ctx);
|
|
/* 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 *name,
|
|
const char *propquery, void *data);
|
|
/* Store a method in a store */
|
|
int (*put)(OPENSSL_CTX *libctx, void *store, void *method,
|
|
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);
|
|
/* 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()).
|
|
|
|
This function assumes that the sub-system method creator implements
|
|
reference counting and acts accordingly (i.e. it will call the
|
|
sub-system destruct() method to decrement the reference count when
|
|
appropriate).
|
|
|
|
=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 in the scope of the library context C<ctx>.
|
|
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 by name.
|
|
|
|
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 the given C<name> and
|
|
data from C<data>
|
|
(which is the C<mcm_data> that was passed to ossl_construct_method())
|
|
and the provided property query C<propquery>.
|
|
|
|
This function is expected to increment the method's reference count.
|
|
|
|
=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 C<name> and property definition
|
|
C<propdef> as well as any identification data given through C<data> (which is
|
|
the C<mcm_data> that was passed to ossl_construct_method()).
|
|
|
|
This function is expected to increment the C<method>'s reference count.
|
|
|
|
=item construct()
|
|
|
|
Constructs a sub-system method for the given C<name> and the given
|
|
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().
|
|
|
|
This function is expected to set the method's reference count to 1.
|
|
|
|
=item desctruct()
|
|
|
|
Decrement the C<method>'s reference count, and destruct it when
|
|
the reference count reaches zero.
|
|
|
|
=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.
|
|
|
|
=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
|