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