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