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