Debian Codegraph @

upstream/debian-unstable/man7/provider-base.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "PROVIDER-BASE 7SSL"
58 .TH PROVIDER-BASE 7SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 provider\-base
65 \&\- The basic OpenSSL library <\-> provider functions
66 .SH SYNOPSIS
67 .IX Header "SYNOPSIS"
68 .Vb 1
69 \& #include <openssl/core_dispatch.h>
70 \&
71 \& /*
72 \& * None of these are actual functions, but are displayed like this for
73 \& * the function signatures for functions that are offered as function
74 \& * pointers in OSSL_DISPATCH arrays.
75 \& */
76 \&
77 \& /* Functions offered by libcrypto to the providers */
78 \& const OSSL_ITEM *core_gettable_params(const OSSL_CORE_HANDLE *handle);
79 \& int core_get_params(const OSSL_CORE_HANDLE *handle, OSSL_PARAM params[]);
80 \&
81 \& typedef void (*OSSL_thread_stop_handler_fn)(void *arg);
82 \& int core_thread_start(const OSSL_CORE_HANDLE *handle,
83 \& OSSL_thread_stop_handler_fn handfn,
84 \& void *arg);
85 \&
86 \& OPENSSL_CORE_CTX *core_get_libctx(const OSSL_CORE_HANDLE *handle);
87 \& void core_new_error(const OSSL_CORE_HANDLE *handle);
88 \& void core_set_error_debug(const OSSL_CORE_HANDLE *handle,
89 \& const char *file, int line, const char *func);
90 \& void core_vset_error(const OSSL_CORE_HANDLE *handle,
91 \& uint32_t reason, const char *fmt, va_list args);
92 \&
93 \& int core_obj_add_sigid(const OSSL_CORE_HANDLE *prov, const char *sign_name,
94 \& const char *digest_name, const char *pkey_name);
95 \& int core_obj_create(const OSSL_CORE_HANDLE *handle, const char *oid,
96 \& const char *sn, const char *ln);
97 \&
98 \& /*
99 \& * Some OpenSSL functionality is directly offered to providers via
100 \& * dispatch
101 \& */
102 \& void *CRYPTO_malloc(size_t num, const char *file, int line);
103 \& void *CRYPTO_zalloc(size_t num, const char *file, int line);
104 \& void CRYPTO_free(void *ptr, const char *file, int line);
105 \& void CRYPTO_clear_free(void *ptr, size_t num,
106 \& const char *file, int line);
107 \& void *CRYPTO_realloc(void *addr, size_t num,
108 \& const char *file, int line);
109 \& void *CRYPTO_clear_realloc(void *addr, size_t old_num, size_t num,
110 \& const char *file, int line);
111 \& void *CRYPTO_secure_malloc(size_t num, const char *file, int line);
112 \& void *CRYPTO_secure_zalloc(size_t num, const char *file, int line);
113 \& void CRYPTO_secure_free(void *ptr, const char *file, int line);
114 \& void CRYPTO_secure_clear_free(void *ptr, size_t num,
115 \& const char *file, int line);
116 \& int CRYPTO_secure_allocated(const void *ptr);
117 \& void OPENSSL_cleanse(void *ptr, size_t len);
118 \&
119 \& unsigned char *OPENSSL_hexstr2buf(const char *str, long *buflen);
120 \&
121 \& OSSL_CORE_BIO *BIO_new_file(const char *filename, const char *mode);
122 \& OSSL_CORE_BIO *BIO_new_membuf(const void *buf, int len);
123 \& int BIO_read_ex(OSSL_CORE_BIO *bio, void *data, size_t data_len,
124 \& size_t *bytes_read);
125 \& int BIO_write_ex(OSSL_CORE_BIO *bio, const void *data, size_t data_len,
126 \& size_t *written);
127 \& int BIO_up_ref(OSSL_CORE_BIO *bio);
128 \& int BIO_free(OSSL_CORE_BIO *bio);
129 \& int BIO_vprintf(OSSL_CORE_BIO *bio, const char *format, va_list args);
130 \& int BIO_vsnprintf(char *buf, size_t n, const char *fmt, va_list args);
131 \&
132 \& void OSSL_SELF_TEST_set_callback(OSSL_LIB_CTX *libctx, OSSL_CALLBACK *cb,
133 \& void *cbarg);
134 \&
135 \& size_t get_entropy(const OSSL_CORE_HANDLE *handle,
136 \& unsigned char **pout, int entropy,
137 \& size_t min_len, size_t max_len);
138 \& size_t get_user_entropy(const OSSL_CORE_HANDLE *handle,
139 \& unsigned char **pout, int entropy,
140 \& size_t min_len, size_t max_len);
141 \& void cleanup_entropy(const OSSL_CORE_HANDLE *handle,
142 \& unsigned char *buf, size_t len);
143 \& void cleanup_user_entropy(const OSSL_CORE_HANDLE *handle,
144 \& unsigned char *buf, size_t len);
145 \& size_t get_nonce(const OSSL_CORE_HANDLE *handle,
146 \& unsigned char **pout, size_t min_len, size_t max_len,
147 \& const void *salt, size_t salt_len);
148 \& size_t get_user_nonce(const OSSL_CORE_HANDLE *handle,
149 \& unsigned char **pout, size_t min_len, size_t max_len,
150 \& const void *salt, size_t salt_len);
151 \& void cleanup_nonce(const OSSL_CORE_HANDLE *handle,
152 \& unsigned char *buf, size_t len);
153 \& void cleanup_user_nonce(const OSSL_CORE_HANDLE *handle,
154 \& unsigned char *buf, size_t len);
155 \&
156 \& /* Functions for querying the providers in the application library context */
157 \& int provider_register_child_cb(const OSSL_CORE_HANDLE *handle,
158 \& int (*create_cb)(const OSSL_CORE_HANDLE *provider,
159 \& void *cbdata),
160 \& int (*remove_cb)(const OSSL_CORE_HANDLE *provider,
161 \& void *cbdata),
162 \& int (*global_props_cb)(const char *props, void *cbdata),
163 \& void *cbdata);
164 \& void provider_deregister_child_cb(const OSSL_CORE_HANDLE *handle);
165 \& const char *provider_name(const OSSL_CORE_HANDLE *prov);
166 \& void *provider_get0_provider_ctx(const OSSL_CORE_HANDLE *prov);
167 \& const OSSL_DISPATCH *provider_get0_dispatch(const OSSL_CORE_HANDLE *prov);
168 \& int provider_up_ref(const OSSL_CORE_HANDLE *prov, int activate);
169 \& int provider_free(const OSSL_CORE_HANDLE *prov, int deactivate);
170 \&
171 \& /* Functions offered by the provider to libcrypto */
172 \& void provider_teardown(void *provctx);
173 \& const OSSL_ITEM *provider_gettable_params(void *provctx);
174 \& int provider_get_params(void *provctx, OSSL_PARAM params[]);
175 \& const OSSL_ALGORITHM *provider_query_operation(void *provctx,
176 \& int operation_id,
177 \& const int *no_store);
178 \& void provider_unquery_operation(void *provctx, int operation_id,
179 \& const OSSL_ALGORITHM *algs);
180 \& const OSSL_ITEM *provider_get_reason_strings(void *provctx);
181 \& int provider_get_capabilities(void *provctx, const char *capability,
182 \& OSSL_CALLBACK *cb, void *arg);
183 \& int provider_self_test(void *provctx);
184 .Ve
185 .SH DESCRIPTION
186 .IX Header "DESCRIPTION"
187 All "functions" mentioned here are passed as function pointers between
188 \&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays, in the call
189 of the provider initialization function. See "Provider" in \fBprovider\fR\|(7)
190 for a description of the initialization function. They are known as "upcalls".
191 .PP
192 All these "functions" have a corresponding function type definition
193 named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the
194 function pointer from a \fBOSSL_DISPATCH\fR\|(3) element named
195 \&\fBOSSL_FUNC_{name}\fR.
196 For example, the "function" \fBcore_gettable_params()\fR has these:
197 .PP
198 .Vb 4
199 \& typedef OSSL_PARAM *
200 \& (OSSL_FUNC_core_gettable_params_fn)(const OSSL_CORE_HANDLE *handle);
201 \& static ossl_inline OSSL_NAME_core_gettable_params_fn
202 \& OSSL_FUNC_core_gettable_params(const OSSL_DISPATCH *opf);
203 .Ve
204 .PP
205 \&\fBOSSL_DISPATCH\fR\|(3) array entries contain a \fIfunction_id\fR field that
206 identifies the function. The \fIfunction_id\fR numbers are provided as
207 macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows:
208 .PP
209 For \fIin\fR (the \fBOSSL_DISPATCH\fR\|(3) array passed from \fIlibcrypto\fR to the
210 provider):
211 .PP
212 .Vb 10
213 \& core_gettable_params OSSL_FUNC_CORE_GETTABLE_PARAMS
214 \& core_get_params OSSL_FUNC_CORE_GET_PARAMS
215 \& core_thread_start OSSL_FUNC_CORE_THREAD_START
216 \& core_get_libctx OSSL_FUNC_CORE_GET_LIBCTX
217 \& core_new_error OSSL_FUNC_CORE_NEW_ERROR
218 \& core_set_error_debug OSSL_FUNC_CORE_SET_ERROR_DEBUG
219 \& core_vset_error OSSL_FUNC_CORE_VSET_ERROR
220 \& core_set_error_mark OSSL_FUNC_CORE_SET_ERROR_MARK
221 \& core_clear_last_error_mark OSSL_FUNC_CORE_CLEAR_LAST_ERROR_MARK
222 \& core_pop_error_to_mark OSSL_FUNC_CORE_POP_ERROR_TO_MARK
223 \& core_count_to_mark OSSL_FUNC_CORE_COUNT_TO_MARK
224 \& core_obj_add_sigid OSSL_FUNC_CORE_OBJ_ADD_SIGID
225 \& core_obj_create OSSL_FUNC_CORE_OBJ_CREATE
226 \& CRYPTO_malloc OSSL_FUNC_CRYPTO_MALLOC
227 \& CRYPTO_zalloc OSSL_FUNC_CRYPTO_ZALLOC
228 \& CRYPTO_free OSSL_FUNC_CRYPTO_FREE
229 \& CRYPTO_clear_free OSSL_FUNC_CRYPTO_CLEAR_FREE
230 \& CRYPTO_realloc OSSL_FUNC_CRYPTO_REALLOC
231 \& CRYPTO_clear_realloc OSSL_FUNC_CRYPTO_CLEAR_REALLOC
232 \& CRYPTO_secure_malloc OSSL_FUNC_CRYPTO_SECURE_MALLOC
233 \& CRYPTO_secure_zalloc OSSL_FUNC_CRYPTO_SECURE_ZALLOC
234 \& CRYPTO_secure_free OSSL_FUNC_CRYPTO_SECURE_FREE
235 \& CRYPTO_secure_clear_free OSSL_FUNC_CRYPTO_SECURE_CLEAR_FREE
236 \& CRYPTO_secure_allocated OSSL_FUNC_CRYPTO_SECURE_ALLOCATED
237 \& BIO_new_file OSSL_FUNC_BIO_NEW_FILE
238 \& BIO_new_mem_buf OSSL_FUNC_BIO_NEW_MEMBUF
239 \& BIO_read_ex OSSL_FUNC_BIO_READ_EX
240 \& BIO_write_ex OSSL_FUNC_BIO_WRITE_EX
241 \& BIO_up_ref OSSL_FUNC_BIO_UP_REF
242 \& BIO_free OSSL_FUNC_BIO_FREE
243 \& BIO_vprintf OSSL_FUNC_BIO_VPRINTF
244 \& BIO_vsnprintf OSSL_FUNC_BIO_VSNPRINTF
245 \& BIO_puts OSSL_FUNC_BIO_PUTS
246 \& BIO_gets OSSL_FUNC_BIO_GETS
247 \& BIO_ctrl OSSL_FUNC_BIO_CTRL
248 \& OPENSSL_cleanse OSSL_FUNC_OPENSSL_CLEANSE
249 \& OSSL_SELF_TEST_set_callback OSSL_FUNC_SELF_TEST_CB
250 \& ossl_rand_get_entropy OSSL_FUNC_GET_ENTROPY
251 \& ossl_rand_get_user_entropy OSSL_FUNC_GET_USER_ENTROPY
252 \& ossl_rand_cleanup_entropy OSSL_FUNC_CLEANUP_ENTROPY
253 \& ossl_rand_cleanup_user_entropy OSSL_FUNC_CLEANUP_USER_ENTROPY
254 \& ossl_rand_get_nonce OSSL_FUNC_GET_NONCE
255 \& ossl_rand_get_user_nonce OSSL_FUNC_GET_USER_NONCE
256 \& ossl_rand_cleanup_nonce OSSL_FUNC_CLEANUP_NONCE
257 \& ossl_rand_cleanup_user_nonce OSSL_FUNC_CLEANUP_USER_NONCE
258 \& provider_register_child_cb OSSL_FUNC_PROVIDER_REGISTER_CHILD_CB
259 \& provider_deregister_child_cb OSSL_FUNC_PROVIDER_DEREGISTER_CHILD_CB
260 \& provider_name OSSL_FUNC_PROVIDER_NAME
261 \& provider_get0_provider_ctx OSSL_FUNC_PROVIDER_GET0_PROVIDER_CTX
262 \& provider_get0_dispatch OSSL_FUNC_PROVIDER_GET0_DISPATCH
263 \& provider_up_ref OSSL_FUNC_PROVIDER_UP_REF
264 \& provider_free OSSL_FUNC_PROVIDER_FREE
265 .Ve
266 .PP
267 For \fI*out\fR (the \fBOSSL_DISPATCH\fR\|(3) array passed from the provider to
268 \&\fIlibcrypto\fR):
269 .PP
270 .Vb 8
271 \& provider_teardown OSSL_FUNC_PROVIDER_TEARDOWN
272 \& provider_gettable_params OSSL_FUNC_PROVIDER_GETTABLE_PARAMS
273 \& provider_get_params OSSL_FUNC_PROVIDER_GET_PARAMS
274 \& provider_query_operation OSSL_FUNC_PROVIDER_QUERY_OPERATION
275 \& provider_unquery_operation OSSL_FUNC_PROVIDER_UNQUERY_OPERATION
276 \& provider_get_reason_strings OSSL_FUNC_PROVIDER_GET_REASON_STRINGS
277 \& provider_get_capabilities OSSL_FUNC_PROVIDER_GET_CAPABILITIES
278 \& provider_self_test OSSL_FUNC_PROVIDER_SELF_TEST
279 .Ve
280 .SS "Core functions"
281 .IX Subsection "Core functions"
282 \&\fBcore_gettable_params()\fR returns a constant array of descriptor
283 \&\fBOSSL_PARAM\fR\|(3), for parameters that \fBcore_get_params()\fR can handle.
284 .PP
285 \&\fBcore_get_params()\fR retrieves parameters from the core for the given \fIhandle\fR.
286 See "Core parameters" below for a description of currently known
287 parameters.
288 .PP
289 The \fBcore_thread_start()\fR function informs the core that the provider has stated
290 an interest in the current thread. The core will inform the provider when the
291 thread eventually stops. It must be passed the \fIhandle\fR for this provider, as
292 well as a callback \fIhandfn\fR which will be called when the thread stops. The
293 callback will subsequently be called, with the supplied argument \fIarg\fR, from
294 the thread that is stopping and gets passed the provider context as an
295 argument. This may be useful to perform thread specific clean up such as
296 freeing thread local variables.
297 .PP
298 \&\fBcore_get_libctx()\fR retrieves the core context in which the library
299 object for the current provider is stored, accessible through the \fIhandle\fR.
300 This function is useful only for built-in providers such as the default
301 provider. Never cast this to OSSL_LIB_CTX in a provider that is not
302 built-in as the OSSL_LIB_CTX of the library loading the provider might be
303 a completely different structure than the OSSL_LIB_CTX of the library the
304 provider is linked to. Use \fBOSSL_LIB_CTX_new_child\fR\|(3) instead to obtain
305 a proper library context that is linked to the application library context.
306 .PP
307 \&\fBcore_new_error()\fR, \fBcore_set_error_debug()\fR and \fBcore_vset_error()\fR are
308 building blocks for reporting an error back to the core, with
309 reference to the \fIhandle\fR.
310 .IP \fBcore_new_error()\fR 4
311 .IX Item "core_new_error()"
312 allocates a new thread specific error record.
313 .Sp
314 This corresponds to the OpenSSL function \fBERR_new\fR\|(3).
315 .IP \fBcore_set_error_debug()\fR 4
316 .IX Item "core_set_error_debug()"
317 sets debugging information in the current thread specific error
318 record.
319 The debugging information includes the name of the file \fIfile\fR, the
320 line \fIline\fR and the function name \fIfunc\fR where the error occurred.
321 .Sp
322 This corresponds to the OpenSSL function \fBERR_set_debug\fR\|(3).
323 .IP \fBcore_vset_error()\fR 4
324 .IX Item "core_vset_error()"
325 sets the \fIreason\fR for the error, along with any addition data.
326 The \fIreason\fR is a number defined by the provider and used to index
327 the reason strings table that's returned by
328 \&\fBprovider_get_reason_strings()\fR.
329 The additional data is given as a format string \fIfmt\fR and a set of
330 arguments \fIargs\fR, which are treated in the same manner as with
331 \&\fBBIO_vsnprintf()\fR.
332 \&\fIfile\fR and \fIline\fR may also be passed to indicate exactly where the
333 error occurred or was reported.
334 .Sp
335 This corresponds to the OpenSSL function \fBERR_vset_error\fR\|(3).
336 .IP \fBcore_set_error_mark()\fR 4
337 .IX Item "core_set_error_mark()"
338 sets a mark on the current topmost error record if there is one.
339 .Sp
340 This corresponds to the OpenSSL function \fBERR_set_mark\fR\|(3).
341 .IP \fBcore_clear_last_error_mark()\fR 4
342 .IX Item "core_clear_last_error_mark()"
343 removes the last mark added if there is one.
344 .Sp
345 This corresponds to the OpenSSL function \fBERR_clear_last_mark\fR\|(3).
346 .IP \fBcore_pop_error_to_mark()\fR 4
347 .IX Item "core_pop_error_to_mark()"
348 pops the top of the error stack until a mark is found. The mark is then removed.
349 If there is no mark, the whole stack is removed.
350 .Sp
351 This corresponds to the OpenSSL function \fBERR_pop_to_mark\fR\|(3).
352 .IP \fBcore_count_to_mark()\fR 4
353 .IX Item "core_count_to_mark()"
354 returns the number of entries on the error stack above the most recently
355 marked entry, not including that entry. If there is no mark in the error stack,
356 the number of entries in the error stack is returned.
357 .Sp
358 This corresponds to the OpenSSL function \fBERR_count_to_mark\fR\|(3).
359 .PP
360 The \fBcore_obj_create()\fR function registers a new OID and associated short name
361 \&\fIsn\fR and long name \fIln\fR for the given \fIhandle\fR. It is similar to the OpenSSL
362 function \fBOBJ_create\fR\|(3) except that it returns 1 on success or 0 on failure.
363 It will treat as success the case where the OID already exists (even if the
364 short name \fIsn\fR or long name \fIln\fR provided as arguments differ from those
365 associated with the existing OID, in which case the new names are not
366 associated).
367 .PP
368 The \fBcore_obj_add_sigid()\fR function registers a new composite signature algorithm
369 (\fIsign_name\fR) consisting of an underlying signature algorithm (\fIpkey_name\fR)
370 and digest algorithm (\fIdigest_name\fR) for the given \fIhandle\fR. It assumes that
371 the OIDs for the composite signature algorithm as well as for the underlying
372 signature and digest algorithms are either already known to OpenSSL or have been
373 registered via a call to \fBcore_obj_create()\fR. It corresponds to the OpenSSL
374 function \fBOBJ_add_sigid\fR\|(3), except that the objects are identified by name
375 rather than a numeric NID. Any name (OID, short name or long name) can be used
376 to identify the object. It will treat as success the case where the composite
377 signature algorithm already exists (even if registered against a different
378 underlying signature or digest algorithm). For \fIdigest_name\fR, NULL or an
379 empty string is permissible for signature algorithms that do not need a digest
380 to operate correctly. The function returns 1 on success or 0 on failure.
381 .PP
382 \&\fBCRYPTO_malloc()\fR, \fBCRYPTO_zalloc()\fR, \fBCRYPTO_free()\fR, \fBCRYPTO_clear_free()\fR,
383 \&\fBCRYPTO_realloc()\fR, \fBCRYPTO_clear_realloc()\fR, \fBCRYPTO_secure_malloc()\fR,
384 \&\fBCRYPTO_secure_zalloc()\fR, \fBCRYPTO_secure_free()\fR,
385 \&\fBCRYPTO_secure_clear_free()\fR, \fBCRYPTO_secure_allocated()\fR,
386 \&\fBBIO_new_file()\fR, \fBBIO_new_mem_buf()\fR, \fBBIO_read_ex()\fR, \fBBIO_write_ex()\fR, \fBBIO_up_ref()\fR,
387 \&\fBBIO_free()\fR, \fBBIO_vprintf()\fR, \fBBIO_vsnprintf()\fR, \fBBIO_gets()\fR, \fBBIO_puts()\fR,
388 \&\fBBIO_ctrl()\fR, \fBOPENSSL_cleanse()\fR and
389 \&\fBOPENSSL_hexstr2buf()\fR correspond exactly to the public functions with
390 the same name. As a matter of fact, the pointers in the \fBOSSL_DISPATCH\fR\|(3)
391 array are typically direct pointers to those public functions. Note that the BIO
392 functions take an \fBOSSL_CORE_BIO\fR type rather than the standard \fBBIO\fR
393 type. This is to ensure that a provider does not mix BIOs from the core
394 with BIOs used on the provider side (the two are not compatible).
395 \&\fBOSSL_SELF_TEST_set_callback()\fR is used to set an optional callback that can be
396 passed into a provider. This may be ignored by a provider.
397 .PP
398 \&\fBget_entropy()\fR retrieves seeding material from the operating system.
399 The seeding material will have at least \fIentropy\fR bytes of randomness and the
400 output will have at least \fImin_len\fR and at most \fImax_len\fR bytes.
401 The buffer address is stored in \fI*pout\fR and the buffer length is
402 returned to the caller. On error, zero is returned.
403 .PP
404 \&\fBget_user_entropy()\fR is the same as \fBget_entropy()\fR except that it will
405 attempt to gather seed material via the seed source specified by a call to
406 \&\fBRAND_set_seed_source_type\fR\|(3) or via "Random Configuration" in \fBconfig\fR\|(5).
407 .PP
408 \&\fBcleanup_entropy()\fR is used to clean up and free the buffer returned by
409 \&\fBget_entropy()\fR. The entropy pointer returned by \fBget_entropy()\fR
410 is passed in \fBbuf\fR and its length in \fBlen\fR.
411 .PP
412 \&\fBcleanup_user_entropy()\fR is used to clean up and free the buffer returned by
413 \&\fBget_user_entropy()\fR. The entropy pointer returned by \fBget_user_entropy()\fR
414 is passed in \fBbuf\fR and its length in \fBlen\fR.
415 .PP
416 \&\fBget_nonce()\fR retrieves a nonce using the passed \fIsalt\fR parameter
417 of length \fIsalt_len\fR and operating system specific information.
418 The \fIsalt\fR should contain uniquely identifying information and this is
419 included, in an unspecified manner, as part of the output.
420 The output is stored in a buffer which contains at least \fImin_len\fR and at
421 most \fImax_len\fR bytes. The buffer address is stored in \fI*pout\fR and the
422 buffer length returned to the caller. On error, zero is returned.
423 .PP
424 \&\fBget_user_nonce()\fR is the same as \fBget_nonce()\fR except that it will attempt
425 to gather seed material via the seed source specified by a call to
426 \&\fBRAND_set_seed_source_type\fR\|(3) or via "Random Configuration" in \fBconfig\fR\|(5).
427 .PP
428 \&\fBcleanup_nonce()\fR is used to clean up and free the buffer returned by
429 \&\fBget_nonce()\fR. The nonce pointer returned by \fBget_nonce()\fR
430 is passed in \fBbuf\fR and its length in \fBlen\fR.
431 .PP
432 \&\fBcleanup_user_nonce()\fR is used to clean up and free the buffer returned by
433 \&\fBget_user_nonce()\fR. The nonce pointer returned by \fBget_user_nonce()\fR
434 is passed in \fBbuf\fR and its length in \fBlen\fR.
435 .PP
436 \&\fBprovider_register_child_cb()\fR registers callbacks for being informed about the
437 loading and unloading of providers in the application's library context.
438 \&\fIhandle\fR is this provider's handle and \fIcbdata\fR is this provider's data
439 that will be passed back to the callbacks. It returns 1 on success or 0
440 otherwise. These callbacks may be called while holding locks in libcrypto. In
441 order to avoid deadlocks the callback implementation must not be long running
442 and must not call other OpenSSL API functions or upcalls.
443 .PP
444 \&\fIcreate_cb\fR is a callback that will be called when a new provider is loaded
445 into the application's library context. It is also called for any providers that
446 are already loaded at the point that this callback is registered. The callback
447 is passed the handle being used for the new provider being loadded and this
448 provider's data in \fIcbdata\fR. It should return 1 on success or 0 on failure.
449 .PP
450 \&\fIremove_cb\fR is a callback that will be called when a new provider is unloaded
451 from the application's library context. It is passed the handle being used for
452 the provider being unloaded and this provider's data in \fIcbdata\fR. It should
453 return 1 on success or 0 on failure.
454 .PP
455 \&\fIglobal_props_cb\fR is a callback that will be called when the global properties
456 from the parent library context are changed. It should return 1 on success
457 or 0 on failure.
458 .PP
459 \&\fBprovider_deregister_child_cb()\fR unregisters callbacks previously registered via
460 \&\fBprovider_register_child_cb()\fR. If \fBprovider_register_child_cb()\fR has been called
461 then \fBprovider_deregister_child_cb()\fR should be called at or before the point that
462 this provider's teardown function is called.
463 .PP
464 \&\fBprovider_name()\fR returns a string giving the name of the provider identified by
465 \&\fIhandle\fR.
466 .PP
467 \&\fBprovider_get0_provider_ctx()\fR returns the provider context that is associated
468 with the provider identified by \fIprov\fR.
469 .PP
470 \&\fBprovider_get0_dispatch()\fR gets the dispatch table registered by the provider
471 identified by \fIprov\fR when it initialised.
472 .PP
473 \&\fBprovider_up_ref()\fR increments the reference count on the provider \fIprov\fR. If
474 \&\fIactivate\fR is nonzero then the provider is also loaded if it is not already
475 loaded. It returns 1 on success or 0 on failure.
476 .PP
477 \&\fBprovider_free()\fR decrements the reference count on the provider \fIprov\fR. If
478 \&\fIdeactivate\fR is nonzero then the provider is also unloaded if it is not
479 already loaded. It returns 1 on success or 0 on failure.
480 .SS "Provider functions"
481 .IX Subsection "Provider functions"
482 \&\fBprovider_teardown()\fR is called when a provider is shut down and removed
483 from the core's provider store.
484 It must free the passed \fIprovctx\fR.
485 .PP
486 \&\fBprovider_gettable_params()\fR should return a constant array of
487 descriptor \fBOSSL_PARAM\fR\|(3), for parameters that \fBprovider_get_params()\fR
488 can handle.
489 .PP
490 \&\fBprovider_get_params()\fR should process the \fBOSSL_PARAM\fR\|(3) array
491 \&\fIparams\fR, setting the values of the parameters it understands.
492 .PP
493 \&\fBprovider_query_operation()\fR should return a constant \fBOSSL_ALGORITHM\fR\|(3)
494 that corresponds to the given \fIoperation_id\fR.
495 It should indicate if the core may store a reference to this array by
496 setting \fI*no_store\fR to 0 (core may store a reference) or 1 (core may
497 not store a reference).
498 .PP
499 \&\fBprovider_unquery_operation()\fR informs the provider that the result of a
500 \&\fBprovider_query_operation()\fR is no longer directly required and that the function
501 pointers have been copied. The \fIoperation_id\fR should match that passed to
502 \&\fBprovider_query_operation()\fR and \fIalgs\fR should be its return value.
503 .PP
504 \&\fBprovider_get_reason_strings()\fR should return a constant \fBOSSL_ITEM\fR\|(3)
505 array that provides reason strings for reason codes the provider may
506 use when reporting errors using \fBcore_put_error()\fR.
507 .PP
508 The \fBprovider_get_capabilities()\fR function should call the callback \fIcb\fR passing
509 it a set of \fBOSSL_PARAM\fR\|(3)s and the caller supplied argument \fIarg\fR. The
510 \&\fBOSSL_PARAM\fR\|(3)s should provide details about the capability with the name given
511 in the \fIcapability\fR argument relevant for the provider context \fIprovctx\fR. If a
512 provider supports multiple capabilities with the given name then it may call the
513 callback multiple times (one for each capability). Capabilities can be useful for
514 describing the services that a provider can offer. For further details see the
515 "CAPABILITIES" section below. It should return 1 on success or 0 on error.
516 .PP
517 The \fBprovider_self_test()\fR function should perform known answer tests on a subset
518 of the algorithms that it uses, and may also verify the integrity of the
519 provider module. It should return 1 on success or 0 on error. It will return 1
520 if this function is not used.
521 .PP
522 None of these functions are mandatory, but a provider is fairly
523 useless without at least \fBprovider_query_operation()\fR, and
524 \&\fBprovider_gettable_params()\fR is fairly useless if not accompanied by
525 \&\fBprovider_get_params()\fR.
526 .SS "Provider parameters"
527 .IX Subsection "Provider parameters"
528 \&\fBprovider_get_params()\fR can return the following provider parameters to the core:
529 .IP """name"" (\fBOSSL_PROV_PARAM_NAME\fR) <UTF8 ptr>" 4
530 .IX Item """name"" (OSSL_PROV_PARAM_NAME) <UTF8 ptr>"
531 This points to a string that should give a unique name for the provider.
532 .IP """version"" (\fBOSSL_PROV_PARAM_VERSION\fR) <UTF8 ptr>" 4
533 .IX Item """version"" (OSSL_PROV_PARAM_VERSION) <UTF8 ptr>"
534 This points to a string that is a version number associated with this provider.
535 OpenSSL in-built providers use OPENSSL_VERSION_STR, but this may be different
536 for any third party provider. This string is for informational purposes only.
537 .IP """buildinfo"" (\fBOSSL_PROV_PARAM_BUILDINFO\fR) <UTF8 ptr>" 4
538 .IX Item """buildinfo"" (OSSL_PROV_PARAM_BUILDINFO) <UTF8 ptr>"
539 This points to a string that is a build information associated with this provider.
540 OpenSSL in-built providers use OPENSSL_FULL_VERSION_STR, but this may be
541 different for any third party provider.
542 .IP """status"" (\fBOSSL_PROV_PARAM_STATUS\fR) <signed integer>" 4
543 .IX Item """status"" (OSSL_PROV_PARAM_STATUS) <signed integer>"
544 This returns 0 if the provider has entered an error state, otherwise it returns
545 1.
546 .PP
547 \&\fBprovider_gettable_params()\fR should return the above parameters.
548 .SS "Core parameters"
549 .IX Subsection "Core parameters"
550 \&\fBcore_get_params()\fR can retrieve the following core parameters for each provider:
551 .IP """openssl-version"" (\fBOSSL_PROV_PARAM_CORE_VERSION\fR) <UTF8 string ptr>" 4
552 .IX Item """openssl-version"" (OSSL_PROV_PARAM_CORE_VERSION) <UTF8 string ptr>"
553 This points to the OpenSSL libraries' full version string, i.e. the string
554 expanded from the macro \fBOPENSSL_VERSION_STR\fR.
555 .IP """provider-name"" (\fBOSSL_PROV_PARAM_CORE_PROV_NAME\fR) <UTF8 string ptr>" 4
556 .IX Item """provider-name"" (OSSL_PROV_PARAM_CORE_PROV_NAME) <UTF8 string ptr>"
557 This points to the OpenSSL libraries' idea of what the calling provider is named.
558 .IP """module-filename"" (\fBOSSL_PROV_PARAM_CORE_MODULE_FILENAME\fR) <UTF8 string ptr>" 4
559 .IX Item """module-filename"" (OSSL_PROV_PARAM_CORE_MODULE_FILENAME) <UTF8 string ptr>"
560 This points to a string containing the full filename of the providers
561 module file.
562 .PP
563 Additionally, provider specific configuration parameters from the
564 config file are available, in dotted name form.
565 The dotted name form is a concatenation of section names and final
566 config command name separated by periods.
567 .PP
568 For example, let's say we have the following config example:
569 .PP
570 .Vb 2
571 \& config_diagnostics = 1
572 \& openssl_conf = openssl_init
573 \&
574 \& [openssl_init]
575 \& providers = providers_sect
576 \&
577 \& [providers_sect]
578 \& foo = foo_sect
579 \&
580 \& [foo_sect]
581 \& activate = 1
582 \& data1 = 2
583 \& data2 = str
584 \& more = foo_more
585 \&
586 \& [foo_more]
587 \& data3 = foo,bar
588 .Ve
589 .PP
590 The provider will have these additional parameters available:
591 .IP """activate""" 4
592 .IX Item """activate"""
593 pointing at the string "1"
594 .IP """data1""" 4
595 .IX Item """data1"""
596 pointing at the string "2"
597 .IP """data2""" 4
598 .IX Item """data2"""
599 pointing at the string "str"
600 .IP """more.data3""" 4
601 .IX Item """more.data3"""
602 pointing at the string "foo,bar"
603 .PP
604 For more information on handling parameters, see \fBOSSL_PARAM\fR\|(3) as
605 \&\fBOSSL_PARAM_int\fR\|(3).
606 .SH CAPABILITIES
607 .IX Header "CAPABILITIES"
608 Capabilities describe some of the services that a provider can offer.
609 Applications can query the capabilities to discover those services.
610 .PP
611 \fI"TLS-GROUP" Capability\fR
612 .IX Subsection """TLS-GROUP"" Capability"
613 .PP
614 The "TLS-GROUP" capability can be queried by libssl to discover the list of
615 TLS groups that a provider can support. Each group supported can be used for
616 \&\fIkey exchange\fR (KEX) or \fIkey encapsulation method\fR (KEM) during a TLS
617 handshake.
618 TLS clients can advertise the list of TLS groups they support in the
619 supported_groups extension, and TLS servers can select a group from the offered
620 list that they also support. In this way a provider can add to the list of
621 groups that libssl already supports with additional ones.
622 .PP
623 Each TLS group that a provider supports should be described via the callback
624 passed in through the provider_get_capabilities function. Each group should have
625 the following details supplied (all are mandatory, except
626 \&\fBOSSL_CAPABILITY_TLS_GROUP_IS_KEM\fR):
627 .IP """tls-group-name"" (\fBOSSL_CAPABILITY_TLS_GROUP_NAME\fR) <UTF8 string>" 4
628 .IX Item """tls-group-name"" (OSSL_CAPABILITY_TLS_GROUP_NAME) <UTF8 string>"
629 The name of the group as given in the IANA TLS Supported Groups registry
630 <https://www.iana.org/assignments/tls\-parameters/tls\-parameters.xhtml#tls\-parameters\-8>.
631 .IP """tls-group-name-internal"" (\fBOSSL_CAPABILITY_TLS_GROUP_NAME_INTERNAL\fR) <UTF8 string>" 4
632 .IX Item """tls-group-name-internal"" (OSSL_CAPABILITY_TLS_GROUP_NAME_INTERNAL) <UTF8 string>"
633 The name of the group as known by the provider. This could be the same as the
634 "tls-group-name", but does not have to be.
635 .IP """tls-group-id"" (\fBOSSL_CAPABILITY_TLS_GROUP_ID\fR) <unsigned integer>" 4
636 .IX Item """tls-group-id"" (OSSL_CAPABILITY_TLS_GROUP_ID) <unsigned integer>"
637 The TLS group id value as given in the IANA TLS Supported Groups registry.
638 .Sp
639 It is possible to register the same group id from within different
640 providers. Users should note that if no property query is specified, or
641 more than one implementation matches the property query then it is
642 unspecified which implementation for a particular group id will be used.
643 .IP """tls-group-alg"" (\fBOSSL_CAPABILITY_TLS_GROUP_ALG\fR) <UTF8 string>" 4
644 .IX Item """tls-group-alg"" (OSSL_CAPABILITY_TLS_GROUP_ALG) <UTF8 string>"
645 The name of a Key Management algorithm that the provider offers and that should
646 be used with this group. Keys created should be able to support \fIkey exchange\fR
647 or \fIkey encapsulation method\fR (KEM), as implied by the optional
648 \&\fBOSSL_CAPABILITY_TLS_GROUP_IS_KEM\fR flag.
649 The algorithm must support key and parameter generation as well as the
650 key/parameter generation parameter, \fBOSSL_PKEY_PARAM_GROUP_NAME\fR. The group
651 name given via "tls-group-name-internal" above will be passed via
652 \&\fBOSSL_PKEY_PARAM_GROUP_NAME\fR when libssl wishes to generate keys/parameters.
653 .IP """tls-group-sec-bits"" (\fBOSSL_CAPABILITY_TLS_GROUP_SECURITY_BITS\fR) <unsigned integer>" 4
654 .IX Item """tls-group-sec-bits"" (OSSL_CAPABILITY_TLS_GROUP_SECURITY_BITS) <unsigned integer>"
655 The number of bits of security offered by keys in this group. The number of bits
656 should be comparable with the ones given in table 2 and 3 of the NIST SP800\-57
657 document.
658 .IP """tls-group-is-kem"" (\fBOSSL_CAPABILITY_TLS_GROUP_IS_KEM\fR) <unsigned integer>" 4
659 .IX Item """tls-group-is-kem"" (OSSL_CAPABILITY_TLS_GROUP_IS_KEM) <unsigned integer>"
660 Boolean flag to describe if the group should be used in \fIkey exchange\fR (KEX)
661 mode (0, default) or in \fIkey encapsulation method\fR (KEM) mode (1).
662 .Sp
663 This parameter is optional: if not specified, KEX mode is assumed as the default
664 mode for the group.
665 .Sp
666 In KEX mode, in a typical Diffie-Hellman fashion, both sides execute \fIkeygen\fR
667 then \fIderive\fR against the peer public key. To operate in KEX mode, the group
668 implementation must support the provider functions as described in
669 \&\fBprovider\-keyexch\fR\|(7).
670 .Sp
671 In KEM mode, the client executes \fIkeygen\fR and sends its public key, the server
672 executes \fIencapsulate\fR using the client's public key and sends back the
673 resulting \fIciphertext\fR, finally the client executes \fIdecapsulate\fR to retrieve
674 the same \fIshared secret\fR generated by the server's \fIencapsulate\fR. To operate
675 in KEM mode, the group implementation must support the provider functions as
676 described in \fBprovider\-kem\fR\|(7).
677 .Sp
678 Both in KEX and KEM mode, the resulting \fIshared secret\fR is then used according
679 to the protocol specification.
680 .IP """tls-min-tls"" (\fBOSSL_CAPABILITY_TLS_GROUP_MIN_TLS\fR) <integer>" 4
681 .IX Item """tls-min-tls"" (OSSL_CAPABILITY_TLS_GROUP_MIN_TLS) <integer>"
682 .PD 0
683 .IP """tls-max-tls"" (\fBOSSL_CAPABILITY_TLS_GROUP_MAX_TLS\fR) <integer>" 4
684 .IX Item """tls-max-tls"" (OSSL_CAPABILITY_TLS_GROUP_MAX_TLS) <integer>"
685 .IP """tls-min-dtls"" (\fBOSSL_CAPABILITY_TLS_GROUP_MIN_DTLS\fR) <integer>" 4
686 .IX Item """tls-min-dtls"" (OSSL_CAPABILITY_TLS_GROUP_MIN_DTLS) <integer>"
687 .IP """tls-max-dtls"" (\fBOSSL_CAPABILITY_TLS_GROUP_MAX_DTLS\fR) <integer>" 4
688 .IX Item """tls-max-dtls"" (OSSL_CAPABILITY_TLS_GROUP_MAX_DTLS) <integer>"
689 .PD
690 These parameters can be used to describe the minimum and maximum TLS and DTLS
691 versions supported by the group. The values equate to the on-the-wire encoding
692 of the various TLS versions. For example TLSv1.3 is 0x0304 (772 decimal), and
693 TLSv1.2 is 0x0303 (771 decimal). A 0 indicates that there is no defined minimum
694 or maximum. A \-1 indicates that the group should not be used in that protocol.
695 .PP
696 \fI"TLS-SIGALG" Capability\fR
697 .IX Subsection """TLS-SIGALG"" Capability"
698 .PP
699 The "TLS-SIGALG" capability can be queried by libssl to discover the list of
700 TLS signature algorithms that a provider can support. Each signature supported
701 can be used for client\- or server-authentication in addition to the built-in
702 signature algorithms.
703 TLS1.3 clients can advertise the list of TLS signature algorithms they support
704 in the signature_algorithms extension, and TLS servers can select an algorithm
705 from the offered list that they also support. In this way a provider can add
706 to the list of signature algorithms that libssl already supports with
707 additional ones.
708 .PP
709 Each TLS signature algorithm that a provider supports should be described via
710 the callback passed in through the provider_get_capabilities function. Each
711 algorithm can have the following details supplied:
712 .IP """iana-name"" (\fBOSSL_CAPABILITY_TLS_SIGALG_IANA_NAME\fR) <UTF8 string>" 4
713 .IX Item """iana-name"" (OSSL_CAPABILITY_TLS_SIGALG_IANA_NAME) <UTF8 string>"
714 The name of the signature algorithm as given in the IANA TLS Signature Scheme
715 registry as "Description":
716 <https://www.iana.org/assignments/tls\-parameters/tls\-parameters.xhtml#tls\-signaturescheme>.
717 This value must be supplied.
718 .IP """iana-code-point"" (\fBOSSL_CAPABILITY_TLS_SIGALG_CODE_POINT\fR) <unsigned integer>" 4
719 .IX Item """iana-code-point"" (OSSL_CAPABILITY_TLS_SIGALG_CODE_POINT) <unsigned integer>"
720 The TLS algorithm ID value as given in the IANA TLS SignatureScheme registry.
721 This value must be supplied.
722 .Sp
723 It is possible to register the same code point from within different
724 providers. Users should note that if no property query is specified, or
725 more than one implementation matches the property query then it is
726 unspecified which implementation for a particular code point will be used.
727 .IP """sigalg-name"" (\fBOSSL_CAPABILITY_TLS_SIGALG_NAME\fR) <UTF8 string>" 4
728 .IX Item """sigalg-name"" (OSSL_CAPABILITY_TLS_SIGALG_NAME) <UTF8 string>"
729 A name for the full (possibly composite hash-and-signature) signature
730 algorithm.
731 The provider may, but is not obligated to, provide a signature implementation
732 with this name; if it doesn't, this is assumed to be a composite of a pure
733 signature algorithm and a hash algorithm, which must be given with the
734 parameters "sig-name" and "hash-name".
735 This value must be supplied.
736 .IP """sigalg-oid"" (\fBOSSL_CAPABILITY_TLS_SIGALG_OID\fR) <UTF8 string>" 4
737 .IX Item """sigalg-oid"" (OSSL_CAPABILITY_TLS_SIGALG_OID) <UTF8 string>"
738 The OID of the "sigalg-name" algorithm in canonical numeric text form. If
739 this parameter is given, \fBOBJ_create()\fR will be used to create an OBJ and
740 a NID for this OID, using the "sigalg-name" parameter for its (short) name.
741 Otherwise, it's assumed to already exist in the object database, possibly
742 done by the provider with the \fBcore_obj_create()\fR upcall.
743 This value is optional.
744 .IP """sig-name"" (\fBOSSL_CAPABILITY_TLS_SIGALG_SIG_NAME\fR) <UTF8 string>" 4
745 .IX Item """sig-name"" (OSSL_CAPABILITY_TLS_SIGALG_SIG_NAME) <UTF8 string>"
746 The name of the pure signature algorithm that is part of a composite
747 "sigalg-name". If "sigalg-name" is implemented by the provider, this
748 parameter is redundant and must not be given.
749 This value is optional.
750 .IP """sig-oid"" (\fBOSSL_CAPABILITY_TLS_SIGALG_SIG_OID\fR) <UTF8 string>" 4
751 .IX Item """sig-oid"" (OSSL_CAPABILITY_TLS_SIGALG_SIG_OID) <UTF8 string>"
752 The OID of the "sig-name" algorithm in canonical numeric text form. If
753 this parameter is given, \fBOBJ_create()\fR will be used to create an OBJ and
754 a NID for this OID, using the "sig-name" parameter for its (short) name.
755 Otherwise, it is assumed to already exist in the object database. This
756 can be done by the provider using the \fBcore_obj_create()\fR upcall.
757 This value is optional.
758 .IP """hash-name"" (\fBOSSL_CAPABILITY_TLS_SIGALG_HASH_NAME\fR) <UTF8 string>" 4
759 .IX Item """hash-name"" (OSSL_CAPABILITY_TLS_SIGALG_HASH_NAME) <UTF8 string>"
760 The name of the hash algorithm that is part of a composite "sigalg-name".
761 If "sigalg-name" is implemented by the provider, this parameter is redundant
762 and must not be given.
763 This value is optional.
764 .IP """hash-oid"" (\fBOSSL_CAPABILITY_TLS_SIGALG_HASH_OID\fR) <UTF8 string>" 4
765 .IX Item """hash-oid"" (OSSL_CAPABILITY_TLS_SIGALG_HASH_OID) <UTF8 string>"
766 The OID of the "hash-name" algorithm in canonical numeric text form. If
767 this parameter is given, \fBOBJ_create()\fR will be used to create an OBJ and
768 a NID for this OID, using the "hash-name" parameter for its (short) name.
769 Otherwise, it's assumed to already exist in the object database, possibly
770 done by the provider with the \fBcore_obj_create()\fR upcall.
771 This value is optional.
772 .IP """key-type"" (\fBOSSL_CAPABILITY_TLS_SIGALG_KEYTYPE\fR) <UTF8 string>" 4
773 .IX Item """key-type"" (OSSL_CAPABILITY_TLS_SIGALG_KEYTYPE) <UTF8 string>"
774 The key type of the public key of applicable certificates. If this parameter
775 isn't present, it's assumed to be the same as "sig-name" if that's present,
776 otherwise "sigalg-name".
777 This value is optional.
778 .IP """key-type-oid"" (\fBOSSL_CAPABILITY_TLS_SIGALG_KEYTYPE_OID\fR) <UTF8 string>" 4
779 .IX Item """key-type-oid"" (OSSL_CAPABILITY_TLS_SIGALG_KEYTYPE_OID) <UTF8 string>"
780 The OID of the "key-type" in canonical numeric text form. If
781 this parameter is given, \fBOBJ_create()\fR will be used to create an OBJ and
782 a NID for this OID, using the "key-type" parameter for its (short) name.
783 Otherwise, it's assumed to already exist in the object database, possibly
784 done by the provider with the \fBcore_obj_create()\fR upcall.
785 This value is optional.
786 .IP """sec-bits"" (\fBOSSL_CAPABILITY_TLS_SIGALG_SECURITY_BITS\fR) <unsigned integer>" 4
787 .IX Item """sec-bits"" (OSSL_CAPABILITY_TLS_SIGALG_SECURITY_BITS) <unsigned integer>"
788 The number of bits of security offered by keys of this algorithm. The number
789 of bits should be comparable with the ones given in table 2 and 3 of the NIST
790 SP800\-57 document. This number is used to determine the security strength of
791 the algorithm if no digest algorithm has been registered that otherwise
792 defines the security strength. If the signature algorithm implements its own
793 digest internally, this value needs to be set to properly reflect the overall
794 security strength.
795 This value must be supplied.
796 .IP """tls-min-tls"" (\fBOSSL_CAPABILITY_TLS_SIGALG_MIN_TLS\fR) <integer>" 4
797 .IX Item """tls-min-tls"" (OSSL_CAPABILITY_TLS_SIGALG_MIN_TLS) <integer>"
798 .PD 0
799 .IP """tls-max-tls"" (\fBOSSL_CAPABILITY_TLS_SIGALG_MAX_TLS\fR) <integer>" 4
800 .IX Item """tls-max-tls"" (OSSL_CAPABILITY_TLS_SIGALG_MAX_TLS) <integer>"
801 .IP """tls-min-dtls"" (\fBOSSL_CAPABILITY_TLS_SIGALG_MIN_DTLS\fR) <integer>" 4
802 .IX Item """tls-min-dtls"" (OSSL_CAPABILITY_TLS_SIGALG_MIN_DTLS) <integer>"
803 .IP """tls-max-dtls"" (\fBOSSL_CAPABILITY_TLS_SIGALG_MAX_DTLS\fR) <integer>" 4
804 .IX Item """tls-max-dtls"" (OSSL_CAPABILITY_TLS_SIGALG_MAX_DTLS) <integer>"
805 .PD
806 These parameters can be used to describe the minimum and maximum TLS and DTLS
807 versions supported by the signature algorithm. The values equate to the
808 on-the-wire encoding of the various TLS versions. For example TLSv1.3 is
809 0x0304 (772 decimal), and TLSv1.2 is 0x0303 (771 decimal). A 0 indicates that
810 there is no defined minimum or maximum. A \-1 in either the min or max field
811 indicates that the signature algorithm should not be used in that protocol.
812 Presently, provider signature algorithms are used only with TLS 1.3, if
813 that's enclosed in the specified range.
814 .SH NOTES
815 .IX Header "NOTES"
816 The \fBcore_obj_create()\fR and \fBcore_obj_add_sigid()\fR functions were not thread safe
817 in OpenSSL 3.0.
818 .SH EXAMPLES
819 .IX Header "EXAMPLES"
820 This is an example of a simple provider made available as a
821 dynamically loadable module.
822 It implements the fictitious algorithm \f(CW\*(C`FOO\*(C'\fR for the fictitious
823 operation \f(CW\*(C`BAR\*(C'\fR.
824 .PP
825 .Vb 3
826 \& #include <malloc.h>
827 \& #include <openssl/core.h>
828 \& #include <openssl/core_dispatch.h>
829 \&
830 \& /* Errors used in this provider */
831 \& #define E_MALLOC 1
832 \&
833 \& static const OSSL_ITEM reasons[] = {
834 \& { E_MALLOC, "memory allocation failure" }.
835 \& OSSL_DISPATCH_END
836 \& };
837 \&
838 \& /*
839 \& * To ensure we get the function signature right, forward declare
840 \& * them using function types provided by openssl/core_dispatch.h
841 \& */
842 \& OSSL_FUNC_bar_newctx_fn foo_newctx;
843 \& OSSL_FUNC_bar_freectx_fn foo_freectx;
844 \& OSSL_FUNC_bar_init_fn foo_init;
845 \& OSSL_FUNC_bar_update_fn foo_update;
846 \& OSSL_FUNC_bar_final_fn foo_final;
847 \&
848 \& OSSL_FUNC_provider_query_operation_fn p_query;
849 \& OSSL_FUNC_provider_get_reason_strings_fn p_reasons;
850 \& OSSL_FUNC_provider_teardown_fn p_teardown;
851 \&
852 \& OSSL_provider_init_fn OSSL_provider_init;
853 \&
854 \& OSSL_FUNC_core_put_error *c_put_error = NULL;
855 \&
856 \& /* Provider context */
857 \& struct prov_ctx_st {
858 \& OSSL_CORE_HANDLE *handle;
859 \& }
860 \&
861 \& /* operation context for the algorithm FOO */
862 \& struct foo_ctx_st {
863 \& struct prov_ctx_st *provctx;
864 \& int b;
865 \& };
866 \&
867 \& static void *foo_newctx(void *provctx)
868 \& {
869 \& struct foo_ctx_st *fooctx = malloc(sizeof(*fooctx));
870 \&
871 \& if (fooctx != NULL)
872 \& fooctx\->provctx = provctx;
873 \& else
874 \& c_put_error(provctx\->handle, E_MALLOC, _\|_FILE_\|_, _\|_LINE_\|_);
875 \& return fooctx;
876 \& }
877 \&
878 \& static void foo_freectx(void *fooctx)
879 \& {
880 \& free(fooctx);
881 \& }
882 \&
883 \& static int foo_init(void *vfooctx)
884 \& {
885 \& struct foo_ctx_st *fooctx = vfooctx;
886 \&
887 \& fooctx\->b = 0x33;
888 \& }
889 \&
890 \& static int foo_update(void *vfooctx, unsigned char *in, size_t inl)
891 \& {
892 \& struct foo_ctx_st *fooctx = vfooctx;
893 \&
894 \& /* did you expect something serious? */
895 \& if (inl == 0)
896 \& return 1;
897 \& for (; inl\-\- > 0; in++)
898 \& *in ^= fooctx\->b;
899 \& return 1;
900 \& }
901 \&
902 \& static int foo_final(void *vfooctx)
903 \& {
904 \& struct foo_ctx_st *fooctx = vfooctx;
905 \&
906 \& fooctx\->b = 0x66;
907 \& }
908 \&
909 \& static const OSSL_DISPATCH foo_fns[] = {
910 \& { OSSL_FUNC_BAR_NEWCTX, (void (*)(void))foo_newctx },
911 \& { OSSL_FUNC_BAR_FREECTX, (void (*)(void))foo_freectx },
912 \& { OSSL_FUNC_BAR_INIT, (void (*)(void))foo_init },
913 \& { OSSL_FUNC_BAR_UPDATE, (void (*)(void))foo_update },
914 \& { OSSL_FUNC_BAR_FINAL, (void (*)(void))foo_final },
915 \& OSSL_DISPATCH_END
916 \& };
917 \&
918 \& static const OSSL_ALGORITHM bars[] = {
919 \& { "FOO", "provider=chumbawamba", foo_fns },
920 \& { NULL, NULL, NULL }
921 \& };
922 \&
923 \& static const OSSL_ALGORITHM *p_query(void *provctx, int operation_id,
924 \& int *no_store)
925 \& {
926 \& switch (operation_id) {
927 \& case OSSL_OP_BAR:
928 \& return bars;
929 \& }
930 \& return NULL;
931 \& }
932 \&
933 \& static const OSSL_ITEM *p_reasons(void *provctx)
934 \& {
935 \& return reasons;
936 \& }
937 \&
938 \& static void p_teardown(void *provctx)
939 \& {
940 \& free(provctx);
941 \& }
942 \&
943 \& static const OSSL_DISPATCH prov_fns[] = {
944 \& { OSSL_FUNC_PROVIDER_TEARDOWN, (void (*)(void))p_teardown },
945 \& { OSSL_FUNC_PROVIDER_QUERY_OPERATION, (void (*)(void))p_query },
946 \& { OSSL_FUNC_PROVIDER_GET_REASON_STRINGS, (void (*)(void))p_reasons },
947 \& OSSL_DISPATCH_END
948 \& };
949 \&
950 \& int OSSL_provider_init(const OSSL_CORE_HANDLE *handle,
951 \& const OSSL_DISPATCH *in,
952 \& const OSSL_DISPATCH **out,
953 \& void **provctx)
954 \& {
955 \& struct prov_ctx_st *pctx = NULL;
956 \&
957 \& for (; in\->function_id != 0; in++)
958 \& switch (in\->function_id) {
959 \& case OSSL_FUNC_CORE_PUT_ERROR:
960 \& c_put_error = OSSL_FUNC_core_put_error(in);
961 \& break;
962 \& }
963 \&
964 \& *out = prov_fns;
965 \&
966 \& if ((pctx = malloc(sizeof(*pctx))) == NULL) {
967 \& /*
968 \& * ALEA IACTA EST, if the core retrieves the reason table
969 \& * regardless, that string will be displayed, otherwise not.
970 \& */
971 \& c_put_error(handle, E_MALLOC, _\|_FILE_\|_, _\|_LINE_\|_);
972 \& return 0;
973 \& }
974 \& pctx\->handle = handle;
975 \& return 1;
976 \& }
977 .Ve
978 .PP
979 This relies on a few things existing in \fIopenssl/core_dispatch.h\fR:
980 .PP
981 .Vb 1
982 \& #define OSSL_OP_BAR 4711
983 \&
984 \& #define OSSL_FUNC_BAR_NEWCTX 1
985 \& typedef void *(OSSL_FUNC_bar_newctx_fn)(void *provctx);
986 \& static ossl_inline OSSL_FUNC_bar_newctx(const OSSL_DISPATCH *opf)
987 \& { return (OSSL_FUNC_bar_newctx_fn *)opf\->function; }
988 \&
989 \& #define OSSL_FUNC_BAR_FREECTX 2
990 \& typedef void (OSSL_FUNC_bar_freectx_fn)(void *ctx);
991 \& static ossl_inline OSSL_FUNC_bar_freectx(const OSSL_DISPATCH *opf)
992 \& { return (OSSL_FUNC_bar_freectx_fn *)opf\->function; }
993 \&
994 \& #define OSSL_FUNC_BAR_INIT 3
995 \& typedef void *(OSSL_FUNC_bar_init_fn)(void *ctx);
996 \& static ossl_inline OSSL_FUNC_bar_init(const OSSL_DISPATCH *opf)
997 \& { return (OSSL_FUNC_bar_init_fn *)opf\->function; }
998 \&
999 \& #define OSSL_FUNC_BAR_UPDATE 4
1000 \& typedef void *(OSSL_FUNC_bar_update_fn)(void *ctx,
1001 \& unsigned char *in, size_t inl);
1002 \& static ossl_inline OSSL_FUNC_bar_update(const OSSL_DISPATCH *opf)
1003 \& { return (OSSL_FUNC_bar_update_fn *)opf\->function; }
1004 \&
1005 \& #define OSSL_FUNC_BAR_FINAL 5
1006 \& typedef void *(OSSL_FUNC_bar_final_fn)(void *ctx);
1007 \& static ossl_inline OSSL_FUNC_bar_final(const OSSL_DISPATCH *opf)
1008 \& { return (OSSL_FUNC_bar_final_fn *)opf\->function; }
1009 .Ve
1010 .SH "SEE ALSO"
1011 .IX Header "SEE ALSO"
1012 \&\fBprovider\fR\|(7)
1013 .SH HISTORY
1014 .IX Header "HISTORY"
1015 The concept of providers and everything surrounding them was
1016 introduced in OpenSSL 3.0.
1017 .PP
1018 Definitions for
1019 \&\fBOSSL_CAPABILITY_TLS_SIGALG_MIN_DTLS\fR
1020 and
1021 \&\fBOSSL_CAPABILITY_TLS_SIGALG_MAX_DTLS\fR
1022 were added in OpenSSL 3.5.
1023 .SH COPYRIGHT
1024 .IX Header "COPYRIGHT"
1025 Copyright 2019\-2026 The OpenSSL Project Authors. All Rights Reserved.
1026 .PP
1027 Licensed under the Apache License 2.0 (the "License"). You may not use
1028 this file except in compliance with the License. You can obtain a copy
1029 in the file LICENSE in the source distribution or at
1030 <https://www.openssl.org/source/license.html>.