Debian Codegraph @

upstream/debian-unstable/man3/OSSL_PROVIDER.3ssl

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 "OSSL_PROVIDER 3SSL"
58 .TH OSSL_PROVIDER 3SSL 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 OSSL_PROVIDER_set_default_search_path,
65 OSSL_PROVIDER_get0_default_search_path,
66 OSSL_PROVIDER, OSSL_PROVIDER_load, OSSL_PROVIDER_try_load, OSSL_PROVIDER_unload,
67 OSSL_PROVIDER_load_ex, OSSL_PROVIDER_try_load_ex,
68 OSSL_PROVIDER_available, OSSL_PROVIDER_do_all,
69 OSSL_PROVIDER_gettable_params, OSSL_PROVIDER_get_params,
70 OSSL_PROVIDER_query_operation, OSSL_PROVIDER_unquery_operation,
71 OSSL_PROVIDER_get0_provider_ctx, OSSL_PROVIDER_get0_dispatch,
72 OSSL_PROVIDER_add_builtin, OSSL_PROVIDER_get0_name, OSSL_PROVIDER_get_capabilities,
73 OSSL_PROVIDER_add_conf_parameter, OSSL_PROVIDER_get_conf_parameters,
74 OSSL_PROVIDER_conf_get_bool, OSSL_PROVIDER_self_test
75 \&\- provider routines
76 .SH SYNOPSIS
77 .IX Header "SYNOPSIS"
78 .Vb 1
79 \& #include <openssl/provider.h>
80 \&
81 \& typedef struct ossl_provider_st OSSL_PROVIDER;
82 \&
83 \& int OSSL_PROVIDER_set_default_search_path(OSSL_LIB_CTX *libctx,
84 \& const char *path);
85 \& const char *OSSL_PROVIDER_get0_default_search_path(OSSL_LIB_CTX *libctx);
86 \&
87 \& OSSL_PROVIDER *OSSL_PROVIDER_load(OSSL_LIB_CTX *libctx, const char *name);
88 \& OSSL_PROVIDER *OSSL_PROVIDER_load_ex(OSSL_LIB_CTX *, const char *name,
89 \& OSSL_PARAM *params);
90 \& OSSL_PROVIDER *OSSL_PROVIDER_try_load(OSSL_LIB_CTX *libctx, const char *name,
91 \& int retain_fallbacks);
92 \& OSSL_PROVIDER *OSSL_PROVIDER_try_load_ex(OSSL_LIB_CTX *, const char *name,
93 \& OSSL_PARAM *params,
94 \& int retain_fallbacks);
95 \& int OSSL_PROVIDER_unload(OSSL_PROVIDER *prov);
96 \& int OSSL_PROVIDER_available(OSSL_LIB_CTX *libctx, const char *name);
97 \& int OSSL_PROVIDER_do_all(OSSL_LIB_CTX *ctx,
98 \& int (*cb)(OSSL_PROVIDER *provider, void *cbdata),
99 \& void *cbdata);
100 \&
101 \& const OSSL_PARAM *OSSL_PROVIDER_gettable_params(OSSL_PROVIDER *prov);
102 \& int OSSL_PROVIDER_get_params(OSSL_PROVIDER *prov, OSSL_PARAM params[]);
103 \&
104 \& const OSSL_ALGORITHM *OSSL_PROVIDER_query_operation(const OSSL_PROVIDER *prov,
105 \& int operation_id,
106 \& int *no_cache);
107 \& void OSSL_PROVIDER_unquery_operation(const OSSL_PROVIDER *prov,
108 \& int operation_id,
109 \& const OSSL_ALGORITHM *algs);
110 \& void *OSSL_PROVIDER_get0_provider_ctx(const OSSL_PROVIDER *prov);
111 \& const OSSL_DISPATCH *OSSL_PROVIDER_get0_dispatch(const OSSL_PROVIDER *prov);
112 \&
113 \& int OSSL_PROVIDER_add_builtin(OSSL_LIB_CTX *libctx, const char *name,
114 \& ossl_provider_init_fn *init_fn);
115 \&
116 \& const char *OSSL_PROVIDER_get0_name(const OSSL_PROVIDER *prov);
117 \&
118 \& int OSSL_PROVIDER_get_capabilities(const OSSL_PROVIDER *prov,
119 \& const char *capability,
120 \& OSSL_CALLBACK *cb,
121 \& void *arg);
122 \& int OSSL_PROVIDER_add_conf_parameter(OSSL_PROVIDER *prov, const char *name,
123 \& const char *value);
124 \& int OSSL_PROVIDER_get_conf_parameters(OSSL_PROVIDER *prov,
125 \& OSSL_PARAM params[]);
126 \& int OSSL_PROVIDER_conf_get_bool(const OSSL_PROVIDER *prov,
127 \& const char *name, int defval);
128 \& int OSSL_PROVIDER_self_test(const OSSL_PROVIDER *prov);
129 .Ve
130 .SH DESCRIPTION
131 .IX Header "DESCRIPTION"
132 \&\fBOSSL_PROVIDER\fR is a type that holds internal information about
133 implementation providers (see \fBprovider\fR\|(7) for information on what a
134 provider is).
135 A provider can be built in to the application or the OpenSSL
136 libraries, or can be a loadable module.
137 The functions described here handle both forms.
138 .PP
139 Some of these functions operate within a library context, please see
140 \&\fBOSSL_LIB_CTX\fR\|(3) for further details.
141 .SS Functions
142 .IX Subsection "Functions"
143 \&\fBOSSL_PROVIDER_set_default_search_path()\fR specifies the default search \fIpath\fR
144 that is to be used for looking for providers in the specified \fIlibctx\fR.
145 If left unspecified, an environment variable and a fall back default value will
146 be used instead.
147 .PP
148 \&\fBOSSL_PROVIDER_get0_default_search_path()\fR retrieves the default search \fIpath\fR
149 that is to be used for looking for providers in the specified \fIlibctx\fR.
150 If successful returns the path or empty string; the path is valid until the
151 context is released or \fBOSSL_PROVIDER_set_default_search_path()\fR is called.
152 .PP
153 \&\fBOSSL_PROVIDER_add_builtin()\fR is used to add a built in provider to
154 \&\fBOSSL_PROVIDER\fR store in the given library context, by associating a
155 provider name with a provider initialization function.
156 This name can then be used with \fBOSSL_PROVIDER_load()\fR.
157 .PP
158 \&\fBOSSL_PROVIDER_load()\fR loads and initializes a provider.
159 This may simply initialize a provider that was previously added with
160 \&\fBOSSL_PROVIDER_add_builtin()\fR and run its given initialization function,
161 or load a provider module with the given name and run its provider
162 entry point, \f(CW\*(C`OSSL_provider_init\*(C'\fR. The \fIname\fR can be a path
163 to a provider module, in that case the provider name as returned
164 by \fBOSSL_PROVIDER_get0_name()\fR will be the path. Interpretation
165 of relative paths is platform dependent and they are relative
166 to the configured "MODULESDIR" directory or the path set in
167 the environment variable OPENSSL_MODULES if set.
168 .PP
169 \&\fBOSSL_PROVIDER_try_load()\fR functions like \fBOSSL_PROVIDER_load()\fR, except that
170 it does not disable the fallback providers if the provider cannot be
171 loaded and initialized or if \fIretain_fallbacks\fR is nonzero.
172 If the provider loads successfully and \fIretain_fallbacks\fR is zero, the
173 fallback providers are disabled.
174 .PP
175 \&\fBOSSL_PROVIDER_load_ex()\fR and \fBOSSL_PROVIDER_try_load_ex()\fR are the variants
176 of the previous functions accepting an \f(CW\*(C`OSSL_PARAM\*(C'\fR array of the parameters
177 that are passed as the configuration of the loaded provider. The parameters
178 of any type but \f(CW\*(C`OSSL_PARAM_UTF8_STRING\*(C'\fR are silently ignored. If the
179 parameters are provided, they replace \fBall\fR the ones specified in the
180 configuration file.
181 .PP
182 \&\fBOSSL_PROVIDER_unload()\fR unloads the given provider.
183 For a provider added with \fBOSSL_PROVIDER_add_builtin()\fR, this simply
184 runs its teardown function.
185 .PP
186 \&\fBOSSL_PROVIDER_available()\fR checks if a named provider is available
187 for use.
188 .PP
189 \&\fBOSSL_PROVIDER_do_all()\fR iterates over all loaded providers, calling
190 \&\fIcb\fR for each one, with the current provider in \fIprovider\fR and the
191 \&\fIcbdata\fR that comes from the caller. If no other provider has been loaded
192 before calling this function, the default provider is still available as
193 fallback.
194 See \fBOSSL_PROVIDER\-default\fR\|(7) for more information on this fallback
195 behaviour.
196 .PP
197 \&\fBOSSL_PROVIDER_gettable_params()\fR is used to get a provider parameter
198 descriptor set as a constant \fBOSSL_PARAM\fR\|(3) array.
199 .PP
200 \&\fBOSSL_PROVIDER_get_params()\fR is used to get provider parameter values.
201 The caller must prepare the \fBOSSL_PARAM\fR\|(3) array before calling this
202 function, and the variables acting as buffers for this parameter array
203 should be filled with data when it returns successfully.
204 .PP
205 \&\fBOSSL_PROVIDER_add_conf_parameter()\fR sets the provider configuration parameter
206 \&\fIname\fR to \fIvalue\fR.
207 Provider configuration parameters are managed by the OpenSSL core and normally
208 set in the configuration file, but can also be set early in the main program
209 before a provider is in use by multiple threads.
210 Parameters that only affect provider initialisation must, for now, be set in
211 the configuration file, only parameters that are also queried later have any
212 affect when set via this interface.
213 Only text parameters can be given, and it's up to the provider to
214 interpret them.
215 .PP
216 \&\fBOSSL_PROVIDER_get_conf_parameters()\fR retrieves global configuration parameters
217 associated with \fIprov\fR.
218 These configuration parameters are stored for each provider by the OpenSSL core,
219 not the provider itself, parameters managed by the provider are queried via
220 \&\fBOSSL_PROVIDER_get_params()\fR described above.
221 The parameters are returned by reference, not as copies, and so the elements of
222 the \fIparam\fR array must have \fBOSSL_PARAM_UTF8_PTR\fR as their \fBdata_type\fR.
223 .PP
224 \&\fBOSSL_PROVIDER_conf_get_bool()\fR parses the global configuration parameter \fIname\fR
225 associated with provider \fIprov\fR as a boolean value, returning a default value
226 \&\fIdefval\fR when unable to retrieve or parse the parameter.
227 Parameter values equal (case-insensitively) to \f(CW1\fR, \f(CW\*(C`on\*(C'\fR, \f(CW\*(C`yes\*(C'\fR, or \f(CW\*(C`true\*(C'\fR
228 yield a true (nonzero) result.
229 Parameter values equal (case-insensitively) to \f(CW0\fR, \f(CW\*(C`off\*(C'\fR, \f(CW\*(C`no\*(C'\fR, or \f(CW\*(C`false\*(C'\fR
230 yield a false (zero) result.
231 .PP
232 \&\fBOSSL_PROVIDER_self_test()\fR is used to run a provider's self tests on demand.
233 If the self tests fail then the provider will fail to provide any further
234 services and algorithms. \fBOSSL_SELF_TEST_set_callback\fR\|(3) may be called
235 beforehand in order to display diagnostics for the running self tests.
236 .PP
237 \&\fBOSSL_PROVIDER_query_operation()\fR calls the provider's \fIquery_operation\fR
238 function (see \fBprovider\fR\|(7)), if the provider has one. It returns an
239 array of \fIOSSL_ALGORITHM\fR for the given \fIoperation_id\fR terminated by an all
240 NULL OSSL_ALGORITHM entry. This is considered a low-level function that most
241 applications should not need to call.
242 .PP
243 \&\fBOSSL_PROVIDER_unquery_operation()\fR calls the provider's \fIunquery_operation\fR
244 function (see \fBprovider\fR\|(7)), if the provider has one. This is considered a
245 low-level function that most applications should not need to call.
246 .PP
247 \&\fBOSSL_PROVIDER_get0_provider_ctx()\fR returns the provider context for the given
248 provider. The provider context is an opaque handle set by the provider itself
249 and is passed back to the provider by libcrypto in various function calls.
250 .PP
251 \&\fBOSSL_PROVIDER_get0_dispatch()\fR returns the provider's dispatch table as it was
252 returned in the \fIout\fR parameter from the provider's init function. See
253 \&\fBprovider\-base\fR\|(7).
254 .PP
255 If it is permissible to cache references to this array then \fI*no_store\fR is set
256 to 0 or 1 otherwise. If the array is not cacheable then it is assumed to
257 have a short lifetime.
258 .PP
259 \&\fBOSSL_PROVIDER_get0_name()\fR returns the name of the given provider.
260 .PP
261 \&\fBOSSL_PROVIDER_get_capabilities()\fR provides information about the capabilities
262 supported by the provider specified in \fIprov\fR with the capability name
263 \&\fIcapability\fR. For each capability of that name supported by the provider it
264 will call the callback \fIcb\fR and supply a set of \fBOSSL_PARAM\fR\|(3)s describing the
265 capability. It will also pass back the argument \fIarg\fR. For more details about
266 capabilities and what they can be used for please see
267 "CAPABILITIES" in \fBprovider\-base\fR\|(7).
268 .SH "RETURN VALUES"
269 .IX Header "RETURN VALUES"
270 \&\fBOSSL_PROVIDER_set_default_search_path()\fR, \fBOSSL_PROVIDER_add()\fR,
271 \&\fBOSSL_PROVIDER_unload()\fR, \fBOSSL_PROVIDER_get_params()\fR,
272 \&\fBOSSL_PROVIDER_add_conf_parameter()\fR, \fBOSSL_PROVIDER_get_conf_parameters()\fR
273 and
274 \&\fBOSSL_PROVIDER_get_capabilities()\fR return 1 on success, or 0 on error.
275 .PP
276 \&\fBOSSL_PROVIDER_get0_default_search_path()\fR returns a pointer to a path on success,
277 or NULL on error or if the path has not previously been set.
278 .PP
279 \&\fBOSSL_PROVIDER_load()\fR and \fBOSSL_PROVIDER_try_load()\fR return a pointer to a
280 provider object on success, or NULL on error.
281 .PP
282 \&\fBOSSL_PROVIDER_do_all()\fR returns 1 if the callback \fIcb\fR returns 1 for every
283 provider it is called with, or 0 if any provider callback invocation returns 0;
284 callback processing stops at the first callback invocation on a provider
285 that returns 0.
286 .PP
287 \&\fBOSSL_PROVIDER_available()\fR returns 1 if the named provider is available,
288 otherwise 0.
289 .PP
290 \&\fBOSSL_PROVIDER_gettable_params()\fR returns a pointer to an array
291 of constant \fBOSSL_PARAM\fR\|(3), or NULL if none is provided.
292 .PP
293 \&\fBOSSL_PROVIDER_get_params()\fR and returns 1 on success, or 0 on error.
294 .PP
295 \&\fBOSSL_PROVIDER_query_operation()\fR returns an array of OSSL_ALGORITHM or NULL on
296 error.
297 .PP
298 \&\fBOSSL_PROVIDER_self_test()\fR returns 1 if the self tests pass, or 0 on error.
299 .SH EXAMPLES
300 .IX Header "EXAMPLES"
301 This demonstrates how to load the provider module "foo" and ask for
302 its build information.
303 .PP
304 .Vb 3
305 \& #include <openssl/params.h>
306 \& #include <openssl/provider.h>
307 \& #include <openssl/err.h>
308 \&
309 \& OSSL_PROVIDER *prov = NULL;
310 \& const char *build = NULL;
311 \& OSSL_PARAM request[] = {
312 \& { "buildinfo", OSSL_PARAM_UTF8_PTR, &build, 0, 0 },
313 \& { NULL, 0, NULL, 0, 0 }
314 \& };
315 \&
316 \& if ((prov = OSSL_PROVIDER_load(NULL, "foo")) != NULL
317 \& && OSSL_PROVIDER_get_params(prov, request))
318 \& printf("Provider \*(Aqfoo\*(Aq buildinfo: %s\en", build);
319 \& else
320 \& ERR_print_errors_fp(stderr);
321 .Ve
322 .SH "SEE ALSO"
323 .IX Header "SEE ALSO"
324 \&\fBopenssl\-core.h\fR\|(7), \fBOSSL_LIB_CTX\fR\|(3), \fBprovider\fR\|(7)
325 .SH HISTORY
326 .IX Header "HISTORY"
327 The type and functions described here were added in OpenSSL 3.0.
328 .PP
329 The \fIOSSL_PROVIDER_load_ex\fR and \fIOSSL_PROVIDER_try_load_ex\fR functions were
330 added in OpenSSL 3.2.
331 .PP
332 The
333 \&\fIOSSL_PROVIDER_add_conf_parameter\fR,
334 \&\fIOSSL_PROVIDER_get_conf_parameters\fR, and
335 \&\fIOSSL_PROVIDER_conf_get_bool\fR functions
336 were added in OpenSSL 3.5.
337 .SH COPYRIGHT
338 .IX Header "COPYRIGHT"
339 Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved.
340 .PP
341 Licensed under the Apache License 2.0 (the "License"). You may not use
342 this file except in compliance with the License. You can obtain a copy
343 in the file LICENSE in the source distribution or at
344 <https://www.openssl.org/source/license.html>.