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_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);
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);
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,
60 int BIO_write_ex(OSSL_CORE_BIO *bio, const void *data, size_t data_len,
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)
66 void self_test_cb(OPENSSL_CORE_CTX *ctx, OSSL_CALLBACK **cb, void **cbarg)
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,
76 const OSSL_ITEM *provider_get_reason_strings(void *provctx);
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.
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
89 For example, the "function" core_gettable_params() has these:
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);
96 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
97 macros in L<openssl-core_numbers.h(7)>, as follows:
99 For I<in> (the B<OSSL_DISPATCH> array passed from F<libcrypto> to the
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
131 For I<*out> (the B<OSSL_DISPATCH> array passed from the provider to
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
140 =head2 Core functions
142 core_gettable_params() returns a constant array of descriptor
143 B<OSSL_PARAM>, for parameters that core_get_params() can handle.
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
149 =for comment core_thread_start() TBA
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.
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>.
162 =item core_new_error()
164 allocates a new thread specific error record.
166 This corresponds to the OpenSSL function L<ERR_new(3)>.
168 =item core_set_error_debug()
170 sets debugging information in the current thread specific error
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.
175 This corresponds to the OpenSSL function L<ERR_set_debug(3)>.
177 =item core_set_error()
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
186 I<file> and I<line> may also be passed to indicate exactly where the
187 error occurred or was reported.
189 This corresponds to the OpenSSL function L<ERR_vset_error(3)>.
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.
209 =head2 Provider functions
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>.
215 provider_gettable_params() should return a constant array of
216 descriptor B<OSSL_PARAM>, for parameters that provider_get_params()
219 provider_get_params() should process the B<OSSL_PARAM> array
220 I<params>, setting the values of the parameters it understands.
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).
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().
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().
237 =head2 Provider parameters
239 provider_get_params() can return the following provider parameters to the core:
243 =item "name" (B<OSSL_PROV_PARAM_NAME>) <UTF8_ptr>
245 This points to a string that should give a unique name for the provider.
247 =item "version" (B<OSSL_PROV_PARAM_VERSION>) <UTF8_ptr>
249 This points to a string that is a version number associated with this provider.
250 OpenSSL in-built providers use OPENSSL_VERSION_STR, but this may be different
251 for any third party provider. This string is for informational purposes only.
253 =item "buildinfo" (B<OSSL_PROV_PARAM_BUILDINFO>) <UTF8_ptr>
255 This points to a string that is a build information associated with this provider.
256 OpenSSL in-built providers use OPENSSL_FULL_VERSION_STR, but this may be
257 different for any third party provider.
261 provider_gettable_params() should return the above parameters.
264 =head2 Core parameters
266 core_get_params() can retrieve the following core parameters for each provider:
270 =item "openssl-version" (B<OSSL_PROV_PARAM_CORE_VERSION>) <UTF8_ptr>
272 This points to the OpenSSL libraries' full version string, i.e. the string
273 expanded from the macro B<OPENSSL_VERSION_STR>.
275 =item "provider-name" (B<OSSL_PROV_PARAM_CORE_PROV_NAME>) <UTF8_ptr>
277 This points to the OpenSSL libraries' idea of what the calling provider is named.
279 =item "module-filename" (B<OSSL_PROV_PARAM_CORE_MODULE_FILENAME>) <UTF8_ptr>
281 This points to a string containing the full filename of the providers
286 Additionally, provider specific configuration parameters from the
287 config file are available, in dotted name form.
288 The dotted name form is a concatenation of section names and final
289 config command name separated by periods.
291 For example, let's say we have the following config example:
293 openssl_conf = openssl_init
296 providers = providers_sect
310 The provider will have these additional parameters available:
316 pointing at the string "1"
320 pointing at the string "2"
324 pointing at the string "str"
328 pointing at the string "foo,bar"
332 For more information on handling parameters, see L<OSSL_PARAM(3)> as
333 L<OSSL_PARAM_int(3)>.
337 This is an example of a simple provider made available as a
338 dynamically loadable module.
339 It implements the fictitious algorithm C<FOO> for the fictitious
343 #include <openssl/core.h>
344 #include <openssl/core_numbers.h>
346 /* Errors used in this provider */
349 static const OSSL_ITEM reasons[] = {
350 { E_MALLOC, "memory allocation failure" }.
351 { 0, NULL } /* Termination */
355 * To ensure we get the function signature right, forward declare
356 * them using function types provided by openssl/core_numbers.h
358 OSSL_OP_bar_newctx_fn foo_newctx;
359 OSSL_OP_bar_freectx_fn foo_freectx;
360 OSSL_OP_bar_init_fn foo_init;
361 OSSL_OP_bar_update_fn foo_update;
362 OSSL_OP_bar_final_fn foo_final;
364 OSSL_provider_query_operation_fn p_query;
365 OSSL_provider_get_reason_strings_fn p_reasons;
366 OSSL_provider_teardown_fn p_teardown;
368 OSSL_provider_init_fn OSSL_provider_init;
370 OSSL_core_put_error *c_put_error = NULL;
372 /* Provider context */
374 OSSL_CORE_HANDLE *handle;
377 /* operation context for the algorithm FOO */
379 struct prov_ctx_st *provctx;
383 static void *foo_newctx(void *provctx)
385 struct foo_ctx_st *fooctx = malloc(sizeof(*fooctx));
388 fooctx->provctx = provctx;
390 c_put_error(provctx->handle, E_MALLOC, __FILE__, __LINE__);
394 static void foo_freectx(void *fooctx)
399 static int foo_init(void *vfooctx)
401 struct foo_ctx_st *fooctx = vfooctx;
406 static int foo_update(void *vfooctx, unsigned char *in, size_t inl)
408 struct foo_ctx_st *fooctx = vfooctx;
410 /* did you expect something serious? */
413 for (; inl-- > 0; in++)
418 static int foo_final(void *vfooctx)
420 struct foo_ctx_st *fooctx = vfooctx;
425 static const OSSL_DISPATCH foo_fns[] = {
426 { OSSL_FUNC_BAR_NEWCTX, (void (*)(void))foo_newctx },
427 { OSSL_FUNC_BAR_FREECTX, (void (*)(void))foo_freectx },
428 { OSSL_FUNC_BAR_INIT, (void (*)(void))foo_init },
429 { OSSL_FUNC_BAR_UPDATE, (void (*)(void))foo_update },
430 { OSSL_FUNC_BAR_FINAL, (void (*)(void))foo_final },
434 static const OSSL_ALGORITHM bars[] = {
435 { "FOO", "provider=chumbawamba", foo_fns },
439 static const OSSL_ALGORITHM *p_query(void *provctx, int operation_id,
442 switch (operation_id) {
449 static const OSSL_ITEM *p_reasons(void *provctx)
454 static void p_teardown(void *provctx)
459 static const OSSL_DISPATCH prov_fns[] = {
460 { OSSL_FUNC_PROVIDER_TEARDOWN, (void (*)(void))p_teardown },
461 { OSSL_FUNC_PROVIDER_QUERY_OPERATION, (void (*)(void))p_query },
462 { OSSL_FUNC_PROVIDER_GET_REASON_STRINGS, (void (*)(void))p_reasons },
466 int OSSL_provider_init(const OSSL_CORE_HANDLE *handle,
467 const OSSL_DISPATCH *in,
468 const OSSL_DISPATCH **out,
471 struct prov_ctx_st *pctx = NULL;
473 for (; in->function_id != 0; in++)
474 switch (in->function_id) {
475 case OSSL_FUNC_CORE_PUT_ERROR:
476 c_put_error = OSSL_get_core_put_error(in);
482 if ((pctx = malloc(sizeof(*pctx))) == NULL) {
484 * ALEA IACTA EST, if the core retrieves the reason table
485 * regardless, that string will be displayed, otherwise not.
487 c_put_error(handle, E_MALLOC, __FILE__, __LINE__);
490 pctx->handle = handle;
494 This relies on a few things existing in F<openssl/core_numbers.h>:
496 #define OSSL_OP_BAR 4711
498 #define OSSL_FUNC_BAR_NEWCTX 1
499 typedef void *(OSSL_OP_bar_newctx_fn)(void *provctx);
500 static ossl_inline OSSL_get_bar_newctx(const OSSL_DISPATCH *opf)
501 { return (OSSL_OP_bar_newctx_fn *)opf->function; }
503 #define OSSL_FUNC_BAR_FREECTX 2
504 typedef void (OSSL_OP_bar_freectx_fn)(void *ctx);
505 static ossl_inline OSSL_get_bar_newctx(const OSSL_DISPATCH *opf)
506 { return (OSSL_OP_bar_freectx_fn *)opf->function; }
508 #define OSSL_FUNC_BAR_INIT 3
509 typedef void *(OSSL_OP_bar_init_fn)(void *ctx);
510 static ossl_inline OSSL_get_bar_init(const OSSL_DISPATCH *opf)
511 { return (OSSL_OP_bar_init_fn *)opf->function; }
513 #define OSSL_FUNC_BAR_UPDATE 4
514 typedef void *(OSSL_OP_bar_update_fn)(void *ctx,
515 unsigned char *in, size_t inl);
516 static ossl_inline OSSL_get_bar_update(const OSSL_DISPATCH *opf)
517 { return (OSSL_OP_bar_update_fn *)opf->function; }
519 #define OSSL_FUNC_BAR_FINAL 5
520 typedef void *(OSSL_OP_bar_final_fn)(void *ctx);
521 static ossl_inline OSSL_get_bar_final(const OSSL_DISPATCH *opf)
522 { return (OSSL_OP_bar_final_fn *)opf->function; }
530 The concept of providers and everything surrounding them was
531 introduced in OpenSSL 3.0.
535 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
537 Licensed under the Apache License 2.0 (the "License"). You may not use
538 this file except in compliance with the License. You can obtain a copy
539 in the file LICENSE in the source distribution or at
540 L<https://www.openssl.org/source/license.html>.