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_get_param_types(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 void core_put_error(const OSSL_PROVIDER *prov,
24 uint32_t reason, const char *file, int line);
25 void core_add_error_vdata(const OSSL_PROVIDER *prov,
26 int num, va_list args);
27 OPENSSL_CTX *core_get_library_context(const OSSL_PROVIDER *prov);
30 * Some OpenSSL functionality is directly offered to providers via
33 void *CRYPTO_malloc(size_t num, const char *file, int line);
34 void *CRYPTO_zalloc(size_t num, const char *file, int line);
35 void *CRYPTO_memdup(const void *str, size_t siz,
36 const char *file, int line);
37 char *CRYPTO_strdup(const char *str, const char *file, int line);
38 char *CRYPTO_strndup(const char *str, size_t s,
39 const char *file, int line);
40 void CRYPTO_free(void *ptr, const char *file, int line);
41 void CRYPTO_clear_free(void *ptr, size_t num,
42 const char *file, int line);
43 void *CRYPTO_realloc(void *addr, size_t num,
44 const char *file, int line);
45 void *CRYPTO_clear_realloc(void *addr, size_t old_num, size_t num,
46 const char *file, int line);
47 void *CRYPTO_secure_malloc(size_t num, const char *file, int line);
48 void *CRYPTO_secure_zalloc(size_t num, const char *file, int line);
49 void CRYPTO_secure_free(void *ptr, const char *file, int line);
50 void CRYPTO_secure_clear_free(void *ptr, size_t num,
51 const char *file, int line);
52 int CRYPTO_secure_allocated(const void *ptr);
53 void OPENSSL_cleanse(void *ptr, size_t len);
54 unsigned char *OPENSSL_hexstr2buf(const char *str, long *len);
56 /* Functions offered by the provider to libcrypto */
57 void provider_teardown(void *provctx);
58 const OSSL_ITEM *provider_get_param_types(void *provctx);
59 int provider_get_params(void *provctx, OSSL_PARAM params[]);
60 const OSSL_ALGORITHM *provider_query_operation(void *provctx,
63 const OSSL_ITEM *provider_get_reason_strings(void *provctx);
67 All "functions" mentioned here are passed as function pointers between
68 F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays, in the call
69 of the provider initialization function. See L<provider(7)/Provider>
70 for a description of the initialization function.
72 All these "functions" have a corresponding function type definition
73 named B<OSSL_{name}_fn>, and a helper function to retrieve the
74 function pointer from a B<OSSL_DISPATCH> element named
76 For example, the "function" core_get_param_types() has these:
79 (OSSL_core_get_param_types_fn)(const OSSL_PROVIDER *prov);
80 static ossl_inline OSSL_NAME_core_get_param_types_fn
81 OSSL_get_core_get_param_types(const OSSL_DISPATCH *opf);
83 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
84 macros in L<openssl-core_numbers.h(7)>, as follows:
86 For I<in> (the B<OSSL_DISPATCH> array passed from F<libcrypto> to the
89 core_get_param_types OSSL_FUNC_CORE_GET_PARAM_TYPES
90 core_get_params OSSL_FUNC_CORE_GET_PARAMS
91 core_thread_start OSSL_FUNC_CORE_THREAD_START
92 core_put_error OSSL_FUNC_CORE_PUT_ERROR
93 core_add_error_vdata OSSL_FUNC_CORE_ADD_ERROR_VDATA
94 core_get_library_context OSSL_FUNC_CORE_GET_LIBRARY_CONTEXT
95 CRYPTO_malloc OSSL_FUNC_CRYPTO_MALLOC
96 CRYPTO_zalloc OSSL_FUNC_CRYPTO_ZALLOC
97 CRYPTO_memdup OSSL_FUNC_CRYPTO_MEMDUP
98 CRYPTO_strdup OSSL_FUNC_CRYPTO_STRDUP
99 CRYPTO_strndup OSSL_FUNC_CRYPTO_STRNDUP
100 CRYPTO_free OSSL_FUNC_CRYPTO_FREE
101 CRYPTO_clear_free OSSL_FUNC_CRYPTO_CLEAR_FREE
102 CRYPTO_realloc OSSL_FUNC_CRYPTO_REALLOC
103 CRYPTO_clear_realloc OSSL_FUNC_CRYPTO_CLEAR_REALLOC
104 CRYPTO_secure_malloc OSSL_FUNC_CRYPTO_SECURE_MALLOC
105 CRYPTO_secure_zalloc OSSL_FUNC_CRYPTO_SECURE_ZALLOC
106 CRYPTO_secure_free OSSL_FUNC_CRYPTO_SECURE_FREE
107 CRYPTO_secure_clear_free OSSL_FUNC_CRYPTO_SECURE_CLEAR_FREE
108 CRYPTO_secure_allocated OSSL_FUNC_CRYPTO_SECURE_ALLOCATED
109 OPENSSL_cleanse OSSL_FUNC_OPENSSL_CLEANSE
110 OPENSSL_hexstr2buf OSSL_FUNC_OPENSSL_HEXSTR2BUF
112 For I<*out> (the B<OSSL_DISPATCH> array passed from the provider to
115 provider_teardown OSSL_FUNC_PROVIDER_TEARDOWN
116 provider_get_param_types OSSL_FUNC_PROVIDER_GET_PARAM_TYPES
117 provider_get_params OSSL_FUNC_PROVIDER_GET_PARAMS
118 provider_query_operation OSSL_FUNC_PROVIDER_QUERY_OPERATION
119 provider_get_reason_strings OSSL_FUNC_PROVIDER_GET_REASON_STRINGS
121 =head2 Core functions
123 core_get_param_types() returns a constant array of descriptor
124 B<OSSL_PARAM>, for parameters that core_get_params() can handle.
126 core_get_params() retrieves I<prov> parameters from the core.
127 See L</Core parameters> below for a description of currently known
130 =for comment core_thread_start() TBA
132 core_put_error() is used to report an error back to the core, with
133 reference to the provider object I<prov>.
134 The I<reason> is a number defined by the provider and used to index
135 the reason strings table that's returned by
136 provider_get_reason_strings().
137 I<file> and I<line> may also be passed to indicate exactly where the
138 error occured or was reported.
139 This corresponds to the OpenSSL function L<ERR_put_error(3)>.
141 core_add_error_vdata() is used to add additional text data to an
142 error already reported with core_put_error().
143 It takes I<num> strings in a B<va_list> and concatenates them.
144 Provider authors will have to write the corresponding variadic
147 core_get_library_context() retrieves the library context in which the
148 B<OSSL_PROVIDER> object I<prov> is stored.
149 This may sometimes be useful if the provider wishes to store a
150 reference to its context in the same library context.
152 CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_memdup(), CRYPTO_strdup(),
153 CRYPTO_strndup(), CRYPTO_free(), CRYPTO_clear_free(),
154 CRYPTO_realloc(), CRYPTO_clear_realloc(), CRYPTO_secure_malloc(),
155 CRYPTO_secure_zalloc(), CRYPTO_secure_free(),
156 CRYPTO_secure_clear_free(), CRYPTO_secure_allocated(),
157 OPENSSL_cleanse(), and OPENSSL_hexstr2buf() correspond exactly to the
158 public functions with the same name.
159 As a matter of fact, the pointers in the B<OSSL_DISPATCH> array are
160 direct pointers to those public functions.
162 =head2 Provider functions
164 provider_teardown() is called when a provider is shut down and removed
165 from the core's provider store.
166 It must free the passed I<provctx>.
168 provider_get_param_types() should return a constant array of
169 descriptor B<OSSL_PARAM>, for parameters that provider_get_params()
172 provider_get_params() should process the B<OSSL_PARAM> array
173 I<params>, setting the values of the parameters it understands.
175 provider_query_operation() should return a constant B<OSSL_ALGORITHM>
176 that corresponds to the given I<operation_id>.
177 It should indicate if the core may store a reference to this array by
178 setting I<*no_store> to 0 (core may store a reference) or 1 (core may
179 not store a reference).
181 provider_get_reason_strings() should return a constant B<OSSL_ITEM>
182 array that provides reason strings for reason codes the provider may
183 use when reporting errors using core_put_error().
185 None of these functions are mandatory, but a provider is fairly
186 useless without at least provider_query_operation(), and
187 provider_get_param_types() is fairly useless if not accompanied by
188 provider_get_params().
190 =head2 Core parameters
192 core_get_params() understands the following known parameters:
196 =item "openssl-version"
198 This is a B<OSSL_PARAM_UTF8_PTR> type of parameter, pointing at the
199 OpenSSL libraries' full version string, i.e. the string expanded from
200 the macro B<OPENSSL_VERSION_STR>.
202 =item "provider-name"
204 This is a B<OSSL_PARAM_UTF8_PTR> type of parameter, pointing at the
205 OpenSSL libraries' idea of what the calling provider is called.
209 Additionally, provider specific configuration parameters from the
210 config file are available, in dotted name form.
211 The dotted name form is a concatenation of section names and final
212 config command name separated by periods.
214 For example, let's say we have the following config example:
216 openssl_conf = openssl_init
219 providers = providers_sect
233 The provider will have these additional parameters available:
239 pointing at the string "1"
243 pointing at the string "2"
247 pointing at the string "str"
251 pointing at the string "foo,bar"
255 For more information on handling parameters, see L<OSSL_PARAM(3)> as
256 L<OSSL_PARAM_int(3)>.
260 This is an example of a simple provider made available as a
261 dynamically loadable module.
262 It implements the fictitious algorithm C<FOO> for the fictitious
266 #include <openssl/core.h>
267 #include <openssl/core_numbers.h>
269 /* Errors used in this provider */
272 static const OSSL_ITEM reasons[] = {
273 { E_MALLOC, "memory allocation failure" }.
274 { 0, NULL } /* Termination */
278 * To ensure we get the function signature right, forward declare
279 * them using function types provided by openssl/core_numbers.h
281 OSSL_OP_bar_newctx_fn foo_newctx;
282 OSSL_OP_bar_freectx_fn foo_freectx;
283 OSSL_OP_bar_init_fn foo_init;
284 OSSL_OP_bar_update_fn foo_update;
285 OSSL_OP_bar_final_fn foo_final;
287 OSSL_provider_query_operation_fn p_query;
288 OSSL_provider_get_reason_strings_fn p_reasons;
289 OSSL_provider_teardown_fn p_teardown;
291 OSSL_provider_init_fn OSSL_provider_init;
293 OSSL_core_put_error *c_put_error = NULL;
295 /* Provider context */
300 /* operation context for the algorithm FOO */
302 struct prov_ctx_st *provctx;
306 static void *foo_newctx(void *provctx)
308 struct foo_ctx_st *fooctx = malloc(sizeof(*fooctx));
311 fooctx->provctx = provctx;
313 c_put_error(provctx->prov, E_MALLOC, __FILE__, __LINE__);
317 static void foo_freectx(void *fooctx)
322 static int foo_init(void *vfooctx)
324 struct foo_ctx_st *fooctx = vfooctx;
329 static int foo_update(void *vfooctx, unsigned char *in, size_t inl)
331 struct foo_ctx_st *fooctx = vfooctx;
333 /* did you expect something serious? */
336 for (; inl-- > 0; in++)
341 static int foo_final(void *vfooctx)
343 struct foo_ctx_st *fooctx = vfooctx;
348 static const OSSL_DISPATCH foo_fns[] = {
349 { OSSL_FUNC_BAR_NEWCTX, (void (*)(void))foo_newctx },
350 { OSSL_FUNC_BAR_FREECTX, (void (*)(void))foo_freectx },
351 { OSSL_FUNC_BAR_INIT, (void (*)(void))foo_init },
352 { OSSL_FUNC_BAR_UPDATE, (void (*)(void))foo_update },
353 { OSSL_FUNC_BAR_FINAL, (void (*)(void))foo_final },
357 static const OSSL_ALGORITHM bars[] = {
358 { "FOO", "provider=chumbawamba", foo_fns },
362 static const OSSL_ALGORITHM *p_query(void *provctx, int operation_id,
365 switch (operation_id) {
372 static const OSSL_ITEM *p_reasons(void *provctx)
377 static void p_teardown(void *provctx)
382 static const OSSL_DISPATCH prov_fns[] = {
383 { OSSL_FUNC_PROVIDER_TEARDOWN, (void (*)(void))p_teardown },
384 { OSSL_FUNC_PROVIDER_QUERY_OPERATION, (void (*)(void))p_query },
385 { OSSL_FUNC_PROVIDER_GET_REASON_STRINGS, (void (*)(void))p_reasons },
389 int OSSL_provider_init(const OSSL_PROVIDER *provider,
390 const OSSL_DISPATCH *in,
391 const OSSL_DISPATCH **out,
394 struct prov_ctx_st *pctx = NULL;
396 for (; in->function_id != 0; in++)
397 switch (in->function_id) {
398 case OSSL_FUNC_CORE_PUT_ERROR:
399 c_put_error = OSSL_get_core_put_error(in);
405 if ((pctx = malloc(sizeof(*pctx))) == NULL) {
407 * ALEA IACTA EST, if the core retrieves the reason table
408 * regardless, that string will be displayed, otherwise not.
410 c_put_error(provider, E_MALLOC, __FILE__, __LINE__);
416 This relies on a few things existing in F<openssl/core_numbers.h>:
418 #define OSSL_OP_BAR 4711
420 #define OSSL_FUNC_BAR_NEWCTX 1
421 typedef void *(OSSL_OP_bar_newctx_fn)(void *provctx);
422 static ossl_inline OSSL_get_bar_newctx(const OSSL_DISPATCH *opf)
423 { return (OSSL_OP_bar_newctx_fn *)opf->function; }
425 #define OSSL_FUNC_BAR_FREECTX 2
426 typedef void (OSSL_OP_bar_freectx_fn)(void *ctx);
427 static ossl_inline OSSL_get_bar_newctx(const OSSL_DISPATCH *opf)
428 { return (OSSL_OP_bar_freectx_fn *)opf->function; }
430 #define OSSL_FUNC_BAR_INIT 3
431 typedef void *(OSSL_OP_bar_init_fn)(void *ctx);
432 static ossl_inline OSSL_get_bar_init(const OSSL_DISPATCH *opf)
433 { return (OSSL_OP_bar_init_fn *)opf->function; }
435 #define OSSL_FUNC_BAR_UPDATE 4
436 typedef void *(OSSL_OP_bar_update_fn)(void *ctx,
437 unsigned char *in, size_t inl);
438 static ossl_inline OSSL_get_bar_update(const OSSL_DISPATCH *opf)
439 { return (OSSL_OP_bar_update_fn *)opf->function; }
441 #define OSSL_FUNC_BAR_FINAL 5
442 typedef void *(OSSL_OP_bar_final_fn)(void *ctx);
443 static ossl_inline OSSL_get_bar_final(const OSSL_DISPATCH *opf)
444 { return (OSSL_OP_bar_final_fn *)opf->function; }
452 The concept of providers and everything surrounding them was
453 introduced in OpenSSL 3.0.
457 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
459 Licensed under the Apache License 2.0 (the "License"). You may not use
460 this file except in compliance with the License. You can obtain a copy
461 in the file LICENSE in the source distribution or at
462 L<https://www.openssl.org/source/license.html>.