Lines Matching +full:engine +full:- +full:specific

18 .\" Set up some character translations and predefined strings.  \*(-- will
24 .tr \(*W-
27 .    ds -- \(*W-
29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
37 .    ds -- \|\(em\|
71 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
81 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
97 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
98 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
99 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
100 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
101 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
102 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
104 .    \" troff and (daisy-wheel) nroff accents
123 .    ds d- d\h'-1'\(ga
124 .    ds D- D\h'-1'\(hy
134 .TH ENGINE_ADD 3ossl "2023-09-19" "3.0.11" "OpenSSL"
178 \&\- ENGINE cryptographic module support
182 \& #include <openssl/engine.h>
186 hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value,
190 \& ENGINE *ENGINE_get_first(void);
191 \& ENGINE *ENGINE_get_last(void);
192 \& ENGINE *ENGINE_get_next(ENGINE *e);
193 \& ENGINE *ENGINE_get_prev(ENGINE *e);
195 \& int ENGINE_add(ENGINE *e);
196 \& int ENGINE_remove(ENGINE *e);
198 \& ENGINE *ENGINE_by_id(const char *id);
200 \& int ENGINE_init(ENGINE *e);
201 \& int ENGINE_finish(ENGINE *e);
205 \& ENGINE *ENGINE_get_default_RSA(void);
206 \& ENGINE *ENGINE_get_default_DSA(void);
207 \& ENGINE *ENGINE_get_default_DH(void);
208 \& ENGINE *ENGINE_get_default_RAND(void);
209 \& ENGINE *ENGINE_get_cipher_engine(int nid);
210 \& ENGINE *ENGINE_get_digest_engine(int nid);
212 \& int ENGINE_set_default_RSA(ENGINE *e);
213 \& int ENGINE_set_default_DSA(ENGINE *e);
214 \& int ENGINE_set_default_DH(ENGINE *e);
215 \& int ENGINE_set_default_RAND(ENGINE *e);
216 \& int ENGINE_set_default_ciphers(ENGINE *e);
217 \& int ENGINE_set_default_digests(ENGINE *e);
218 \& int ENGINE_set_default_string(ENGINE *e, const char *list);
220 \& int ENGINE_set_default(ENGINE *e, unsigned int flags);
225 \& int ENGINE_register_RSA(ENGINE *e);
226 \& void ENGINE_unregister_RSA(ENGINE *e);
228 \& int ENGINE_register_DSA(ENGINE *e);
229 \& void ENGINE_unregister_DSA(ENGINE *e);
231 \& int ENGINE_register_DH(ENGINE *e);
232 \& void ENGINE_unregister_DH(ENGINE *e);
234 \& int ENGINE_register_RAND(ENGINE *e);
235 \& void ENGINE_unregister_RAND(ENGINE *e);
237 \& int ENGINE_register_ciphers(ENGINE *e);
238 \& void ENGINE_unregister_ciphers(ENGINE *e);
240 \& int ENGINE_register_digests(ENGINE *e);
241 \& void ENGINE_unregister_digests(ENGINE *e);
243 \& int ENGINE_register_complete(ENGINE *e);
246 \& int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void));
247 \& int ENGINE_cmd_is_executable(ENGINE *e, int cmd);
248 \& int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name,
250 \& int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg,
253 \& ENGINE *ENGINE_new(void);
254 \& int ENGINE_free(ENGINE *e);
255 \& int ENGINE_up_ref(ENGINE *e);
257 \& int ENGINE_set_id(ENGINE *e, const char *id);
258 \& int ENGINE_set_name(ENGINE *e, const char *name);
259 \& int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth);
260 \& int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth);
261 \& int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth);
262 \& int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth);
263 \& int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f);
264 \& int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f);
265 \& int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f);
266 \& int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f);
267 \& int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f);
268 \& int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f);
269 \& int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f);
270 \& int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f);
271 \& int ENGINE_set_flags(ENGINE *e, int flags);
272 \& int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns);
274 \& const char *ENGINE_get_id(const ENGINE *e);
275 \& const char *ENGINE_get_name(const ENGINE *e);
276 \& const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e);
277 \& const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e);
278 \& const DH_METHOD *ENGINE_get_DH(const ENGINE *e);
279 \& const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e);
280 \& ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e);
281 \& ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e);
282 \& ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e);
283 \& ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e);
284 \& ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e);
285 \& ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e);
286 \& ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e);
287 \& ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e);
288 \& const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid);
289 \& const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid);
290 \& int ENGINE_get_flags(const ENGINE *e);
291 \& const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e);
293 \& EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id,
295 \& EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id,
300 hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value,
312 form of \fB\s-1ENGINE\s0\fR objects. These objects act as containers for
314 reference-counted mechanism to allow them to be dynamically loaded in and
317 The cryptographic functionality that can be provided by an \fB\s-1ENGINE\s0\fR
321 \& RSA_METHOD \- for providing alternative RSA implementations
323 \&       \- similarly for other OpenSSL APIs
324 \& EVP_CIPHER \- potentially multiple cipher algorithms (indexed by \*(Aqnid\*(Aq)
325 \& EVP_DIGEST \- potentially multiple hash algorithms (indexed by \*(Aqnid\*(Aq)
326 \& key\-loading \- loading public and/or private EVP_PKEY keys
330 Due to the modular nature of the \s-1ENGINE API,\s0 pointers to ENGINEs need to be
331 treated as handles \- i.e. not only as pointers, but also as references to
332 the underlying \s-1ENGINE\s0 object. Ie. one should obtain a new reference when
333 making copies of an \s-1ENGINE\s0 pointer if the copies will be used (and
336 \&\s-1ENGINE\s0 objects have two levels of reference-counting to match the way in
337 which the objects are used. At the most basic level, each \s-1ENGINE\s0 pointer is
338 inherently a \fBstructural\fR reference \- a structural reference is required
342 However, a structural reference provides no guarantee that the \s-1ENGINE\s0 is
346 support specialised hardware. To use an \s-1ENGINE\s0's functionality, you need a
349 implicitly contains a structural reference as well \- however to avoid
350 difficult-to-find programming bugs, it is recommended to treat the two
352 \&\s-1ENGINE,\s0 you have a guarantee that the \s-1ENGINE\s0 has been initialised and
359 iterating across OpenSSL's internal linked-list of loaded
360 ENGINEs, reading information about an \s-1ENGINE,\s0 etc. Essentially a structural
362 an \s-1ENGINE\s0 implementation rather than use its functionality.
365 \&\s-1ENGINE\s0 object. There are other \s-1ENGINE API\s0 functions that return structural
368 released by a corresponding to call to the \fBENGINE_free()\fR function \- the
369 \&\s-1ENGINE\s0 object itself will only actually be cleaned up and deallocated when
372 It should also be noted that many \s-1ENGINE API\s0 function calls that accept a
373 structural reference will internally obtain another reference \- typically
374 this happens whenever the supplied \s-1ENGINE\s0 will be needed by OpenSSL after
375 the function has returned. Eg. the function to add a new \s-1ENGINE\s0 to
376 OpenSSL's internal list is \fBENGINE_add()\fR \- if this function returns success,
383 \&\s-1ENGINE\s0 list \- they will return a new structural reference to the next (or
384 previous) \s-1ENGINE\s0 in the list or \s-1NULL\s0 if at the end (or beginning) of the
390 the \fI<openssl/engine.h>\fR header file includes some hints.
395 functionality of an \s-1ENGINE\s0 is required to be available. A functional
397 reference to the required \s-1ENGINE,\s0 or by asking OpenSSL for the default
398 operational \s-1ENGINE\s0 for a given cryptographic purpose.
401 call the \fBENGINE_init()\fR function. This returns zero if the \s-1ENGINE\s0 was not
404 return nonzero to indicate that the \s-1ENGINE\s0 is now operational and will
405 have allocated a new \fBfunctional\fR reference to the \s-1ENGINE.\s0 All functional
414 algorithm-specific types in OpenSSL, such as \s-1RSA, DSA, EVP_CIPHER_CTX,\s0 etc.
417 For each supported abstraction, the \s-1ENGINE\s0 code maintains an internal table
421 abstractions like \s-1EVP_CIPHER\s0 and \s-1EVP_DIGEST\s0 support many distinct
423 In the case of other abstractions like \s-1RSA, DSA,\s0 etc, there is only one
427 When a default \s-1ENGINE\s0 is requested for a given abstraction/algorithm/mode, (e.g.
428 when calling RSA_new_method(\s-1NULL\s0)), a \*(L"get_default\*(R" call will be made to the
429 \&\s-1ENGINE\s0 subsystem to process the corresponding state table and return a
430 functional reference to an initialised \s-1ENGINE\s0 whose implementation should be
431 used. If no \s-1ENGINE\s0 should (or can) be used, it will return \s-1NULL\s0 and the caller
432 will operate with a \s-1NULL ENGINE\s0 handle \- this usually equates to using the
434 then on behave the way it used to before the \s-1ENGINE API\s0 existed.
440 operational. If it returns a functional reference to an \s-1ENGINE,\s0 it will
442 needing to iterate across the table). Likewise, it will cache a \s-1NULL\s0
443 response if no \s-1ENGINE\s0 was available so that future queries won't repeat the
445 changed; if the \s-1ENGINE_TABLE_FLAG_NOINIT\s0 flag is set (using
447 instead the only way for the state table to return a non-NULL \s-1ENGINE\s0 to the
451 query. In the case of abstractions like \s-1EVP_CIPHER,\s0 where implementations are
452 indexed by 'nid', these flags and cached-responses are distinct for each 'nid'
457 support to make the most useful elements of the \s-1ENGINE\s0 functionality
459 programmer wishes to make alternative \s-1ENGINE\s0 modules available to the
461 \&\*(L"visible\*(R" ENGINEs from which it has to operate \- at start-up, this list is
462 empty and in fact if an application does not call any \s-1ENGINE API\s0 calls and
464 binary will not contain any alternative \s-1ENGINE\s0 code at all. So the first
465 consideration is whether any/all available \s-1ENGINE\s0 implementations should be
466 made visible to OpenSSL \- this is controlled by calling the various \*(L"load\*(R"
470 the program and loaded into memory at run-time) does not mean they are
471 \&\*(L"registered\*(R" or called into use by OpenSSL automatically \- that behaviour
473 will want to allow the user to specify exactly which \s-1ENGINE\s0 they want used
475 OpenSSL automatically use at run-time any \s-1ENGINE\s0 that is able to
476 successfully initialise \- i.e. to assume that this corresponds to
481 source code to openssl's built-in utilities as guides.
483 If no \s-1ENGINE API\s0 functions are called within an application, then OpenSSL
488 \&\fIUsing a specific \s-1ENGINE\s0 implementation\fR
491 to want to use the \*(L"\s-1ACME\*(R" ENGINE\s0 if it is available in the version of
493 used by default for all \s-1RSA, DSA,\s0 and symmetric cipher operations, otherwise
494 OpenSSL should use its built-in software as per usual. The following code
498 \& ENGINE *e;
503 \&     /* the engine isn\*(Aqt available */
506 \&     /* the engine couldn\*(Aqt initialise, release \*(Aqe\*(Aq */
524 \&\fIAutomatically using built-in \s-1ENGINE\s0 implementations\fR
526 Here we'll assume we want to load and register all \s-1ENGINE\s0 implementations
528 OpenSSL \- if there is an \s-1ENGINE\s0 that implements it and can be initialised,
539 \&\s-1RSA\s0 key, any bundled ENGINEs that implement \s-1RSA_METHOD\s0 will be passed to
540 \&\fBENGINE_init()\fR and if any of those succeed, that \s-1ENGINE\s0 will be set as the
541 default for \s-1RSA\s0 use from then on.
544 There is a mechanism supported by the \s-1ENGINE\s0 framework that allows each
545 \&\s-1ENGINE\s0 implementation to define an arbitrary set of configuration
547 OpenSSL. This mechanism is entirely based on the use of name-value pairs
548 and assumes \s-1ASCII\s0 input (no unicode or \s-1UTF\s0 for now!), so it is ideal if
551 possible for the application to dynamically interrogate the loaded \s-1ENGINE\s0
554 scheme. However, if the user is expected to know which \s-1ENGINE\s0 device he/she
563 implementation (which may know nothing at all specific to the host system)
566 smart-card identifiers, passwords to initialise protected devices,
568 passed to an \s-1ENGINE\s0 \fBbefore\fR attempting to initialise it, i.e. before
572 in some cases both. \s-1ENGINE\s0 implementations should provide indications of
573 this in the descriptions attached to built-in control commands and/or in
576 \&\fIIssuing control commands to an \s-1ENGINE\s0\fR
579 name of the \s-1ENGINE\s0 it wishes to use, a table of string-pairs for use before
581 the string-pairs used for control commands consist of a command \*(L"name\*(R"
582 followed by the command \*(L"parameter\*(R" \- the parameter could be \s-1NULL\s0 in some
583 cases but the name can not. This function should initialise the \s-1ENGINE\s0
585 and set it as the default for everything except \s-1RAND\s0 and then return a
593 \&     ENGINE *e = ENGINE_by_id(engine_id);
595 \&     while (pre_num\-\-) {
597 \&             fprintf(stderr, "Failed command (%s \- %s:%s)\en", engine_id,
614 \&     while (post_num\-\-) {
616 \&             fprintf(stderr, "Failed command (%s \- %s:%s)\en", engine_id,
630 relax the semantics of the function \- if set nonzero it will only return
631 failure if the \s-1ENGINE\s0 supported the given command name but failed while
632 executing it, if the \s-1ENGINE\s0 doesn't support the command name it will simply
634 only supplying commands specific to the given \s-1ENGINE\s0 so we set this to
635 \&\s-1FALSE.\s0
639 It is possible to discover at run-time the names, numerical-ids, descriptions
640 and input parameters of the control commands supported by an \s-1ENGINE\s0 using a
643 \&\s-1ENGINE,\s0 i.e. the \s-1ENGINE\s0's \fBctrl()\fR handler is not used for the control command.
644 \&\fI<openssl/engine.h>\fR defines an index, \s-1ENGINE_CMD_BASE,\s0 that all control
650 commands implemented by a given \s-1ENGINE,\s0 specifically the commands:
665 they use various properties exposed by each \s-1ENGINE\s0 to process these
666 queries. An \s-1ENGINE\s0 has 3 properties it exposes that can affect how this behaves;
667 it can supply a \fBctrl()\fR handler, it can specify \s-1ENGINE_FLAGS_MANUAL_CMD_CTRL\s0 in
668 the \s-1ENGINE\s0's flags, and it can expose an array of control command descriptions.
669 If an \s-1ENGINE\s0 specifies the \s-1ENGINE_FLAGS_MANUAL_CMD_CTRL\s0 flag, then it will
670 simply pass all these \*(L"core\*(R" control commands directly to the \s-1ENGINE\s0's \fBctrl()\fR
671 handler (and thus, it must have supplied one), so it is up to the \s-1ENGINE\s0 to
687 If the \s-1ENGINE\s0's array of control commands is empty then all other commands will
688 fail, otherwise; \s-1ENGINE_CTRL_GET_FIRST_CMD_TYPE\s0 returns the identifier of
689 the first command supported by the \s-1ENGINE, ENGINE_GET_NEXT_CMD_TYPE\s0 takes the
690 identifier of a command supported by the \s-1ENGINE\s0 and returns the next command
691 identifier or fails if there are no more, \s-1ENGINE_CMD_FROM_NAME\s0 takes a string
695 \&\s-1ENGINE_CTRL_GET_FLAGS\s0 return the string length of a command name or description,
697 description. \s-1ENGINE_CTRL_GET_FLAGS\s0 returns a bitwise-OR'd mask of the following
707 If the \s-1ENGINE_CMD_FLAG_INTERNAL\s0 flag is set, then any other flags are purely
708 informational to the caller \- this flag will prevent the command being usable
709 for any higher-level \s-1ENGINE\s0 functions such as \fBENGINE_ctrl_cmd_string()\fR.
710 \&\*(L"\s-1INTERNAL\*(R"\s0 commands are not intended to be exposed to text-based configuration
714 discovery mechanisms simply to allow applications to determine if an \s-1ENGINE\s0
715 supports certain specific commands it might want to use (e.g. application \*(L"foo\*(R"
716 might query various ENGINEs to see if they implement \*(L"\s-1FOO_GET_VENDOR_LOGO_GIF\*(R"\s0 \-
717 and \s-1ENGINE\s0 could therefore decide whether or not to support this \*(L"foo\*(R"\-specific
721 .IP "\fB\s-1OPENSSL_ENGINES\s0\fR" 4
724 Ignored in set-user-ID and set-group-ID programs.
728 return a valid \fB\s-1ENGINE\s0\fR structure or \s-1NULL\s0 if an error occurred.
732 \&\fBENGINE_by_id()\fR returns a valid \fB\s-1ENGINE\s0\fR structure or \s-1NULL\s0 if an error occ…
737 \&\fBENGINE_get_digest_engine()\fR return a valid \fB\s-1ENGINE\s0\fR structure on success or \s-1N…
746 \&\fB\s-1ENGINE\s0\fR implementations.
758 \&\fBENGINE_new()\fR returns a valid \fB\s-1ENGINE\s0\fR structure on success or \s-1NULL\s0 if an …
770 and the name of the \s-1ENGINE\s0 \fBe\fR respectively.
781 \&\fBENGINE_get_cipher()\fR returns a valid \fB\s-1EVP_CIPHER\s0\fR structure on success or \s-1NUL…
784 \&\fBENGINE_get_digest()\fR returns a valid \fB\s-1EVP_MD\s0\fR structure on success or \s-1NULL\s0…
787 \&\fBENGINE_get_flags()\fR returns an integer representing the \s-1ENGINE\s0 flags which are
788 used to control various behaviours of an \s-1ENGINE.\s0
790 \&\fBENGINE_get_cmd_defns()\fR returns an \fB\s-1ENGINE_CMD_DEFN\s0\fR structure or \s-1NULL\s0 if …
793 \&\fBENGINE_load_private_key()\fR and \fBENGINE_load_public_key()\fR return a valid \fB\s-1EVP_PKEY…
794 structure on success or \s-1NULL\s0 if an error occurred.
808 Copyright 2002\-2021 The OpenSSL Project Authors. All Rights Reserved.
812 in the file \s-1LICENSE\s0 in the source distribution or at