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