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