1PROVIDER-BASE(7ossl)                OpenSSL               PROVIDER-BASE(7ossl)
2
3
4

NAME

6       provider-base - The basic OpenSSL library <-> provider functions
7

SYNOPSIS

9        #include <openssl/core_dispatch.h>
10
11        /*
12         * None of these are actual functions, but are displayed like this for
13         * the function signatures for functions that are offered as function
14         * pointers in OSSL_DISPATCH arrays.
15         */
16
17        /* Functions offered by libcrypto to the providers */
18        const OSSL_ITEM *core_gettable_params(const OSSL_CORE_HANDLE *handle);
19        int core_get_params(const OSSL_CORE_HANDLE *handle, OSSL_PARAM params[]);
20
21        typedef void (*OSSL_thread_stop_handler_fn)(void *arg);
22        int core_thread_start(const OSSL_CORE_HANDLE *handle,
23                              OSSL_thread_stop_handler_fn handfn,
24                              void *arg);
25
26        OPENSSL_CORE_CTX *core_get_libctx(const OSSL_CORE_HANDLE *handle);
27        void core_new_error(const OSSL_CORE_HANDLE *handle);
28        void core_set_error_debug(const OSSL_CORE_HANDLE *handle,
29                                  const char *file, int line, const char *func);
30        void core_vset_error(const OSSL_CORE_HANDLE *handle,
31                             uint32_t reason, const char *fmt, va_list args);
32
33        int core_obj_add_sigid(const OSSL_CORE_HANDLE *prov, const char  *sign_name,
34                               const char *digest_name, const char *pkey_name);
35        int core_obj_create(const OSSL_CORE_HANDLE *handle, const char *oid,
36                            const char *sn, const char *ln);
37
38        /*
39         * Some OpenSSL functionality is directly offered to providers via
40         * dispatch
41         */
42        void *CRYPTO_malloc(size_t num, const char *file, int line);
43        void *CRYPTO_zalloc(size_t num, const char *file, int line);
44        void CRYPTO_free(void *ptr, const char *file, int line);
45        void CRYPTO_clear_free(void *ptr, size_t num,
46                               const char *file, int line);
47        void *CRYPTO_realloc(void *addr, size_t num,
48                             const char *file, int line);
49        void *CRYPTO_clear_realloc(void *addr, size_t old_num, size_t num,
50                                   const char *file, int line);
51        void *CRYPTO_secure_malloc(size_t num, const char *file, int line);
52        void *CRYPTO_secure_zalloc(size_t num, const char *file, int line);
53        void CRYPTO_secure_free(void *ptr, const char *file, int line);
54        void CRYPTO_secure_clear_free(void *ptr, size_t num,
55                                      const char *file, int line);
56        int CRYPTO_secure_allocated(const void *ptr);
57        void OPENSSL_cleanse(void *ptr, size_t len);
58
59        unsigned char *OPENSSL_hexstr2buf(const char *str, long *buflen);
60
61        OSSL_CORE_BIO *BIO_new_file(const char *filename, const char *mode);
62        OSSL_CORE_BIO *BIO_new_membuf(const void *buf, int len);
63        int BIO_read_ex(OSSL_CORE_BIO *bio, void *data, size_t data_len,
64                        size_t *bytes_read);
65        int BIO_write_ex(OSSL_CORE_BIO *bio, const void *data, size_t data_len,
66                         size_t *written);
67        int BIO_up_ref(OSSL_CORE_BIO *bio);
68        int BIO_free(OSSL_CORE_BIO *bio);
69        int BIO_vprintf(OSSL_CORE_BIO *bio, const char *format, va_list args);
70        int BIO_vsnprintf(char *buf, size_t n, const char *fmt, va_list args);
71
72        void OSSL_SELF_TEST_set_callback(OSSL_LIB_CTX *libctx, OSSL_CALLBACK *cb,
73                                         void *cbarg);
74
75        size_t get_entropy(const OSSL_CORE_HANDLE *handle,
76                           unsigned char **pout, int entropy,
77                           size_t min_len, size_t max_len);
78        void cleanup_entropy(const OSSL_CORE_HANDLE *handle,
79                             unsigned char *buf, size_t len);
80        size_t get_nonce(const OSSL_CORE_HANDLE *handle,
81                         unsigned char **pout, size_t min_len, size_t max_len,
82                         const void *salt, size_t salt_len);
83        void cleanup_nonce(const OSSL_CORE_HANDLE *handle,
84                           unsigned char *buf, size_t len);
85
86        /* Functions for querying the providers in the application library context */
87        int provider_register_child_cb(const OSSL_CORE_HANDLE *handle,
88                            int (*create_cb)(const OSSL_CORE_HANDLE *provider,
89                                             void *cbdata),
90                            int (*remove_cb)(const OSSL_CORE_HANDLE *provider,
91                                             void *cbdata),
92                            int (*global_props_cb)(const char *props, void *cbdata),
93                            void *cbdata);
94        void provider_deregister_child_cb(const OSSL_CORE_HANDLE *handle);
95        const char *provider_name(const OSSL_CORE_HANDLE *prov);
96        void *provider_get0_provider_ctx(const OSSL_CORE_HANDLE *prov);
97        const OSSL_DISPATCH *provider_get0_dispatch(const OSSL_CORE_HANDLE *prov);
98        int provider_up_ref(const OSSL_CORE_HANDLE *prov, int activate);
99        int provider_free(const OSSL_CORE_HANDLE *prov, int deactivate);
100
101        /* Functions offered by the provider to libcrypto */
102        void provider_teardown(void *provctx);
103        const OSSL_ITEM *provider_gettable_params(void *provctx);
104        int provider_get_params(void *provctx, OSSL_PARAM params[]);
105        const OSSL_ALGORITHM *provider_query_operation(void *provctx,
106                                                       int operation_id,
107                                                       const int *no_store);
108        void provider_unquery_operation(void *provctx, int operation_id,
109                                        const OSSL_ALGORITHM *algs);
110        const OSSL_ITEM *provider_get_reason_strings(void *provctx);
111        int provider_get_capabilities(void *provctx, const char *capability,
112                                      OSSL_CALLBACK *cb, void *arg);
113        int provider_self_test(void *provctx);
114

