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 =head2 Structures
  53
  54 A central part of constructing a sub-system specific method is to give
  55 ossl_method_construct a set of functions, all in the
  56 C<OSSL_METHOD_CONSTRUCT_METHOD> structure, which holds the following
  57 function pointers:
  58
  59 =over 4
  60
  61 =item alloc_tmp_store()
  62
  63 Create a temporary method store.
  64 This store is used to temporarily store methods for easier lookup, for
  65 when the provider doesn't want its dispatch table stored in a longer
  66 term cache.
  67
  68 =item dealloc_tmp_store()
  69
  70 Remove a temporary store.
  71
  72 =item get()
  73
  74 Look up an already existing method from a store.
  75
  76 The store may be given with C<store>.
  77 B<NULL> is a valid value and means that a sub-system default store
  78 must be used.
  79 This default store should be stored in the library context C<libctx>.
  80
  81 The method to be looked up should be identified with data from C<data>
  82 (which is the C<mcm_data> that was passed to ossl_construct_method())
  83 and the provided property query C<propquery>.
  84
  85 =item put()
  86
  87 Places the C<method> created by the construct() function (see below)
  88 in a store.
  89
  90 The store may be given with C<store>.
  91 B<NULL> is a valid value and means that a sub-system default store
  92 must be used.
  93 This default store should be stored in the library context C<libctx>.
  94
  95 The method should be associated with the given property definition
  96 C<propdef> and any identification data given through C<data> (which is
  97 the C<mcm_data> that was passed to ossl_construct_method()).
  98
  99 =item construct()
 100
 101 Constructs a sub-system method given a dispatch table C<fns>.
 102
 103 The associated I<provider object> C<prov> is passed as well, to make
 104 it possible for the sub-system constructor to keep a reference, which
 105 is recommended.
 106 If such a reference is kept, the I<provider object> reference counter
 107 must be incremented, using ossl_provider_upref().
 108
 109 =item desctruct()
 110
 111 Destruct the given C<method>.
 112
 113 =back
 114
 115 =head1 RETURN VALUES
 116
 117 ossl_method_construct() returns a constructed method on success, or
 118 B<NULL> on error.
 119
 120 =head1 HISTORY
 121
 122 This functionality was added to OpenSSL 3.0.0.
 123
 124 =head1 COPYRIGHT
 125
 126 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 127
 128 Licensed under the Apache License 2.0 (the "License").  You may not use this
 129 file except in compliance with the License.  You can obtain a copy in the file
 130 LICENSE in the source distribution or at
 131 L<https://www.openssl.org/source/license.html>.
 132
 133 =cut