doc/internal/man3/ossl_method_construct.pod

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