DESCRIPTION

116       All "functions" mentioned here are passed as function pointers between
117       libcrypto and the provider in OSSL_DISPATCH arrays, in the call of the
118       provider initialization function.  See "Provider" in provider(7) for a
119       description of the initialization function. They are known as
120       "upcalls".
121
122       All these "functions" have a corresponding function type definition
123       named OSSL_FUNC_{name}_fn, and a helper function to retrieve the
124       function pointer from a OSSL_DISPATCH element named OSSL_FUNC_{name}.
125       For example, the "function" core_gettable_params() has these:
126
127        typedef OSSL_PARAM *
128            (OSSL_FUNC_core_gettable_params_fn)(const OSSL_CORE_HANDLE *handle);
129        static ossl_inline OSSL_NAME_core_gettable_params_fn
130            OSSL_FUNC_core_gettable_params(const OSSL_DISPATCH *opf);
131
132       OSSL_DISPATCH arrays are indexed by numbers that are provided as macros
133       in openssl-core_dispatch.h(7), as follows:
134
135       For in (the OSSL_DISPATCH array passed from libcrypto to the provider):
136
137        core_gettable_params           OSSL_FUNC_CORE_GETTABLE_PARAMS
138        core_get_params                OSSL_FUNC_CORE_GET_PARAMS
139        core_thread_start              OSSL_FUNC_CORE_THREAD_START
140        core_get_libctx                OSSL_FUNC_CORE_GET_LIBCTX
141        core_new_error                 OSSL_FUNC_CORE_NEW_ERROR
142        core_set_error_debug           OSSL_FUNC_CORE_SET_ERROR_DEBUG
143        core_vset_error                OSSL_FUNC_CORE_VSET_ERROR
144        core_obj_add_sigid             OSSL_FUNC_CORE_OBJ_ADD_SIGID
145        core_obj_create                OSSL_FUNC_CORE_OBJ_CREATE
146        CRYPTO_malloc                  OSSL_FUNC_CRYPTO_MALLOC
147        CRYPTO_zalloc                  OSSL_FUNC_CRYPTO_ZALLOC
148        CRYPTO_free                    OSSL_FUNC_CRYPTO_FREE
149        CRYPTO_clear_free              OSSL_FUNC_CRYPTO_CLEAR_FREE
150        CRYPTO_realloc                 OSSL_FUNC_CRYPTO_REALLOC
151        CRYPTO_clear_realloc           OSSL_FUNC_CRYPTO_CLEAR_REALLOC
152        CRYPTO_secure_malloc           OSSL_FUNC_CRYPTO_SECURE_MALLOC
153        CRYPTO_secure_zalloc           OSSL_FUNC_CRYPTO_SECURE_ZALLOC
154        CRYPTO_secure_free             OSSL_FUNC_CRYPTO_SECURE_FREE
155        CRYPTO_secure_clear_free       OSSL_FUNC_CRYPTO_SECURE_CLEAR_FREE
156        CRYPTO_secure_allocated        OSSL_FUNC_CRYPTO_SECURE_ALLOCATED
157        BIO_new_file                   OSSL_FUNC_BIO_NEW_FILE
158        BIO_new_mem_buf                OSSL_FUNC_BIO_NEW_MEMBUF
159        BIO_read_ex                    OSSL_FUNC_BIO_READ_EX
160        BIO_write_ex                   OSSL_FUNC_BIO_WRITE_EX
161        BIO_up_ref                     OSSL_FUNC_BIO_UP_REF
162        BIO_free                       OSSL_FUNC_BIO_FREE
163        BIO_vprintf                    OSSL_FUNC_BIO_VPRINTF
164        BIO_vsnprintf                  OSSL_FUNC_BIO_VSNPRINTF
165        BIO_puts                       OSSL_FUNC_BIO_PUTS
166        BIO_gets                       OSSL_FUNC_BIO_GETS
167        BIO_ctrl                       OSSL_FUNC_BIO_CTRL
168        OPENSSL_cleanse                OSSL_FUNC_OPENSSL_CLEANSE
169        OSSL_SELF_TEST_set_callback    OSSL_FUNC_SELF_TEST_CB
170        ossl_rand_get_entropy          OSSL_FUNC_GET_ENTROPY
171        ossl_rand_cleanup_entropy      OSSL_FUNC_CLEANUP_ENTROPY
172        ossl_rand_get_nonce            OSSL_FUNC_GET_NONCE
173        ossl_rand_cleanup_nonce        OSSL_FUNC_CLEANUP_NONCE
174        provider_register_child_cb     OSSL_FUNC_PROVIDER_REGISTER_CHILD_CB
175        provider_deregister_child_cb   OSSL_FUNC_PROVIDER_DEREGISTER_CHILD_CB
176        provider_name                  OSSL_FUNC_PROVIDER_NAME
177        provider_get0_provider_ctx     OSSL_FUNC_PROVIDER_GET0_PROVIDER_CTX
178        provider_get0_dispatch         OSSL_FUNC_PROVIDER_GET0_DISPATCH
179        provider_up_ref                OSSL_FUNC_PROVIDER_UP_REF
180        provider_free                  OSSL_FUNC_PROVIDER_FREE
181
182       For *out (the OSSL_DISPATCH array passed from the provider to
183       libcrypto):
184
185        provider_teardown              OSSL_FUNC_PROVIDER_TEARDOWN
186        provider_gettable_params       OSSL_FUNC_PROVIDER_GETTABLE_PARAMS
187        provider_get_params            OSSL_FUNC_PROVIDER_GET_PARAMS
188        provider_query_operation       OSSL_FUNC_PROVIDER_QUERY_OPERATION
189        provider_unquery_operation     OSSL_FUNC_PROVIDER_UNQUERY_OPERATION
190        provider_get_reason_strings    OSSL_FUNC_PROVIDER_GET_REASON_STRINGS
191        provider_get_capabilities      OSSL_FUNC_PROVIDER_GET_CAPABILITIES
192        provider_self_test             OSSL_FUNC_PROVIDER_SELF_TEST
193
194   Core functions
195       core_gettable_params() returns a constant array of descriptor
196       OSSL_PARAM, for parameters that core_get_params() can handle.
197
198       core_get_params() retrieves parameters from the core for the given
199       handle.  See "Core parameters" below for a description of currently
200       known parameters.
201
202       The core_thread_start() function informs the core that the provider has
203       stated an interest in the current thread. The core will inform the
204       provider when the thread eventually stops. It must be passed the handle
205       for this provider, as well as a callback handfn which will be called
206       when the thread stops. The callback will subsequently be called, with
207       the supplied argument arg, from the thread that is stopping and gets
208       passed the provider context as an argument. This may be useful to
209       perform thread specific clean up such as freeing thread local
210       variables.
211
212       core_get_libctx() retrieves the core context in which the library
213       object for the current provider is stored, accessible through the
214       handle.  This function is useful only for built-in providers such as
215       the default provider. Never cast this to OSSL_LIB_CTX in a provider
216       that is not built-in as the OSSL_LIB_CTX of the library loading the
217       provider might be a completely different structure than the
218       OSSL_LIB_CTX of the library the provider is linked to. Use
219       OSSL_LIB_CTX_new_child(3) instead to obtain a proper library context
220       that is linked to the application library context.
221
222       core_new_error(), core_set_error_debug() and core_vset_error() are
223       building blocks for reporting an error back to the core, with reference
224       to the handle.
225
226       core_new_error()
227           allocates a new thread specific error record.
228
229           This corresponds to the OpenSSL function ERR_new(3).
230
231       core_set_error_debug()
232           sets debugging information in the current thread specific error
233           record.  The debugging information includes the name of the file
234           file, the line line and the function name func where the error
235           occurred.
236
237           This corresponds to the OpenSSL function ERR_set_debug(3).
238
239       core_vset_error()
240           sets the reason for the error, along with any addition data.  The
241           reason is a number defined by the provider and used to index the
242           reason strings table that's returned by
243           provider_get_reason_strings().  The additional data is given as a
244           format string fmt and a set of arguments args, which are treated in
245           the same manner as with BIO_vsnprintf().  file and line may also be
246           passed to indicate exactly where the error occurred or was
247           reported.
248
249           This corresponds to the OpenSSL function ERR_vset_error(3).
250
251       The core_obj_create() function registers a new OID and associated short
252       name sn and long name ln for the given handle. It is similar to the
253       OpenSSL function OBJ_create(3) except that it returns 1 on success or 0
254       on failure.  It will treat as success the case where the OID already
255       exists (even if the short name sn or long name ln provided as arguments
256       differ from those associated with the existing OID, in which case the
257       new names are not associated).  This function is not thread safe.
258
259       The core_obj_add_sigid() function registers a new composite signature
260       algorithm (sign_name) consisting of an underlying signature algorithm
261       (pkey_name) and digest algorithm (digest_name) for the given handle. It
262       assumes that the OIDs for the composite signature algorithm as well as
263       for the underlying signature and digest algorithms are either already
264       known to OpenSSL or have been registered via a call to
265       core_obj_create(). It corresponds to the OpenSSL function
266       OBJ_add_sigid(3), except that the objects are identified by name rather
267       than a numeric NID. Any name (OID, short name or long name) can be used
268       to identify the object. It will treat as success the case where the
269       composite signature algorithm already exists (even if registered
270       against a different underlying signature or digest algorithm). For
271       digest_name, NULL or an empty string is permissible for signature
272       algorithms that do not need a digest to operate correctly. The function
273       returns 1 on success or 0 on failure.  This function is not thread
274       safe.
275
276       CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_free(), CRYPTO_clear_free(),
277       CRYPTO_realloc(), CRYPTO_clear_realloc(), CRYPTO_secure_malloc(),
278       CRYPTO_secure_zalloc(), CRYPTO_secure_free(),
279       CRYPTO_secure_clear_free(), CRYPTO_secure_allocated(), BIO_new_file(),
280       BIO_new_mem_buf(), BIO_read_ex(), BIO_write_ex(), BIO_up_ref(),
281       BIO_free(), BIO_vprintf(), BIO_vsnprintf(), BIO_gets(), BIO_puts(),
282       BIO_ctrl(), OPENSSL_cleanse() and OPENSSL_hexstr2buf() correspond
283       exactly to the public functions with the same name.  As a matter of
284       fact, the pointers in the OSSL_DISPATCH array are typically direct
285       pointers to those public functions. Note that the BIO functions take an
286       OSSL_CORE_BIO type rather than the standard BIO type. This is to ensure
287       that a provider does not mix BIOs from the core with BIOs used on the
288       provider side (the two are not compatible).
289       OSSL_SELF_TEST_set_callback() is used to set an optional callback that
290       can be passed into a provider. This may be ignored by a provider.
291
292       get_entropy() retrieves seeding material from the operating system.
293       The seeding material will have at least entropy bytes of randomness and
294       the output will have at least min_len and at most max_len bytes.  The
295       buffer address is stored in *pout and the buffer length is returned to
296       the caller.  On error, zero is returned.
297
298       cleanup_entropy() is used to clean up and free the buffer returned by
299       get_entropy().  The entropy pointer returned by get_entropy() is passed
300       in buf and its length in len.
301
302       get_nonce() retrieves a nonce using the passed salt parameter of length
303       salt_len and operating system specific information.  The salt should
304       contain uniquely identifying information and this is included, in an
305       unspecified manner, as part of the output.  The output is stored in a
306       buffer which contrains at least min_len and at most max_len bytes.  The
307       buffer address is stored in *pout and the buffer length returned to the
308       caller.  On error, zero is returned.
309
310       cleanup_nonce() is used to clean up and free the buffer returned by
311       get_nonce().  The nonce pointer returned by get_nonce() is passed in
312       buf and its length in len.
313
314       provider_register_child_cb() registers callbacks for being informed
315       about the loading and unloading of providers in the application's
316       library context.  handle is this provider's handle and cbdata is this
317       provider's data that will be passed back to the callbacks. It returns 1
318       on success or 0 otherwise. These callbacks may be called while holding
319       locks in libcrypto. In order to avoid deadlocks the callback
320       implementation must not be long running and must not call other OpenSSL
321       API functions or upcalls.
322
323       create_cb is a callback that will be called when a new provider is
324       loaded into the application's library context. It is also called for
325       any providers that are already loaded at the point that this callback
326       is registered. The callback is passed the handle being used for the new
327       provider being loadded and this provider's data in cbdata. It should
328       return 1 on success or 0 on failure.
329
330       remove_cb is a callback that will be called when a new provider is
331       unloaded from the application's library context. It is passed the
332       handle being used for the provider being unloaded and this provider's
333       data in cbdata. It should return 1 on success or 0 on failure.
334
335       global_props_cb is a callback that will be called when the global
336       properties from the parent library context are changed. It should
337       return 1 on success or 0 on failure.
338
339       provider_deregister_child_cb() unregisters callbacks previously
340       registered via provider_register_child_cb(). If
341       provider_register_child_cb() has been called then
342       provider_deregister_child_cb() should be called at or before the point
343       that this provider's teardown function is called.
344
345       provider_name() returns a string giving the name of the provider
346       identified by handle.
347
348       provider_get0_provider_ctx() returns the provider context that is
349       associated with the provider identified by prov.
350
351       provider_get0_dispatch() gets the dispatch table registered by the
352       provider identified by prov when it initialised.
353
354       provider_up_ref() increments the reference count on the provider prov.
355       If activate is nonzero then the provider is also loaded if it is not
356       already loaded. It returns 1 on success or 0 on failure.
357
358       provider_free() decrements the reference count on the provider prov. If
359       deactivate is nonzero then the provider is also unloaded if it is not
360       already loaded. It returns 1 on success or 0 on failure.
361
362   Provider functions
363       provider_teardown() is called when a provider is shut down and removed
364       from the core's provider store.  It must free the passed provctx.
365
366       provider_gettable_params() should return a constant array of descriptor
367       OSSL_PARAM, for parameters that provider_get_params() can handle.
368
369       provider_get_params() should process the OSSL_PARAM array params,
370       setting the values of the parameters it understands.
371
372       provider_query_operation() should return a constant OSSL_ALGORITHM that
373       corresponds to the given operation_id.  It should indicate if the core
374       may store a reference to this array by setting *no_store to 0 (core may
375       store a reference) or 1 (core may not store a reference).
376
377       provider_unquery_operation() informs the provider that the result of a
378       provider_query_operation() is no longer directly required and that the
379       function pointers have been copied.  The operation_id should match that
380       passed to provider_query_operation() and algs should be its return
381       value.
382
383       provider_get_reason_strings() should return a constant OSSL_ITEM array
384       that provides reason strings for reason codes the provider may use when
385       reporting errors using core_put_error().
386
387       The provider_get_capabilities() function should call the callback cb
388       passing it a set of OSSL_PARAMs and the caller supplied argument arg.
389       The OSSL_PARAMs should provide details about the capability with the
390       name given in the capability argument relevant for the provider context
391       provctx. If a provider supports multiple capabilities with the given
392       name then it may call the callback multiple times (one for each
393       capability). Capabilities can be useful for describing the services
394       that a provider can offer. For further details see the "CAPABILITIES"
395       section below. It should return 1 on success or 0 on error.
396
397       The provider_self_test() function should perform known answer tests on
398       a subset of the algorithms that it uses, and may also verify the
399       integrity of the provider module. It should return 1 on success or 0 on
400       error. It will return 1 if this function is not used.
401
402       None of these functions are mandatory, but a provider is fairly useless
403       without at least provider_query_operation(), and
404       provider_gettable_params() is fairly useless if not accompanied by
405       provider_get_params().
406
407   Provider parameters
408       provider_get_params() can return the following provider parameters to
409       the core:
410
411       "name" (OSSL_PROV_PARAM_NAME) <UTF8 ptr>
412           This points to a string that should give a unique name for the
413           provider.
414
415       "version" (OSSL_PROV_PARAM_VERSION) <UTF8 ptr>
416           This points to a string that is a version number associated with
417           this provider.  OpenSSL in-built providers use OPENSSL_VERSION_STR,
418           but this may be different for any third party provider. This string
419           is for informational purposes only.
420
421       "buildinfo" (OSSL_PROV_PARAM_BUILDINFO) <UTF8 ptr>
422           This points to a string that is a build information associated with
423           this provider.  OpenSSL in-built providers use
424           OPENSSL_FULL_VERSION_STR, but this may be different for any third
425           party provider.
426
427       "status" (OSSL_PROV_PARAM_STATUS) <unsigned integer>
428           This returns 0 if the provider has entered an error state,
429           otherwise it returns 1.
430
431       provider_gettable_params() should return the above parameters.
432
433   Core parameters
434       core_get_params() can retrieve the following core parameters for each
435       provider:
436
437       "openssl-version" (OSSL_PROV_PARAM_CORE_VERSION) <UTF8 string ptr>
438           This points to the OpenSSL libraries' full version string, i.e. the
439           string expanded from the macro OPENSSL_VERSION_STR.
440
441       "provider-name" (OSSL_PROV_PARAM_CORE_PROV_NAME) <UTF8 string ptr>
442           This points to the OpenSSL libraries' idea of what the calling
443           provider is named.
444
445       "module-filename" (OSSL_PROV_PARAM_CORE_MODULE_FILENAME) <UTF8 string
446       ptr>
447           This points to a string containing the full filename of the
448           providers module file.
449
450       Additionally, provider specific configuration parameters from the
451       config file are available, in dotted name form.  The dotted name form
452       is a concatenation of section names and final config command name
453       separated by periods.
454
455       For example, let's say we have the following config example:
456
457        config_diagnostics = 1
458        openssl_conf = openssl_init
459
460        [openssl_init]
461        providers = providers_sect
462
463        [providers_sect]
464        foo = foo_sect
465
466        [foo_sect]
467        activate = 1
468        data1 = 2
469        data2 = str
470        more = foo_more
471
472        [foo_more]
473        data3 = foo,bar
474
475       The provider will have these additional parameters available:
476
477       "activate"
478           pointing at the string "1"
479
480       "data1"
481           pointing at the string "2"
482
483       "data2"
484           pointing at the string "str"
485
486       "more.data3"
487           pointing at the string "foo,bar"
488
489       For more information on handling parameters, see OSSL_PARAM(3) as
490       OSSL_PARAM_int(3).
491

