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