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