]>
Commit | Line | Data |
---|---|---|
c4532834 RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
6bd4e3f2 | 5 | OSSL_PROVIDER_set_default_search_path, |
ebe3f24b | 6 | OSSL_PROVIDER, OSSL_PROVIDER_load, OSSL_PROVIDER_try_load, OSSL_PROVIDER_unload, |
a7ad40c5 | 7 | OSSL_PROVIDER_available, OSSL_PROVIDER_do_all, |
dca97d00 | 8 | OSSL_PROVIDER_gettable_params, OSSL_PROVIDER_get_params, |
b0001d0c | 9 | OSSL_PROVIDER_query_operation, OSSL_PROVIDER_unquery_operation, |
878be71c | 10 | OSSL_PROVIDER_get0_provider_ctx, OSSL_PROVIDER_get0_dispatch, |
c4e91674 | 11 | OSSL_PROVIDER_add_builtin, OSSL_PROVIDER_get0_name, OSSL_PROVIDER_get_capabilities, |
878be71c | 12 | OSSL_PROVIDER_self_test |
04cb5ec0 | 13 | - provider routines |
c4532834 RL |
14 | |
15 | =head1 SYNOPSIS | |
16 | ||
17 | #include <openssl/provider.h> | |
18 | ||
19 | typedef struct ossl_provider_st OSSL_PROVIDER; | |
20 | ||
b4250010 | 21 | void OSSL_PROVIDER_set_default_search_path(OSSL_LIB_CTX *libctx, |
6bd4e3f2 P |
22 | const char *path); |
23 | ||
b4250010 | 24 | OSSL_PROVIDER *OSSL_PROVIDER_load(OSSL_LIB_CTX *libctx, const char *name); |
299f5ff3 P |
25 | OSSL_PROVIDER *OSSL_PROVIDER_try_load(OSSL_LIB_CTX *libctx, const char *name, |
26 | int retain_fallbacks); | |
c4532834 | 27 | int OSSL_PROVIDER_unload(OSSL_PROVIDER *prov); |
b4250010 DMSP |
28 | int OSSL_PROVIDER_available(OSSL_LIB_CTX *libctx, const char *name); |
29 | int OSSL_PROVIDER_do_all(OSSL_LIB_CTX *ctx, | |
a7ad40c5 RL |
30 | int (*cb)(OSSL_PROVIDER *provider, void *cbdata), |
31 | void *cbdata); | |
c4532834 | 32 | |
dca97d00 | 33 | const OSSL_PARAM *OSSL_PROVIDER_gettable_params(OSSL_PROVIDER *prov); |
4e7991b4 | 34 | int OSSL_PROVIDER_get_params(OSSL_PROVIDER *prov, OSSL_PARAM params[]); |
c4532834 | 35 | |
5f603a28 MC |
36 | const OSSL_ALGORITHM *OSSL_PROVIDER_query_operation(const OSSL_PROVIDER *prov, |
37 | int operation_id, | |
38 | int *no_cache); | |
b0001d0c P |
39 | void OSSL_PROVIDER_unquery_operation(const OSSL_PROVIDER *prov, |
40 | int operation_id, | |
41 | const OSSL_ALGORITHM *algs); | |
d01d3752 | 42 | void *OSSL_PROVIDER_get0_provider_ctx(const OSSL_PROVIDER *prov); |
878be71c | 43 | const OSSL_DISPATCH *OSSL_PROVIDER_get0_dispatch(const OSSL_PROVIDER *prov); |
5f603a28 | 44 | |
b4250010 | 45 | int OSSL_PROVIDER_add_builtin(OSSL_LIB_CTX *libctx, const char *name, |
c4532834 RL |
46 | ossl_provider_init_fn *init_fn); |
47 | ||
c4e91674 | 48 | const char *OSSL_PROVIDER_get0_name(const OSSL_PROVIDER *prov); |
b37066fd | 49 | |
3c49e4ff MC |
50 | int OSSL_PROVIDER_get_capabilities(const OSSL_PROVIDER *prov, |
51 | const char *capability, | |
52 | OSSL_CALLBACK *cb, | |
53 | void *arg); | |
04cb5ec0 | 54 | int OSSL_PROVIDER_self_test(const OSSL_PROVIDER *prov); |
3c49e4ff | 55 | |
c4532834 RL |
56 | =head1 DESCRIPTION |
57 | ||
58 | B<OSSL_PROVIDER> is a type that holds internal information about | |
59 | implementation providers (see L<provider(7)> for information on what a | |
60 | provider is). | |
61 | A provider can be built in to the application or the OpenSSL | |
62 | libraries, or can be a loadable module. | |
63 | The functions described here handle both forms. | |
64 | ||
36f5ec55 | 65 | Some of these functions operate within a library context, please see |
b4250010 | 66 | L<OSSL_LIB_CTX(3)> for further details. |
36f5ec55 | 67 | |
c4532834 RL |
68 | =head2 Functions |
69 | ||
2645c94b RL |
70 | OSSL_PROVIDER_set_default_search_path() specifies the default search I<path> |
71 | that is to be used for looking for providers in the specified I<libctx>. | |
6bd4e3f2 P |
72 | If left unspecified, an environment variable and a fall back default value will |
73 | be used instead. | |
74 | ||
c4532834 RL |
75 | OSSL_PROVIDER_add_builtin() is used to add a built in provider to |
76 | B<OSSL_PROVIDER> store in the given library context, by associating a | |
77 | provider name with a provider initialization function. | |
78 | This name can then be used with OSSL_PROVIDER_load(). | |
79 | ||
80 | OSSL_PROVIDER_load() loads and initializes a provider. | |
81 | This may simply initialize a provider that was previously added with | |
82 | OSSL_PROVIDER_add_builtin() and run its given initialization function, | |
83 | or load a provider module with the given name and run its provider | |
84 | entry point, C<OSSL_provider_init>. | |
85 | ||
ebe3f24b | 86 | OSSL_PROVIDER_try_load() functions like OSSL_PROVIDER_load(), except that |
3bc061eb | 87 | it does not disable the fallback providers if the provider cannot be |
299f5ff3 P |
88 | loaded and initialized or if I<retain_fallbacks> is zero. |
89 | If the provider loads successfully and I<retain_fallbacks> is nonzero, the | |
90 | fallback providers are disabled. | |
ebe3f24b | 91 | |
c4532834 RL |
92 | OSSL_PROVIDER_unload() unloads the given provider. |
93 | For a provider added with OSSL_PROVIDER_add_builtin(), this simply | |
94 | runs its teardown function. | |
95 | ||
36f5ec55 RL |
96 | OSSL_PROVIDER_available() checks if a named provider is available |
97 | for use. | |
98 | ||
a7ad40c5 RL |
99 | OSSL_PROVIDER_do_all() iterates over all loaded providers, calling |
100 | I<cb> for each one, with the current provider in I<provider> and the | |
3bc061eb MB |
101 | I<cbdata> that comes from the caller. If no other provider has been loaded |
102 | before calling this function, the default provider is still available as | |
103 | fallback. | |
104 | See L<OSSL_PROVIDER-default(7)> for more information on this fallback | |
105 | behaviour. | |
a7ad40c5 | 106 | |
dca97d00 | 107 | OSSL_PROVIDER_gettable_params() is used to get a provider parameter |
26175013 RL |
108 | descriptor set as a constant B<OSSL_PARAM> array. |
109 | See L<OSSL_PARAM(3)> for more information. | |
c4532834 RL |
110 | |
111 | OSSL_PROVIDER_get_params() is used to get provider parameter values. | |
112 | The caller must prepare the B<OSSL_PARAM> array before calling this | |
113 | function, and the variables acting as buffers for this parameter array | |
114 | should be filled with data when it returns successfully. | |
115 | ||
04cb5ec0 SL |
116 | OSSL_PROVIDER_self_test() is used to run a provider's self tests on demand. |
117 | If the self tests fail then the provider will fail to provide any further | |
118 | services and algorithms. L<OSSL_SELF_TEST_set_callback(3)> may be called | |
119 | beforehand in order to display diagnostics for the running self tests. | |
120 | ||
5f603a28 | 121 | OSSL_PROVIDER_query_operation() calls the provider's I<query_operation> |
d01d3752 | 122 | function (see L<provider(7)>), if the provider has one. It returns an |
5f603a28 MC |
123 | array of I<OSSL_ALGORITHM> for the given I<operation_id> terminated by an all |
124 | NULL OSSL_ALGORITHM entry. This is considered a low-level function that most | |
125 | applications should not need to call. | |
126 | ||
b0001d0c P |
127 | OSSL_PROVIDER_unquery_operation() calls the provider's I<unquery_operation> |
128 | function (see L<provider(7)>), if the provider has one. This is considered a | |
129 | low-level function that most applications should not need to call. | |
130 | ||
d01d3752 MC |
131 | OSSL_PROVIDER_get0_provider_ctx() returns the provider context for the given |
132 | provider. The provider context is an opaque handle set by the provider itself | |
133 | and is passed back to the provider by libcrypto in various function calls. | |
134 | ||
878be71c MC |
135 | OSSL_PROVIDER_get0_dispatch() returns the provider's dispatch table as it was |
136 | returned in the I<out> parameter from the provider's init function. See | |
137 | L<provider-base(7)>. | |
138 | ||
5f603a28 | 139 | If it is permissible to cache references to this array then I<*no_store> is set |
d01d3752 | 140 | to 0 or 1 otherwise. If the array is not cacheable then it is assumed to |
5f603a28 MC |
141 | have a short lifetime. |
142 | ||
c4e91674 | 143 | OSSL_PROVIDER_get0_name() returns the name of the given provider. |
b37066fd | 144 | |
3c49e4ff MC |
145 | OSSL_PROVIDER_get_capabilities() provides information about the capabilities |
146 | supported by the provider specified in I<prov> with the capability name | |
147 | I<capability>. For each capability of that name supported by the provider it | |
148 | will call the callback I<cb> and supply a set of B<OSSL_PARAM>s describing the | |
149 | capability. It will also pass back the argument I<arg>. For more details about | |
150 | capabilities and what they can be used for please see | |
151 | L<provider-base(7)/CAPABILTIIES>. | |
152 | ||
c4532834 RL |
153 | =head1 RETURN VALUES |
154 | ||
3c49e4ff MC |
155 | OSSL_PROVIDER_add(), OSSL_PROVIDER_unload(), OSSL_PROVIDER_get_params() and |
156 | OSSL_PROVIDER_get_capabilities() return 1 on success, or 0 on error. | |
c4532834 | 157 | |
ebe3f24b | 158 | OSSL_PROVIDER_load() and OSSL_PROVIDER_try_load() return a pointer to a |
2645c94b | 159 | provider object on success, or NULL on error. |
c4532834 | 160 | |
3bc061eb MB |
161 | OSSL_PROVIDER_do_all() returns 1 if the callback I<cb> returns 1 for every |
162 | provider it is called with, or 0 if any provider callback invocation returns 0; | |
163 | callback processing stops at the first callback invocation on a provider | |
164 | that returns 0. | |
165 | ||
36f5ec55 RL |
166 | OSSL_PROVIDER_available() returns 1 if the named provider is available, |
167 | otherwise 0. | |
168 | ||
dca97d00 | 169 | OSSL_PROVIDER_gettable_params() returns a pointer to an array |
26175013 | 170 | of constant B<OSSL_PARAM>, or NULL if none is provided. |
c4532834 | 171 | |
04cb5ec0 | 172 | OSSL_PROVIDER_get_params() and returns 1 on success, or 0 on error. |
c4532834 | 173 | |
5f603a28 MC |
174 | OSSL_PROVIDER_query_operation() returns an array of OSSL_ALGORITHM or NULL on |
175 | error. | |
176 | ||
04cb5ec0 SL |
177 | OSSL_PROVIDER_self_test() returns 1 if the self tests pass, or 0 on error. |
178 | ||
c4532834 RL |
179 | =head1 EXAMPLES |
180 | ||
181 | This demonstrates how to load the provider module "foo" and ask for | |
182 | its build number. | |
183 | ||
184 | OSSL_PROVIDER *prov = NULL; | |
185 | const char *build = NULL; | |
186 | size_t built_l = 0; | |
4e7991b4 | 187 | OSSL_PARAM request[] = { |
c4532834 RL |
188 | { "build", OSSL_PARAM_UTF8_STRING_PTR, &build, 0, &build_l }, |
189 | { NULL, 0, NULL, 0, NULL } | |
190 | }; | |
191 | ||
192 | if ((prov = OSSL_PROVIDER_load(NULL, "foo")) != NULL | |
193 | && OSSL_PROVIDER_get_params(prov, request)) | |
194 | printf("Provider 'foo' build %s\n", build); | |
195 | else | |
196 | ERR_print_errors_fp(stderr); | |
197 | ||
198 | =head1 SEE ALSO | |
199 | ||
b4250010 | 200 | L<openssl-core.h(7)>, L<OSSL_LIB_CTX(3)>, L<provider(7)> |
c4532834 RL |
201 | |
202 | =head1 HISTORY | |
203 | ||
204 | The type and functions described here were added in OpenSSL 3.0. | |
205 | ||
206 | =head1 COPYRIGHT | |
207 | ||
4333b89f | 208 | Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. |
c4532834 RL |
209 | |
210 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
211 | this file except in compliance with the License. You can obtain a copy | |
212 | in the file LICENSE in the source distribution or at | |
213 | L<https://www.openssl.org/source/license.html>. | |
214 | ||
215 | =cut |