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