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