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