]>
Commit | Line | Data |
---|---|---|
3f90e450 GT |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
1722496f | 5 | ENGINE_get_DH, ENGINE_get_DSA, |
c952780c | 6 | ENGINE_by_id, ENGINE_get_cipher_engine, ENGINE_get_default_DH, |
1722496f RS |
7 | ENGINE_get_default_DSA, |
8 | ENGINE_get_default_RAND, | |
c952780c RS |
9 | ENGINE_get_default_RSA, ENGINE_get_digest_engine, ENGINE_get_first, |
10 | ENGINE_get_last, ENGINE_get_next, ENGINE_get_prev, ENGINE_new, | |
11 | ENGINE_get_ciphers, ENGINE_get_ctrl_function, ENGINE_get_digests, | |
12 | ENGINE_get_destroy_function, ENGINE_get_finish_function, | |
13 | ENGINE_get_init_function, ENGINE_get_load_privkey_function, | |
14 | ENGINE_get_load_pubkey_function, ENGINE_load_private_key, | |
15 | ENGINE_load_public_key, ENGINE_get_RAND, ENGINE_get_RSA, ENGINE_get_id, | |
91da5e77 | 16 | ENGINE_get_name, ENGINE_get_cmd_defns, ENGINE_get_cipher, |
c952780c RS |
17 | ENGINE_get_digest, ENGINE_add, ENGINE_cmd_is_executable, |
18 | ENGINE_ctrl, ENGINE_ctrl_cmd, ENGINE_ctrl_cmd_string, | |
19 | ENGINE_finish, ENGINE_free, ENGINE_get_flags, ENGINE_init, | |
1722496f RS |
20 | ENGINE_register_DH, ENGINE_register_DSA, |
21 | ENGINE_register_RAND, ENGINE_register_RSA, | |
c952780c RS |
22 | ENGINE_register_all_complete, ENGINE_register_ciphers, |
23 | ENGINE_register_complete, ENGINE_register_digests, ENGINE_remove, | |
1722496f | 24 | ENGINE_set_DH, ENGINE_set_DSA, |
c952780c RS |
25 | ENGINE_set_RAND, ENGINE_set_RSA, ENGINE_set_ciphers, |
26 | ENGINE_set_cmd_defns, ENGINE_set_ctrl_function, ENGINE_set_default, | |
1722496f RS |
27 | ENGINE_set_default_DH, ENGINE_set_default_DSA, |
28 | ENGINE_set_default_RAND, ENGINE_set_default_RSA, | |
c952780c RS |
29 | ENGINE_set_default_ciphers, ENGINE_set_default_digests, |
30 | ENGINE_set_default_string, ENGINE_set_destroy_function, | |
31 | ENGINE_set_digests, ENGINE_set_finish_function, ENGINE_set_flags, | |
32 | ENGINE_set_id, ENGINE_set_init_function, ENGINE_set_load_privkey_function, | |
33 | ENGINE_set_load_pubkey_function, ENGINE_set_name, ENGINE_up_ref, | |
34 | ENGINE_get_table_flags, ENGINE_cleanup, | |
35 | ENGINE_load_builtin_engines, ENGINE_register_all_DH, | |
1722496f RS |
36 | ENGINE_register_all_DSA, |
37 | ENGINE_register_all_RAND, | |
c952780c RS |
38 | ENGINE_register_all_RSA, ENGINE_register_all_ciphers, |
39 | ENGINE_register_all_digests, ENGINE_set_table_flags, ENGINE_unregister_DH, | |
1722496f | 40 | ENGINE_unregister_DSA, |
c952780c RS |
41 | ENGINE_unregister_RAND, ENGINE_unregister_RSA, ENGINE_unregister_ciphers, |
42 | ENGINE_unregister_digests | |
43 | - ENGINE cryptographic module support | |
3f90e450 GT |
44 | |
45 | =head1 SYNOPSIS | |
46 | ||
47 | #include <openssl/engine.h> | |
48 | ||
49 | ENGINE *ENGINE_get_first(void); | |
50 | ENGINE *ENGINE_get_last(void); | |
51 | ENGINE *ENGINE_get_next(ENGINE *e); | |
52 | ENGINE *ENGINE_get_prev(ENGINE *e); | |
53 | ||
54 | int ENGINE_add(ENGINE *e); | |
55 | int ENGINE_remove(ENGINE *e); | |
56 | ||
57 | ENGINE *ENGINE_by_id(const char *id); | |
58 | ||
59 | int ENGINE_init(ENGINE *e); | |
60 | int ENGINE_finish(ENGINE *e); | |
61 | ||
3f90e450 GT |
62 | void ENGINE_load_builtin_engines(void); |
63 | ||
3f90e450 GT |
64 | ENGINE *ENGINE_get_default_RSA(void); |
65 | ENGINE *ENGINE_get_default_DSA(void); | |
66 | ENGINE *ENGINE_get_default_DH(void); | |
67 | ENGINE *ENGINE_get_default_RAND(void); | |
68 | ENGINE *ENGINE_get_cipher_engine(int nid); | |
69 | ENGINE *ENGINE_get_digest_engine(int nid); | |
70 | ||
71 | int ENGINE_set_default_RSA(ENGINE *e); | |
72 | int ENGINE_set_default_DSA(ENGINE *e); | |
73 | int ENGINE_set_default_DH(ENGINE *e); | |
74 | int ENGINE_set_default_RAND(ENGINE *e); | |
75 | int ENGINE_set_default_ciphers(ENGINE *e); | |
76 | int ENGINE_set_default_digests(ENGINE *e); | |
77 | int ENGINE_set_default_string(ENGINE *e, const char *list); | |
78 | ||
79 | int ENGINE_set_default(ENGINE *e, unsigned int flags); | |
80 | ||
81 | unsigned int ENGINE_get_table_flags(void); | |
82 | void ENGINE_set_table_flags(unsigned int flags); | |
83 | ||
84 | int ENGINE_register_RSA(ENGINE *e); | |
85 | void ENGINE_unregister_RSA(ENGINE *e); | |
86 | void ENGINE_register_all_RSA(void); | |
87 | int ENGINE_register_DSA(ENGINE *e); | |
88 | void ENGINE_unregister_DSA(ENGINE *e); | |
89 | void ENGINE_register_all_DSA(void); | |
90 | int ENGINE_register_DH(ENGINE *e); | |
91 | void ENGINE_unregister_DH(ENGINE *e); | |
92 | void ENGINE_register_all_DH(void); | |
93 | int ENGINE_register_RAND(ENGINE *e); | |
94 | void ENGINE_unregister_RAND(ENGINE *e); | |
95 | void ENGINE_register_all_RAND(void); | |
96 | int ENGINE_register_ciphers(ENGINE *e); | |
97 | void ENGINE_unregister_ciphers(ENGINE *e); | |
98 | void ENGINE_register_all_ciphers(void); | |
99 | int ENGINE_register_digests(ENGINE *e); | |
100 | void ENGINE_unregister_digests(ENGINE *e); | |
101 | void ENGINE_register_all_digests(void); | |
102 | int ENGINE_register_complete(ENGINE *e); | |
103 | int ENGINE_register_all_complete(void); | |
104 | ||
6a659296 | 105 | int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void)); |
3f90e450 GT |
106 | int ENGINE_cmd_is_executable(ENGINE *e, int cmd); |
107 | int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name, | |
e9b77246 | 108 | long i, void *p, void (*f)(void), int cmd_optional); |
3f90e450 | 109 | int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg, |
e9b77246 | 110 | int cmd_optional); |
3f90e450 | 111 | |
3f90e450 GT |
112 | ENGINE *ENGINE_new(void); |
113 | int ENGINE_free(ENGINE *e); | |
6a659296 | 114 | int ENGINE_up_ref(ENGINE *e); |
3f90e450 GT |
115 | |
116 | int ENGINE_set_id(ENGINE *e, const char *id); | |
117 | int ENGINE_set_name(ENGINE *e, const char *name); | |
118 | int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth); | |
119 | int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth); | |
120 | int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth); | |
121 | int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth); | |
122 | int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f); | |
123 | int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f); | |
124 | int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f); | |
125 | int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f); | |
126 | int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f); | |
127 | int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f); | |
128 | int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f); | |
129 | int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f); | |
130 | int ENGINE_set_flags(ENGINE *e, int flags); | |
131 | int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns); | |
132 | ||
133 | const char *ENGINE_get_id(const ENGINE *e); | |
134 | const char *ENGINE_get_name(const ENGINE *e); | |
135 | const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e); | |
136 | const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e); | |
137 | const DH_METHOD *ENGINE_get_DH(const ENGINE *e); | |
138 | const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e); | |
139 | ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e); | |
140 | ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e); | |
141 | ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e); | |
142 | ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e); | |
143 | ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e); | |
144 | ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e); | |
145 | ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e); | |
146 | ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e); | |
147 | const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid); | |
148 | const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid); | |
149 | int ENGINE_get_flags(const ENGINE *e); | |
150 | const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e); | |
151 | ||
152 | EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id, | |
e9b77246 | 153 | UI_METHOD *ui_method, void *callback_data); |
3f90e450 | 154 | EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id, |
e9b77246 | 155 | UI_METHOD *ui_method, void *callback_data); |
3f90e450 | 156 | |
be80b21d RL |
157 | Deprecated since OpenSSL 1.1.0, can be hidden entirely by defining |
158 | B<OPENSSL_API_COMPAT> with a suitable version value, see | |
159 | L<openssl_user_macros(7)>: | |
6d4fb1d5 | 160 | |
1d5099de | 161 | void ENGINE_cleanup(void) |
6d4fb1d5 | 162 | |
3f90e450 GT |
163 | =head1 DESCRIPTION |
164 | ||
165 | These functions create, manipulate, and use cryptographic modules in the | |
166 | form of B<ENGINE> objects. These objects act as containers for | |
167 | implementations of cryptographic algorithms, and support a | |
168 | reference-counted mechanism to allow them to be dynamically loaded in and | |
169 | out of the running application. | |
170 | ||
171 | The cryptographic functionality that can be provided by an B<ENGINE> | |
172 | implementation includes the following abstractions; | |
173 | ||
174 | RSA_METHOD - for providing alternative RSA implementations | |
6a659296 | 175 | DSA_METHOD, DH_METHOD, RAND_METHOD, ECDH_METHOD, ECDSA_METHOD, |
7984f082 | 176 | - similarly for other OpenSSL APIs |
3f90e450 GT |
177 | EVP_CIPHER - potentially multiple cipher algorithms (indexed by 'nid') |
178 | EVP_DIGEST - potentially multiple hash algorithms (indexed by 'nid') | |
179 | key-loading - loading public and/or private EVP_PKEY keys | |
180 | ||
181 | =head2 Reference counting and handles | |
182 | ||
183 | Due to the modular nature of the ENGINE API, pointers to ENGINEs need to be | |
184 | treated as handles - ie. not only as pointers, but also as references to | |
6a659296 | 185 | the underlying ENGINE object. Ie. one should obtain a new reference when |
3f90e450 | 186 | making copies of an ENGINE pointer if the copies will be used (and |
b6a338cb | 187 | released) independently. |
3f90e450 GT |
188 | |
189 | ENGINE objects have two levels of reference-counting to match the way in | |
190 | which the objects are used. At the most basic level, each ENGINE pointer is | |
6a659296 GT |
191 | inherently a B<structural> reference - a structural reference is required |
192 | to use the pointer value at all, as this kind of reference is a guarantee | |
193 | that the structure can not be deallocated until the reference is released. | |
194 | ||
195 | However, a structural reference provides no guarantee that the ENGINE is | |
740ceb5b | 196 | initialised and able to use any of its cryptographic |
6a659296 GT |
197 | implementations. Indeed it's quite possible that most ENGINEs will not |
198 | initialise at all in typical environments, as ENGINEs are typically used to | |
3f90e450 GT |
199 | support specialised hardware. To use an ENGINE's functionality, you need a |
200 | B<functional> reference. This kind of reference can be considered a | |
201 | specialised form of structural reference, because each functional reference | |
202 | implicitly contains a structural reference as well - however to avoid | |
203 | difficult-to-find programming bugs, it is recommended to treat the two | |
b6a338cb | 204 | kinds of reference independently. If you have a functional reference to an |
740ceb5b RS |
205 | ENGINE, you have a guarantee that the ENGINE has been initialised and |
206 | is ready to perform cryptographic operations, and will remain initialised | |
6a659296 | 207 | until after you have released your reference. |
3f90e450 | 208 | |
4390d661 | 209 | I<Structural references> |
3f90e450 | 210 | |
6a659296 GT |
211 | This basic type of reference is used for instantiating new ENGINEs, |
212 | iterating across OpenSSL's internal linked-list of loaded | |
3f90e450 GT |
213 | ENGINEs, reading information about an ENGINE, etc. Essentially a structural |
214 | reference is sufficient if you only need to query or manipulate the data of | |
215 | an ENGINE implementation rather than use its functionality. | |
216 | ||
217 | The ENGINE_new() function returns a structural reference to a new (empty) | |
6a659296 GT |
218 | ENGINE object. There are other ENGINE API functions that return structural |
219 | references such as; ENGINE_by_id(), ENGINE_get_first(), ENGINE_get_last(), | |
220 | ENGINE_get_next(), ENGINE_get_prev(). All structural references should be | |
221 | released by a corresponding to call to the ENGINE_free() function - the | |
222 | ENGINE object itself will only actually be cleaned up and deallocated when | |
223 | the last structural reference is released. | |
3f90e450 GT |
224 | |
225 | It should also be noted that many ENGINE API function calls that accept a | |
226 | structural reference will internally obtain another reference - typically | |
227 | this happens whenever the supplied ENGINE will be needed by OpenSSL after | |
228 | the function has returned. Eg. the function to add a new ENGINE to | |
229 | OpenSSL's internal list is ENGINE_add() - if this function returns success, | |
230 | then OpenSSL will have stored a new structural reference internally so the | |
231 | caller is still responsible for freeing their own reference with | |
232 | ENGINE_free() when they are finished with it. In a similar way, some | |
233 | functions will automatically release the structural reference passed to it | |
234 | if part of the function's job is to do so. Eg. the ENGINE_get_next() and | |
235 | ENGINE_get_prev() functions are used for iterating across the internal | |
236 | ENGINE list - they will return a new structural reference to the next (or | |
237 | previous) ENGINE in the list or NULL if at the end (or beginning) of the | |
238 | list, but in either case the structural reference passed to the function is | |
239 | released on behalf of the caller. | |
240 | ||
241 | To clarify a particular function's handling of references, one should | |
242 | always consult that function's documentation "man" page, or failing that | |
243 | the openssl/engine.h header file includes some hints. | |
244 | ||
4390d661 | 245 | I<Functional references> |
3f90e450 GT |
246 | |
247 | As mentioned, functional references exist when the cryptographic | |
248 | functionality of an ENGINE is required to be available. A functional | |
249 | reference can be obtained in one of two ways; from an existing structural | |
250 | reference to the required ENGINE, or by asking OpenSSL for the default | |
251 | operational ENGINE for a given cryptographic purpose. | |
252 | ||
253 | To obtain a functional reference from an existing structural reference, | |
254 | call the ENGINE_init() function. This returns zero if the ENGINE was not | |
255 | already operational and couldn't be successfully initialised (eg. lack of | |
256 | system drivers, no special hardware attached, etc), otherwise it will | |
257 | return non-zero to indicate that the ENGINE is now operational and will | |
6a659296 GT |
258 | have allocated a new B<functional> reference to the ENGINE. All functional |
259 | references are released by calling ENGINE_finish() (which removes the | |
260 | implicit structural reference as well). | |
3f90e450 GT |
261 | |
262 | The second way to get a functional reference is by asking OpenSSL for a | |
263 | default implementation for a given task, eg. by ENGINE_get_default_RSA(), | |
264 | ENGINE_get_default_cipher_engine(), etc. These are discussed in the next | |
265 | section, though they are not usually required by application programmers as | |
266 | they are used automatically when creating and using the relevant | |
267 | algorithm-specific types in OpenSSL, such as RSA, DSA, EVP_CIPHER_CTX, etc. | |
268 | ||
269 | =head2 Default implementations | |
270 | ||
271 | For each supported abstraction, the ENGINE code maintains an internal table | |
272 | of state to control which implementations are available for a given | |
273 | abstraction and which should be used by default. These implementations are | |
6a659296 | 274 | registered in the tables and indexed by an 'nid' value, because |
3f90e450 | 275 | abstractions like EVP_CIPHER and EVP_DIGEST support many distinct |
6a659296 GT |
276 | algorithms and modes, and ENGINEs can support arbitrarily many of them. |
277 | In the case of other abstractions like RSA, DSA, etc, there is only one | |
278 | "algorithm" so all implementations implicitly register using the same 'nid' | |
279 | index. | |
280 | ||
281 | When a default ENGINE is requested for a given abstraction/algorithm/mode, (eg. | |
282 | when calling RSA_new_method(NULL)), a "get_default" call will be made to the | |
283 | ENGINE subsystem to process the corresponding state table and return a | |
284 | functional reference to an initialised ENGINE whose implementation should be | |
285 | used. If no ENGINE should (or can) be used, it will return NULL and the caller | |
286 | will operate with a NULL ENGINE handle - this usually equates to using the | |
287 | conventional software implementation. In the latter case, OpenSSL will from | |
288 | then on behave the way it used to before the ENGINE API existed. | |
3f90e450 GT |
289 | |
290 | Each state table has a flag to note whether it has processed this | |
291 | "get_default" query since the table was last modified, because to process | |
292 | this question it must iterate across all the registered ENGINEs in the | |
293 | table trying to initialise each of them in turn, in case one of them is | |
294 | operational. If it returns a functional reference to an ENGINE, it will | |
295 | also cache another reference to speed up processing future queries (without | |
296 | needing to iterate across the table). Likewise, it will cache a NULL | |
297 | response if no ENGINE was available so that future queries won't repeat the | |
298 | same iteration unless the state table changes. This behaviour can also be | |
299 | changed; if the ENGINE_TABLE_FLAG_NOINIT flag is set (using | |
300 | ENGINE_set_table_flags()), no attempted initialisations will take place, | |
301 | instead the only way for the state table to return a non-NULL ENGINE to the | |
302 | "get_default" query will be if one is expressly set in the table. Eg. | |
303 | ENGINE_set_default_RSA() does the same job as ENGINE_register_RSA() except | |
304 | that it also sets the state table's cached response for the "get_default" | |
6a659296 GT |
305 | query. In the case of abstractions like EVP_CIPHER, where implementations are |
306 | indexed by 'nid', these flags and cached-responses are distinct for each 'nid' | |
307 | value. | |
3f90e450 GT |
308 | |
309 | =head2 Application requirements | |
310 | ||
311 | This section will explain the basic things an application programmer should | |
312 | support to make the most useful elements of the ENGINE functionality | |
313 | available to the user. The first thing to consider is whether the | |
314 | programmer wishes to make alternative ENGINE modules available to the | |
315 | application and user. OpenSSL maintains an internal linked list of | |
316 | "visible" ENGINEs from which it has to operate - at start-up, this list is | |
317 | empty and in fact if an application does not call any ENGINE API calls and | |
318 | it uses static linking against openssl, then the resulting application | |
319 | binary will not contain any alternative ENGINE code at all. So the first | |
320 | consideration is whether any/all available ENGINE implementations should be | |
321 | made visible to OpenSSL - this is controlled by calling the various "load" | |
f672aee4 | 322 | functions. |
3f90e450 | 323 | |
3f90e450 GT |
324 | The fact that ENGINEs are made visible to OpenSSL (and thus are linked into |
325 | the program and loaded into memory at run-time) does not mean they are | |
326 | "registered" or called into use by OpenSSL automatically - that behaviour | |
6a659296 | 327 | is something for the application to control. Some applications |
3f90e450 GT |
328 | will want to allow the user to specify exactly which ENGINE they want used |
329 | if any is to be used at all. Others may prefer to load all support and have | |
330 | OpenSSL automatically use at run-time any ENGINE that is able to | |
331 | successfully initialise - ie. to assume that this corresponds to | |
332 | acceleration hardware attached to the machine or some such thing. There are | |
333 | probably numerous other ways in which applications may prefer to handle | |
334 | things, so we will simply illustrate the consequences as they apply to a | |
335 | couple of simple cases and leave developers to consider these and the | |
336 | source code to openssl's builtin utilities as guides. | |
337 | ||
b3696a55 RS |
338 | If no ENGINE API functions are called within an application, then OpenSSL |
339 | will not allocate any internal resources. Prior to OpenSSL 1.1.0, however, | |
340 | if any ENGINEs are loaded, even if not registered or used, it was necessary to | |
341 | call ENGINE_cleanup() before the program exits. | |
342 | ||
4390d661 | 343 | I<Using a specific ENGINE implementation> |
3f90e450 GT |
344 | |
345 | Here we'll assume an application has been configured by its user or admin | |
346 | to want to use the "ACME" ENGINE if it is available in the version of | |
347 | OpenSSL the application was compiled with. If it is available, it should be | |
740ceb5b | 348 | used by default for all RSA, DSA, and symmetric cipher operations, otherwise |
3f90e450 GT |
349 | OpenSSL should use its builtin software as per usual. The following code |
350 | illustrates how to approach this; | |
351 | ||
352 | ENGINE *e; | |
353 | const char *engine_id = "ACME"; | |
354 | ENGINE_load_builtin_engines(); | |
355 | e = ENGINE_by_id(engine_id); | |
2947af32 | 356 | if (!e) |
3f90e450 GT |
357 | /* the engine isn't available */ |
358 | return; | |
2947af32 | 359 | if (!ENGINE_init(e)) { |
3f90e450 GT |
360 | /* the engine couldn't initialise, release 'e' */ |
361 | ENGINE_free(e); | |
362 | return; | |
363 | } | |
2947af32 BB |
364 | if (!ENGINE_set_default_RSA(e)) |
365 | /* | |
366 | * This should only happen when 'e' can't initialise, but the previous | |
367 | * statement suggests it did. | |
368 | */ | |
3f90e450 GT |
369 | abort(); |
370 | ENGINE_set_default_DSA(e); | |
371 | ENGINE_set_default_ciphers(e); | |
372 | /* Release the functional reference from ENGINE_init() */ | |
373 | ENGINE_finish(e); | |
374 | /* Release the structural reference from ENGINE_by_id() */ | |
375 | ENGINE_free(e); | |
376 | ||
4390d661 | 377 | I<Automatically using builtin ENGINE implementations> |
3f90e450 GT |
378 | |
379 | Here we'll assume we want to load and register all ENGINE implementations | |
380 | bundled with OpenSSL, such that for any cryptographic algorithm required by | |
740ceb5b | 381 | OpenSSL - if there is an ENGINE that implements it and can be initialised, |
3f90e450 GT |
382 | it should be used. The following code illustrates how this can work; |
383 | ||
384 | /* Load all bundled ENGINEs into memory and make them visible */ | |
385 | ENGINE_load_builtin_engines(); | |
386 | /* Register all of them for every algorithm they collectively implement */ | |
387 | ENGINE_register_all_complete(); | |
388 | ||
389 | That's all that's required. Eg. the next time OpenSSL tries to set up an | |
390 | RSA key, any bundled ENGINEs that implement RSA_METHOD will be passed to | |
391 | ENGINE_init() and if any of those succeed, that ENGINE will be set as the | |
6a659296 | 392 | default for RSA use from then on. |
3f90e450 GT |
393 | |
394 | =head2 Advanced configuration support | |
395 | ||
396 | There is a mechanism supported by the ENGINE framework that allows each | |
397 | ENGINE implementation to define an arbitrary set of configuration | |
398 | "commands" and expose them to OpenSSL and any applications based on | |
399 | OpenSSL. This mechanism is entirely based on the use of name-value pairs | |
6a659296 | 400 | and assumes ASCII input (no unicode or UTF for now!), so it is ideal if |
3f90e450 GT |
401 | applications want to provide a transparent way for users to provide |
402 | arbitrary configuration "directives" directly to such ENGINEs. It is also | |
403 | possible for the application to dynamically interrogate the loaded ENGINE | |
404 | implementations for the names, descriptions, and input flags of their | |
405 | available "control commands", providing a more flexible configuration | |
406 | scheme. However, if the user is expected to know which ENGINE device he/she | |
407 | is using (in the case of specialised hardware, this goes without saying) | |
408 | then applications may not need to concern themselves with discovering the | |
6a659296 GT |
409 | supported control commands and simply prefer to pass settings into ENGINEs |
410 | exactly as they are provided by the user. | |
3f90e450 GT |
411 | |
412 | Before illustrating how control commands work, it is worth mentioning what | |
413 | they are typically used for. Broadly speaking there are two uses for | |
414 | control commands; the first is to provide the necessary details to the | |
415 | implementation (which may know nothing at all specific to the host system) | |
416 | so that it can be initialised for use. This could include the path to any | |
417 | driver or config files it needs to load, required network addresses, | |
6a659296 | 418 | smart-card identifiers, passwords to initialise protected devices, |
3f90e450 GT |
419 | logging information, etc etc. This class of commands typically needs to be |
420 | passed to an ENGINE B<before> attempting to initialise it, ie. before | |
421 | calling ENGINE_init(). The other class of commands consist of settings or | |
422 | operations that tweak certain behaviour or cause certain operations to take | |
423 | place, and these commands may work either before or after ENGINE_init(), or | |
6a659296 | 424 | in some cases both. ENGINE implementations should provide indications of |
3f90e450 GT |
425 | this in the descriptions attached to builtin control commands and/or in |
426 | external product documentation. | |
427 | ||
4390d661 | 428 | I<Issuing control commands to an ENGINE> |
3f90e450 GT |
429 | |
430 | Let's illustrate by example; a function for which the caller supplies the | |
431 | name of the ENGINE it wishes to use, a table of string-pairs for use before | |
432 | initialisation, and another table for use after initialisation. Note that | |
433 | the string-pairs used for control commands consist of a command "name" | |
434 | followed by the command "parameter" - the parameter could be NULL in some | |
435 | cases but the name can not. This function should initialise the ENGINE | |
436 | (issuing the "pre" commands beforehand and the "post" commands afterwards) | |
437 | and set it as the default for everything except RAND and then return a | |
438 | boolean success or failure. | |
439 | ||
440 | int generic_load_engine_fn(const char *engine_id, | |
441 | const char **pre_cmds, int pre_num, | |
442 | const char **post_cmds, int post_num) | |
443 | { | |
444 | ENGINE *e = ENGINE_by_id(engine_id); | |
2f8e53d7 F |
445 | if (!e) return 0; |
446 | while (pre_num--) { | |
2947af32 | 447 | if (!ENGINE_ctrl_cmd_string(e, pre_cmds[0], pre_cmds[1], 0)) { |
3f90e450 | 448 | fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id, |
2947af32 | 449 | pre_cmds[0], pre_cmds[1] ? pre_cmds[1] : "(NULL)"); |
3f90e450 GT |
450 | ENGINE_free(e); |
451 | return 0; | |
452 | } | |
24c2cd39 | 453 | pre_cmds += 2; |
3f90e450 | 454 | } |
2f8e53d7 | 455 | if (!ENGINE_init(e)) { |
3f90e450 GT |
456 | fprintf(stderr, "Failed initialisation\n"); |
457 | ENGINE_free(e); | |
458 | return 0; | |
459 | } | |
2947af32 BB |
460 | /* |
461 | * ENGINE_init() returned a functional reference, so free the structural | |
462 | * reference from ENGINE_by_id(). | |
463 | */ | |
3f90e450 | 464 | ENGINE_free(e); |
2947af32 BB |
465 | while (post_num--) { |
466 | if (!ENGINE_ctrl_cmd_string(e, post_cmds[0], post_cmds[1], 0)) { | |
3f90e450 | 467 | fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id, |
2947af32 | 468 | post_cmds[0], post_cmds[1] ? post_cmds[1] : "(NULL)"); |
3f90e450 GT |
469 | ENGINE_finish(e); |
470 | return 0; | |
471 | } | |
24c2cd39 | 472 | post_cmds += 2; |
3f90e450 GT |
473 | } |
474 | ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND); | |
475 | /* Success */ | |
476 | return 1; | |
477 | } | |
478 | ||
479 | Note that ENGINE_ctrl_cmd_string() accepts a boolean argument that can | |
480 | relax the semantics of the function - if set non-zero it will only return | |
481 | failure if the ENGINE supported the given command name but failed while | |
482 | executing it, if the ENGINE doesn't support the command name it will simply | |
483 | return success without doing anything. In this case we assume the user is | |
484 | only supplying commands specific to the given ENGINE so we set this to | |
485 | FALSE. | |
486 | ||
4390d661 | 487 | I<Discovering supported control commands> |
3f90e450 GT |
488 | |
489 | It is possible to discover at run-time the names, numerical-ids, descriptions | |
6a659296 GT |
490 | and input parameters of the control commands supported by an ENGINE using a |
491 | structural reference. Note that some control commands are defined by OpenSSL | |
492 | itself and it will intercept and handle these control commands on behalf of the | |
493 | ENGINE, ie. the ENGINE's ctrl() handler is not used for the control command. | |
494 | openssl/engine.h defines an index, ENGINE_CMD_BASE, that all control commands | |
495 | implemented by ENGINEs should be numbered from. Any command value lower than | |
496 | this symbol is considered a "generic" command is handled directly by the | |
497 | OpenSSL core routines. | |
3f90e450 | 498 | |
b9b6a7e5 | 499 | It is using these "core" control commands that one can discover the control |
91da5e77 RS |
500 | commands implemented by a given ENGINE, specifically the commands: |
501 | ||
502 | ENGINE_HAS_CTRL_FUNCTION | |
503 | ENGINE_CTRL_GET_FIRST_CMD_TYPE | |
504 | ENGINE_CTRL_GET_NEXT_CMD_TYPE | |
505 | ENGINE_CTRL_GET_CMD_FROM_NAME | |
506 | ENGINE_CTRL_GET_NAME_LEN_FROM_CMD | |
507 | ENGINE_CTRL_GET_NAME_FROM_CMD | |
508 | ENGINE_CTRL_GET_DESC_LEN_FROM_CMD | |
509 | ENGINE_CTRL_GET_DESC_FROM_CMD | |
510 | ENGINE_CTRL_GET_CMD_FLAGS | |
3f90e450 GT |
511 | |
512 | Whilst these commands are automatically processed by the OpenSSL framework code, | |
6a659296 GT |
513 | they use various properties exposed by each ENGINE to process these |
514 | queries. An ENGINE has 3 properties it exposes that can affect how this behaves; | |
3f90e450 GT |
515 | it can supply a ctrl() handler, it can specify ENGINE_FLAGS_MANUAL_CMD_CTRL in |
516 | the ENGINE's flags, and it can expose an array of control command descriptions. | |
517 | If an ENGINE specifies the ENGINE_FLAGS_MANUAL_CMD_CTRL flag, then it will | |
518 | simply pass all these "core" control commands directly to the ENGINE's ctrl() | |
519 | handler (and thus, it must have supplied one), so it is up to the ENGINE to | |
520 | reply to these "discovery" commands itself. If that flag is not set, then the | |
e9b77246 | 521 | OpenSSL framework code will work with the following rules: |
3f90e450 GT |
522 | |
523 | if no ctrl() handler supplied; | |
524 | ENGINE_HAS_CTRL_FUNCTION returns FALSE (zero), | |
525 | all other commands fail. | |
526 | if a ctrl() handler was supplied but no array of control commands; | |
527 | ENGINE_HAS_CTRL_FUNCTION returns TRUE, | |
528 | all other commands fail. | |
529 | if a ctrl() handler and array of control commands was supplied; | |
530 | ENGINE_HAS_CTRL_FUNCTION returns TRUE, | |
531 | all other commands proceed processing ... | |
532 | ||
533 | If the ENGINE's array of control commands is empty then all other commands will | |
534 | fail, otherwise; ENGINE_CTRL_GET_FIRST_CMD_TYPE returns the identifier of | |
535 | the first command supported by the ENGINE, ENGINE_GET_NEXT_CMD_TYPE takes the | |
536 | identifier of a command supported by the ENGINE and returns the next command | |
537 | identifier or fails if there are no more, ENGINE_CMD_FROM_NAME takes a string | |
538 | name for a command and returns the corresponding identifier or fails if no such | |
539 | command name exists, and the remaining commands take a command identifier and | |
540 | return properties of the corresponding commands. All except | |
541 | ENGINE_CTRL_GET_FLAGS return the string length of a command name or description, | |
542 | or populate a supplied character buffer with a copy of the command name or | |
543 | description. ENGINE_CTRL_GET_FLAGS returns a bitwise-OR'd mask of the following | |
91da5e77 | 544 | possible values: |
3f90e450 | 545 | |
91da5e77 RS |
546 | ENGINE_CMD_FLAG_NUMERIC |
547 | ENGINE_CMD_FLAG_STRING | |
548 | ENGINE_CMD_FLAG_NO_INPUT | |
549 | ENGINE_CMD_FLAG_INTERNAL | |
3f90e450 GT |
550 | |
551 | If the ENGINE_CMD_FLAG_INTERNAL flag is set, then any other flags are purely | |
552 | informational to the caller - this flag will prevent the command being usable | |
553 | for any higher-level ENGINE functions such as ENGINE_ctrl_cmd_string(). | |
554 | "INTERNAL" commands are not intended to be exposed to text-based configuration | |
555 | by applications, administrations, users, etc. These can support arbitrary | |
556 | operations via ENGINE_ctrl(), including passing to and/or from the control | |
557 | commands data of any arbitrary type. These commands are supported in the | |
186bb907 | 558 | discovery mechanisms simply to allow applications to determine if an ENGINE |
3f90e450 GT |
559 | supports certain specific commands it might want to use (eg. application "foo" |
560 | might query various ENGINEs to see if they implement "FOO_GET_VENDOR_LOGO_GIF" - | |
561 | and ENGINE could therefore decide whether or not to support this "foo"-specific | |
562 | extension). | |
563 | ||
c81c38cb PS |
564 | =head1 ENVIRONMENT |
565 | ||
566 | =over 4 | |
567 | ||
568 | =item B<OPENSSL_ENGINES> | |
569 | ||
570 | The path to the engines directory. | |
284f4f6b | 571 | Ignored in set-user-ID and set-group-ID programs. |
c81c38cb PS |
572 | |
573 | =back | |
574 | ||
1f13ad31 PY |
575 | =head1 RETURN VALUES |
576 | ||
577 | ENGINE_get_first(), ENGINE_get_last(), ENGINE_get_next() and ENGINE_get_prev() | |
578 | return a valid B<ENGINE> structure or NULL if an error occurred. | |
579 | ||
580 | ENGINE_add() and ENGINE_remove() return 1 on success or 0 on error. | |
581 | ||
582 | ENGINE_by_id() returns a valid B<ENGINE> structure or NULL if an error occurred. | |
583 | ||
584 | ENGINE_init() and ENGINE_finish() return 1 on success or 0 on error. | |
585 | ||
586 | All ENGINE_get_default_TYPE() functions, ENGINE_get_cipher_engine() and | |
587 | ENGINE_get_digest_engine() return a valid B<ENGINE> structure on success or NULL | |
588 | if an error occurred. | |
589 | ||
590 | All ENGINE_set_default_TYPE() functions return 1 on success or 0 on error. | |
591 | ||
592 | ENGINE_set_default() returns 1 on success or 0 on error. | |
593 | ||
594 | ENGINE_get_table_flags() returns an unsigned integer value representing the | |
595 | global table flags which are used to control the registration behaviour of | |
596 | B<ENGINE> implementations. | |
597 | ||
598 | All ENGINE_register_TYPE() functions return 1 on success or 0 on error. | |
599 | ||
600 | ENGINE_register_complete() and ENGINE_register_all_complete() return 1 on success | |
601 | or 0 on error. | |
602 | ||
603 | ENGINE_ctrl() returns a positive value on success or others on error. | |
604 | ||
605 | ENGINE_cmd_is_executable() returns 1 if B<cmd> is executable or 0 otherwise. | |
606 | ||
607 | ENGINE_ctrl_cmd() and ENGINE_ctrl_cmd_string() return 1 on success or 0 on error. | |
608 | ||
609 | ENGINE_new() returns a valid B<ENGINE> structure on success or NULL if an error | |
610 | occurred. | |
611 | ||
612 | ENGINE_free() returns 1 on success or 0 on error. | |
613 | ||
614 | ENGINE_up_ref() returns 1 on success or 0 on error. | |
615 | ||
616 | ENGINE_set_id() and ENGINE_set_name() return 1 on success or 0 on error. | |
617 | ||
618 | All other B<ENGINE_set_*> functions return 1 on success or 0 on error. | |
619 | ||
620 | ENGINE_get_id() and ENGINE_get_name() return a string representing the identifier | |
621 | and the name of the ENGINE B<e> respectively. | |
622 | ||
623 | ENGINE_get_RSA(), ENGINE_get_DSA(), ENGINE_get_DH() and ENGINE_get_RAND() | |
624 | return corresponding method structures for each algorithms. | |
625 | ||
626 | ENGINE_get_destroy_function(), ENGINE_get_init_function(), | |
627 | ENGINE_get_finish_function(), ENGINE_get_ctrl_function(), | |
628 | ENGINE_get_load_privkey_function(), ENGINE_get_load_pubkey_function(), | |
629 | ENGINE_get_ciphers() and ENGINE_get_digests() return corresponding function | |
630 | pointers of the callbacks. | |
631 | ||
632 | ENGINE_get_cipher() returns a valid B<EVP_CIPHER> structure on success or NULL | |
633 | if an error occurred. | |
634 | ||
635 | ENGINE_get_digest() returns a valid B<EVP_MD> structure on success or NULL if an | |
636 | error occurred. | |
637 | ||
638 | ENGINE_get_flags() returns an integer representing the ENGINE flags which are | |
639 | used to control various behaviours of an ENGINE. | |
640 | ||
641 | ENGINE_get_cmd_defns() returns an B<ENGINE_CMD_DEFN> structure or NULL if it's | |
642 | not set. | |
643 | ||
644 | ENGINE_load_private_key() and ENGINE_load_public_key() return a valid B<EVP_PKEY> | |
645 | structure on success or NULL if an error occurred. | |
646 | ||
3f90e450 GT |
647 | =head1 SEE ALSO |
648 | ||
c81c38cb PS |
649 | L<OPENSSL_init_crypto(3)>, L<RSA_new_method(3)>, L<DSA_new(3)>, L<DH_new(3)>, |
650 | L<RAND_bytes(3)>, L<config(5)> | |
f672aee4 RS |
651 | |
652 | =head1 HISTORY | |
653 | ||
b3696a55 RS |
654 | ENGINE_cleanup() was deprecated in OpenSSL 1.1.0 by the automatic cleanup |
655 | done by OPENSSL_cleanup() | |
656 | and should not be used. | |
3f90e450 | 657 | |
e2f92610 RS |
658 | =head1 COPYRIGHT |
659 | ||
3c7d0945 | 660 | Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 661 | |
4746f25a | 662 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
663 | this file except in compliance with the License. You can obtain a copy |
664 | in the file LICENSE in the source distribution or at | |
665 | L<https://www.openssl.org/source/license.html>. | |
666 | ||
667 | =cut |