doc/internal/man3/ossl_provider_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 ossl_provider_find, ossl_provider_new, ossl_provider_upref,
   6 ossl_provider_free, ossl_provider_add_module_location,
   7 ossl_provider_activate, ossl_provider_name, ossl_provider_dso,
   8 ossl_provider_module_name, ossl_provider_module_path,
   9 ossl_provider_teardown, ossl_provider_get_param_types,
  10 ossl_provider_get_params - internal provider routines
  11
  12 =head1 SYNOPSIS
  13
  14  #include "internal/provider.h"
  15
  16  OSSL_PROVIDER *ossl_provider_find(OPENSSL_CTX *libctx, const char *name);
  17  OSSL_PROVIDER *ossl_provider_new(OPENSSL_CTX *libctx, const char *name,
  18                                   ossl_provider_init_fn *init_function);
  19  int ossl_provider_upref(OSSL_PROVIDER *prov);
  20  void ossl_provider_free(OSSL_PROVIDER *prov);
  21
  22  /* Setters */
  23  int ossl_provider_add_module_location(OSSL_PROVIDER *prov, const char *loc);
  24
  25  /* Load and initialize the Provider */
  26  int ossl_provider_activate(OSSL_PROVIDER *prov);
  27
  28  /* Getters for other library functions */
  29  const char *ossl_provider_name(OSSL_PROVIDER *prov);
  30  const DSO *ossl_provider_dso(OSSL_PROVIDER *prov);
  31  const char *ossl_provider_module_name(OSSL_PROVIDER *prov);
  32  const char *ossl_provider_module_path(OSSL_PROVIDER *prov);
  33
  34  /* Thin wrappers around calls to the provider */
  35  void ossl_provider_teardown(const OSSL_PROVIDER *prov);
  36  const OSSL_ITEM *ossl_provider_get_param_types(const OSSL_PROVIDER *prov);
  37  int ossl_provider_get_params(const OSSL_PROVIDER *prov,
  38                               const OSSL_PARAM params[]);
  39
  40 =head1 DESCRIPTION
  41
  42 C<OSSL_PROVIDER> is a type that holds all the necessary information
  43 to handle a provider, regardless of if it's built in to the
  44 application or the OpenSSL libraries, or if it's a loadable provider
  45 module.
  46 Instances of this type are commonly refered to as I<provider object>s.
  47
  48 A I<provider object> is always stored in a set of I<provider object>s
  49 in the library context.
  50
  51 I<provider object>s are reference counted.
  52
  53 I<provider object>s are initially inactive, i.e. they are only
  54 recorded in the store, but are not used.
  55 They are activated with the first call to ossl_provider_activate(),
  56 and are inactivated when ossl_provider_free() has been called as many
  57 times as ossl_provider_activate() has.
  58
  59 =head2 Functions
  60
  61 ossl_provider_find() finds an existing I<provider object> in the
  62 I<provider object> store by C<name>.
  63 The I<provider object> it finds gets it's reference count
  64 incremented.
  65
  66 ossl_provider_new() creates a new I<provider object> and stores it in
  67 the I<provider object> store, unless there already is one there with
  68 the same name.
  69 The reference counter of a newly created I<provider object> will
  70 always be 2; one for being added to the store, and one for the
  71 returned reference.
  72 To indicate a built-in provider, the C<init_function> argument must
  73 point at the provider initialization function for that provider.
  74
  75 ossl_provider_free() decrements a I<provider object>'s reference
  76 counter; if it drops to one, the I<provider object> will be
  77 inactivated (it's teardown function is called) but kept in the store;
  78 if it drops down to zero, the associated module will be unloaded if
  79 one was loaded, and the I<provider object> will be freed.
  80
  81 ossl_provider_add_module_location() adds a location to look for a
  82 provider module.
  83
  84 ossl_provider_activate() "activates" the provider for the given
  85 I<provider object>.
  86 What "activates" means depends on what type of I<provider object> it
  87 is:
  88
  89 =over 4
  90
  91 =item *
  92
  93 If an initialization function was given with ossl_provider_new(), that
  94 function will get called.
  95
  96 =item *
  97
  98 If no intialization function was given with ossl_provider_new(), a
  99 loadable module with the C<name> that was given to ossl_provider_new()
 100 will be located and loaded, then the symbol C<OSSL_provider_init> will
 101 be located in that module, and called.
 102
 103 =back
 104
 105 ossl_provider_name() returns the name that was given with
 106 ossl_provider_new().
 107
 108 ossl_provider_dso() returns a reference to the module, for providers
 109 that come in the form of loadable modules.
 110
 111 ossl_provider_module_name() returns the file name of the module, for
 112 providers that come in the form of loadable modules.
 113
 114 ossl_provider_module_path() returns the full path of the module file,
 115 for providers that come in the form of loadable modules.
 116
 117 ossl_provider_teardown() calls the provider's C<teardown> function, if
 118 the provider has one.
 119
 120 ossl_provider_get_param_types() calls the provider's C<get_param_types>
 121 function, if the provider has one.
 122 It should return an array of C<OSSL_ITEM> to describe all the
 123 parameters that the provider has for the I<provider object>.
 124
 125 ossl_provider_get_params() calls the provider's parameter request
 126 responder.
 127 It should treat the given C<OSSL_PARAM> array as described in
 128 L<OSSL_PARAM(3)>.
 129
 130 =head1 NOTES
 131
 132 Locating a provider module happens as follows:
 133
 134 =over 4
 135
 136 =item 1.
 137
 138 Look in each directory given by ossl_provider_add_module_location().
 139
 140 =item 2.
 141
 142 Look in the directory given by the environment variable
 143 B<OPENSSL_MODULES>.
 144
 145 =item 3.
 146
 147 Look in the directory given by the OpenSSL built in macro
 148 B<MODULESDIR>.
 149
 150 =back
 151
 152 =head1 RETURN VALUES
 153
 154 ossl_provider_find() and ossl_provider_new() return a pointer to a
 155 I<provider object> (C<OSSL_PROVIDER>) on success, or B<NULL> on error.
 156
 157 ossl_provider_upref() returns the value of the reference counter after
 158 it has been incremented.
 159
 160 ossl_provider_free() doesn't return any value.
 161
 162 ossl_provider_add_module_location() and ossl_provider_activate()
 163 return 1 on success, or 0 on error.
 164
 165 ossl_provider_name(), ossl_provider_dso(),
 166 ossl_provider_module_name(), and ossl_provider_module_path() return a
 167 pointer to their respective data if it's available, otherwise B<NULL>
 168 is returned.
 169
 170 ossl_provider_teardown() doesnt't return any value.
 171
 172 ossl_provider_get_param_types() returns a pointer to an C<OSSL_ITEM>
 173 array if this function is available in the provider, otherwise
 174 B<NULL>.
 175
 176 ossl_provider_get_params() returns 1 on success, or 0 on error.
 177 If this function isn't available in the provider, 0 is returned.
 178
 179 =head1 SEE ALSO
 180
 181 L<OSSL_PROVIDER(3)>, L<provider(7)>
 182
 183 =head1 HISTORY
 184
 185 The functions described here were all added in OpenSSL 3.0.
 186
 187 =head1 COPYRIGHT
 188
 189 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 190
 191 Licensed under the Apache License 2.0 (the "License").  You may not use
 192 this file except in compliance with the License.  You can obtain a copy
 193 in the file LICENSE in the source distribution or at
 194 L<https://www.openssl.org/source/license.html>.
 195
 196 =cut