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