6 - The basic OpenSSL library E<lt>-E<gt> provider functions
10 #include <openssl/core_numbers.h>
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.
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);
31 * Some OpenSSL functionality is directly offered to providers via
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);
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,
64 const OSSL_ITEM *provider_get_reason_strings(void *provctx);
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.
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
77 For example, the "function" core_gettable_params() has these:
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);
84 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
85 macros in L<openssl-core_numbers.h(7)>, as follows:
87 For I<in> (the B<OSSL_DISPATCH> array passed from F<libcrypto> to the
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 CRYPTO_mem_ctrl OSSL_FUNC_CRYPTO_MEM_CTRL
112 BIO_new_file OSSL_FUNC_BIO_NEW_FILE
113 BIO_new_mem_buf OSSL_FUNC_BIO_NEW_MEMBUF
114 BIO_read_ex OSSL_FUNC_BIO_READ_EX
115 BIO_free OSSL_FUNC_BIO_FREE
116 BIO_vprintf OSSL_FUNC_BIO_VPRINTF
117 OPENSSL_cleanse OSSL_FUNC_OPENSSL_CLEANSE
118 OPENSSL_hexstr2buf OSSL_FUNC_OPENSSL_HEXSTR2BUF
120 For I<*out> (the B<OSSL_DISPATCH> array passed from the provider to
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
129 =head2 Core functions
131 core_gettable_params() returns a constant array of descriptor
132 B<OSSL_PARAM>, for parameters that core_get_params() can handle.
134 core_get_params() retrieves I<prov> parameters from the core.
135 See L</Core parameters> below for a description of currently known
138 =for comment core_thread_start() TBA
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.
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>.
151 =item core_new_error()
153 allocates a new thread specific error record.
155 This corresponds to the OpenSSL function L<ERR_new(3)>.
157 =item core_set_error_debug()
159 sets debugging information in the current thread specific error
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.
164 This corresponds to the OpenSSL function L<ERR_set_debug(3)>.
166 =item core_set_error()
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
175 I<file> and I<line> may also be passed to indicate exactly where the
176 error occurred or was reported.
178 This corresponds to the OpenSSL function L<ERR_vset_error(3)>.
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(), CRYPTO_mem_ctrl(),
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.
193 =head2 Provider functions
195 provider_teardown() is called when a provider is shut down and removed
196 from the core's provider store.
197 It must free the passed I<provctx>.
199 provider_gettable_params() should return a constant array of
200 descriptor B<OSSL_PARAM>, for parameters that provider_get_params()
203 provider_get_params() should process the B<OSSL_PARAM> array
204 I<params>, setting the values of the parameters it understands.
206 provider_query_operation() should return a constant B<OSSL_ALGORITHM>
207 that corresponds to the given I<operation_id>.
208 It should indicate if the core may store a reference to this array by
209 setting I<*no_store> to 0 (core may store a reference) or 1 (core may
210 not store a reference).
212 provider_get_reason_strings() should return a constant B<OSSL_ITEM>
213 array that provides reason strings for reason codes the provider may
214 use when reporting errors using core_put_error().
216 None of these functions are mandatory, but a provider is fairly
217 useless without at least provider_query_operation(), and
218 provider_gettable_params() is fairly useless if not accompanied by
219 provider_get_params().
221 =head2 Core parameters
223 core_get_params() understands the following known parameters:
227 =item "openssl-version"
229 This is a B<OSSL_PARAM_UTF8_PTR> type of parameter, pointing at the
230 OpenSSL libraries' full version string, i.e. the string expanded from
231 the macro B<OPENSSL_VERSION_STR>.
233 =item "provider-name"
235 This is a B<OSSL_PARAM_UTF8_PTR> type of parameter, pointing at the
236 OpenSSL libraries' idea of what the calling provider is called.
240 Additionally, provider specific configuration parameters from the
241 config file are available, in dotted name form.
242 The dotted name form is a concatenation of section names and final
243 config command name separated by periods.
245 For example, let's say we have the following config example:
247 openssl_conf = openssl_init
250 providers = providers_sect
264 The provider will have these additional parameters available:
270 pointing at the string "1"
274 pointing at the string "2"
278 pointing at the string "str"
282 pointing at the string "foo,bar"
286 For more information on handling parameters, see L<OSSL_PARAM(3)> as
287 L<OSSL_PARAM_int(3)>.
291 This is an example of a simple provider made available as a
292 dynamically loadable module.
293 It implements the fictitious algorithm C<FOO> for the fictitious
297 #include <openssl/core.h>
298 #include <openssl/core_numbers.h>
300 /* Errors used in this provider */
303 static const OSSL_ITEM reasons[] = {
304 { E_MALLOC, "memory allocation failure" }.
305 { 0, NULL } /* Termination */
309 * To ensure we get the function signature right, forward declare
310 * them using function types provided by openssl/core_numbers.h
312 OSSL_OP_bar_newctx_fn foo_newctx;
313 OSSL_OP_bar_freectx_fn foo_freectx;
314 OSSL_OP_bar_init_fn foo_init;
315 OSSL_OP_bar_update_fn foo_update;
316 OSSL_OP_bar_final_fn foo_final;
318 OSSL_provider_query_operation_fn p_query;
319 OSSL_provider_get_reason_strings_fn p_reasons;
320 OSSL_provider_teardown_fn p_teardown;
322 OSSL_provider_init_fn OSSL_provider_init;
324 OSSL_core_put_error *c_put_error = NULL;
326 /* Provider context */
331 /* operation context for the algorithm FOO */
333 struct prov_ctx_st *provctx;
337 static void *foo_newctx(void *provctx)
339 struct foo_ctx_st *fooctx = malloc(sizeof(*fooctx));
342 fooctx->provctx = provctx;
344 c_put_error(provctx->prov, E_MALLOC, __FILE__, __LINE__);
348 static void foo_freectx(void *fooctx)
353 static int foo_init(void *vfooctx)
355 struct foo_ctx_st *fooctx = vfooctx;
360 static int foo_update(void *vfooctx, unsigned char *in, size_t inl)
362 struct foo_ctx_st *fooctx = vfooctx;
364 /* did you expect something serious? */
367 for (; inl-- > 0; in++)
372 static int foo_final(void *vfooctx)
374 struct foo_ctx_st *fooctx = vfooctx;
379 static const OSSL_DISPATCH foo_fns[] = {
380 { OSSL_FUNC_BAR_NEWCTX, (void (*)(void))foo_newctx },
381 { OSSL_FUNC_BAR_FREECTX, (void (*)(void))foo_freectx },
382 { OSSL_FUNC_BAR_INIT, (void (*)(void))foo_init },
383 { OSSL_FUNC_BAR_UPDATE, (void (*)(void))foo_update },
384 { OSSL_FUNC_BAR_FINAL, (void (*)(void))foo_final },
388 static const OSSL_ALGORITHM bars[] = {
389 { "FOO", "provider=chumbawamba", foo_fns },
393 static const OSSL_ALGORITHM *p_query(void *provctx, int operation_id,
396 switch (operation_id) {
403 static const OSSL_ITEM *p_reasons(void *provctx)
408 static void p_teardown(void *provctx)
413 static const OSSL_DISPATCH prov_fns[] = {
414 { OSSL_FUNC_PROVIDER_TEARDOWN, (void (*)(void))p_teardown },
415 { OSSL_FUNC_PROVIDER_QUERY_OPERATION, (void (*)(void))p_query },
416 { OSSL_FUNC_PROVIDER_GET_REASON_STRINGS, (void (*)(void))p_reasons },
420 int OSSL_provider_init(const OSSL_PROVIDER *provider,
421 const OSSL_DISPATCH *in,
422 const OSSL_DISPATCH **out,
425 struct prov_ctx_st *pctx = NULL;
427 for (; in->function_id != 0; in++)
428 switch (in->function_id) {
429 case OSSL_FUNC_CORE_PUT_ERROR:
430 c_put_error = OSSL_get_core_put_error(in);
436 if ((pctx = malloc(sizeof(*pctx))) == NULL) {
438 * ALEA IACTA EST, if the core retrieves the reason table
439 * regardless, that string will be displayed, otherwise not.
441 c_put_error(provider, E_MALLOC, __FILE__, __LINE__);
447 This relies on a few things existing in F<openssl/core_numbers.h>:
449 #define OSSL_OP_BAR 4711
451 #define OSSL_FUNC_BAR_NEWCTX 1
452 typedef void *(OSSL_OP_bar_newctx_fn)(void *provctx);
453 static ossl_inline OSSL_get_bar_newctx(const OSSL_DISPATCH *opf)
454 { return (OSSL_OP_bar_newctx_fn *)opf->function; }
456 #define OSSL_FUNC_BAR_FREECTX 2
457 typedef void (OSSL_OP_bar_freectx_fn)(void *ctx);
458 static ossl_inline OSSL_get_bar_newctx(const OSSL_DISPATCH *opf)
459 { return (OSSL_OP_bar_freectx_fn *)opf->function; }
461 #define OSSL_FUNC_BAR_INIT 3
462 typedef void *(OSSL_OP_bar_init_fn)(void *ctx);
463 static ossl_inline OSSL_get_bar_init(const OSSL_DISPATCH *opf)
464 { return (OSSL_OP_bar_init_fn *)opf->function; }
466 #define OSSL_FUNC_BAR_UPDATE 4
467 typedef void *(OSSL_OP_bar_update_fn)(void *ctx,
468 unsigned char *in, size_t inl);
469 static ossl_inline OSSL_get_bar_update(const OSSL_DISPATCH *opf)
470 { return (OSSL_OP_bar_update_fn *)opf->function; }
472 #define OSSL_FUNC_BAR_FINAL 5
473 typedef void *(OSSL_OP_bar_final_fn)(void *ctx);
474 static ossl_inline OSSL_get_bar_final(const OSSL_DISPATCH *opf)
475 { return (OSSL_OP_bar_final_fn *)opf->function; }
483 The concept of providers and everything surrounding them was
484 introduced in OpenSSL 3.0.
488 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
490 Licensed under the Apache License 2.0 (the "License"). You may not use
491 this file except in compliance with the License. You can obtain a copy
492 in the file LICENSE in the source distribution or at
493 L<https://www.openssl.org/source/license.html>.