doc/internal/man3/ossl_provider_new.pod

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