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