Update documentation following changes of various types
[openssl.git] / 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 Core parameters
238
239 core_get_params() understands the following known parameters:
240
241 =over 4
242
243 =item "openssl-version"
244
245 This is a B<OSSL_PARAM_UTF8_PTR> type of parameter, pointing at the
246 OpenSSL libraries' full version string, i.e. the string expanded from
247 the macro B<OPENSSL_VERSION_STR>.
248
249 =item "provider-name"
250
251 This is a B<OSSL_PARAM_UTF8_PTR> type of parameter, pointing at the
252 OpenSSL libraries' idea of what the calling provider is called.
253
254 =back
255
256 Additionally, provider specific configuration parameters from the
257 config file are available, in dotted name form.
258 The dotted name form is a concatenation of section names and final
259 config command name separated by periods.
260
261 For example, let's say we have the following config example:
262
263  openssl_conf = openssl_init
264
265  [openssl_init]
266  providers = providers_sect
267
268  [providers_sect]
269  foo = foo_sect
270
271  [foo_sect]
272  activate = 1
273  data1 = 2
274  data2 = str
275  more = foo_more
276
277  [foo_more]
278  data3 = foo,bar
279
280 The provider will have these additional parameters available:
281
282 =over 4
283
284 =item "activate"
285
286 pointing at the string "1"
287
288 =item "data1"
289
290 pointing at the string "2"
291
292 =item "data2"
293
294 pointing at the string "str"
295
296 =item "more.data3"
297
298 pointing at the string "foo,bar"
299
300 =back
301
302 For more information on handling parameters, see L<OSSL_PARAM(3)> as
303 L<OSSL_PARAM_int(3)>.
304
305 =head1 EXAMPLES
306
307 This is an example of a simple provider made available as a
308 dynamically loadable module.
309 It implements the fictitious algorithm C<FOO> for the fictitious
310 operation C<BAR>.
311
312  #include <malloc.h>
313  #include <openssl/core.h>
314  #include <openssl/core_numbers.h>
315
316  /* Errors used in this provider */
317  #define E_MALLOC       1
318
319  static const OSSL_ITEM reasons[] = {
320      { E_MALLOC, "memory allocation failure" }.
321      { 0, NULL } /* Termination */
322  };
323
324  /*
325   * To ensure we get the function signature right, forward declare
326   * them using function types provided by openssl/core_numbers.h
327   */
328  OSSL_OP_bar_newctx_fn foo_newctx;
329  OSSL_OP_bar_freectx_fn foo_freectx;
330  OSSL_OP_bar_init_fn foo_init;
331  OSSL_OP_bar_update_fn foo_update;
332  OSSL_OP_bar_final_fn foo_final;
333
334  OSSL_provider_query_operation_fn p_query;
335  OSSL_provider_get_reason_strings_fn p_reasons;
336  OSSL_provider_teardown_fn p_teardown;
337
338  OSSL_provider_init_fn OSSL_provider_init;
339
340  OSSL_core_put_error *c_put_error = NULL;
341
342  /* Provider context */
343  struct prov_ctx_st {
344      OSSL_CORE_HANDLE *handle;
345  }
346
347  /* operation context for the algorithm FOO */
348  struct foo_ctx_st {
349      struct prov_ctx_st *provctx;
350      int b;
351  };
352
353  static void *foo_newctx(void *provctx)
354  {
355      struct foo_ctx_st *fooctx = malloc(sizeof(*fooctx));
356
357      if (fooctx != NULL)
358          fooctx->provctx = provctx;
359      else
360          c_put_error(provctx->handle, E_MALLOC, __FILE__, __LINE__);
361      return fooctx;
362  }
363
364  static void foo_freectx(void *fooctx)
365  {
366      free(fooctx);
367  }
368
369  static int foo_init(void *vfooctx)
370  {
371      struct foo_ctx_st *fooctx = vfooctx;
372
373      fooctx->b = 0x33;
374  }
375
376  static int foo_update(void *vfooctx, unsigned char *in, size_t inl)
377  {
378      struct foo_ctx_st *fooctx = vfooctx;
379
380      /* did you expect something serious? */
381      if (inl == 0)
382          return 1;
383      for (; inl-- > 0; in++)
384          *in ^= fooctx->b;
385      return 1;
386  }
387
388  static int foo_final(void *vfooctx)
389  {
390      struct foo_ctx_st *fooctx = vfooctx;
391
392      fooctx->b = 0x66;
393  }
394
395  static const OSSL_DISPATCH foo_fns[] = {
396      { OSSL_FUNC_BAR_NEWCTX, (void (*)(void))foo_newctx },
397      { OSSL_FUNC_BAR_FREECTX, (void (*)(void))foo_freectx },
398      { OSSL_FUNC_BAR_INIT, (void (*)(void))foo_init },
399      { OSSL_FUNC_BAR_UPDATE, (void (*)(void))foo_update },
400      { OSSL_FUNC_BAR_FINAL, (void (*)(void))foo_final },
401      { 0, NULL }
402  };
403
404  static const OSSL_ALGORITHM bars[] = {
405      { "FOO", "provider=chumbawamba", foo_fns },
406      { NULL, NULL, NULL }
407  };
408
409  static const OSSL_ALGORITHM *p_query(void *provctx, int operation_id,
410                                       int *no_store)
411  {
412      switch (operation_id) {
413      case OSSL_OP_BAR:
414          return bars;
415      }
416      return NULL;
417  }
418
419  static const OSSL_ITEM *p_reasons(void *provctx)
420  {
421      return reasons;
422  }
423
424  static void p_teardown(void *provctx)
425  {
426      free(provctx);
427  }
428
429  static const OSSL_DISPATCH prov_fns[] = {
430      { OSSL_FUNC_PROVIDER_TEARDOWN, (void (*)(void))p_teardown },
431      { OSSL_FUNC_PROVIDER_QUERY_OPERATION, (void (*)(void))p_query },
432      { OSSL_FUNC_PROVIDER_GET_REASON_STRINGS, (void (*)(void))p_reasons },
433      { 0, NULL }
434  };
435
436  int OSSL_provider_init(const OSSL_CORE_HANDLE *handle,
437                         const OSSL_DISPATCH *in,
438                         const OSSL_DISPATCH **out,
439                         void **provctx)
440  {
441      struct prov_ctx_st *pctx = NULL;
442
443      for (; in->function_id != 0; in++)
444          switch (in->function_id) {
445          case OSSL_FUNC_CORE_PUT_ERROR:
446              c_put_error = OSSL_get_core_put_error(in);
447              break;
448          }
449
450      *out = prov_fns;
451
452      if ((pctx = malloc(sizeof(*pctx))) == NULL) {
453          /*
454           * ALEA IACTA EST, if the core retrieves the reason table
455           * regardless, that string will be displayed, otherwise not.
456           */
457          c_put_error(handle, E_MALLOC, __FILE__, __LINE__);
458          return 0;
459      }
460      pctx->handle = handle;
461      return 1;
462  }
463
464 This relies on a few things existing in F<openssl/core_numbers.h>:
465
466  #define OSSL_OP_BAR            4711
467
468  #define OSSL_FUNC_BAR_NEWCTX      1
469  typedef void *(OSSL_OP_bar_newctx_fn)(void *provctx);
470  static ossl_inline OSSL_get_bar_newctx(const OSSL_DISPATCH *opf)
471  { return (OSSL_OP_bar_newctx_fn *)opf->function; }
472
473  #define OSSL_FUNC_BAR_FREECTX     2
474  typedef void (OSSL_OP_bar_freectx_fn)(void *ctx);
475  static ossl_inline OSSL_get_bar_newctx(const OSSL_DISPATCH *opf)
476  { return (OSSL_OP_bar_freectx_fn *)opf->function; }
477
478  #define OSSL_FUNC_BAR_INIT        3
479  typedef void *(OSSL_OP_bar_init_fn)(void *ctx);
480  static ossl_inline OSSL_get_bar_init(const OSSL_DISPATCH *opf)
481  { return (OSSL_OP_bar_init_fn *)opf->function; }
482
483  #define OSSL_FUNC_BAR_UPDATE      4
484  typedef void *(OSSL_OP_bar_update_fn)(void *ctx,
485                                        unsigned char *in, size_t inl);
486  static ossl_inline OSSL_get_bar_update(const OSSL_DISPATCH *opf)
487  { return (OSSL_OP_bar_update_fn *)opf->function; }
488
489  #define OSSL_FUNC_BAR_FINAL       5
490  typedef void *(OSSL_OP_bar_final_fn)(void *ctx);
491  static ossl_inline OSSL_get_bar_final(const OSSL_DISPATCH *opf)
492  { return (OSSL_OP_bar_final_fn *)opf->function; }
493
494 =head1 SEE ALSO
495
496 L<provider(7)>
497
498 =head1 HISTORY
499
500 The concept of providers and everything surrounding them was
501 introduced in OpenSSL 3.0.
502
503 =head1 COPYRIGHT
504
505 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
506
507 Licensed under the Apache License 2.0 (the "License").  You may not use
508 this file except in compliance with the License.  You can obtain a copy
509 in the file LICENSE in the source distribution or at
510 L<https://www.openssl.org/source/license.html>.
511
512 =cut