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_dispatch.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_libctx(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  size_t get_entropy(const OSSL_CORE_HANDLE *handle,
  69                     unsigned char **pout, int entropy,
  70                     size_t min_len, size_t max_len)
  71  void cleanup_entropy(const OSSL_CORE_HANDLE *handle,
  72                       unsigned char *buf, size_t len)
  73  size_t get_nonce(const OSSL_CORE_HANDLE *handle,
  74                   unsigned char **pout, size_t min_len, size_t max_len,
  75                   const void *salt, size_t salt_len)
  76  void cleanup_nonce(const OSSL_CORE_HANDLE *handle,
  77                     unsigned char *buf, size_t len)
  78
  79  /* Functions offered by the provider to libcrypto */
  80  void provider_teardown(void *provctx);
  81  const OSSL_ITEM *provider_gettable_params(void *provctx);
  82  int provider_get_params(void *provctx, OSSL_PARAM params[]);
  83  const OSSL_ALGORITHM *provider_query_operation(void *provctx,
  84                                                 int operation_id,
  85                                                 const int *no_store);
  86  const OSSL_ITEM *provider_get_reason_strings(void *provctx);
  87  int provider_get_capabilities(void *provctx, const char *capability,
  88                                OSSL_CALLBACK *cb, void *arg);
  89
  90 =head1 DESCRIPTION
  91
  92 All "functions" mentioned here are passed as function pointers between
  93 F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays, in the call
  94 of the provider initialization function.  See L<provider(7)/Provider>
  95 for a description of the initialization function.
  96
  97 All these "functions" have a corresponding function type definition
  98 named B<OSSL_{name}_fn>, and a helper function to retrieve the
  99 function pointer from a B<OSSL_DISPATCH> element named
 100 B<OSSL_FUNC_{name}>.
 101 For example, the "function" core_gettable_params() has these:
 102
 103  typedef OSSL_PARAM *
 104      (OSSL_FUNC_core_gettable_params_fn)(const OSSL_CORE_HANDLE *handle);
 105  static ossl_inline OSSL_NAME_core_gettable_params_fn
 106      OSSL_FUNC_core_gettable_params(const OSSL_DISPATCH *opf);
 107
 108 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
 109 macros in L<openssl-core_dispatch.h(7)>, as follows:
 110
 111 For I<in> (the B<OSSL_DISPATCH> array passed from F<libcrypto> to the
 112 provider):
 113
 114  core_gettable_params           OSSL_FUNC_CORE_GETTABLE_PARAMS
 115  core_get_params                OSSL_FUNC_CORE_GET_PARAMS
 116  core_thread_start              OSSL_FUNC_CORE_THREAD_START
 117  core_get_libctx                OSSL_FUNC_CORE_GET_LIBCTX
 118  core_new_error                 OSSL_FUNC_CORE_NEW_ERROR
 119  core_set_error_debug           OSSL_FUNC_CORE_SET_ERROR_DEBUG
 120  core_set_error                 OSSL_FUNC_CORE_SET_ERROR
 121  CRYPTO_malloc                  OSSL_FUNC_CRYPTO_MALLOC
 122  CRYPTO_zalloc                  OSSL_FUNC_CRYPTO_ZALLOC
 123  CRYPTO_memdup                  OSSL_FUNC_CRYPTO_MEMDUP
 124  CRYPTO_strdup                  OSSL_FUNC_CRYPTO_STRDUP
 125  CRYPTO_strndup                 OSSL_FUNC_CRYPTO_STRNDUP
 126  CRYPTO_free                    OSSL_FUNC_CRYPTO_FREE
 127  CRYPTO_clear_free              OSSL_FUNC_CRYPTO_CLEAR_FREE
 128  CRYPTO_realloc                 OSSL_FUNC_CRYPTO_REALLOC
 129  CRYPTO_clear_realloc           OSSL_FUNC_CRYPTO_CLEAR_REALLOC
 130  CRYPTO_secure_malloc           OSSL_FUNC_CRYPTO_SECURE_MALLOC
 131  CRYPTO_secure_zalloc           OSSL_FUNC_CRYPTO_SECURE_ZALLOC
 132  CRYPTO_secure_free             OSSL_FUNC_CRYPTO_SECURE_FREE
 133  CRYPTO_secure_clear_free       OSSL_FUNC_CRYPTO_SECURE_CLEAR_FREE
 134  CRYPTO_secure_allocated        OSSL_FUNC_CRYPTO_SECURE_ALLOCATED
 135  BIO_new_file                   OSSL_FUNC_BIO_NEW_FILE
 136  BIO_new_mem_buf                OSSL_FUNC_BIO_NEW_MEMBUF
 137  BIO_read_ex                    OSSL_FUNC_BIO_READ_EX
 138  BIO_free                       OSSL_FUNC_BIO_FREE
 139  BIO_vprintf                    OSSL_FUNC_BIO_VPRINTF
 140  OPENSSL_cleanse                OSSL_FUNC_OPENSSL_CLEANSE
 141  OSSL_SELF_TEST_set_callback    OSSL_FUNC_SELF_TEST_CB
 142  ossl_rand_get_entropy          OSSL_FUNC_GET_ENTROPY
 143  ossl_rand_cleanup_entropy      OSSL_FUNC_CLEANUP_ENTROPY
 144  ossl_rand_get_nonce            OSSL_FUNC_GET_NONCE
 145  ossl_rand_cleanup_nonce        OSSL_FUNC_CLEANUP_NONCE
 146
 147 For I<*out> (the B<OSSL_DISPATCH> array passed from the provider to
 148 F<libcrypto>):
 149
 150  provider_teardown              OSSL_FUNC_PROVIDER_TEARDOWN
 151  provider_gettable_params       OSSL_FUNC_PROVIDER_GETTABLE_PARAMS
 152  provider_get_params            OSSL_FUNC_PROVIDER_GET_PARAMS
 153  provider_query_operation       OSSL_FUNC_PROVIDER_QUERY_OPERATION
 154  provider_get_reason_strings    OSSL_FUNC_PROVIDER_GET_REASON_STRINGS
 155  provider_get_capabilities      OSSL_FUNC_PROVIDER_GET_CAPABILITIES
 156  provider_self_test             OSSL_FUNC_PROVIDER_SELF_TEST
 157
 158 =head2 Core functions
 159
 160 core_gettable_params() returns a constant array of descriptor
 161 B<OSSL_PARAM>, for parameters that core_get_params() can handle.
 162
 163 core_get_params() retrieves parameters from the core for the given I<handle>.
 164 See L</Core parameters> below for a description of currently known
 165 parameters.
 166
 167 =for comment core_thread_start() TBA
 168
 169 core_get_libctx() retrieves the library context in which the library
 170 object for the current provider is stored, accessible through the I<handle>.
 171 This may sometimes be useful if the provider wishes to store a
 172 reference to its context in the same library context.
 173
 174 core_new_error(), core_set_error_debug() and core_set_error() are
 175 building blocks for reporting an error back to the core, with
 176 reference to the I<handle>.
 177
 178 =over 4
 179
 180 =item core_new_error()
 181
 182 allocates a new thread specific error record.
 183
 184 This corresponds to the OpenSSL function L<ERR_new(3)>.
 185
 186 =item core_set_error_debug()
 187
 188 sets debugging information in the current thread specific error
 189 record.
 190 The debugging information includes the name of the file I<file>, the
 191 line I<line> and the function name I<func> where the error occurred.
 192
 193 This corresponds to the OpenSSL function L<ERR_set_debug(3)>.
 194
 195 =item core_set_error()
 196
 197 sets the I<reason> for the error, along with any addition data.
 198 The I<reason> is a number defined by the provider and used to index
 199 the reason strings table that's returned by
 200 provider_get_reason_strings().
 201 The additional data is given as a format string I<fmt> and a set of
 202 arguments I<args>, which are treated in the same manner as with
 203 BIO_vsnprintf().
 204 I<file> and I<line> may also be passed to indicate exactly where the
 205 error occurred or was reported.
 206
 207 This corresponds to the OpenSSL function L<ERR_vset_error(3)>.
 208
 209 =back
 210
 211 CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_memdup(), CRYPTO_strdup(),
 212 CRYPTO_strndup(), CRYPTO_free(), CRYPTO_clear_free(),
 213 CRYPTO_realloc(), CRYPTO_clear_realloc(), CRYPTO_secure_malloc(),
 214 CRYPTO_secure_zalloc(), CRYPTO_secure_free(),
 215 CRYPTO_secure_clear_free(), CRYPTO_secure_allocated(),
 216 BIO_new_file(), BIO_new_mem_buf(), BIO_read_ex(), BIO_free(),
 217 BIO_vprintf(), OPENSSL_cleanse(), and OPENSSL_hexstr2buf()
 218 correspond exactly to the public functions with the same name.
 219 As a matter of fact, the pointers in the B<OSSL_DISPATCH> array are
 220 direct pointers to those public functions. Note that the BIO functions take an
 221 B<OSSL_CORE_BIO> type rather than the standard B<BIO> type. This is to ensure
 222 that a provider does not mix BIOs from the core with BIOs used on the provider
 223 side (the two are not compatible).
 224 OSSL_SELF_TEST_set_callback() is used to set an optional callback that can be
 225 passed into a provider. This may be ignored by a provider.
 226
 227 get_entropy() retrieves seeding material from the operating system.
 228 The seeding material will have at least I<entropy> bytes of randomness and the
 229 output will have at least I<min_len> and at most I<max_len> bytes.
 230 The buffer address is stored in I<*pout> and the buffer length is
 231 returned to the caller.  On error, zero is returned.
 232
 233 cleanup_entropy() is used to clean up and free the buffer returned by
 234 get_entropy().  The entropy pointer returned by get_entropy() is passed in
 235 B<buf> and its length in B<len>.
 236
 237 get_nonce() retrieves a nonce using the passed I<salt> parameter
 238 of length I<salt_len> and operating system specific information.
 239 The I<salt> should contain uniquely identifying information and this is
 240 included, in an unspecified manner, as part of the output.
 241 The output is stored in a buffer which contrains at least I<min_len> and at
 242 most I<max_len> bytes.  The buffer address is stored in I<*pout> and the
 243 buffer length returned to the caller.  On error, zero is returned.
 244
 245 cleanup_nonce() is used to clean up and free the buffer returned by
 246 get_nonce().  The nonce pointer returned by get_nonce() is passed in
 247 B<buf> and its length in B<len>.
 248
 249 =head2 Provider functions
 250
 251 provider_teardown() is called when a provider is shut down and removed
 252 from the core's provider store.
 253 It must free the passed I<provctx>.
 254
 255 provider_gettable_params() should return a constant array of
 256 descriptor B<OSSL_PARAM>, for parameters that provider_get_params()
 257 can handle.
 258
 259 provider_get_params() should process the B<OSSL_PARAM> array
 260 I<params>, setting the values of the parameters it understands.
 261
 262 provider_query_operation() should return a constant B<OSSL_ALGORITHM>
 263 that corresponds to the given I<operation_id>.
 264 It should indicate if the core may store a reference to this array by
 265 setting I<*no_store> to 0 (core may store a reference) or 1 (core may
 266 not store a reference).
 267
 268 provider_get_reason_strings() should return a constant B<OSSL_ITEM>
 269 array that provides reason strings for reason codes the provider may
 270 use when reporting errors using core_put_error().
 271
 272 The provider_get_capabilities() function should call the callback I<cb> passing
 273 it a set of B<OSSL_PARAM>s and the caller supplied argument I<arg>. The
 274 B<OSSL_PARAM>s should provide details about the capability with the name given
 275 in the I<capability> argument relevant for the provider context I<provctx>. If a
 276 provider supports multiple capabilities with the given name then it may call the
 277 callback multiple times (one for each capability). Capabilities can be useful for
 278 describing the services that a provider can offer. For further details see the
 279 L</CAPABILITIES> section below. It should return 1 on success or 0 on error.
 280
 281 The provider_self_test() function should perform known answer tests on a subset
 282 of the algorithms that it uses, and may also verify the integrity of the
 283 provider module. It should return 1 on success or 0 on error. It will return 1
 284 if this function is not used.
 285
 286 None of these functions are mandatory, but a provider is fairly
 287 useless without at least provider_query_operation(), and
 288 provider_gettable_params() is fairly useless if not accompanied by
 289 provider_get_params().
 290
 291 =head2 Provider parameters
 292
 293 provider_get_params() can return the following provider parameters to the core:
 294
 295 =over 4
 296
 297 =item "name" (B<OSSL_PROV_PARAM_NAME>) <UTF8_ptr>
 298
 299 This points to a string that should give a unique name for the provider.
 300
 301 =item "version" (B<OSSL_PROV_PARAM_VERSION>) <UTF8_ptr>
 302
 303 This points to a string that is a version number associated with this provider.
 304 OpenSSL in-built providers use OPENSSL_VERSION_STR, but this may be different
 305 for any third party provider. This string is for informational purposes only.
 306
 307 =item "buildinfo" (B<OSSL_PROV_PARAM_BUILDINFO>) <UTF8_ptr>
 308
 309 This points to a string that is a build information associated with this provider.
 310 OpenSSL in-built providers use OPENSSL_FULL_VERSION_STR, but this may be
 311 different for any third party provider.
 312
 313 =item "status" (B<OSSL_PROV_PARAM_STATUS>) <unsigned integer>
 314
 315 This returns 0 if the provider has entered an error state, otherwise it returns
 316 1.
 317
 318 =back
 319
 320 provider_gettable_params() should return the above parameters.
 321
 322
 323 =head2 Core parameters
 324
 325 core_get_params() can retrieve the following core parameters for each provider:
 326
 327 =over 4
 328
 329 =item "openssl-version" (B<OSSL_PROV_PARAM_CORE_VERSION>) <UTF8_ptr>
 330
 331 This points to the OpenSSL libraries' full version string, i.e. the string
 332 expanded from the macro B<OPENSSL_VERSION_STR>.
 333
 334 =item "provider-name" (B<OSSL_PROV_PARAM_CORE_PROV_NAME>) <UTF8_ptr>
 335
 336 This points to the OpenSSL libraries' idea of what the calling provider is named.
 337
 338 =item "module-filename" (B<OSSL_PROV_PARAM_CORE_MODULE_FILENAME>) <UTF8_ptr>
 339
 340 This points to a string containing the full filename of the providers
 341 module file.
 342
 343 =back
 344
 345 Additionally, provider specific configuration parameters from the
 346 config file are available, in dotted name form.
 347 The dotted name form is a concatenation of section names and final
 348 config command name separated by periods.
 349
 350 For example, let's say we have the following config example:
 351
 352  openssl_conf = openssl_init
 353
 354  [openssl_init]
 355  providers = providers_sect
 356
 357  [providers_sect]
 358  foo = foo_sect
 359
 360  [foo_sect]
 361  activate = 1
 362  data1 = 2
 363  data2 = str
 364  more = foo_more
 365
 366  [foo_more]
 367  data3 = foo,bar
 368
 369 The provider will have these additional parameters available:
 370
 371 =over 4
 372
 373 =item "activate"
 374
 375 pointing at the string "1"
 376
 377 =item "data1"
 378
 379 pointing at the string "2"
 380
 381 =item "data2"
 382
 383 pointing at the string "str"
 384
 385 =item "more.data3"
 386
 387 pointing at the string "foo,bar"
 388
 389 =back
 390
 391 For more information on handling parameters, see L<OSSL_PARAM(3)> as
 392 L<OSSL_PARAM_int(3)>.
 393
 394 =head1 CAPABILITIES
 395
 396 Capabilities describe some of the services that a provider can offer.
 397 Applications can query the capabilities to discover those services.
 398
 399 =head3 "TLS-GROUP" Capability
 400
 401 The "TLS-GROUP" capability can be queried by libssl to discover the list of
 402 TLS groups that a provider can support. Each group supported can be used for
 403 I<key exchange> (KEX) or I<key encapsulation method> (KEM) during a TLS
 404 handshake.
 405 TLS clients can advertise the list of TLS groups they support in the
 406 supported_groups extension, and TLS servers can select a group from the offered
 407 list that they also support. In this way a provider can add to the list of
 408 groups that libssl already supports with additional ones.
 409
 410 Each TLS group that a provider supports should be described via the callback
 411 passed in through the provider_get_capabilities function. Each group should have
 412 the following details supplied (all are mandatory, except
 413 B<OSSL_CAPABILITY_TLS_GROUP_IS_KEM>):
 414
 415 =over 4
 416
 417 =item "tls-group-name" (B<OSSL_CAPABILITY_TLS_GROUP_NAME>) <utf8 string>
 418
 419 The name of the group as given in the IANA TLS Supported Groups registry
 420 L<https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8>.
 421
 422 =item "tls-group-name-internal" (B<OSSL_CAPABILITY_TLS_GROUP_NAME_INTERNAL>) <utf8 string>
 423
 424 The name of the group as known by the provider. This could be the same as the
 425 "tls-group-name", but does not have to be.
 426
 427 =item "tls-group-id" (B<OSSL_CAPABILITY_TLS_GROUP_ID>) <unsigned integer>
 428
 429 The TLS group id value as given in the IANA TLS Supported Groups registry.
 430
 431 =item "tls-group-alg" (B<OSSL_CAPABILITY_TLS_GROUP_ALG>) <utf8 string>
 432
 433 The name of a Key Management algorithm that the provider offers and that should
 434 be used with this group. Keys created should be able to support I<key exchange>
 435 or I<key encapsulation method> (KEM), as implied by the optional
 436 B<OSSL_CAPABILITY_TLS_GROUP_IS_KEM> flag.
 437 The algorithm must support key and parameter generation as well as the
 438 key/parameter generation parameter, B<OSSL_PKEY_PARAM_GROUP_NAME>. The group
 439 name given via "tls-group-name-internal" above will be passed via
 440 B<OSSL_PKEY_PARAM_GROUP_NAME> when libssl wishes to generate keys/parameters.
 441
 442 =item "tls-group-sec-bits" (B<OSSL_CAPABILITY_TLS_GROUP_SECURITY_BITS>) <unsigned integer>
 443
 444 The number of bits of security offered by keys in this group. The number of bits
 445 should be comparable with the ones given in table 2 and 3 of the NIST SP800-57
 446 document.
 447
 448 =item "tls-group-is-kem" (B<OSSL_CAPABILITY_TLS_GROUP_IS_KEM>) <unsigned integer>
 449
 450 Boolean flag to describe if the group should be used in I<key exchange> (KEX)
 451 mode (0, default) or in I<key encapsulation method> (KEM) mode (1).
 452
 453 This parameter is optional: if not specified, KEX mode is assumed as the default
 454 mode for the group.
 455
 456 In KEX mode, in a typical Diffie-Hellman fashion, both sides execute I<keygen>
 457 then I<derive> against the peer public key. To operate in KEX mode, the group
 458 implementation must support the provider functions as described in
 459 L<provider-keyexch(7)>.
 460
 461 In KEM mode, the client executes I<keygen> and sends its public key, the server
 462 executes I<encapsulate> using the client's public key and sends back the
 463 resulting I<ciphertext>, finally the client executes I<decapsulate> to retrieve
 464 the same I<shared secret> generated by the server's I<encapsulate>. To operate
 465 in KEM mode, the group implementation must support the provider functions as
 466 described in L<provider-kem(7)>.
 467
 468 Both in KEX and KEM mode, the resulting I<shared secret> is then used according
 469 to the protocol specification.
 470
 471 =item "tls-min-tls" (B<OSSL_CAPABILITY_TLS_GROUP_MIN_TLS>) <integer>
 472
 473 =item "tls-max-tls" (B<OSSL_CAPABILITY_TLS_GROUP_MAX_TLS>) <integer>
 474
 475 =item "tls-min-dtls" (B<OSSL_CAPABILITY_TLS_GROUP_MIN_DTLS>) <integer>
 476
 477 =item "tls-max-dtls" (B<OSSL_CAPABILITY_TLS_GROUP_MAX_DTLS>) <integer>
 478
 479 These parameters can be used to describe the minimum and maximum TLS and DTLS
 480 versions supported by the group. The values equate to the on-the-wire encoding
 481 of the various TLS versions. For example TLSv1.3 is 0x0304 (772 decimal), and
 482 TLSv1.2 is 0x0303 (771 decimal). A 0 indicates that there is no defined minimum
 483 or maximum. A -1 indicates that the group should not be used in that protocol.
 484
 485 =back
 486
 487 =head1 EXAMPLES
 488
 489 This is an example of a simple provider made available as a
 490 dynamically loadable module.
 491 It implements the fictitious algorithm C<FOO> for the fictitious
 492 operation C<BAR>.
 493
 494  #include <malloc.h>
 495  #include <openssl/core.h>
 496  #include <openssl/core_dispatch.h>
 497
 498  /* Errors used in this provider */
 499  #define E_MALLOC       1
 500
 501  static const OSSL_ITEM reasons[] = {
 502      { E_MALLOC, "memory allocation failure" }.
 503      { 0, NULL } /* Termination */
 504  };
 505
 506  /*
 507   * To ensure we get the function signature right, forward declare
 508   * them using function types provided by openssl/core_dispatch.h
 509   */
 510  OSSL_FUNC_bar_newctx_fn foo_newctx;
 511  OSSL_FUNC_bar_freectx_fn foo_freectx;
 512  OSSL_FUNC_bar_init_fn foo_init;
 513  OSSL_FUNC_bar_update_fn foo_update;
 514  OSSL_FUNC_bar_final_fn foo_final;
 515
 516  OSSL_FUNC_provider_query_operation_fn p_query;
 517  OSSL_FUNC_provider_get_reason_strings_fn p_reasons;
 518  OSSL_FUNC_provider_teardown_fn p_teardown;
 519
 520  OSSL_provider_init_fn OSSL_provider_init;
 521
 522  OSSL_FUNC_core_put_error *c_put_error = NULL;
 523
 524  /* Provider context */
 525  struct prov_ctx_st {
 526      OSSL_CORE_HANDLE *handle;
 527  }
 528
 529  /* operation context for the algorithm FOO */
 530  struct foo_ctx_st {
 531      struct prov_ctx_st *provctx;
 532      int b;
 533  };
 534
 535  static void *foo_newctx(void *provctx)
 536  {
 537      struct foo_ctx_st *fooctx = malloc(sizeof(*fooctx));
 538
 539      if (fooctx != NULL)
 540          fooctx->provctx = provctx;
 541      else
 542          c_put_error(provctx->handle, E_MALLOC, __FILE__, __LINE__);
 543      return fooctx;
 544  }
 545
 546  static void foo_freectx(void *fooctx)
 547  {
 548      free(fooctx);
 549  }
 550
 551  static int foo_init(void *vfooctx)
 552  {
 553      struct foo_ctx_st *fooctx = vfooctx;
 554
 555      fooctx->b = 0x33;
 556  }
 557
 558  static int foo_update(void *vfooctx, unsigned char *in, size_t inl)
 559  {
 560      struct foo_ctx_st *fooctx = vfooctx;
 561
 562      /* did you expect something serious? */
 563      if (inl == 0)
 564          return 1;
 565      for (; inl-- > 0; in++)
 566          *in ^= fooctx->b;
 567      return 1;
 568  }
 569
 570  static int foo_final(void *vfooctx)
 571  {
 572      struct foo_ctx_st *fooctx = vfooctx;
 573
 574      fooctx->b = 0x66;
 575  }
 576
 577  static const OSSL_DISPATCH foo_fns[] = {
 578      { OSSL_FUNC_BAR_NEWCTX, (void (*)(void))foo_newctx },
 579      { OSSL_FUNC_BAR_FREECTX, (void (*)(void))foo_freectx },
 580      { OSSL_FUNC_BAR_INIT, (void (*)(void))foo_init },
 581      { OSSL_FUNC_BAR_UPDATE, (void (*)(void))foo_update },
 582      { OSSL_FUNC_BAR_FINAL, (void (*)(void))foo_final },
 583      { 0, NULL }
 584  };
 585
 586  static const OSSL_ALGORITHM bars[] = {
 587      { "FOO", "provider=chumbawamba", foo_fns },
 588      { NULL, NULL, NULL }
 589  };
 590
 591  static const OSSL_ALGORITHM *p_query(void *provctx, int operation_id,
 592                                       int *no_store)
 593  {
 594      switch (operation_id) {
 595      case OSSL_OP_BAR:
 596          return bars;
 597      }
 598      return NULL;
 599  }
 600
 601  static const OSSL_ITEM *p_reasons(void *provctx)
 602  {
 603      return reasons;
 604  }
 605
 606  static void p_teardown(void *provctx)
 607  {
 608      free(provctx);
 609  }
 610
 611  static const OSSL_DISPATCH prov_fns[] = {
 612      { OSSL_FUNC_PROVIDER_TEARDOWN, (void (*)(void))p_teardown },
 613      { OSSL_FUNC_PROVIDER_QUERY_OPERATION, (void (*)(void))p_query },
 614      { OSSL_FUNC_PROVIDER_GET_REASON_STRINGS, (void (*)(void))p_reasons },
 615      { 0, NULL }
 616  };
 617
 618  int OSSL_provider_init(const OSSL_CORE_HANDLE *handle,
 619                         const OSSL_DISPATCH *in,
 620                         const OSSL_DISPATCH **out,
 621                         void **provctx)
 622  {
 623      struct prov_ctx_st *pctx = NULL;
 624
 625      for (; in->function_id != 0; in++)
 626          switch (in->function_id) {
 627          case OSSL_FUNC_CORE_PUT_ERROR:
 628              c_put_error = OSSL_FUNC_core_put_error(in);
 629              break;
 630          }
 631
 632      *out = prov_fns;
 633
 634      if ((pctx = malloc(sizeof(*pctx))) == NULL) {
 635          /*
 636           * ALEA IACTA EST, if the core retrieves the reason table
 637           * regardless, that string will be displayed, otherwise not.
 638           */
 639          c_put_error(handle, E_MALLOC, __FILE__, __LINE__);
 640          return 0;
 641      }
 642      pctx->handle = handle;
 643      return 1;
 644  }
 645
 646 This relies on a few things existing in F<openssl/core_dispatch.h>:
 647
 648  #define OSSL_OP_BAR            4711
 649
 650  #define OSSL_FUNC_BAR_NEWCTX      1
 651  typedef void *(OSSL_FUNC_bar_newctx_fn)(void *provctx);
 652  static ossl_inline OSSL_FUNC_bar_newctx(const OSSL_DISPATCH *opf)
 653  { return (OSSL_FUNC_bar_newctx_fn *)opf->function; }
 654
 655  #define OSSL_FUNC_BAR_FREECTX     2
 656  typedef void (OSSL_FUNC_bar_freectx_fn)(void *ctx);
 657  static ossl_inline OSSL_FUNC_bar_newctx(const OSSL_DISPATCH *opf)
 658  { return (OSSL_FUNC_bar_freectx_fn *)opf->function; }
 659
 660  #define OSSL_FUNC_BAR_INIT        3
 661  typedef void *(OSSL_FUNC_bar_init_fn)(void *ctx);
 662  static ossl_inline OSSL_FUNC_bar_init(const OSSL_DISPATCH *opf)
 663  { return (OSSL_FUNC_bar_init_fn *)opf->function; }
 664
 665  #define OSSL_FUNC_BAR_UPDATE      4
 666  typedef void *(OSSL_FUNC_bar_update_fn)(void *ctx,
 667                                        unsigned char *in, size_t inl);
 668  static ossl_inline OSSL_FUNC_bar_update(const OSSL_DISPATCH *opf)
 669  { return (OSSL_FUNC_bar_update_fn *)opf->function; }
 670
 671  #define OSSL_FUNC_BAR_FINAL       5
 672  typedef void *(OSSL_FUNC_bar_final_fn)(void *ctx);
 673  static ossl_inline OSSL_FUNC_bar_final(const OSSL_DISPATCH *opf)
 674  { return (OSSL_FUNC_bar_final_fn *)opf->function; }
 675
 676 =head1 SEE ALSO
 677
 678 L<provider(7)>
 679
 680 =head1 HISTORY
 681
 682 The concept of providers and everything surrounding them was
 683 introduced in OpenSSL 3.0.
 684
 685 =head1 COPYRIGHT
 686
 687 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
 688
 689 Licensed under the Apache License 2.0 (the "License").  You may not use
 690 this file except in compliance with the License.  You can obtain a copy
 691 in the file LICENSE in the source distribution or at
 692 L<https://www.openssl.org/source/license.html>.
 693
 694 =cut