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