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