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