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