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