Lines Matching +full:engine +full:- +full:specific
43 - ENGINE cryptographic module support
47 #include <openssl/engine.h>
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);
58 int ENGINE_add(ENGINE *e);
59 int ENGINE_remove(ENGINE *e);
61 ENGINE *ENGINE_by_id(const char *id);
63 int ENGINE_init(ENGINE *e);
64 int ENGINE_finish(ENGINE *e);
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);
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);
83 int ENGINE_set_default(ENGINE *e, unsigned int flags);
88 int ENGINE_register_RSA(ENGINE *e);
89 void ENGINE_unregister_RSA(ENGINE *e);
91 int ENGINE_register_DSA(ENGINE *e);
92 void ENGINE_unregister_DSA(ENGINE *e);
94 int ENGINE_register_DH(ENGINE *e);
95 void ENGINE_unregister_DH(ENGINE *e);
97 int ENGINE_register_RAND(ENGINE *e);
98 void ENGINE_unregister_RAND(ENGINE *e);
100 int ENGINE_register_ciphers(ENGINE *e);
101 void ENGINE_unregister_ciphers(ENGINE *e);
103 int ENGINE_register_digests(ENGINE *e);
104 void ENGINE_unregister_digests(ENGINE *e);
106 int ENGINE_register_complete(ENGINE *e);
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,
113 int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg,
116 ENGINE *ENGINE_new(void);
117 int ENGINE_free(ENGINE *e);
118 int ENGINE_up_ref(ENGINE *e);
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);
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);
156 EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id,
158 EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id,
173 form of B<ENGINE> objects. These objects act as containers for
175 reference-counted mechanism to allow them to be dynamically loaded in and
178 The cryptographic functionality that can be provided by an B<ENGINE>
181 RSA_METHOD - for providing alternative RSA implementations
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
190 Due to the modular nature of the ENGINE API, pointers to ENGINEs need to be
191 treated as handles - i.e. not only as pointers, but also as references to
192 the underlying ENGINE object. Ie. one should obtain a new reference when
193 making copies of an ENGINE pointer if the copies will be used (and
196 ENGINE objects have two levels of reference-counting to match the way in
197 which the objects are used. At the most basic level, each ENGINE pointer is
198 inherently a B<structural> reference - a structural reference is required
202 However, a structural reference provides no guarantee that the ENGINE is
206 support specialised hardware. To use an ENGINE's functionality, you need a
209 implicitly contains a structural reference as well - however to avoid
210 difficult-to-find programming bugs, it is recommended to treat the two
212 ENGINE, you have a guarantee that the ENGINE has been initialised and
219 iterating across OpenSSL's internal linked-list of loaded
220 ENGINEs, reading information about an ENGINE, etc. Essentially a structural
222 an ENGINE implementation rather than use its functionality.
225 ENGINE object. There are other ENGINE API functions that return structural
228 released by a corresponding to call to the ENGINE_free() function - the
229 ENGINE object itself will only actually be cleaned up and deallocated when
233 It should also be noted that many ENGINE API function calls that accept a
234 structural reference will internally obtain another reference - typically
235 this happens whenever the supplied ENGINE will be needed by OpenSSL after
236 the function has returned. Eg. the function to add a new ENGINE to
237 OpenSSL's internal list is ENGINE_add() - if this function returns success,
244 ENGINE list - they will return a new structural reference to the next (or
245 previous) ENGINE in the list or NULL if at the end (or beginning) of the
251 the F<< <openssl/engine.h> >> header file includes some hints.
256 functionality of an ENGINE is required to be available. A functional
258 reference to the required ENGINE, or by asking OpenSSL for the default
259 operational ENGINE for a given cryptographic purpose.
262 call the ENGINE_init() function. This returns zero if the ENGINE was not
265 return nonzero to indicate that the ENGINE is now operational and will
266 have allocated a new B<functional> reference to the ENGINE. All functional
275 algorithm-specific types in OpenSSL, such as RSA, DSA, EVP_CIPHER_CTX, etc.
279 For each supported abstraction, the ENGINE code maintains an internal table
289 When a default ENGINE is requested for a given abstraction/algorithm/mode, (e.g.
291 ENGINE subsystem to process the corresponding state table and return a
292 functional reference to an initialised ENGINE whose implementation should be
293 used. If no ENGINE should (or can) be used, it will return NULL and the caller
294 will operate with a NULL ENGINE handle - this usually equates to using the
296 then on behave the way it used to before the ENGINE API existed.
302 operational. If it returns a functional reference to an ENGINE, it will
305 response if no ENGINE was available so that future queries won't repeat the
309 instead the only way for the state table to return a non-NULL ENGINE to the
314 indexed by 'nid', these flags and cached-responses are distinct for each 'nid'
320 support to make the most useful elements of the ENGINE functionality
322 programmer wishes to make alternative ENGINE modules available to the
324 "visible" ENGINEs from which it has to operate - at start-up, this list is
325 empty and in fact if an application does not call any ENGINE API calls and
327 binary will not contain any alternative ENGINE code at all. So the first
328 consideration is whether any/all available ENGINE implementations should be
329 made visible to OpenSSL - this is controlled by calling the various "load"
333 the program and loaded into memory at run-time) does not mean they are
334 "registered" or called into use by OpenSSL automatically - that behaviour
336 will want to allow the user to specify exactly which ENGINE they want used
338 OpenSSL automatically use at run-time any ENGINE that is able to
339 successfully initialise - i.e. to assume that this corresponds to
344 source code to openssl's built-in utilities as guides.
346 If no ENGINE API functions are called within an application, then OpenSSL
351 I<Using a specific ENGINE implementation>
354 to want to use the "ACME" ENGINE if it is available in the version of
357 OpenSSL should use its built-in software as per usual. The following code
360 ENGINE *e;
365 /* the engine isn't available */
368 /* the engine couldn't initialise, release 'e' */
385 I<Automatically using built-in ENGINE implementations>
387 Here we'll assume we want to load and register all ENGINE implementations
389 OpenSSL - if there is an ENGINE that implements it and can be initialised,
399 ENGINE_init() and if any of those succeed, that ENGINE will be set as the
404 There is a mechanism supported by the ENGINE framework that allows each
405 ENGINE implementation to define an arbitrary set of configuration
407 OpenSSL. This mechanism is entirely based on the use of name-value pairs
411 possible for the application to dynamically interrogate the loaded ENGINE
414 scheme. However, if the user is expected to know which ENGINE device he/she
423 implementation (which may know nothing at all specific to the host system)
426 smart-card identifiers, passwords to initialise protected devices,
428 passed to an ENGINE B<before> attempting to initialise it, i.e. before
432 in some cases both. ENGINE implementations should provide indications of
433 this in the descriptions attached to built-in control commands and/or in
436 I<Issuing control commands to an ENGINE>
439 name of the ENGINE it wishes to use, a table of string-pairs for use before
441 the string-pairs used for control commands consist of a command "name"
442 followed by the command "parameter" - the parameter could be NULL in some
443 cases but the name can not. This function should initialise the ENGINE
452 ENGINE *e = ENGINE_by_id(engine_id);
454 while (pre_num--) {
456 fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id,
473 while (post_num--) {
475 fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id,
488 relax the semantics of the function - if set nonzero it will only return
489 failure if the ENGINE supported the given command name but failed while
490 executing it, if the ENGINE doesn't support the command name it will simply
492 only supplying commands specific to the given ENGINE so we set this to
497 It is possible to discover at run-time the names, numerical-ids, descriptions
498 and input parameters of the control commands supported by an ENGINE using a
501 ENGINE, i.e. the ENGINE's ctrl() handler is not used for the control command.
502 F<< <openssl/engine.h> >> defines an index, ENGINE_CMD_BASE, that all control
508 commands implemented by a given ENGINE, specifically the commands:
521 they use various properties exposed by each ENGINE to process these
522 queries. An ENGINE has 3 properties it exposes that can affect how this behaves;
524 the ENGINE's flags, and it can expose an array of control command descriptions.
525 If an ENGINE specifies the ENGINE_FLAGS_MANUAL_CMD_CTRL flag, then it will
526 simply pass all these "core" control commands directly to the ENGINE's ctrl()
527 handler (and thus, it must have supplied one), so it is up to the ENGINE to
541 If the ENGINE's array of control commands is empty then all other commands will
543 the first command supported by the ENGINE, ENGINE_GET_NEXT_CMD_TYPE takes the
544 identifier of a command supported by the ENGINE and returns the next command
551 description. ENGINE_CTRL_GET_FLAGS returns a bitwise-OR'd mask of the following
560 informational to the caller - this flag will prevent the command being usable
561 for any higher-level ENGINE functions such as ENGINE_ctrl_cmd_string().
562 "INTERNAL" commands are not intended to be exposed to text-based configuration
566 discovery mechanisms simply to allow applications to determine if an ENGINE
567 supports certain specific commands it might want to use (e.g. application "foo"
568 might query various ENGINEs to see if they implement "FOO_GET_VENDOR_LOGO_GIF" -
569 and ENGINE could therefore decide whether or not to support this "foo"-specific
579 Ignored in set-user-ID and set-group-ID programs.
586 return a valid B<ENGINE> structure or NULL if an error occurred.
590 ENGINE_by_id() returns a valid B<ENGINE> structure or NULL if an error occurred.
595 ENGINE_get_digest_engine() return a valid B<ENGINE> structure on success or NULL
604 B<ENGINE> implementations.
616 ENGINE_new() returns a valid B<ENGINE> structure on success or NULL if an error
628 and the name of the ENGINE B<e> respectively.
645 ENGINE_get_flags() returns an integer representing the ENGINE flags which are
646 used to control various behaviours of an ENGINE.
669 Copyright 2002-2024 The OpenSSL Project Authors. All Rights Reserved.