Add FIPS Self test kats for digests
[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_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  BIO_vprintf                    OSSL_FUNC_BIO_VPRINTF
116  OPENSSL_cleanse                OSSL_FUNC_OPENSSL_CLEANSE
117  OPENSSL_hexstr2buf             OSSL_FUNC_OPENSSL_HEXSTR2BUF
118  OSSL_SELF_TEST_set_callback    OSSL_FUNC_SELF_TEST_CB
119
120 For I<*out> (the B<OSSL_DISPATCH> array passed from the provider to
121 F<libcrypto>):
122
123  provider_teardown              OSSL_FUNC_PROVIDER_TEARDOWN
124  provider_gettable_params       OSSL_FUNC_PROVIDER_GETTABLE_PARAMS
125  provider_get_params            OSSL_FUNC_PROVIDER_GET_PARAMS
126  provider_query_operation       OSSL_FUNC_PROVIDER_QUERY_OPERATION
127  provider_get_reason_strings    OSSL_FUNC_PROVIDER_GET_REASON_STRINGS
128
129 =head2 Core functions
130
131 core_gettable_params() returns a constant array of descriptor
132 B<OSSL_PARAM>, for parameters that core_get_params() can handle.
133
134 core_get_params() retrieves I<prov> parameters from the core.
135 See L</Core parameters> below for a description of currently known
136 parameters.
137
138 =for comment core_thread_start() TBA
139
140 core_get_library_context() retrieves the library context in which the
141 B<OSSL_PROVIDER> object I<prov> is stored.
142 This may sometimes be useful if the provider wishes to store a
143 reference to its context in the same library context.
144
145 core_new_error(), core_set_error_debug() and core_set_error() are
146 building blocks for reporting an error back to the core, with
147 reference to the provider object I<prov>.
148
149 =over 4
150
151 =item core_new_error()
152
153 allocates a new thread specific error record.
154
155 This corresponds to the OpenSSL function L<ERR_new(3)>.
156
157 =item core_set_error_debug()
158
159 sets debugging information in the current thread specific error
160 record.
161 The debugging information includes the name of the file I<file>, the
162 line I<line> and the function name I<func> where the error occurred.
163
164 This corresponds to the OpenSSL function L<ERR_set_debug(3)>.
165
166 =item core_set_error()
167
168 sets the I<reason> for the error, along with any addition data.
169 The I<reason> is a number defined by the provider and used to index
170 the reason strings table that's returned by
171 provider_get_reason_strings().
172 The additional data is given as a format string I<fmt> and a set of
173 arguments I<args>, which are treated in the same manner as with
174 BIO_vsnprintf().
175 I<file> and I<line> may also be passed to indicate exactly where the
176 error occurred or was reported.
177
178 This corresponds to the OpenSSL function L<ERR_vset_error(3)>.
179
180 =back
181
182 CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_memdup(), CRYPTO_strdup(),
183 CRYPTO_strndup(), CRYPTO_free(), CRYPTO_clear_free(),
184 CRYPTO_realloc(), CRYPTO_clear_realloc(), CRYPTO_secure_malloc(),
185 CRYPTO_secure_zalloc(), CRYPTO_secure_free(),
186 CRYPTO_secure_clear_free(), CRYPTO_secure_allocated(),
187 BIO_new_file(), BIO_new_mem_buf(), BIO_read_ex(), BIO_free(),
188 BIO_vprintf(), OPENSSL_cleanse(), and OPENSSL_hexstr2buf()
189 correspond exactly to the public functions with the same name.
190 As a matter of fact, the pointers in the B<OSSL_DISPATCH> array are
191 direct pointers to those public functions.
192 OSSL_SELF_TEST_set_callback() is used to set an optional callback that can be
193 passed into a provider. This may be ignored by a provider.
194
195 =head2 Provider functions
196
197 provider_teardown() is called when a provider is shut down and removed
198 from the core's provider store.
199 It must free the passed I<provctx>.
200
201 provider_gettable_params() should return a constant array of
202 descriptor B<OSSL_PARAM>, for parameters that provider_get_params()
203 can handle.
204
205 provider_get_params() should process the B<OSSL_PARAM> array
206 I<params>, setting the values of the parameters it understands.
207
208 provider_query_operation() should return a constant B<OSSL_ALGORITHM>
209 that corresponds to the given I<operation_id>.
210 It should indicate if the core may store a reference to this array by
211 setting I<*no_store> to 0 (core may store a reference) or 1 (core may
212 not store a reference).
213
214 provider_get_reason_strings() should return a constant B<OSSL_ITEM>
215 array that provides reason strings for reason codes the provider may
216 use when reporting errors using core_put_error().
217
218 None of these functions are mandatory, but a provider is fairly
219 useless without at least provider_query_operation(), and
220 provider_gettable_params() is fairly useless if not accompanied by
221 provider_get_params().
222
223 =head2 Core parameters
224
225 core_get_params() understands the following known parameters:
226
227 =over 4
228
229 =item "openssl-version"
230
231 This is a B<OSSL_PARAM_UTF8_PTR> type of parameter, pointing at the
232 OpenSSL libraries' full version string, i.e. the string expanded from
233 the macro B<OPENSSL_VERSION_STR>.
234
235 =item "provider-name"
236
237 This is a B<OSSL_PARAM_UTF8_PTR> type of parameter, pointing at the
238 OpenSSL libraries' idea of what the calling provider is called.
239
240 =back
241
242 Additionally, provider specific configuration parameters from the
243 config file are available, in dotted name form.
244 The dotted name form is a concatenation of section names and final
245 config command name separated by periods.
246
247 For example, let's say we have the following config example:
248
249  openssl_conf = openssl_init
250
251  [openssl_init]
252  providers = providers_sect
253
254  [providers_sect]
255  foo = foo_sect
256
257  [foo_sect]
258  activate = 1
259  data1 = 2
260  data2 = str
261  more = foo_more
262
263  [foo_more]
264  data3 = foo,bar
265
266 The provider will have these additional parameters available:
267
268 =over 4
269
270 =item "activate"
271
272 pointing at the string "1"
273
274 =item "data1"
275
276 pointing at the string "2"
277
278 =item "data2"
279
280 pointing at the string "str"
281
282 =item "more.data3"
283
284 pointing at the string "foo,bar"
285
286 =back
287
288 For more information on handling parameters, see L<OSSL_PARAM(3)> as
289 L<OSSL_PARAM_int(3)>.
290
291 =head1 EXAMPLES
292
293 This is an example of a simple provider made available as a
294 dynamically loadable module.
295 It implements the fictitious algorithm C<FOO> for the fictitious
296 operation C<BAR>.
297
298  #include <malloc.h>
299  #include <openssl/core.h>
300  #include <openssl/core_numbers.h>
301
302  /* Errors used in this provider */
303  #define E_MALLOC       1
304
305  static const OSSL_ITEM reasons[] = {
306      { E_MALLOC, "memory allocation failure" }.
307      { 0, NULL } /* Termination */
308  };
309
310  /*
311   * To ensure we get the function signature right, forward declare
312   * them using function types provided by openssl/core_numbers.h
313   */
314  OSSL_OP_bar_newctx_fn foo_newctx;
315  OSSL_OP_bar_freectx_fn foo_freectx;
316  OSSL_OP_bar_init_fn foo_init;
317  OSSL_OP_bar_update_fn foo_update;
318  OSSL_OP_bar_final_fn foo_final;
319
320  OSSL_provider_query_operation_fn p_query;
321  OSSL_provider_get_reason_strings_fn p_reasons;
322  OSSL_provider_teardown_fn p_teardown;
323
324  OSSL_provider_init_fn OSSL_provider_init;
325
326  OSSL_core_put_error *c_put_error = NULL;
327
328  /* Provider context */
329  struct prov_ctx_st {
330      OSSL_PROVIDER *prov;
331  }
332
333  /* operation context for the algorithm FOO */
334  struct foo_ctx_st {
335      struct prov_ctx_st *provctx;
336      int b;
337  };
338
339  static void *foo_newctx(void *provctx)
340  {
341      struct foo_ctx_st *fooctx = malloc(sizeof(*fooctx));
342
343      if (fooctx != NULL)
344          fooctx->provctx = provctx;
345      else
346          c_put_error(provctx->prov, E_MALLOC, __FILE__, __LINE__);
347      return fooctx;
348  }
349
350  static void foo_freectx(void *fooctx)
351  {
352      free(fooctx);
353  }
354
355  static int foo_init(void *vfooctx)
356  {
357      struct foo_ctx_st *fooctx = vfooctx;
358
359      fooctx->b = 0x33;
360  }
361
362  static int foo_update(void *vfooctx, unsigned char *in, size_t inl)
363  {
364      struct foo_ctx_st *fooctx = vfooctx;
365
366      /* did you expect something serious? */
367      if (inl == 0)
368          return 1;
369      for (; inl-- > 0; in++)
370          *in ^= fooctx->b;
371      return 1;
372  }
373
374  static int foo_final(void *vfooctx)
375  {
376      struct foo_ctx_st *fooctx = vfooctx;
377
378      fooctx->b = 0x66;
379  }
380
381  static const OSSL_DISPATCH foo_fns[] = {
382      { OSSL_FUNC_BAR_NEWCTX, (void (*)(void))foo_newctx },
383      { OSSL_FUNC_BAR_FREECTX, (void (*)(void))foo_freectx },
384      { OSSL_FUNC_BAR_INIT, (void (*)(void))foo_init },
385      { OSSL_FUNC_BAR_UPDATE, (void (*)(void))foo_update },
386      { OSSL_FUNC_BAR_FINAL, (void (*)(void))foo_final },
387      { 0, NULL }
388  };
389
390  static const OSSL_ALGORITHM bars[] = {
391      { "FOO", "provider=chumbawamba", foo_fns },
392      { NULL, NULL, NULL }
393  };
394
395  static const OSSL_ALGORITHM *p_query(void *provctx, int operation_id,
396                                       int *no_store)
397  {
398      switch (operation_id) {
399      case OSSL_OP_BAR:
400          return bars;
401      }
402      return NULL;
403  }
404
405  static const OSSL_ITEM *p_reasons(void *provctx)
406  {
407      return reasons;
408  }
409
410  static void p_teardown(void *provctx)
411  {
412      free(provctx);
413  }
414
415  static const OSSL_DISPATCH prov_fns[] = {
416      { OSSL_FUNC_PROVIDER_TEARDOWN, (void (*)(void))p_teardown },
417      { OSSL_FUNC_PROVIDER_QUERY_OPERATION, (void (*)(void))p_query },
418      { OSSL_FUNC_PROVIDER_GET_REASON_STRINGS, (void (*)(void))p_reasons },
419      { 0, NULL }
420  };
421
422  int OSSL_provider_init(const OSSL_PROVIDER *provider,
423                         const OSSL_DISPATCH *in,
424                         const OSSL_DISPATCH **out,
425                         void **provctx)
426  {
427      struct prov_ctx_st *pctx = NULL;
428
429      for (; in->function_id != 0; in++)
430          switch (in->function_id) {
431          case OSSL_FUNC_CORE_PUT_ERROR:
432              c_put_error = OSSL_get_core_put_error(in);
433              break;
434          }
435
436      *out = prov_fns;
437
438      if ((pctx = malloc(sizeof(*pctx))) == NULL) {
439          /*
440           * ALEA IACTA EST, if the core retrieves the reason table
441           * regardless, that string will be displayed, otherwise not.
442           */
443          c_put_error(provider, E_MALLOC, __FILE__, __LINE__);
444          return 0;
445      }
446      return 1;
447  }
448
449 This relies on a few things existing in F<openssl/core_numbers.h>:
450
451  #define OSSL_OP_BAR            4711
452
453  #define OSSL_FUNC_BAR_NEWCTX      1
454  typedef void *(OSSL_OP_bar_newctx_fn)(void *provctx);
455  static ossl_inline OSSL_get_bar_newctx(const OSSL_DISPATCH *opf)
456  { return (OSSL_OP_bar_newctx_fn *)opf->function; }
457
458  #define OSSL_FUNC_BAR_FREECTX     2
459  typedef void (OSSL_OP_bar_freectx_fn)(void *ctx);
460  static ossl_inline OSSL_get_bar_newctx(const OSSL_DISPATCH *opf)
461  { return (OSSL_OP_bar_freectx_fn *)opf->function; }
462
463  #define OSSL_FUNC_BAR_INIT        3
464  typedef void *(OSSL_OP_bar_init_fn)(void *ctx);
465  static ossl_inline OSSL_get_bar_init(const OSSL_DISPATCH *opf)
466  { return (OSSL_OP_bar_init_fn *)opf->function; }
467
468  #define OSSL_FUNC_BAR_UPDATE      4
469  typedef void *(OSSL_OP_bar_update_fn)(void *ctx,
470                                        unsigned char *in, size_t inl);
471  static ossl_inline OSSL_get_bar_update(const OSSL_DISPATCH *opf)
472  { return (OSSL_OP_bar_update_fn *)opf->function; }
473
474  #define OSSL_FUNC_BAR_FINAL       5
475  typedef void *(OSSL_OP_bar_final_fn)(void *ctx);
476  static ossl_inline OSSL_get_bar_final(const OSSL_DISPATCH *opf)
477  { return (OSSL_OP_bar_final_fn *)opf->function; }
478
479 =head1 SEE ALSO
480
481 L<provider(7)>
482
483 =head1 HISTORY
484
485 The concept of providers and everything surrounding them was
486 introduced in OpenSSL 3.0.
487
488 =head1 COPYRIGHT
489
490 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
491
492 Licensed under the Apache License 2.0 (the "License").  You may not use
493 this file except in compliance with the License.  You can obtain a copy
494 in the file LICENSE in the source distribution or at
495 L<https://www.openssl.org/source/license.html>.
496
497 =cut