CAPABILITIES

493       Capabilities describe some of the services that a provider can offer.
494       Applications can query the capabilities to discover those services.
495
496       "TLS-GROUP" Capability
497
498       The "TLS-GROUP" capability can be queried by libssl to discover the
499       list of TLS groups that a provider can support. Each group supported
500       can be used for key exchange (KEX) or key encapsulation method (KEM)
501       during a TLS handshake.  TLS clients can advertise the list of TLS
502       groups they support in the supported_groups extension, and TLS servers
503       can select a group from the offered list that they also support. In
504       this way a provider can add to the list of groups that libssl already
505       supports with additional ones.
506
507       Each TLS group that a provider supports should be described via the
508       callback passed in through the provider_get_capabilities function. Each
509       group should have the following details supplied (all are mandatory,
510       except OSSL_CAPABILITY_TLS_GROUP_IS_KEM):
511
512       "tls-group-name" (OSSL_CAPABILITY_TLS_GROUP_NAME) <UTF8 string>
513           The name of the group as given in the IANA TLS Supported Groups
514           registry
515           <https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8>.
516
517       "tls-group-name-internal" (OSSL_CAPABILITY_TLS_GROUP_NAME_INTERNAL)
518       <UTF8 string>
519           The name of the group as known by the provider. This could be the
520           same as the "tls-group-name", but does not have to be.
521
522       "tls-group-id" (OSSL_CAPABILITY_TLS_GROUP_ID) <unsigned integer>
523           The TLS group id value as given in the IANA TLS Supported Groups
524           registry.
525
526       "tls-group-alg" (OSSL_CAPABILITY_TLS_GROUP_ALG) <UTF8 string>
527           The name of a Key Management algorithm that the provider offers and
528           that should be used with this group. Keys created should be able to
529           support key exchange or key encapsulation method (KEM), as implied
530           by the optional OSSL_CAPABILITY_TLS_GROUP_IS_KEM flag.  The
531           algorithm must support key and parameter generation as well as the
532           key/parameter generation parameter, OSSL_PKEY_PARAM_GROUP_NAME. The
533           group name given via "tls-group-name-internal" above will be passed
534           via OSSL_PKEY_PARAM_GROUP_NAME when libssl wishes to generate
535           keys/parameters.
536
537       "tls-group-sec-bits" (OSSL_CAPABILITY_TLS_GROUP_SECURITY_BITS)
538       <unsigned integer>
539           The number of bits of security offered by keys in this group. The
540           number of bits should be comparable with the ones given in table 2
541           and 3 of the NIST SP800-57 document.
542
543       "tls-group-is-kem" (OSSL_CAPABILITY_TLS_GROUP_IS_KEM) <unsigned
544       integer>
545           Boolean flag to describe if the group should be used in key
546           exchange (KEX) mode (0, default) or in key encapsulation method
547           (KEM) mode (1).
548
549           This parameter is optional: if not specified, KEX mode is assumed
550           as the default mode for the group.
551
552           In KEX mode, in a typical Diffie-Hellman fashion, both sides
553           execute keygen then derive against the peer public key. To operate
554           in KEX mode, the group implementation must support the provider
555           functions as described in provider-keyexch(7).
556
557           In KEM mode, the client executes keygen and sends its public key,
558           the server executes encapsulate using the client's public key and
559           sends back the resulting ciphertext, finally the client executes
560           decapsulate to retrieve the same shared secret generated by the
561           server's encapsulate. To operate in KEM mode, the group
562           implementation must support the provider functions as described in
563           provider-kem(7).
564
565           Both in KEX and KEM mode, the resulting shared secret is then used
566           according to the protocol specification.
567
568       "tls-min-tls" (OSSL_CAPABILITY_TLS_GROUP_MIN_TLS) <integer>
569       "tls-max-tls" (OSSL_CAPABILITY_TLS_GROUP_MAX_TLS) <integer>
570       "tls-min-dtls" (OSSL_CAPABILITY_TLS_GROUP_MIN_DTLS) <integer>
571       "tls-max-dtls" (OSSL_CAPABILITY_TLS_GROUP_MAX_DTLS) <integer>
572           These parameters can be used to describe the minimum and maximum
573           TLS and DTLS versions supported by the group. The values equate to
574           the on-the-wire encoding of the various TLS versions. For example
575           TLSv1.3 is 0x0304 (772 decimal), and TLSv1.2 is 0x0303 (771
576           decimal). A 0 indicates that there is no defined minimum or
577           maximum. A -1 indicates that the group should not be used in that
578           protocol.
579

