doc/internal/man3/ossl_provider_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 ossl_provider_find, ossl_provider_new, ossl_provider_up_ref,
   6 ossl_provider_free,
   7 ossl_provider_set_fallback, ossl_provider_set_module_path,
   8 ossl_provider_add_parameter,
   9 ossl_provider_activate, ossl_provider_available,
  10 ossl_provider_ctx,
  11 ossl_provider_forall_loaded,
  12 ossl_provider_name, ossl_provider_dso,
  13 ossl_provider_module_name, ossl_provider_module_path,
  14 ossl_provider_library_context,
  15 ossl_provider_teardown, ossl_provider_gettable_params,
  16 ossl_provider_get_params, ossl_provider_query_operation,
  17 ossl_provider_set_operation_bit, ossl_provider_test_operation_bit
  18 - internal provider routines
  19
  20 =head1 SYNOPSIS
  21
  22  #include "internal/provider.h"
  23
  24  OSSL_PROVIDER *ossl_provider_find(OPENSSL_CTX *libctx, const char *name,
  25                                    int noconfig);
  26  OSSL_PROVIDER *ossl_provider_new(OPENSSL_CTX *libctx, const char *name,
  27                                   ossl_provider_init_fn *init_function
  28                                   int noconfig);
  29  int ossl_provider_up_ref(OSSL_PROVIDER *prov);
  30  void ossl_provider_free(OSSL_PROVIDER *prov);
  31
  32  /* Setters */
  33  int ossl_provider_set_fallback(OSSL_PROVIDER *prov);
  34  int ossl_provider_set_module_path(OSSL_PROVIDER *prov, const char *path);
  35  int ossl_provider_add_parameter(OSSL_PROVIDER *prov, const char *name,
  36                                  const char *value);
  37
  38  /* Load and initialize the Provider */
  39  int ossl_provider_activate(OSSL_PROVIDER *prov);
  40  /* Check if provider is available */
  41  int ossl_provider_available(OSSL_PROVIDER *prov);
  42
  43  /* Return pointer to the provider's context */
  44  void *ossl_provider_ctx(const OSSL_PROVIDER *prov);
  45
  46  /* Iterate over all loaded providers */
  47  int ossl_provider_forall_loaded(OPENSSL_CTX *,
  48                                  int (*cb)(OSSL_PROVIDER *provider,
  49                                            void *cbdata),
  50                                  void *cbdata);
  51
  52  /* Getters for other library functions */
  53  const char *ossl_provider_name(OSSL_PROVIDER *prov);
  54  const DSO *ossl_provider_dso(OSSL_PROVIDER *prov);
  55  const char *ossl_provider_module_name(OSSL_PROVIDER *prov);
  56  const char *ossl_provider_module_path(OSSL_PROVIDER *prov);
  57  OPENSSL_CTX *ossl_provider_library_context(const OSSL_PROVIDER *prov);
  58
  59  /* Thin wrappers around calls to the provider */
  60  void ossl_provider_teardown(const OSSL_PROVIDER *prov);
  61  const OSSL_PARAM *ossl_provider_gettable_params(const OSSL_PROVIDER *prov);
  62  int ossl_provider_get_params(const OSSL_PROVIDER *prov, OSSL_PARAM params[]);
  63  const OSSL_ALGORITHM *ossl_provider_query_operation(const OSSL_PROVIDER *prov,
  64                                                      int operation_id,
  65                                                      int *no_cache);
  66
  67  int ossl_provider_set_operation_bit(OSSL_PROVIDER *provider, size_t bitnum);
  68  int ossl_provider_test_operation_bit(OSSL_PROVIDER *provider, size_t bitnum,
  69                                       int *result);
  70
  71 =head1 DESCRIPTION
  72
  73 I<OSSL_PROVIDER> is a type that holds all the necessary information
  74 to handle a provider, regardless of if it's built in to the
  75 application or the OpenSSL libraries, or if it's a loadable provider
  76 module.
  77 Instances of this type are commonly referred to as "provider objects".
  78
  79 A provider object is always stored in a set of provider objects
  80 in the library context.
  81
  82 Provider objects are reference counted.
  83
  84 Provider objects are initially inactive, i.e. they are only recorded
  85 in the store, but are not used.
  86 They are activated with the first call to ossl_provider_activate(),
  87 and are inactivated when ossl_provider_free() has been called as many
  88 times as ossl_provider_activate() has.
  89
  90 =head2 Functions
  91
  92 ossl_provider_find() finds an existing provider object in the provider
  93 object store by I<name>.
  94 The config file will be automatically loaded unless I<noconfig> is set.
  95 Typically I<noconfig> should be 0.
  96 We set I<noconfig> to 1 only when calling these functions while processing a
  97 config file in order to avoid recursively attempting to load the file.
  98 The provider object it finds has its reference count incremented.
  99
 100 ossl_provider_new() creates a new provider object named I<name> and
 101 stores it in the provider object store, unless there already is one
 102 there with the same name.
 103 If there already is one with the same name, it's returned with its
 104 reference count incremented.
 105 The config file will be automatically loaded unless I<noconfig> is set.
 106 Typically I<noconfig> should be 0.
 107 We set I<noconfig> to 1 only when calling these functions while processing a
 108 config file in order to avoid recursively attempting to load the file.
 109 The reference count of a newly created provider object will always
 110 be 2; one for being added to the store, and one for the returned
 111 reference.
 112 If I<init_function> is NULL, the provider is assumed to be a
 113 dynamically loadable module, with the symbol B<OSSL_provider_init> as
 114 its initialisation function.
 115 If I<init_function> isn't NULL, the provider is assumed to be built
 116 in, with I<init_function> being the pointer to its initialisation
 117 function.
 118 For further description of the initialisation function, see the
 119 description of ossl_provider_activate() below.
 120
 121 ossl_provider_up_ref() increments the provider object I<prov>'s
 122 reference count.
 123
 124 ossl_provider_free() decrements the provider object I<prov>'s
 125 reference count; if it drops below 2, the provider object is assumed
 126 to have fallen out of use and will be deactivated (its I<teardown>
 127 function is called); if it drops down to zero, I<prov> is assumed to
 128 have been taken out of the store, and the associated module will be
 129 unloaded if one was loaded, and I<prov> itself will be freed.
 130
 131 ossl_provider_set_fallback() marks an available provider I<prov> as
 132 fallback.
 133 Note that after this call, the provider object pointer that was
 134 used can simply be dropped, but not freed.
 135
 136 ossl_provider_set_module_path() sets the module path to load the
 137 provider module given the provider object I<prov>.
 138 This will be used in preference to automatically trying to figure out
 139 the path from the provider name and the default module directory (more
 140 on this in L</NOTES>).
 141
 142 ossl_provider_library_context() returns the library context the given
 143 provider I<prov> is registered in.
 144
 145 ossl_provider_add_parameter() adds a global parameter for the provider
 146 to retrieve as it sees fit.
 147 The parameters are a combination of I<name> and I<value>, and the
 148 provider will use the name to find the value it wants.
 149 Only text parameters can be given, and it's up to the provider to
 150 interpret them.
 151
 152 ossl_provider_activate() "activates" the provider for the given
 153 provider object I<prov>.
 154 What "activates" means depends on what type of provider object it
 155 is:
 156
 157 =over 4
 158
 159 =item *
 160
 161 If an initialization function was given with ossl_provider_new(), that
 162 function will get called.
 163
 164 =item *
 165
 166 If no initialization function was given with ossl_provider_new(), a
 167 loadable module with the I<name> that was given to ossl_provider_new()
 168 will be located and loaded, then the symbol B<OSSL_provider_init> will
 169 be located in that module, and called.
 170
 171 =back
 172
 173 ossl_provider_available() activates all fallbacks if no provider is
 174 activated yet, then checks if given provider object I<prov> is
 175 activated.
 176
 177 ossl_provider_ctx() returns a context created by the provider.
 178 Outside of the provider, it's completely opaque, but it needs to be
 179 passed back to some of the provider functions.
 180
 181 ossl_provider_forall_loaded() iterates over all the currently
 182 "activated" providers, and calls I<cb> for each of them.
 183 If no providers have been "activated" yet, it tries to activate all
 184 available fallback providers and tries another iteration.
 185
 186 ossl_provider_name() returns the name that was given with
 187 ossl_provider_new().
 188
 189 ossl_provider_dso() returns a reference to the module, for providers
 190 that come in the form of loadable modules.
 191
 192 ossl_provider_module_name() returns the filename of the module, for
 193 providers that come in the form of loadable modules.
 194
 195 ossl_provider_module_path() returns the full path of the module file,
 196 for providers that come in the form of loadable modules.
 197
 198 ossl_provider_teardown() calls the provider's I<teardown> function, if
 199 the provider has one.
 200
 201 ossl_provider_gettable_params() calls the provider's I<gettable_params>
 202 function, if the provider has one.
 203 It should return an array of I<OSSL_PARAM> to describe all the
 204 parameters that the provider has for the provider object.
 205
 206 ossl_provider_get_params() calls the provider's parameter request
 207 responder.
 208 It should treat the given I<OSSL_PARAM> array as described in
 209 L<OSSL_PARAM(3)>.
 210
 211 ossl_provider_query_operation() calls the provider's
 212 I<query_operation> function, if the provider has one.
 213 It should return an array of I<OSSL_ALGORITHM> for the given
 214 I<operation_id>.
 215
 216 ossl_provider_set_operation_bit() registers a 1 for operation I<bitnum>
 217 in a bitstring that's internal to I<provider>.
 218
 219 ossl_provider_tests_operation_bit() checks if the bit operation I<bitnum>
 220 is set (1) or not (0) in the internal I<provider> bitstring, and sets
 221 I<*result> to 1 or 0 accorddingly.
 222
 223 =head1 NOTES
 224
 225 Locating a provider module happens as follows:
 226
 227 =over 4
 228
 229 =item 1.
 230
 231 If a path was given with ossl_provider_set_module_path(), use that as
 232 module path.
 233 Otherwise, use the provider object's name as module path, with
 234 platform specific standard extensions added.
 235
 236 =item 2.
 237
 238 If the environment variable B<OPENSSL_MODULES> is defined, assume its
 239 value is a directory specification and merge it with the module path.
 240 Otherwise, merge the value of the OpenSSL built in macro B<MODULESDIR>
 241 with the module path.
 242
 243 =back
 244
 245 When this process is done, the result is used when trying to load the
 246 provider module.
 247
 248 The command C<openssl version -m> can be used to find out the value
 249 of the built in macro B<MODULESDIR>.
 250
 251 =head1 RETURN VALUES
 252
 253 ossl_provider_find() and ossl_provider_new() return a pointer to a
 254 provider object (I<OSSL_PROVIDER>) on success, or NULL on error.
 255
 256 ossl_provider_up_ref() returns the value of the reference count after
 257 it has been incremented.
 258
 259 ossl_provider_free() doesn't return any value.
 260
 261 ossl_provider_set_module_path(), ossl_provider_set_fallback() and
 262 ossl_provider_activate() return 1 on success, or 0 on error.
 263
 264 ossl_provider_available() return 1 if the provider is available,
 265 otherwise 0.
 266
 267 ossl_provider_name(), ossl_provider_dso(),
 268 ossl_provider_module_name(), and ossl_provider_module_path() return a
 269 pointer to their respective data if it's available, otherwise NULL
 270 is returned.
 271
 272 ossl_provider_library_context() return a pointer to the library context.
 273 This may be NULL, and is perfectly valid, as it denotes the default
 274 global library context.
 275
 276 ossl_provider_teardown() doesn't return any value.
 277
 278 ossl_provider_gettable_params() returns a pointer to a constant
 279 I<OSSL_PARAM> array if this function is available in the provider,
 280 otherwise NULL.
 281
 282 ossl_provider_get_params() returns 1 on success, or 0 on error.
 283 If this function isn't available in the provider, 0 is returned.
 284
 285 ossl_provider_set_operation_bit() and ossl_provider_test_operation_bit()
 286 return 1 on success, or 0 on error.
 287
 288 =head1 SEE ALSO
 289
 290 L<OSSL_PROVIDER(3)>, L<provider(7)>, L<openssl(1)>
 291
 292 =head1 HISTORY
 293
 294 The functions described here were all added in OpenSSL 3.0.
 295
 296 =head1 COPYRIGHT
 297
 298 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 299
 300 Licensed under the Apache License 2.0 (the "License").  You may not use
 301 this file except in compliance with the License.  You can obtain a copy
 302 in the file LICENSE in the source distribution or at
 303 L<https://www.openssl.org/source/license.html>.
 304
 305 =cut