doc/man7/provider-base.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 provider-base
   6 - The basic OpenSSL library E<lt>-E<gt> provider functions
   7
   8 =head1 SYNOPSIS
   9
  10  #include <openssl/core_numbers.h>
  11
  12  /*
  13   * None of these are actual functions, but are displayed like this for
  14   * the function signatures for functions that are offered as function
  15   * pointers in OSSL_DISPATCH arrays.
  16   */
  17
  18  /* Functions offered by libcrypto to the providers */
  19  const OSSL_ITEM *core_gettable_params(const OSSL_PROVIDER *prov);
  20  int core_get_params(const OSSL_PROVIDER *prov, OSSL_PARAM params[]);
  21  int core_thread_start(const OSSL_PROVIDER *prov,
  22                        OSSL_thread_stop_handler_fn handfn);
  23  OPENSSL_CTX *core_get_library_context(const OSSL_PROVIDER *prov);
  24  void core_new_error(const OSSL_PROVIDER *prov);
  25  void core_set_error_debug(const OSSL_PROVIDER *prov,
  26                            const char *file, int line, const char *func);
  27  void core_vset_error(const OSSL_PROVIDER *prov,
  28                       uint32_t reason, const char *fmt, va_list args);
  29
  30  /*
  31   * Some OpenSSL functionality is directly offered to providers via
  32   * dispatch
  33   */
  34  void *CRYPTO_malloc(size_t num, const char *file, int line);
  35  void *CRYPTO_zalloc(size_t num, const char *file, int line);
  36  void *CRYPTO_memdup(const void *str, size_t siz,
  37                      const char *file, int line);
  38  char *CRYPTO_strdup(const char *str, const char *file, int line);
  39  char *CRYPTO_strndup(const char *str, size_t s,
  40                       const char *file, int line);
  41  void CRYPTO_free(void *ptr, const char *file, int line);
  42  void CRYPTO_clear_free(void *ptr, size_t num,
  43                         const char *file, int line);
  44  void *CRYPTO_realloc(void *addr, size_t num,
  45                       const char *file, int line);
  46  void *CRYPTO_clear_realloc(void *addr, size_t old_num, size_t num,
  47                             const char *file, int line);
  48  void *CRYPTO_secure_malloc(size_t num, const char *file, int line);
  49  void *CRYPTO_secure_zalloc(size_t num, const char *file, int line);
  50  void CRYPTO_secure_free(void *ptr, const char *file, int line);
  51  void CRYPTO_secure_clear_free(void *ptr, size_t num,
  52                                const char *file, int line);
  53  int CRYPTO_secure_allocated(const void *ptr);
  54  void OPENSSL_cleanse(void *ptr, size_t len);
  55  unsigned char *OPENSSL_hexstr2buf(const char *str, long *len);
  56
  57  /* Functions offered by the provider to libcrypto */
  58  void provider_teardown(void *provctx);
  59  const OSSL_ITEM *provider_gettable_params(void *provctx);
  60  int provider_get_params(void *provctx, OSSL_PARAM params[]);
  61  const OSSL_ALGORITHM *provider_query_operation(void *provctx,
  62                                                 int operation_id,
  63                                                 const int *no_store);
  64  const OSSL_ITEM *provider_get_reason_strings(void *provctx);
  65
  66 =head1 DESCRIPTION
  67
  68 All "functions" mentioned here are passed as function pointers between
  69 F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays, in the call
  70 of the provider initialization function.  See L<provider(7)/Provider>
  71 for a description of the initialization function.
  72
  73 All these "functions" have a corresponding function type definition
  74 named B<OSSL_{name}_fn>, and a helper function to retrieve the
  75 function pointer from a B<OSSL_DISPATCH> element named
  76 B<OSSL_get_{name}>.
  77 For example, the "function" core_gettable_params() has these:
  78
  79  typedef OSSL_ITEM *
  80      (OSSL_core_gettable_params_fn)(const OSSL_PROVIDER *prov);
  81  static ossl_inline OSSL_NAME_core_gettable_params_fn
  82      OSSL_get_core_gettable_params(const OSSL_DISPATCH *opf);
  83
  84 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
  85 macros in L<openssl-core_numbers.h(7)>, as follows:
  86
  87 For I<in> (the B<OSSL_DISPATCH> array passed from F<libcrypto> to the
  88 provider):
  89
  90  core_gettable_params           OSSL_FUNC_CORE_GETTABLE_PARAMS
  91  core_get_params                OSSL_FUNC_CORE_GET_PARAMS
  92  core_thread_start              OSSL_FUNC_CORE_THREAD_START
  93  core_get_library_context       OSSL_FUNC_CORE_GET_LIBRARY_CONTEXT
  94  core_new_error                 OSSL_FUNC_CORE_NEW_ERROR
  95  core_set_error_debug           OSSL_FUNC_CORE_SET_ERROR_DEBUG
  96  core_set_error                 OSSL_FUNC_CORE_SET_ERROR
  97  CRYPTO_malloc                  OSSL_FUNC_CRYPTO_MALLOC
  98  CRYPTO_zalloc                  OSSL_FUNC_CRYPTO_ZALLOC
  99  CRYPTO_memdup                  OSSL_FUNC_CRYPTO_MEMDUP
 100  CRYPTO_strdup                  OSSL_FUNC_CRYPTO_STRDUP
 101  CRYPTO_strndup                 OSSL_FUNC_CRYPTO_STRNDUP
 102  CRYPTO_free                    OSSL_FUNC_CRYPTO_FREE
 103  CRYPTO_clear_free              OSSL_FUNC_CRYPTO_CLEAR_FREE
 104  CRYPTO_realloc                 OSSL_FUNC_CRYPTO_REALLOC
 105  CRYPTO_clear_realloc           OSSL_FUNC_CRYPTO_CLEAR_REALLOC
 106  CRYPTO_secure_malloc           OSSL_FUNC_CRYPTO_SECURE_MALLOC
 107  CRYPTO_secure_zalloc           OSSL_FUNC_CRYPTO_SECURE_ZALLOC
 108  CRYPTO_secure_free             OSSL_FUNC_CRYPTO_SECURE_FREE
 109  CRYPTO_secure_clear_free       OSSL_FUNC_CRYPTO_SECURE_CLEAR_FREE
 110  CRYPTO_secure_allocated        OSSL_FUNC_CRYPTO_SECURE_ALLOCATED
 111  BIO_new_file                   OSSL_FUNC_BIO_NEW_FILE
 112  BIO_new_mem_buf                OSSL_FUNC_BIO_NEW_MEMBUF
 113  BIO_read_ex                    OSSL_FUNC_BIO_READ_EX
 114  BIO_free                       OSSL_FUNC_BIO_FREE
 115  OPENSSL_cleanse                OSSL_FUNC_OPENSSL_CLEANSE
 116  OPENSSL_hexstr2buf             OSSL_FUNC_OPENSSL_HEXSTR2BUF
 117
 118 For I<*out> (the B<OSSL_DISPATCH> array passed from the provider to
 119 F<libcrypto>):
 120
 121  provider_teardown              OSSL_FUNC_PROVIDER_TEARDOWN
 122  provider_gettable_params       OSSL_FUNC_PROVIDER_GETTABLE_PARAMS
 123  provider_get_params            OSSL_FUNC_PROVIDER_GET_PARAMS
 124  provider_query_operation       OSSL_FUNC_PROVIDER_QUERY_OPERATION
 125  provider_get_reason_strings    OSSL_FUNC_PROVIDER_GET_REASON_STRINGS
 126
 127 =head2 Core functions
 128
 129 core_gettable_params() returns a constant array of descriptor
 130 B<OSSL_PARAM>, for parameters that core_get_params() can handle.
 131
 132 core_get_params() retrieves I<prov> parameters from the core.
 133 See L</Core parameters> below for a description of currently known
 134 parameters.
 135
 136 =for comment core_thread_start() TBA
 137
 138 core_get_library_context() retrieves the library context in which the
 139 B<OSSL_PROVIDER> object I<prov> is stored.
 140 This may sometimes be useful if the provider wishes to store a
 141 reference to its context in the same library context.
 142
 143 core_new_error(), core_set_error_debug() and core_set_error() are
 144 building blocks for reporting an error back to the core, with
 145 reference to the provider object I<prov>.
 146
 147 =over 4
 148
 149 =item core_new_error()
 150
 151 allocates a new thread specific error record.
 152
 153 This corresponds to the OpenSSL function L<ERR_new(3)>.
 154
 155 =item core_set_error_debug()
 156
 157 sets debugging information in the current thread specific error
 158 record.
 159 The debugging information includes the name of the file I<file>, the
 160 line I<line> and the function name I<func> where the error occured.
 161
 162 This corresponds to the OpenSSL function L<ERR_set_debug(3)>.
 163
 164 =item core_set_error()
 165
 166 sets the I<reason> for the error, along with any addition data.
 167 The I<reason> is a number defined by the provider and used to index
 168 the reason strings table that's returned by
 169 provider_get_reason_strings().
 170 The additional data is given as a format string I<fmt> and a set of
 171 arguments I<args>, which are treated in the same manner as with
 172 BIO_vsnprintf().
 173 I<file> and I<line> may also be passed to indicate exactly where the
 174 error occured or was reported.
 175
 176 This corresponds to the OpenSSL function L<ERR_vset_error(3)>.
 177
 178 =back
 179
 180 CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_memdup(), CRYPTO_strdup(),
 181 CRYPTO_strndup(), CRYPTO_free(), CRYPTO_clear_free(),
 182 CRYPTO_realloc(), CRYPTO_clear_realloc(), CRYPTO_secure_malloc(),
 183 CRYPTO_secure_zalloc(), CRYPTO_secure_free(),
 184 CRYPTO_secure_clear_free(), CRYPTO_secure_allocated(),
 185 BIO_new_file(), BIO_new_mem_buf(), BIO_read_ex(), BIO_free(),
 186 OPENSSL_cleanse(), and OPENSSL_hexstr2buf() correspond exactly to the
 187 public functions with the same name.
 188 As a matter of fact, the pointers in the B<OSSL_DISPATCH> array are
 189 direct pointers to those public functions.
 190
 191 =head2 Provider functions
 192
 193 provider_teardown() is called when a provider is shut down and removed
 194 from the core's provider store.
 195 It must free the passed I<provctx>.
 196
 197 provider_gettable_params() should return a constant array of
 198 descriptor B<OSSL_PARAM>, for parameters that provider_get_params()
 199 can handle.
 200
 201 provider_get_params() should process the B<OSSL_PARAM> array
 202 I<params>, setting the values of the parameters it understands.
 203
 204 provider_query_operation() should return a constant B<OSSL_ALGORITHM>
 205 that corresponds to the given I<operation_id>.
 206 It should indicate if the core may store a reference to this array by
 207 setting I<*no_store> to 0 (core may store a reference) or 1 (core may
 208 not store a reference).
 209
 210 provider_get_reason_strings() should return a constant B<OSSL_ITEM>
 211 array that provides reason strings for reason codes the provider may
 212 use when reporting errors using core_put_error().
 213
 214 None of these functions are mandatory, but a provider is fairly
 215 useless without at least provider_query_operation(), and
 216 provider_gettable_params() is fairly useless if not accompanied by
 217 provider_get_params().
 218
 219 =head2 Core parameters
 220
 221 core_get_params() understands the following known parameters:
 222
 223 =over 4
 224
 225 =item "openssl-version"
 226
 227 This is a B<OSSL_PARAM_UTF8_PTR> type of parameter, pointing at the
 228 OpenSSL libraries' full version string, i.e. the string expanded from
 229 the macro B<OPENSSL_VERSION_STR>.
 230
 231 =item "provider-name"
 232
 233 This is a B<OSSL_PARAM_UTF8_PTR> type of parameter, pointing at the
 234 OpenSSL libraries' idea of what the calling provider is called.
 235
 236 =back
 237
 238 Additionally, provider specific configuration parameters from the
 239 config file are available, in dotted name form.
 240 The dotted name form is a concatenation of section names and final
 241 config command name separated by periods.
 242
 243 For example, let's say we have the following config example:
 244
 245  openssl_conf = openssl_init
 246
 247  [openssl_init]
 248  providers = providers_sect
 249
 250  [providers_sect]
 251  foo = foo_sect
 252
 253  [foo_sect]
 254  activate = 1
 255  data1 = 2
 256  data2 = str
 257  more = foo_more
 258
 259  [foo_more]
 260  data3 = foo,bar
 261
 262 The provider will have these additional parameters available:
 263
 264 =over 4
 265
 266 =item "activate"
 267
 268 pointing at the string "1"
 269
 270 =item "data1"
 271
 272 pointing at the string "2"
 273
 274 =item "data2"
 275
 276 pointing at the string "str"
 277
 278 =item "more.data3"
 279
 280 pointing at the string "foo,bar"
 281
 282 =back
 283
 284 For more information on handling parameters, see L<OSSL_PARAM(3)> as
 285 L<OSSL_PARAM_int(3)>.
 286
 287 =head1 EXAMPLES
 288
 289 This is an example of a simple provider made available as a
 290 dynamically loadable module.
 291 It implements the fictitious algorithm C<FOO> for the fictitious
 292 operation C<BAR>.
 293
 294  #include <malloc.h>
 295  #include <openssl/core.h>
 296  #include <openssl/core_numbers.h>
 297
 298  /* Errors used in this provider */
 299  #define E_MALLOC       1
 300
 301  static const OSSL_ITEM reasons[] = {
 302      { E_MALLOC, "memory allocation failure" }.
 303      { 0, NULL } /* Termination */
 304  };
 305
 306  /*
 307   * To ensure we get the function signature right, forward declare
 308   * them using function types provided by openssl/core_numbers.h
 309   */
 310  OSSL_OP_bar_newctx_fn foo_newctx;
 311  OSSL_OP_bar_freectx_fn foo_freectx;
 312  OSSL_OP_bar_init_fn foo_init;
 313  OSSL_OP_bar_update_fn foo_update;
 314  OSSL_OP_bar_final_fn foo_final;
 315
 316  OSSL_provider_query_operation_fn p_query;
 317  OSSL_provider_get_reason_strings_fn p_reasons;
 318  OSSL_provider_teardown_fn p_teardown;
 319
 320  OSSL_provider_init_fn OSSL_provider_init;
 321
 322  OSSL_core_put_error *c_put_error = NULL;
 323
 324  /* Provider context */
 325  struct prov_ctx_st {
 326      OSSL_PROVIDER *prov;
 327  }
 328
 329  /* operation context for the algorithm FOO */
 330  struct foo_ctx_st {
 331      struct prov_ctx_st *provctx;
 332      int b;
 333  };
 334
 335  static void *foo_newctx(void *provctx)
 336  {
 337      struct foo_ctx_st *fooctx = malloc(sizeof(*fooctx));
 338
 339      if (fooctx != NULL)
 340          fooctx->provctx = provctx;
 341      else
 342          c_put_error(provctx->prov, E_MALLOC, __FILE__, __LINE__);
 343      return fooctx;
 344  }
 345
 346  static void foo_freectx(void *fooctx)
 347  {
 348      free(fooctx);
 349  }
 350
 351  static int foo_init(void *vfooctx)
 352  {
 353      struct foo_ctx_st *fooctx = vfooctx;
 354
 355      fooctx->b = 0x33;
 356  }
 357
 358  static int foo_update(void *vfooctx, unsigned char *in, size_t inl)
 359  {
 360      struct foo_ctx_st *fooctx = vfooctx;
 361
 362      /* did you expect something serious? */
 363      if (inl == 0)
 364          return 1;
 365      for (; inl-- > 0; in++)
 366          *in ^= fooctx->b;
 367      return 1;
 368  }
 369
 370  static int foo_final(void *vfooctx)
 371  {
 372      struct foo_ctx_st *fooctx = vfooctx;
 373
 374      fooctx->b = 0x66;
 375  }
 376
 377  static const OSSL_DISPATCH foo_fns[] = {
 378      { OSSL_FUNC_BAR_NEWCTX, (void (*)(void))foo_newctx },
 379      { OSSL_FUNC_BAR_FREECTX, (void (*)(void))foo_freectx },
 380      { OSSL_FUNC_BAR_INIT, (void (*)(void))foo_init },
 381      { OSSL_FUNC_BAR_UPDATE, (void (*)(void))foo_update },
 382      { OSSL_FUNC_BAR_FINAL, (void (*)(void))foo_final },
 383      { 0, NULL }
 384  };
 385
 386  static const OSSL_ALGORITHM bars[] = {
 387      { "FOO", "provider=chumbawamba", foo_fns },
 388      { NULL, NULL, NULL }
 389  };
 390
 391  static const OSSL_ALGORITHM *p_query(void *provctx, int operation_id,
 392                                       int *no_store)
 393  {
 394      switch (operation_id) {
 395      case OSSL_OP_BAR:
 396          return bars;
 397      }
 398      return NULL;
 399  }
 400
 401  static const OSSL_ITEM *p_reasons(void *provctx)
 402  {
 403      return reasons;
 404  }
 405
 406  static void p_teardown(void *provctx)
 407  {
 408      free(provctx);
 409  }
 410
 411  static const OSSL_DISPATCH prov_fns[] = {
 412      { OSSL_FUNC_PROVIDER_TEARDOWN, (void (*)(void))p_teardown },
 413      { OSSL_FUNC_PROVIDER_QUERY_OPERATION, (void (*)(void))p_query },
 414      { OSSL_FUNC_PROVIDER_GET_REASON_STRINGS, (void (*)(void))p_reasons },
 415      { 0, NULL }
 416  };
 417
 418  int OSSL_provider_init(const OSSL_PROVIDER *provider,
 419                         const OSSL_DISPATCH *in,
 420                         const OSSL_DISPATCH **out,
 421                         void **provctx)
 422  {
 423      struct prov_ctx_st *pctx = NULL;
 424
 425      for (; in->function_id != 0; in++)
 426          switch (in->function_id) {
 427          case OSSL_FUNC_CORE_PUT_ERROR:
 428              c_put_error = OSSL_get_core_put_error(in);
 429              break;
 430          }
 431
 432      *out = prov_fns;
 433
 434      if ((pctx = malloc(sizeof(*pctx))) == NULL) {
 435          /*
 436           * ALEA IACTA EST, if the core retrieves the reason table
 437           * regardless, that string will be displayed, otherwise not.
 438           */
 439          c_put_error(provider, E_MALLOC, __FILE__, __LINE__);
 440          return 0;
 441      }
 442      return 1;
 443  }
 444
 445 This relies on a few things existing in F<openssl/core_numbers.h>:
 446
 447  #define OSSL_OP_BAR            4711
 448
 449  #define OSSL_FUNC_BAR_NEWCTX      1
 450  typedef void *(OSSL_OP_bar_newctx_fn)(void *provctx);
 451  static ossl_inline OSSL_get_bar_newctx(const OSSL_DISPATCH *opf)
 452  { return (OSSL_OP_bar_newctx_fn *)opf->function; }
 453
 454  #define OSSL_FUNC_BAR_FREECTX     2
 455  typedef void (OSSL_OP_bar_freectx_fn)(void *ctx);
 456  static ossl_inline OSSL_get_bar_newctx(const OSSL_DISPATCH *opf)
 457  { return (OSSL_OP_bar_freectx_fn *)opf->function; }
 458
 459  #define OSSL_FUNC_BAR_INIT        3
 460  typedef void *(OSSL_OP_bar_init_fn)(void *ctx);
 461  static ossl_inline OSSL_get_bar_init(const OSSL_DISPATCH *opf)
 462  { return (OSSL_OP_bar_init_fn *)opf->function; }
 463
 464  #define OSSL_FUNC_BAR_UPDATE      4
 465  typedef void *(OSSL_OP_bar_update_fn)(void *ctx,
 466                                        unsigned char *in, size_t inl);
 467  static ossl_inline OSSL_get_bar_update(const OSSL_DISPATCH *opf)
 468  { return (OSSL_OP_bar_update_fn *)opf->function; }
 469
 470  #define OSSL_FUNC_BAR_FINAL       5
 471  typedef void *(OSSL_OP_bar_final_fn)(void *ctx);
 472  static ossl_inline OSSL_get_bar_final(const OSSL_DISPATCH *opf)
 473  { return (OSSL_OP_bar_final_fn *)opf->function; }
 474
 475 =head1 SEE ALSO
 476
 477 L<provider(7)>
 478
 479 =head1 HISTORY
 480
 481 The concept of providers and everything surrounding them was
 482 introduced in OpenSSL 3.0.
 483
 484 =head1 COPYRIGHT
 485
 486 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 487
 488 Licensed under the Apache License 2.0 (the "License").  You may not use
 489 this file except in compliance with the License.  You can obtain a copy
 490 in the file LICENSE in the source distribution or at
 491 L<https://www.openssl.org/source/license.html>.
 492
 493 =cut