EXAMPLES

581       This is an example of a simple provider made available as a dynamically
582       loadable module.  It implements the fictitious algorithm "FOO" for the
583       fictitious operation "BAR".
584
585        #include <malloc.h>
586        #include <openssl/core.h>
587        #include <openssl/core_dispatch.h>
588
589        /* Errors used in this provider */
590        #define E_MALLOC       1
591
592        static const OSSL_ITEM reasons[] = {
593            { E_MALLOC, "memory allocation failure" }.
594            { 0, NULL } /* Termination */
595        };
596
597        /*
598         * To ensure we get the function signature right, forward declare
599         * them using function types provided by openssl/core_dispatch.h
600         */
601        OSSL_FUNC_bar_newctx_fn foo_newctx;
602        OSSL_FUNC_bar_freectx_fn foo_freectx;
603        OSSL_FUNC_bar_init_fn foo_init;
604        OSSL_FUNC_bar_update_fn foo_update;
605        OSSL_FUNC_bar_final_fn foo_final;
606
607        OSSL_FUNC_provider_query_operation_fn p_query;
608        OSSL_FUNC_provider_get_reason_strings_fn p_reasons;
609        OSSL_FUNC_provider_teardown_fn p_teardown;
610
611        OSSL_provider_init_fn OSSL_provider_init;
612
613        OSSL_FUNC_core_put_error *c_put_error = NULL;
614
615        /* Provider context */
616        struct prov_ctx_st {
617            OSSL_CORE_HANDLE *handle;
618        }
619
620        /* operation context for the algorithm FOO */
621        struct foo_ctx_st {
622            struct prov_ctx_st *provctx;
623            int b;
624        };
625
626        static void *foo_newctx(void *provctx)
627        {
628            struct foo_ctx_st *fooctx = malloc(sizeof(*fooctx));
629
630            if (fooctx != NULL)
631                fooctx->provctx = provctx;
632            else
633                c_put_error(provctx->handle, E_MALLOC, __FILE__, __LINE__);
634            return fooctx;
635        }
636
637        static void foo_freectx(void *fooctx)
638        {
639            free(fooctx);
640        }
641
642        static int foo_init(void *vfooctx)
643        {
644            struct foo_ctx_st *fooctx = vfooctx;
645
646            fooctx->b = 0x33;
647        }
648
649        static int foo_update(void *vfooctx, unsigned char *in, size_t inl)
650        {
651            struct foo_ctx_st *fooctx = vfooctx;
652
653            /* did you expect something serious? */
654            if (inl == 0)
655                return 1;
656            for (; inl-- > 0; in++)
657                *in ^= fooctx->b;
658            return 1;
659        }
660
661        static int foo_final(void *vfooctx)
662        {
663            struct foo_ctx_st *fooctx = vfooctx;
664
665            fooctx->b = 0x66;
666        }
667
668        static const OSSL_DISPATCH foo_fns[] = {
669            { OSSL_FUNC_BAR_NEWCTX, (void (*)(void))foo_newctx },
670            { OSSL_FUNC_BAR_FREECTX, (void (*)(void))foo_freectx },
671            { OSSL_FUNC_BAR_INIT, (void (*)(void))foo_init },
672            { OSSL_FUNC_BAR_UPDATE, (void (*)(void))foo_update },
673            { OSSL_FUNC_BAR_FINAL, (void (*)(void))foo_final },
674            { 0, NULL }
675        };
676
677        static const OSSL_ALGORITHM bars[] = {
678            { "FOO", "provider=chumbawamba", foo_fns },
679            { NULL, NULL, NULL }
680        };
681
682        static const OSSL_ALGORITHM *p_query(void *provctx, int operation_id,
683                                             int *no_store)
684        {
685            switch (operation_id) {
686            case OSSL_OP_BAR:
687                return bars;
688            }
689            return NULL;
690        }
691
692        static const OSSL_ITEM *p_reasons(void *provctx)
693        {
694            return reasons;
695        }
696
697        static void p_teardown(void *provctx)
698        {
699            free(provctx);
700        }
701
702        static const OSSL_DISPATCH prov_fns[] = {
703            { OSSL_FUNC_PROVIDER_TEARDOWN, (void (*)(void))p_teardown },
704            { OSSL_FUNC_PROVIDER_QUERY_OPERATION, (void (*)(void))p_query },
705            { OSSL_FUNC_PROVIDER_GET_REASON_STRINGS, (void (*)(void))p_reasons },
706            { 0, NULL }
707        };
708
709        int OSSL_provider_init(const OSSL_CORE_HANDLE *handle,
710                               const OSSL_DISPATCH *in,
711                               const OSSL_DISPATCH **out,
712                               void **provctx)
713        {
714            struct prov_ctx_st *pctx = NULL;
715
716            for (; in->function_id != 0; in++)
717                switch (in->function_id) {
718                case OSSL_FUNC_CORE_PUT_ERROR:
719                    c_put_error = OSSL_FUNC_core_put_error(in);
720                    break;
721                }
722
723            *out = prov_fns;
724
725            if ((pctx = malloc(sizeof(*pctx))) == NULL) {
726                /*
727                 * ALEA IACTA EST, if the core retrieves the reason table
728                 * regardless, that string will be displayed, otherwise not.
729                 */
730                c_put_error(handle, E_MALLOC, __FILE__, __LINE__);
731                return 0;
732            }
733            pctx->handle = handle;
734            return 1;
735        }
736
737       This relies on a few things existing in openssl/core_dispatch.h:
738
739        #define OSSL_OP_BAR            4711
740
741        #define OSSL_FUNC_BAR_NEWCTX      1
742        typedef void *(OSSL_FUNC_bar_newctx_fn)(void *provctx);
743        static ossl_inline OSSL_FUNC_bar_newctx(const OSSL_DISPATCH *opf)
744        { return (OSSL_FUNC_bar_newctx_fn *)opf->function; }
745
746        #define OSSL_FUNC_BAR_FREECTX     2
747        typedef void (OSSL_FUNC_bar_freectx_fn)(void *ctx);
748        static ossl_inline OSSL_FUNC_bar_newctx(const OSSL_DISPATCH *opf)
749        { return (OSSL_FUNC_bar_freectx_fn *)opf->function; }
750
751        #define OSSL_FUNC_BAR_INIT        3
752        typedef void *(OSSL_FUNC_bar_init_fn)(void *ctx);
753        static ossl_inline OSSL_FUNC_bar_init(const OSSL_DISPATCH *opf)
754        { return (OSSL_FUNC_bar_init_fn *)opf->function; }
755
756        #define OSSL_FUNC_BAR_UPDATE      4
757        typedef void *(OSSL_FUNC_bar_update_fn)(void *ctx,
758                                              unsigned char *in, size_t inl);
759        static ossl_inline OSSL_FUNC_bar_update(const OSSL_DISPATCH *opf)
760        { return (OSSL_FUNC_bar_update_fn *)opf->function; }
761
762        #define OSSL_FUNC_BAR_FINAL       5
763        typedef void *(OSSL_FUNC_bar_final_fn)(void *ctx);
764        static ossl_inline OSSL_FUNC_bar_final(const OSSL_DISPATCH *opf)
765        { return (OSSL_FUNC_bar_final_fn *)opf->function; }
766

SEE ALSO

768       provider(7)
769

HISTORY

771       The concept of providers and everything surrounding them was introduced
772       in OpenSSL 3.0.
773
775       Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
776
777       Licensed under the Apache License 2.0 (the "License").  You may not use
778       this file except in compliance with the License.  You can obtain a copy
779       in the file LICENSE in the source distribution or at
780       <https://www.openssl.org/source/license.html>.
781
782
783
7843.0.5                             2022-11-01              PROVIDER-BASE(7ossl)
Impressum