]>
Commit | Line | Data |
---|---|---|
d4c69c69 RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | provider-base | |
6 | - The basic OpenSSL library E<lt>-E<gt> provider functions | |
7 | ||
8 | =head1 SYNOPSIS | |
9 | ||
23c48d94 | 10 | #include <openssl/core_dispatch.h> |
d4c69c69 RL |
11 | |
12 | /* | |
13 | * None of these are actual functions, but are displayed like this for | |
14 | * the function signatures for functions that are offered as function | |
15 | * pointers in OSSL_DISPATCH arrays. | |
16 | */ | |
17 | ||
18 | /* Functions offered by libcrypto to the providers */ | |
06a2027b MC |
19 | const OSSL_ITEM *core_gettable_params(const OSSL_CORE_HANDLE *handle); |
20 | int core_get_params(const OSSL_CORE_HANDLE *handle, OSSL_PARAM params[]); | |
886ad004 MC |
21 | |
22 | typedef void (*OSSL_thread_stop_handler_fn)(void *arg); | |
06a2027b | 23 | int core_thread_start(const OSSL_CORE_HANDLE *handle, |
bca0ffe8 P |
24 | OSSL_thread_stop_handler_fn handfn, |
25 | void *arg); | |
886ad004 | 26 | |
a829b735 | 27 | OPENSSL_CORE_CTX *core_get_libctx(const OSSL_CORE_HANDLE *handle); |
06a2027b MC |
28 | void core_new_error(const OSSL_CORE_HANDLE *handle); |
29 | void core_set_error_debug(const OSSL_CORE_HANDLE *handle, | |
49c64346 | 30 | const char *file, int line, const char *func); |
06a2027b | 31 | void core_vset_error(const OSSL_CORE_HANDLE *handle, |
49c64346 | 32 | uint32_t reason, const char *fmt, va_list args); |
d4c69c69 | 33 | |
599429e0 MC |
34 | int core_obj_add_sigid(const OSSL_CORE_HANDLE *prov, const char *sign_name, |
35 | const char *digest_name, const char *pkey_name); | |
36 | int core_obj_create(const OSSL_CORE_HANDLE *handle, const char *oid, | |
37 | const char *sn, const char *ln); | |
38 | ||
d4c69c69 RL |
39 | /* |
40 | * Some OpenSSL functionality is directly offered to providers via | |
41 | * dispatch | |
42 | */ | |
43 | void *CRYPTO_malloc(size_t num, const char *file, int line); | |
44 | void *CRYPTO_zalloc(size_t num, const char *file, int line); | |
d4c69c69 RL |
45 | void CRYPTO_free(void *ptr, const char *file, int line); |
46 | void CRYPTO_clear_free(void *ptr, size_t num, | |
47 | const char *file, int line); | |
48 | void *CRYPTO_realloc(void *addr, size_t num, | |
49 | const char *file, int line); | |
50 | void *CRYPTO_clear_realloc(void *addr, size_t old_num, size_t num, | |
51 | const char *file, int line); | |
52 | void *CRYPTO_secure_malloc(size_t num, const char *file, int line); | |
53 | void *CRYPTO_secure_zalloc(size_t num, const char *file, int line); | |
54 | void CRYPTO_secure_free(void *ptr, const char *file, int line); | |
55 | void CRYPTO_secure_clear_free(void *ptr, size_t num, | |
56 | const char *file, int line); | |
57 | int CRYPTO_secure_allocated(const void *ptr); | |
58 | void OPENSSL_cleanse(void *ptr, size_t len); | |
06a2027b | 59 | |
af352165 P |
60 | unsigned char *OPENSSL_hexstr2buf(const char *str, long *buflen); |
61 | ||
925b5360 P |
62 | OSSL_CORE_BIO *BIO_new_file(const char *filename, const char *mode); |
63 | OSSL_CORE_BIO *BIO_new_membuf(const void *buf, int len); | |
06a2027b | 64 | int BIO_read_ex(OSSL_CORE_BIO *bio, void *data, size_t data_len, |
925b5360 | 65 | size_t *bytes_read); |
06a2027b | 66 | int BIO_write_ex(OSSL_CORE_BIO *bio, const void *data, size_t data_len, |
925b5360 P |
67 | size_t *written); |
68 | int BIO_up_ref(OSSL_CORE_BIO *bio); | |
69 | int BIO_free(OSSL_CORE_BIO *bio); | |
70 | int BIO_vprintf(OSSL_CORE_BIO *bio, const char *format, va_list args); | |
71 | int BIO_vsnprintf(char *buf, size_t n, const char *fmt, va_list args); | |
06a2027b | 72 | |
af352165 P |
73 | void OSSL_SELF_TEST_set_callback(OSSL_LIB_CTX *libctx, OSSL_CALLBACK *cb, |
74 | void *cbarg); | |
06a2027b | 75 | |
71febb39 P |
76 | size_t get_entropy(const OSSL_CORE_HANDLE *handle, |
77 | unsigned char **pout, int entropy, | |
925b5360 | 78 | size_t min_len, size_t max_len); |
71febb39 | 79 | void cleanup_entropy(const OSSL_CORE_HANDLE *handle, |
925b5360 | 80 | unsigned char *buf, size_t len); |
71febb39 P |
81 | size_t get_nonce(const OSSL_CORE_HANDLE *handle, |
82 | unsigned char **pout, size_t min_len, size_t max_len, | |
925b5360 | 83 | const void *salt, size_t salt_len); |
71febb39 | 84 | void cleanup_nonce(const OSSL_CORE_HANDLE *handle, |
925b5360 | 85 | unsigned char *buf, size_t len); |
d4c69c69 | 86 | |
878be71c MC |
87 | /* Functions for querying the providers in the application library context */ |
88 | int provider_register_child_cb(const OSSL_CORE_HANDLE *handle, | |
89 | int (*create_cb)(const OSSL_CORE_HANDLE *provider, | |
90 | void *cbdata), | |
91 | int (*remove_cb)(const OSSL_CORE_HANDLE *provider, | |
92 | void *cbdata), | |
b1956770 | 93 | int (*global_props_cb)(const char *props, void *cbdata), |
878be71c MC |
94 | void *cbdata); |
95 | void provider_deregister_child_cb(const OSSL_CORE_HANDLE *handle); | |
96 | const char *provider_name(const OSSL_CORE_HANDLE *prov); | |
97 | void *provider_get0_provider_ctx(const OSSL_CORE_HANDLE *prov); | |
98 | const OSSL_DISPATCH *provider_get0_dispatch(const OSSL_CORE_HANDLE *prov); | |
99 | int provider_up_ref(const OSSL_CORE_HANDLE *prov, int activate); | |
100 | int provider_free(const OSSL_CORE_HANDLE *prov, int deactivate); | |
101 | ||
d4c69c69 RL |
102 | /* Functions offered by the provider to libcrypto */ |
103 | void provider_teardown(void *provctx); | |
dca97d00 | 104 | const OSSL_ITEM *provider_gettable_params(void *provctx); |
d4c69c69 RL |
105 | int provider_get_params(void *provctx, OSSL_PARAM params[]); |
106 | const OSSL_ALGORITHM *provider_query_operation(void *provctx, | |
107 | int operation_id, | |
108 | const int *no_store); | |
b0001d0c P |
109 | void provider_unquery_operation(void *provctx, int operation_id, |
110 | const OSSL_ALGORITHM *algs); | |
d4c69c69 | 111 | const OSSL_ITEM *provider_get_reason_strings(void *provctx); |
3c49e4ff MC |
112 | int provider_get_capabilities(void *provctx, const char *capability, |
113 | OSSL_CALLBACK *cb, void *arg); | |
af352165 | 114 | int provider_self_test(void *provctx); |
d4c69c69 RL |
115 | |
116 | =head1 DESCRIPTION | |
117 | ||
118 | All "functions" mentioned here are passed as function pointers between | |
318a9dfa | 119 | F<libcrypto> and the provider in L<OSSL_DISPATCH(3)> arrays, in the call |
d4c69c69 | 120 | of the provider initialization function. See L<provider(7)/Provider> |
9b6d17e4 | 121 | for a description of the initialization function. They are known as "upcalls". |
d4c69c69 RL |
122 | |
123 | All these "functions" have a corresponding function type definition | |
bd6e7fb7 | 124 | named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the |
318a9dfa | 125 | function pointer from a L<OSSL_DISPATCH(3)> element named |
363b1e5d | 126 | B<OSSL_FUNC_{name}>. |
dca97d00 | 127 | For example, the "function" core_gettable_params() has these: |
d4c69c69 | 128 | |
06a2027b | 129 | typedef OSSL_PARAM * |
363b1e5d | 130 | (OSSL_FUNC_core_gettable_params_fn)(const OSSL_CORE_HANDLE *handle); |
dca97d00 | 131 | static ossl_inline OSSL_NAME_core_gettable_params_fn |
363b1e5d | 132 | OSSL_FUNC_core_gettable_params(const OSSL_DISPATCH *opf); |
d4c69c69 | 133 | |
318a9dfa | 134 | L<OSSL_DISPATCH(3)> arrays are indexed by numbers that are provided as |
23c48d94 | 135 | macros in L<openssl-core_dispatch.h(7)>, as follows: |
d4c69c69 | 136 | |
318a9dfa | 137 | For I<in> (the L<OSSL_DISPATCH(3)> array passed from F<libcrypto> to the |
d4c69c69 RL |
138 | provider): |
139 | ||
dca97d00 | 140 | core_gettable_params OSSL_FUNC_CORE_GETTABLE_PARAMS |
d4c69c69 RL |
141 | core_get_params OSSL_FUNC_CORE_GET_PARAMS |
142 | core_thread_start OSSL_FUNC_CORE_THREAD_START | |
a829b735 | 143 | core_get_libctx OSSL_FUNC_CORE_GET_LIBCTX |
49c64346 RL |
144 | core_new_error OSSL_FUNC_CORE_NEW_ERROR |
145 | core_set_error_debug OSSL_FUNC_CORE_SET_ERROR_DEBUG | |
af352165 | 146 | core_vset_error OSSL_FUNC_CORE_VSET_ERROR |
599429e0 MC |
147 | core_obj_add_sigid OSSL_FUNC_CORE_OBJ_ADD_SIGID |
148 | core_obj_create OSSL_FUNC_CORE_OBJ_CREATE | |
d4c69c69 RL |
149 | CRYPTO_malloc OSSL_FUNC_CRYPTO_MALLOC |
150 | CRYPTO_zalloc OSSL_FUNC_CRYPTO_ZALLOC | |
d4c69c69 RL |
151 | CRYPTO_free OSSL_FUNC_CRYPTO_FREE |
152 | CRYPTO_clear_free OSSL_FUNC_CRYPTO_CLEAR_FREE | |
153 | CRYPTO_realloc OSSL_FUNC_CRYPTO_REALLOC | |
154 | CRYPTO_clear_realloc OSSL_FUNC_CRYPTO_CLEAR_REALLOC | |
155 | CRYPTO_secure_malloc OSSL_FUNC_CRYPTO_SECURE_MALLOC | |
156 | CRYPTO_secure_zalloc OSSL_FUNC_CRYPTO_SECURE_ZALLOC | |
157 | CRYPTO_secure_free OSSL_FUNC_CRYPTO_SECURE_FREE | |
158 | CRYPTO_secure_clear_free OSSL_FUNC_CRYPTO_SECURE_CLEAR_FREE | |
159 | CRYPTO_secure_allocated OSSL_FUNC_CRYPTO_SECURE_ALLOCATED | |
25e60144 SL |
160 | BIO_new_file OSSL_FUNC_BIO_NEW_FILE |
161 | BIO_new_mem_buf OSSL_FUNC_BIO_NEW_MEMBUF | |
7bb82f92 | 162 | BIO_read_ex OSSL_FUNC_BIO_READ_EX |
56ba2b78 | 163 | BIO_write_ex OSSL_FUNC_BIO_WRITE_EX |
925b5360 | 164 | BIO_up_ref OSSL_FUNC_BIO_UP_REF |
25e60144 | 165 | BIO_free OSSL_FUNC_BIO_FREE |
63665fff | 166 | BIO_vprintf OSSL_FUNC_BIO_VPRINTF |
56ba2b78 P |
167 | BIO_vsnprintf OSSL_FUNC_BIO_VSNPRINTF |
168 | BIO_puts OSSL_FUNC_BIO_PUTS | |
169 | BIO_gets OSSL_FUNC_BIO_GETS | |
170 | BIO_ctrl OSSL_FUNC_BIO_CTRL | |
d4c69c69 | 171 | OPENSSL_cleanse OSSL_FUNC_OPENSSL_CLEANSE |
36fc5fc6 | 172 | OSSL_SELF_TEST_set_callback OSSL_FUNC_SELF_TEST_CB |
71febb39 P |
173 | ossl_rand_get_entropy OSSL_FUNC_GET_ENTROPY |
174 | ossl_rand_cleanup_entropy OSSL_FUNC_CLEANUP_ENTROPY | |
175 | ossl_rand_get_nonce OSSL_FUNC_GET_NONCE | |
176 | ossl_rand_cleanup_nonce OSSL_FUNC_CLEANUP_NONCE | |
b88a3b10 P |
177 | provider_register_child_cb OSSL_FUNC_PROVIDER_REGISTER_CHILD_CB |
178 | provider_deregister_child_cb OSSL_FUNC_PROVIDER_DEREGISTER_CHILD_CB | |
179 | provider_name OSSL_FUNC_PROVIDER_NAME | |
180 | provider_get0_provider_ctx OSSL_FUNC_PROVIDER_GET0_PROVIDER_CTX | |
181 | provider_get0_dispatch OSSL_FUNC_PROVIDER_GET0_DISPATCH | |
182 | provider_up_ref OSSL_FUNC_PROVIDER_UP_REF | |
183 | provider_free OSSL_FUNC_PROVIDER_FREE | |
d4c69c69 | 184 | |
318a9dfa | 185 | For I<*out> (the L<OSSL_DISPATCH(3)> array passed from the provider to |
d4c69c69 RL |
186 | F<libcrypto>): |
187 | ||
188 | provider_teardown OSSL_FUNC_PROVIDER_TEARDOWN | |
dca97d00 | 189 | provider_gettable_params OSSL_FUNC_PROVIDER_GETTABLE_PARAMS |
d4c69c69 RL |
190 | provider_get_params OSSL_FUNC_PROVIDER_GET_PARAMS |
191 | provider_query_operation OSSL_FUNC_PROVIDER_QUERY_OPERATION | |
b0001d0c | 192 | provider_unquery_operation OSSL_FUNC_PROVIDER_UNQUERY_OPERATION |
d4c69c69 | 193 | provider_get_reason_strings OSSL_FUNC_PROVIDER_GET_REASON_STRINGS |
3c49e4ff | 194 | provider_get_capabilities OSSL_FUNC_PROVIDER_GET_CAPABILITIES |
04cb5ec0 | 195 | provider_self_test OSSL_FUNC_PROVIDER_SELF_TEST |
d4c69c69 RL |
196 | |
197 | =head2 Core functions | |
198 | ||
dca97d00 | 199 | core_gettable_params() returns a constant array of descriptor |
318a9dfa | 200 | L<OSSL_PARAM(3)>, for parameters that core_get_params() can handle. |
d4c69c69 | 201 | |
06a2027b | 202 | core_get_params() retrieves parameters from the core for the given I<handle>. |
d4c69c69 RL |
203 | See L</Core parameters> below for a description of currently known |
204 | parameters. | |
205 | ||
bca0ffe8 | 206 | The core_thread_start() function informs the core that the provider has stated |
886ad004 MC |
207 | an interest in the current thread. The core will inform the provider when the |
208 | thread eventually stops. It must be passed the I<handle> for this provider, as | |
209 | well as a callback I<handfn> which will be called when the thread stops. The | |
bca0ffe8 P |
210 | callback will subsequently be called, with the supplied argument I<arg>, from |
211 | the thread that is stopping and gets passed the provider context as an | |
212 | argument. This may be useful to perform thread specific clean up such as | |
213 | freeing thread local variables. | |
d4c69c69 | 214 | |
2b80a749 | 215 | core_get_libctx() retrieves the core context in which the library |
06a2027b | 216 | object for the current provider is stored, accessible through the I<handle>. |
2b80a749 TM |
217 | This function is useful only for built-in providers such as the default |
218 | provider. Never cast this to OSSL_LIB_CTX in a provider that is not | |
219 | built-in as the OSSL_LIB_CTX of the library loading the provider might be | |
220 | a completely different structure than the OSSL_LIB_CTX of the library the | |
221 | provider is linked to. Use L<OSSL_LIB_CTX_new_child(3)> instead to obtain | |
222 | a proper library context that is linked to the application library context. | |
49c64346 | 223 | |
af352165 | 224 | core_new_error(), core_set_error_debug() and core_vset_error() are |
49c64346 | 225 | building blocks for reporting an error back to the core, with |
06a2027b | 226 | reference to the I<handle>. |
49c64346 RL |
227 | |
228 | =over 4 | |
229 | ||
230 | =item core_new_error() | |
231 | ||
232 | allocates a new thread specific error record. | |
233 | ||
234 | This corresponds to the OpenSSL function L<ERR_new(3)>. | |
235 | ||
236 | =item core_set_error_debug() | |
237 | ||
238 | sets debugging information in the current thread specific error | |
239 | record. | |
240 | The debugging information includes the name of the file I<file>, the | |
79c44b4e | 241 | line I<line> and the function name I<func> where the error occurred. |
49c64346 RL |
242 | |
243 | This corresponds to the OpenSSL function L<ERR_set_debug(3)>. | |
244 | ||
af352165 | 245 | =item core_vset_error() |
49c64346 RL |
246 | |
247 | sets the I<reason> for the error, along with any addition data. | |
d4c69c69 RL |
248 | The I<reason> is a number defined by the provider and used to index |
249 | the reason strings table that's returned by | |
250 | provider_get_reason_strings(). | |
49c64346 RL |
251 | The additional data is given as a format string I<fmt> and a set of |
252 | arguments I<args>, which are treated in the same manner as with | |
253 | BIO_vsnprintf(). | |
d4c69c69 | 254 | I<file> and I<line> may also be passed to indicate exactly where the |
79c44b4e | 255 | error occurred or was reported. |
d4c69c69 | 256 | |
49c64346 | 257 | This corresponds to the OpenSSL function L<ERR_vset_error(3)>. |
d4c69c69 | 258 | |
49c64346 | 259 | =back |
d4c69c69 | 260 | |
599429e0 MC |
261 | The core_obj_create() function registers a new OID and associated short name |
262 | I<sn> and long name I<ln> for the given I<handle>. It is similar to the OpenSSL | |
263 | function L<OBJ_create(3)> except that it returns 1 on success or 0 on failure. | |
264 | It will treat as success the case where the OID already exists (even if the | |
265 | short name I<sn> or long name I<ln> provided as arguments differ from those | |
266 | associated with the existing OID, in which case the new names are not | |
267 | associated). | |
268 | ||
269 | The core_obj_add_sigid() function registers a new composite signature algorithm | |
270 | (I<sign_name>) consisting of an underlying signature algorithm (I<pkey_name>) | |
271 | and digest algorithm (I<digest_name>) for the given I<handle>. It assumes that | |
272 | the OIDs for the composite signature algorithm as well as for the underlying | |
273 | signature and digest algorithms are either already known to OpenSSL or have been | |
274 | registered via a call to core_obj_create(). It corresponds to the OpenSSL | |
275 | function L<OBJ_add_sigid(3)>, except that the objects are identified by name | |
276 | rather than a numeric NID. Any name (OID, short name or long name) can be used | |
277 | to identify the object. It will treat as success the case where the composite | |
278 | signature algorithm already exists (even if registered against a different | |
4f716249 MB |
279 | underlying signature or digest algorithm). For I<digest_name>, NULL or an |
280 | empty string is permissible for signature algorithms that do not need a digest | |
281 | to operate correctly. The function returns 1 on success or 0 on failure. | |
599429e0 | 282 | |
6d770c5b | 283 | CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_free(), CRYPTO_clear_free(), |
d4c69c69 RL |
284 | CRYPTO_realloc(), CRYPTO_clear_realloc(), CRYPTO_secure_malloc(), |
285 | CRYPTO_secure_zalloc(), CRYPTO_secure_free(), | |
742ccab3 | 286 | CRYPTO_secure_clear_free(), CRYPTO_secure_allocated(), |
af352165 | 287 | BIO_new_file(), BIO_new_mem_buf(), BIO_read_ex(), BIO_write_ex(), BIO_up_ref(), |
56ba2b78 P |
288 | BIO_free(), BIO_vprintf(), BIO_vsnprintf(), BIO_gets(), BIO_puts(), |
289 | BIO_ctrl(), OPENSSL_cleanse() and | |
599429e0 | 290 | OPENSSL_hexstr2buf() correspond exactly to the public functions with |
318a9dfa | 291 | the same name. As a matter of fact, the pointers in the L<OSSL_DISPATCH(3)> |
599429e0 | 292 | array are typically direct pointers to those public functions. Note that the BIO |
af352165 P |
293 | functions take an B<OSSL_CORE_BIO> type rather than the standard B<BIO> |
294 | type. This is to ensure that a provider does not mix BIOs from the core | |
295 | with BIOs used on the provider side (the two are not compatible). | |
36fc5fc6 SL |
296 | OSSL_SELF_TEST_set_callback() is used to set an optional callback that can be |
297 | passed into a provider. This may be ignored by a provider. | |
d4c69c69 | 298 | |
71febb39 P |
299 | get_entropy() retrieves seeding material from the operating system. |
300 | The seeding material will have at least I<entropy> bytes of randomness and the | |
301 | output will have at least I<min_len> and at most I<max_len> bytes. | |
302 | The buffer address is stored in I<*pout> and the buffer length is | |
303 | returned to the caller. On error, zero is returned. | |
304 | ||
305 | cleanup_entropy() is used to clean up and free the buffer returned by | |
306 | get_entropy(). The entropy pointer returned by get_entropy() is passed in | |
307 | B<buf> and its length in B<len>. | |
308 | ||
309 | get_nonce() retrieves a nonce using the passed I<salt> parameter | |
310 | of length I<salt_len> and operating system specific information. | |
311 | The I<salt> should contain uniquely identifying information and this is | |
312 | included, in an unspecified manner, as part of the output. | |
313 | The output is stored in a buffer which contrains at least I<min_len> and at | |
314 | most I<max_len> bytes. The buffer address is stored in I<*pout> and the | |
315 | buffer length returned to the caller. On error, zero is returned. | |
316 | ||
317 | cleanup_nonce() is used to clean up and free the buffer returned by | |
318 | get_nonce(). The nonce pointer returned by get_nonce() is passed in | |
319 | B<buf> and its length in B<len>. | |
320 | ||
878be71c MC |
321 | provider_register_child_cb() registers callbacks for being informed about the |
322 | loading and unloading of providers in the application's library context. | |
323 | I<handle> is this provider's handle and I<cbdata> is this provider's data | |
324 | that will be passed back to the callbacks. It returns 1 on success or 0 | |
9b6d17e4 MC |
325 | otherwise. These callbacks may be called while holding locks in libcrypto. In |
326 | order to avoid deadlocks the callback implementation must not be long running | |
327 | and must not call other OpenSSL API functions or upcalls. | |
878be71c MC |
328 | |
329 | I<create_cb> is a callback that will be called when a new provider is loaded | |
330 | into the application's library context. It is also called for any providers that | |
331 | are already loaded at the point that this callback is registered. The callback | |
332 | is passed the handle being used for the new provider being loadded and this | |
b1956770 | 333 | provider's data in I<cbdata>. It should return 1 on success or 0 on failure. |
878be71c MC |
334 | |
335 | I<remove_cb> is a callback that will be called when a new provider is unloaded | |
336 | from the application's library context. It is passed the handle being used for | |
337 | the provider being unloaded and this provider's data in I<cbdata>. It should | |
b1956770 MC |
338 | return 1 on success or 0 on failure. |
339 | ||
340 | I<global_props_cb> is a callback that will be called when the global properties | |
341 | from the parent library context are changed. It should return 1 on success | |
342 | or 0 on failure. | |
878be71c MC |
343 | |
344 | provider_deregister_child_cb() unregisters callbacks previously registered via | |
345 | provider_register_child_cb(). If provider_register_child_cb() has been called | |
346 | then provider_deregister_child_cb() should be called at or before the point that | |
347 | this provider's teardown function is called. | |
348 | ||
349 | provider_name() returns a string giving the name of the provider identified by | |
350 | I<handle>. | |
351 | ||
352 | provider_get0_provider_ctx() returns the provider context that is associated | |
353 | with the provider identified by I<prov>. | |
354 | ||
355 | provider_get0_dispatch() gets the dispatch table registered by the provider | |
356 | identified by I<prov> when it initialised. | |
357 | ||
358 | provider_up_ref() increments the reference count on the provider I<prov>. If | |
359 | I<activate> is nonzero then the provider is also loaded if it is not already | |
360 | loaded. It returns 1 on success or 0 on failure. | |
361 | ||
362 | provider_free() decrements the reference count on the provider I<prov>. If | |
363 | I<deactivate> is nonzero then the provider is also unloaded if it is not | |
364 | already loaded. It returns 1 on success or 0 on failure. | |
365 | ||
d4c69c69 RL |
366 | =head2 Provider functions |
367 | ||
368 | provider_teardown() is called when a provider is shut down and removed | |
369 | from the core's provider store. | |
370 | It must free the passed I<provctx>. | |
371 | ||
dca97d00 | 372 | provider_gettable_params() should return a constant array of |
318a9dfa | 373 | descriptor L<OSSL_PARAM(3)>, for parameters that provider_get_params() |
d4c69c69 RL |
374 | can handle. |
375 | ||
318a9dfa | 376 | provider_get_params() should process the L<OSSL_PARAM(3)> array |
d4c69c69 RL |
377 | I<params>, setting the values of the parameters it understands. |
378 | ||
318a9dfa | 379 | provider_query_operation() should return a constant L<OSSL_ALGORITHM(3)> |
d4c69c69 RL |
380 | that corresponds to the given I<operation_id>. |
381 | It should indicate if the core may store a reference to this array by | |
382 | setting I<*no_store> to 0 (core may store a reference) or 1 (core may | |
383 | not store a reference). | |
384 | ||
b0001d0c P |
385 | provider_unquery_operation() informs the provider that the result of a |
386 | provider_query_operation() is no longer directly required and that the function | |
387 | pointers have been copied. The I<operation_id> should match that passed to | |
388 | provider_query_operation() and I<algs> should be its return value. | |
389 | ||
318a9dfa | 390 | provider_get_reason_strings() should return a constant L<OSSL_ITEM(3)> |
d4c69c69 RL |
391 | array that provides reason strings for reason codes the provider may |
392 | use when reporting errors using core_put_error(). | |
393 | ||
3c49e4ff | 394 | The provider_get_capabilities() function should call the callback I<cb> passing |
318a9dfa RL |
395 | it a set of L<OSSL_PARAM(3)>s and the caller supplied argument I<arg>. The |
396 | L<OSSL_PARAM(3)>s should provide details about the capability with the name given | |
3c49e4ff MC |
397 | in the I<capability> argument relevant for the provider context I<provctx>. If a |
398 | provider supports multiple capabilities with the given name then it may call the | |
8c1cbc72 | 399 | callback multiple times (one for each capability). Capabilities can be useful for |
3c49e4ff MC |
400 | describing the services that a provider can offer. For further details see the |
401 | L</CAPABILITIES> section below. It should return 1 on success or 0 on error. | |
402 | ||
04cb5ec0 SL |
403 | The provider_self_test() function should perform known answer tests on a subset |
404 | of the algorithms that it uses, and may also verify the integrity of the | |
405 | provider module. It should return 1 on success or 0 on error. It will return 1 | |
406 | if this function is not used. | |
407 | ||
d4c69c69 RL |
408 | None of these functions are mandatory, but a provider is fairly |
409 | useless without at least provider_query_operation(), and | |
dca97d00 | 410 | provider_gettable_params() is fairly useless if not accompanied by |
d4c69c69 RL |
411 | provider_get_params(). |
412 | ||
b8086652 SL |
413 | =head2 Provider parameters |
414 | ||
415 | provider_get_params() can return the following provider parameters to the core: | |
416 | ||
417 | =over 4 | |
418 | ||
809526a0 | 419 | =item "name" (B<OSSL_PROV_PARAM_NAME>) <UTF8 ptr> |
b8086652 SL |
420 | |
421 | This points to a string that should give a unique name for the provider. | |
422 | ||
809526a0 | 423 | =item "version" (B<OSSL_PROV_PARAM_VERSION>) <UTF8 ptr> |
b8086652 SL |
424 | |
425 | This points to a string that is a version number associated with this provider. | |
426 | OpenSSL in-built providers use OPENSSL_VERSION_STR, but this may be different | |
427 | for any third party provider. This string is for informational purposes only. | |
428 | ||
809526a0 | 429 | =item "buildinfo" (B<OSSL_PROV_PARAM_BUILDINFO>) <UTF8 ptr> |
b8086652 SL |
430 | |
431 | This points to a string that is a build information associated with this provider. | |
432 | OpenSSL in-built providers use OPENSSL_FULL_VERSION_STR, but this may be | |
433 | different for any third party provider. | |
434 | ||
04cb5ec0 SL |
435 | =item "status" (B<OSSL_PROV_PARAM_STATUS>) <unsigned integer> |
436 | ||
437 | This returns 0 if the provider has entered an error state, otherwise it returns | |
438 | 1. | |
439 | ||
57cd10dd | 440 | =back |
b8086652 SL |
441 | |
442 | provider_gettable_params() should return the above parameters. | |
443 | ||
444 | ||
d4c69c69 RL |
445 | =head2 Core parameters |
446 | ||
b8086652 | 447 | core_get_params() can retrieve the following core parameters for each provider: |
d4c69c69 RL |
448 | |
449 | =over 4 | |
450 | ||
c9f18e59 | 451 | =item "openssl-version" (B<OSSL_PROV_PARAM_CORE_VERSION>) <UTF8 string ptr> |
b8086652 SL |
452 | |
453 | This points to the OpenSSL libraries' full version string, i.e. the string | |
454 | expanded from the macro B<OPENSSL_VERSION_STR>. | |
455 | ||
c9f18e59 | 456 | =item "provider-name" (B<OSSL_PROV_PARAM_CORE_PROV_NAME>) <UTF8 string ptr> |
d4c69c69 | 457 | |
b8086652 | 458 | This points to the OpenSSL libraries' idea of what the calling provider is named. |
d4c69c69 | 459 | |
c9f18e59 | 460 | =item "module-filename" (B<OSSL_PROV_PARAM_CORE_MODULE_FILENAME>) <UTF8 string ptr> |
d4c69c69 | 461 | |
b8086652 SL |
462 | This points to a string containing the full filename of the providers |
463 | module file. | |
d4c69c69 RL |
464 | |
465 | =back | |
466 | ||
467 | Additionally, provider specific configuration parameters from the | |
468 | config file are available, in dotted name form. | |
469 | The dotted name form is a concatenation of section names and final | |
470 | config command name separated by periods. | |
471 | ||
472 | For example, let's say we have the following config example: | |
473 | ||
5540855b | 474 | config_diagnostics = 1 |
d4c69c69 RL |
475 | openssl_conf = openssl_init |
476 | ||
477 | [openssl_init] | |
478 | providers = providers_sect | |
479 | ||
480 | [providers_sect] | |
481 | foo = foo_sect | |
482 | ||
483 | [foo_sect] | |
484 | activate = 1 | |
485 | data1 = 2 | |
486 | data2 = str | |
487 | more = foo_more | |
488 | ||
489 | [foo_more] | |
490 | data3 = foo,bar | |
491 | ||
492 | The provider will have these additional parameters available: | |
493 | ||
494 | =over 4 | |
495 | ||
496 | =item "activate" | |
497 | ||
498 | pointing at the string "1" | |
499 | ||
500 | =item "data1" | |
501 | ||
502 | pointing at the string "2" | |
503 | ||
504 | =item "data2" | |
505 | ||
506 | pointing at the string "str" | |
507 | ||
508 | =item "more.data3" | |
509 | ||
510 | pointing at the string "foo,bar" | |
511 | ||
512 | =back | |
513 | ||
514 | For more information on handling parameters, see L<OSSL_PARAM(3)> as | |
515 | L<OSSL_PARAM_int(3)>. | |
516 | ||
3c49e4ff MC |
517 | =head1 CAPABILITIES |
518 | ||
8c1cbc72 | 519 | Capabilities describe some of the services that a provider can offer. |
3c49e4ff MC |
520 | Applications can query the capabilities to discover those services. |
521 | ||
522 | =head3 "TLS-GROUP" Capability | |
523 | ||
524 | The "TLS-GROUP" capability can be queried by libssl to discover the list of | |
525 | TLS groups that a provider can support. Each group supported can be used for | |
c1a74f59 NT |
526 | I<key exchange> (KEX) or I<key encapsulation method> (KEM) during a TLS |
527 | handshake. | |
528 | TLS clients can advertise the list of TLS groups they support in the | |
529 | supported_groups extension, and TLS servers can select a group from the offered | |
530 | list that they also support. In this way a provider can add to the list of | |
531 | groups that libssl already supports with additional ones. | |
3c49e4ff MC |
532 | |
533 | Each TLS group that a provider supports should be described via the callback | |
534 | passed in through the provider_get_capabilities function. Each group should have | |
c1a74f59 NT |
535 | the following details supplied (all are mandatory, except |
536 | B<OSSL_CAPABILITY_TLS_GROUP_IS_KEM>): | |
3c49e4ff MC |
537 | |
538 | =over 4 | |
539 | ||
c9f18e59 | 540 | =item "tls-group-name" (B<OSSL_CAPABILITY_TLS_GROUP_NAME>) <UTF8 string> |
3c49e4ff MC |
541 | |
542 | The name of the group as given in the IANA TLS Supported Groups registry | |
543 | L<https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8>. | |
544 | ||
c9f18e59 | 545 | =item "tls-group-name-internal" (B<OSSL_CAPABILITY_TLS_GROUP_NAME_INTERNAL>) <UTF8 string> |
3c49e4ff MC |
546 | |
547 | The name of the group as known by the provider. This could be the same as the | |
548 | "tls-group-name", but does not have to be. | |
549 | ||
550 | =item "tls-group-id" (B<OSSL_CAPABILITY_TLS_GROUP_ID>) <unsigned integer> | |
551 | ||
552 | The TLS group id value as given in the IANA TLS Supported Groups registry. | |
553 | ||
c9f18e59 | 554 | =item "tls-group-alg" (B<OSSL_CAPABILITY_TLS_GROUP_ALG>) <UTF8 string> |
3c49e4ff MC |
555 | |
556 | The name of a Key Management algorithm that the provider offers and that should | |
c1a74f59 NT |
557 | be used with this group. Keys created should be able to support I<key exchange> |
558 | or I<key encapsulation method> (KEM), as implied by the optional | |
559 | B<OSSL_CAPABILITY_TLS_GROUP_IS_KEM> flag. | |
3c49e4ff MC |
560 | The algorithm must support key and parameter generation as well as the |
561 | key/parameter generation parameter, B<OSSL_PKEY_PARAM_GROUP_NAME>. The group | |
562 | name given via "tls-group-name-internal" above will be passed via | |
563 | B<OSSL_PKEY_PARAM_GROUP_NAME> when libssl wishes to generate keys/parameters. | |
564 | ||
565 | =item "tls-group-sec-bits" (B<OSSL_CAPABILITY_TLS_GROUP_SECURITY_BITS>) <unsigned integer> | |
566 | ||
567 | The number of bits of security offered by keys in this group. The number of bits | |
568 | should be comparable with the ones given in table 2 and 3 of the NIST SP800-57 | |
569 | document. | |
570 | ||
c1a74f59 NT |
571 | =item "tls-group-is-kem" (B<OSSL_CAPABILITY_TLS_GROUP_IS_KEM>) <unsigned integer> |
572 | ||
573 | Boolean flag to describe if the group should be used in I<key exchange> (KEX) | |
574 | mode (0, default) or in I<key encapsulation method> (KEM) mode (1). | |
575 | ||
576 | This parameter is optional: if not specified, KEX mode is assumed as the default | |
577 | mode for the group. | |
578 | ||
579 | In KEX mode, in a typical Diffie-Hellman fashion, both sides execute I<keygen> | |
580 | then I<derive> against the peer public key. To operate in KEX mode, the group | |
581 | implementation must support the provider functions as described in | |
582 | L<provider-keyexch(7)>. | |
583 | ||
584 | In KEM mode, the client executes I<keygen> and sends its public key, the server | |
585 | executes I<encapsulate> using the client's public key and sends back the | |
586 | resulting I<ciphertext>, finally the client executes I<decapsulate> to retrieve | |
587 | the same I<shared secret> generated by the server's I<encapsulate>. To operate | |
588 | in KEM mode, the group implementation must support the provider functions as | |
589 | described in L<provider-kem(7)>. | |
590 | ||
591 | Both in KEX and KEM mode, the resulting I<shared secret> is then used according | |
592 | to the protocol specification. | |
593 | ||
3c49e4ff MC |
594 | =item "tls-min-tls" (B<OSSL_CAPABILITY_TLS_GROUP_MIN_TLS>) <integer> |
595 | ||
596 | =item "tls-max-tls" (B<OSSL_CAPABILITY_TLS_GROUP_MAX_TLS>) <integer> | |
597 | ||
598 | =item "tls-min-dtls" (B<OSSL_CAPABILITY_TLS_GROUP_MIN_DTLS>) <integer> | |
599 | ||
600 | =item "tls-max-dtls" (B<OSSL_CAPABILITY_TLS_GROUP_MAX_DTLS>) <integer> | |
601 | ||
602 | These parameters can be used to describe the minimum and maximum TLS and DTLS | |
603 | versions supported by the group. The values equate to the on-the-wire encoding | |
604 | of the various TLS versions. For example TLSv1.3 is 0x0304 (772 decimal), and | |
605 | TLSv1.2 is 0x0303 (771 decimal). A 0 indicates that there is no defined minimum | |
606 | or maximum. A -1 indicates that the group should not be used in that protocol. | |
607 | ||
608 | =back | |
609 | ||
ee58915c MB |
610 | =head3 "TLS-SIGALG" Capability |
611 | ||
612 | The "TLS-SIGALG" capability can be queried by libssl to discover the list of | |
613 | TLS signature algorithms that a provider can support. Each signature supported | |
614 | can be used for client- or server-authentication in addition to the built-in | |
615 | signature algorithms. | |
616 | TLS1.3 clients can advertise the list of TLS signature algorithms they support | |
617 | in the signature_algorithms extension, and TLS servers can select an algorithm | |
618 | from the offered list that they also support. In this way a provider can add | |
619 | to the list of signature algorithms that libssl already supports with | |
620 | additional ones. | |
621 | ||
622 | Each TLS signature algorithm that a provider supports should be described via | |
623 | the callback passed in through the provider_get_capabilities function. Each | |
624 | algorithm can have the following details supplied: | |
625 | ||
626 | =over 4 | |
627 | ||
628 | =item "iana-name" (B<OSSL_CAPABILITY_TLS_SIGALG_IANA_NAME>) <UTF8 string> | |
629 | ||
630 | The name of the signature algorithm as given in the IANA TLS Signature Scheme | |
631 | registry as "Description": | |
632 | L<https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-signaturescheme>. | |
633 | This value must be supplied. | |
634 | ||
635 | =item "iana-code-point" (B<OSSL_CAPABILITY_TLS_SIGALG_CODE_POINT>) <unsigned integer> | |
636 | ||
637 | The TLS algorithm ID value as given in the IANA TLS SignatureScheme registry. | |
638 | This value must be supplied. | |
639 | ||
640 | =item "sigalg-name" (B<OSSL_CAPABILITY_TLS_SIGALG_NAME>) <UTF8 string> | |
641 | ||
642 | A name for the full (possibly composite hash-and-signature) signature | |
643 | algorithm. | |
644 | The provider may, but is not obligated to, provide a signature implementation | |
645 | with this name; if it doesn't, this is assumed to be a composite of a pure | |
646 | signature algorithm and a hash algorithm, which must be given with the | |
647 | parameters "sig-name" and "hash-name". | |
648 | This value must be supplied. | |
649 | ||
650 | =item "sigalg-oid" (B<OSSL_CAPABILITY_TLS_SIGALG_OID>) <UTF8 string> | |
651 | ||
652 | The OID of the "sigalg-name" algorithm in canonical numeric text form. If | |
653 | this parameter is given, OBJ_create() will be used to create an OBJ and | |
654 | a NID for this OID, using the "sigalg-name" parameter for its (short) name. | |
655 | Otherwise, it's assumed to already exist in the object database, possibly | |
656 | done by the provider with the core_obj_create() upcall. | |
657 | This value is optional. | |
658 | ||
659 | =item "sig-name" (B<OSSL_CAPABILITY_TLS_SIGALG_SIG_NAME>) <UTF8 string> | |
660 | ||
661 | The name of the pure signature algorithm that is part of a composite | |
662 | "sigalg-name". If "sigalg-name" is implemented by the provider, this | |
663 | parameter is redundant and must not be given. | |
664 | This value is optional. | |
665 | ||
666 | =item "sig-oid" (B<OSSL_CAPABILITY_TLS_SIGALG_SIG_OID>) <UTF8 string> | |
667 | ||
668 | The OID of the "sig-name" algorithm in canonical numeric text form. If | |
669 | this parameter is given, OBJ_create() will be used to create an OBJ and | |
670 | a NID for this OID, using the "sig-name" parameter for its (short) name. | |
671 | Otherwise, it is assumed to already exist in the object database. This | |
672 | can be done by the provider using the core_obj_create() upcall. | |
673 | This value is optional. | |
674 | ||
675 | =item "hash-name" (B<OSSL_CAPABILITY_TLS_SIGALG_HASH_NAME>) <UTF8 string> | |
676 | ||
677 | The name of the hash algorithm that is part of a composite "sigalg-name". | |
678 | If "sigalg-name" is implemented by the provider, this parameter is redundant | |
679 | and must not be given. | |
680 | This value is optional. | |
681 | ||
682 | =item "hash-oid" (B<OSSL_CAPABILITY_TLS_SIGALG_HASH_OID>) <UTF8 string> | |
683 | ||
684 | The OID of the "hash-name" algorithm in canonical numeric text form. If | |
685 | this parameter is given, OBJ_create() will be used to create an OBJ and | |
686 | a NID for this OID, using the "hash-name" parameter for its (short) name. | |
687 | Otherwise, it's assumed to already exist in the object database, possibly | |
688 | done by the provider with the core_obj_create() upcall. | |
689 | This value is optional. | |
690 | ||
691 | =item "key-type" (B<OSSL_CAPABILITY_TLS_SIGALG_KEYTYPE>) <UTF8 string> | |
692 | ||
693 | The key type of the public key of applicable certificates. If this parameter | |
694 | isn't present, it's assumed to be the same as "sig-name" if that's present, | |
695 | otherwise "sigalg-name". | |
696 | This value is optional. | |
697 | ||
698 | =item "key-type-oid" (B<OSSL_CAPABILITY_TLS_SIGALG_KEYTYPE_OID>) <UTF8 string> | |
699 | ||
700 | The OID of the "key-type" in canonical numeric text form. If | |
701 | this parameter is given, OBJ_create() will be used to create an OBJ and | |
702 | a NID for this OID, using the "key-type" parameter for its (short) name. | |
703 | Otherwise, it's assumed to already exist in the object database, possibly | |
704 | done by the provider with the core_obj_create() upcall. | |
705 | This value is optional. | |
706 | ||
707 | =item "sec-bits" (B<OSSL_CAPABILITY_TLS_SIGALG_SECURITY_BITS>) <unsigned integer> | |
708 | ||
709 | The number of bits of security offered by keys of this algorithm. The number | |
710 | of bits should be comparable with the ones given in table 2 and 3 of the NIST | |
711 | SP800-57 document. This number is used to determine the security strength of | |
712 | the algorithm if no digest algorithm has been registered that otherwise | |
713 | defines the security strength. If the signature algorithm implements its own | |
714 | digest internally, this value needs to be set to properly reflect the overall | |
715 | security strength. | |
716 | This value must be supplied. | |
717 | ||
718 | =item "tls-min-tls" (B<OSSL_CAPABILITY_TLS_SIGALG_MIN_TLS>) <integer> | |
719 | ||
720 | =item "tls-max-tls" (B<OSSL_CAPABILITY_TLS_SIGALG_MAX_TLS>) <integer> | |
721 | ||
722 | These parameters can be used to describe the minimum and maximum TLS | |
723 | versions supported by the signature algorithm. The values equate to the | |
724 | on-the-wire encoding of the various TLS versions. For example TLSv1.3 is | |
725 | 0x0304 (772 decimal), and TLSv1.2 is 0x0303 (771 decimal). A 0 indicates that | |
726 | there is no defined minimum or maximum. A -1 indicates that the signature | |
727 | algorithm should not be used in that protocol. | |
728 | Presently values representing anything other than TLS1.3 mean that the | |
729 | complete algorithm is ignored. | |
730 | ||
731 | =back | |
732 | ||
06394a6c P |
733 | =head1 NOTES |
734 | ||
735 | The core_obj_create() and core_obj_add_sigid() functions were not thread safe | |
736 | in OpenSSL 3.0. | |
737 | ||
d4c69c69 RL |
738 | =head1 EXAMPLES |
739 | ||
740 | This is an example of a simple provider made available as a | |
741 | dynamically loadable module. | |
742 | It implements the fictitious algorithm C<FOO> for the fictitious | |
743 | operation C<BAR>. | |
744 | ||
745 | #include <malloc.h> | |
746 | #include <openssl/core.h> | |
23c48d94 | 747 | #include <openssl/core_dispatch.h> |
d4c69c69 RL |
748 | |
749 | /* Errors used in this provider */ | |
750 | #define E_MALLOC 1 | |
751 | ||
752 | static const OSSL_ITEM reasons[] = { | |
753 | { E_MALLOC, "memory allocation failure" }. | |
754 | { 0, NULL } /* Termination */ | |
755 | }; | |
756 | ||
757 | /* | |
758 | * To ensure we get the function signature right, forward declare | |
23c48d94 | 759 | * them using function types provided by openssl/core_dispatch.h |
d4c69c69 | 760 | */ |
363b1e5d DMSP |
761 | OSSL_FUNC_bar_newctx_fn foo_newctx; |
762 | OSSL_FUNC_bar_freectx_fn foo_freectx; | |
763 | OSSL_FUNC_bar_init_fn foo_init; | |
764 | OSSL_FUNC_bar_update_fn foo_update; | |
765 | OSSL_FUNC_bar_final_fn foo_final; | |
d4c69c69 | 766 | |
363b1e5d DMSP |
767 | OSSL_FUNC_provider_query_operation_fn p_query; |
768 | OSSL_FUNC_provider_get_reason_strings_fn p_reasons; | |
769 | OSSL_FUNC_provider_teardown_fn p_teardown; | |
d4c69c69 RL |
770 | |
771 | OSSL_provider_init_fn OSSL_provider_init; | |
772 | ||
363b1e5d | 773 | OSSL_FUNC_core_put_error *c_put_error = NULL; |
d4c69c69 RL |
774 | |
775 | /* Provider context */ | |
776 | struct prov_ctx_st { | |
06a2027b | 777 | OSSL_CORE_HANDLE *handle; |
d4c69c69 RL |
778 | } |
779 | ||
780 | /* operation context for the algorithm FOO */ | |
781 | struct foo_ctx_st { | |
782 | struct prov_ctx_st *provctx; | |
783 | int b; | |
784 | }; | |
785 | ||
786 | static void *foo_newctx(void *provctx) | |
787 | { | |
788 | struct foo_ctx_st *fooctx = malloc(sizeof(*fooctx)); | |
789 | ||
790 | if (fooctx != NULL) | |
791 | fooctx->provctx = provctx; | |
792 | else | |
06a2027b | 793 | c_put_error(provctx->handle, E_MALLOC, __FILE__, __LINE__); |
d4c69c69 RL |
794 | return fooctx; |
795 | } | |
796 | ||
797 | static void foo_freectx(void *fooctx) | |
798 | { | |
799 | free(fooctx); | |
800 | } | |
801 | ||
802 | static int foo_init(void *vfooctx) | |
803 | { | |
804 | struct foo_ctx_st *fooctx = vfooctx; | |
805 | ||
806 | fooctx->b = 0x33; | |
807 | } | |
808 | ||
809 | static int foo_update(void *vfooctx, unsigned char *in, size_t inl) | |
810 | { | |
811 | struct foo_ctx_st *fooctx = vfooctx; | |
812 | ||
813 | /* did you expect something serious? */ | |
814 | if (inl == 0) | |
815 | return 1; | |
816 | for (; inl-- > 0; in++) | |
817 | *in ^= fooctx->b; | |
818 | return 1; | |
819 | } | |
820 | ||
821 | static int foo_final(void *vfooctx) | |
822 | { | |
823 | struct foo_ctx_st *fooctx = vfooctx; | |
824 | ||
825 | fooctx->b = 0x66; | |
826 | } | |
827 | ||
828 | static const OSSL_DISPATCH foo_fns[] = { | |
829 | { OSSL_FUNC_BAR_NEWCTX, (void (*)(void))foo_newctx }, | |
830 | { OSSL_FUNC_BAR_FREECTX, (void (*)(void))foo_freectx }, | |
831 | { OSSL_FUNC_BAR_INIT, (void (*)(void))foo_init }, | |
832 | { OSSL_FUNC_BAR_UPDATE, (void (*)(void))foo_update }, | |
833 | { OSSL_FUNC_BAR_FINAL, (void (*)(void))foo_final }, | |
834 | { 0, NULL } | |
835 | }; | |
836 | ||
837 | static const OSSL_ALGORITHM bars[] = { | |
838 | { "FOO", "provider=chumbawamba", foo_fns }, | |
839 | { NULL, NULL, NULL } | |
840 | }; | |
841 | ||
842 | static const OSSL_ALGORITHM *p_query(void *provctx, int operation_id, | |
843 | int *no_store) | |
844 | { | |
845 | switch (operation_id) { | |
846 | case OSSL_OP_BAR: | |
847 | return bars; | |
848 | } | |
849 | return NULL; | |
850 | } | |
851 | ||
852 | static const OSSL_ITEM *p_reasons(void *provctx) | |
853 | { | |
854 | return reasons; | |
855 | } | |
856 | ||
857 | static void p_teardown(void *provctx) | |
858 | { | |
859 | free(provctx); | |
860 | } | |
861 | ||
862 | static const OSSL_DISPATCH prov_fns[] = { | |
863 | { OSSL_FUNC_PROVIDER_TEARDOWN, (void (*)(void))p_teardown }, | |
864 | { OSSL_FUNC_PROVIDER_QUERY_OPERATION, (void (*)(void))p_query }, | |
865 | { OSSL_FUNC_PROVIDER_GET_REASON_STRINGS, (void (*)(void))p_reasons }, | |
866 | { 0, NULL } | |
867 | }; | |
868 | ||
06a2027b | 869 | int OSSL_provider_init(const OSSL_CORE_HANDLE *handle, |
d4c69c69 RL |
870 | const OSSL_DISPATCH *in, |
871 | const OSSL_DISPATCH **out, | |
872 | void **provctx) | |
873 | { | |
874 | struct prov_ctx_st *pctx = NULL; | |
875 | ||
876 | for (; in->function_id != 0; in++) | |
877 | switch (in->function_id) { | |
878 | case OSSL_FUNC_CORE_PUT_ERROR: | |
363b1e5d | 879 | c_put_error = OSSL_FUNC_core_put_error(in); |
d4c69c69 RL |
880 | break; |
881 | } | |
882 | ||
883 | *out = prov_fns; | |
884 | ||
885 | if ((pctx = malloc(sizeof(*pctx))) == NULL) { | |
886 | /* | |
887 | * ALEA IACTA EST, if the core retrieves the reason table | |
888 | * regardless, that string will be displayed, otherwise not. | |
889 | */ | |
06a2027b | 890 | c_put_error(handle, E_MALLOC, __FILE__, __LINE__); |
d4c69c69 RL |
891 | return 0; |
892 | } | |
06a2027b | 893 | pctx->handle = handle; |
d4c69c69 RL |
894 | return 1; |
895 | } | |
896 | ||
23c48d94 | 897 | This relies on a few things existing in F<openssl/core_dispatch.h>: |
d4c69c69 RL |
898 | |
899 | #define OSSL_OP_BAR 4711 | |
900 | ||
901 | #define OSSL_FUNC_BAR_NEWCTX 1 | |
363b1e5d DMSP |
902 | typedef void *(OSSL_FUNC_bar_newctx_fn)(void *provctx); |
903 | static ossl_inline OSSL_FUNC_bar_newctx(const OSSL_DISPATCH *opf) | |
904 | { return (OSSL_FUNC_bar_newctx_fn *)opf->function; } | |
d4c69c69 RL |
905 | |
906 | #define OSSL_FUNC_BAR_FREECTX 2 | |
363b1e5d DMSP |
907 | typedef void (OSSL_FUNC_bar_freectx_fn)(void *ctx); |
908 | static ossl_inline OSSL_FUNC_bar_newctx(const OSSL_DISPATCH *opf) | |
909 | { return (OSSL_FUNC_bar_freectx_fn *)opf->function; } | |
d4c69c69 RL |
910 | |
911 | #define OSSL_FUNC_BAR_INIT 3 | |
363b1e5d DMSP |
912 | typedef void *(OSSL_FUNC_bar_init_fn)(void *ctx); |
913 | static ossl_inline OSSL_FUNC_bar_init(const OSSL_DISPATCH *opf) | |
914 | { return (OSSL_FUNC_bar_init_fn *)opf->function; } | |
d4c69c69 RL |
915 | |
916 | #define OSSL_FUNC_BAR_UPDATE 4 | |
363b1e5d | 917 | typedef void *(OSSL_FUNC_bar_update_fn)(void *ctx, |
d4c69c69 | 918 | unsigned char *in, size_t inl); |
363b1e5d DMSP |
919 | static ossl_inline OSSL_FUNC_bar_update(const OSSL_DISPATCH *opf) |
920 | { return (OSSL_FUNC_bar_update_fn *)opf->function; } | |
d4c69c69 RL |
921 | |
922 | #define OSSL_FUNC_BAR_FINAL 5 | |
363b1e5d DMSP |
923 | typedef void *(OSSL_FUNC_bar_final_fn)(void *ctx); |
924 | static ossl_inline OSSL_FUNC_bar_final(const OSSL_DISPATCH *opf) | |
925 | { return (OSSL_FUNC_bar_final_fn *)opf->function; } | |
d4c69c69 RL |
926 | |
927 | =head1 SEE ALSO | |
928 | ||
929 | L<provider(7)> | |
930 | ||
931 | =head1 HISTORY | |
932 | ||
933 | The concept of providers and everything surrounding them was | |
934 | introduced in OpenSSL 3.0. | |
935 | ||
936 | =head1 COPYRIGHT | |
937 | ||
4333b89f | 938 | Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. |
d4c69c69 RL |
939 | |
940 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
941 | this file except in compliance with the License. You can obtain a copy | |
942 | in the file LICENSE in the source distribution or at | |
943 | L<https://www.openssl.org/source/license.html>. | |
944 | ||
945 | =cut |