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