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