1=pod 2 3=head1 NAME 4 5OSSL_METHOD_CONSTRUCT_METHOD, ossl_method_construct 6- generic method constructor 7 8=head1 SYNOPSIS 9 10 #include "internal/core.h" 11 12 struct ossl_method_construct_method_st { 13 /* Get a temporary store */ 14 void *(*get_tmp_store)(void *data); 15 /* Get an already existing method from a store */ 16 void *(*get)(void *store, const OSSL_PROVIDER *prov, void *data); 17 /* Store a method in a store */ 18 int (*put)(void *store, void *method, const OSSL_PROVIDER *prov, 19 const char *name, const char *propdef, void *data); 20 /* Construct a new method */ 21 void *(*construct)(const OSSL_ALGORITHM *algodef, OSSL_PROVIDER *prov, 22 void *data); 23 /* Destruct a method */ 24 void (*destruct)(void *method, void *data); 25 }; 26 typedef struct ossl_method_construct_method OSSL_METHOD_CONSTRUCT_METHOD; 27 28 void *ossl_method_construct(OSSL_LIB_CTX *ctx, int operation_id, 29 OSSL_PROVIDER *prov, int force_cache, 30 OSSL_METHOD_CONSTRUCT_METHOD *mcm, void *mcm_data); 31 32 33=head1 DESCRIPTION 34 35All libcrypto subsystems that want to create their own methods based 36on provider dispatch tables need to do so in exactly the same way. 37ossl_method_construct() does this while leaving it to the subsystems 38to define more precisely how the methods are created, stored, etc. 39 40It's important to keep in mind that a method is identified by three things: 41 42=over 4 43 44=item The operation identity 45 46=item The name of the algorithm 47 48=item The properties associated with the algorithm implementation 49 50=back 51 52=head2 Functions 53 54ossl_method_construct() creates a method by asking all available 55providers for a dispatch table given an I<operation_id>, and then 56calling the appropriate functions given by the subsystem specific 57method creator through I<mcm> and the data in I<mcm_data> (which is 58passed by ossl_method_construct()). 59If I<prov> is not NULL, only that provider is considered, which is 60useful in the case a method must be found in that particular 61provider. 62 63This function assumes that the subsystem method creator implements 64reference counting and acts accordingly (i.e. it will call the 65subsystem destruct() method to decrement the reference count when 66appropriate). 67 68=head2 Structures 69 70A central part of constructing a subsystem specific method is to give 71ossl_method_construct a set of functions, all in the 72B<OSSL_METHOD_CONSTRUCT_METHOD> structure, which holds the following 73function pointers: 74 75=over 4 76 77=item get_tmp_store() 78 79Create a temporary method store in the scope of the library context I<ctx>. 80This store is used to temporarily store methods for easier lookup, for 81when the provider doesn't want its dispatch table stored in a longer 82term cache. 83 84=item get() 85 86Look up an already existing method from a store by name. 87 88The store may be given with I<store>. 89NULL is a valid value and means that a subsystem default store 90must be used. 91This default store should be stored in the library context I<libctx>. 92 93The method to be looked up should be identified with data found in I<data> 94(which is the I<mcm_data> that was passed to ossl_construct_method()). 95In other words, the ossl_method_construct() caller is entirely responsible 96for ensuring the necesssary data is made available. 97 98Optionally, I<prov> may be given as a search criterion, to narrow down the 99search of a method belonging to just one provider. 100 101This function is expected to increment the resulting method's reference count. 102 103=item put() 104 105Places the I<method> created by the construct() function (see below) 106in a store. 107 108The store may be given with I<store>. 109NULL is a valid value and means that a subsystem default store 110must be used. 111This default store should be stored in the library context I<libctx>. 112 113The method should be associated with the given provider I<prov>, 114I<name> and property definition I<propdef> as well as any 115identification data given through I<data> (which is the I<mcm_data> 116that was passed to ossl_construct_method()). 117 118This function is expected to increment the I<method>'s reference count. 119 120=item construct() 121 122Constructs a subsystem method for the given I<name> and the given 123dispatch table I<fns>. 124 125The associated provider object I<prov> is passed as well, to make 126it possible for the subsystem constructor to keep a reference, which 127is recommended. 128If such a reference is kept, the I<provider object> reference counter 129must be incremented, using ossl_provider_up_ref(). 130 131This function is expected to set the method's reference count to 1. 132 133=item destruct() 134 135Decrement the I<method>'s reference count, and destruct it when 136the reference count reaches zero. 137 138=back 139 140=head1 RETURN VALUES 141 142ossl_method_construct() returns a constructed method on success, or 143NULL on error. 144 145=head1 HISTORY 146 147This functionality was added to OpenSSL 3.0. 148 149=head1 COPYRIGHT 150 151Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. 152 153Licensed under the Apache License 2.0 (the "License"). You may not use this 154file except in compliance with the License. You can obtain a copy in the file 155LICENSE in the source distribution or at 156L<https://www.openssl.org/source/license.html>. 157 158=cut 159