Lines Matching +full:zero +full:- +full:initialised
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
186 hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value,
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
343 initialised and able to use any of its cryptographic
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
353 is ready to perform cryptographic operations, and will remain initialised
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
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
402 already operational and couldn't be successfully initialised (e.g. lack of
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
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
564 so that it can be initialised for use. This could include the path to any
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
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
677 \& ENGINE_HAS_CTRL_FUNCTION returns FALSE (zero),
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
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