#include <openssl/engine.h>
+The following functions have been deprecated since OpenSSL 3.0, and can be
+hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
+see L<openssl_user_macros(7)>:
+
ENGINE *ENGINE_get_first(void);
ENGINE *ENGINE_get_last(void);
ENGINE *ENGINE_get_next(ENGINE *e);
EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id,
UI_METHOD *ui_method, void *callback_data);
-Deprecated:
+The following function has been deprecated since OpenSSL 1.1.0, and can be
+hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
+see L<openssl_user_macros(7)>:
- #if OPENSSL_API_COMPAT < 0x10100000L
- void ENGINE_cleanup(void)
- #endif
+ void ENGINE_cleanup(void);
=head1 DESCRIPTION
+All of the functions described on this page are deprecated.
+Applications should instead use the provider APIs.
+
These functions create, manipulate, and use cryptographic modules in the
form of B<ENGINE> objects. These objects act as containers for
implementations of cryptographic algorithms, and support a
=head2 Reference counting and handles
Due to the modular nature of the ENGINE API, pointers to ENGINEs need to be
-treated as handles - ie. not only as pointers, but also as references to
+treated as handles - i.e. not only as pointers, but also as references to
the underlying ENGINE object. Ie. one should obtain a new reference when
making copies of an ENGINE pointer if the copies will be used (and
released) independently.
To clarify a particular function's handling of references, one should
always consult that function's documentation "man" page, or failing that
-the openssl/engine.h header file includes some hints.
+the F<< <openssl/engine.h> >> header file includes some hints.
I<Functional references>
To obtain a functional reference from an existing structural reference,
call the ENGINE_init() function. This returns zero if the ENGINE was not
-already operational and couldn't be successfully initialised (eg. lack of
+already operational and couldn't be successfully initialised (e.g. lack of
system drivers, no special hardware attached, etc), otherwise it will
-return non-zero to indicate that the ENGINE is now operational and will
+return nonzero to indicate that the ENGINE is now operational and will
have allocated a new B<functional> reference to the ENGINE. All functional
references are released by calling ENGINE_finish() (which removes the
implicit structural reference as well).
The second way to get a functional reference is by asking OpenSSL for a
-default implementation for a given task, eg. by ENGINE_get_default_RSA(),
+default implementation for a given task, e.g. by ENGINE_get_default_RSA(),
ENGINE_get_default_cipher_engine(), etc. These are discussed in the next
section, though they are not usually required by application programmers as
they are used automatically when creating and using the relevant
"algorithm" so all implementations implicitly register using the same 'nid'
index.
-When a default ENGINE is requested for a given abstraction/algorithm/mode, (eg.
+When a default ENGINE is requested for a given abstraction/algorithm/mode, (e.g.
when calling RSA_new_method(NULL)), a "get_default" call will be made to the
ENGINE subsystem to process the corresponding state table and return a
functional reference to an initialised ENGINE whose implementation should be
will want to allow the user to specify exactly which ENGINE they want used
if any is to be used at all. Others may prefer to load all support and have
OpenSSL automatically use at run-time any ENGINE that is able to
-successfully initialise - ie. to assume that this corresponds to
+successfully initialise - i.e. to assume that this corresponds to
acceleration hardware attached to the machine or some such thing. There are
probably numerous other ways in which applications may prefer to handle
things, so we will simply illustrate the consequences as they apply to a
couple of simple cases and leave developers to consider these and the
-source code to openssl's builtin utilities as guides.
+source code to openssl's built-in utilities as guides.
If no ENGINE API functions are called within an application, then OpenSSL
will not allocate any internal resources. Prior to OpenSSL 1.1.0, however,
to want to use the "ACME" ENGINE if it is available in the version of
OpenSSL the application was compiled with. If it is available, it should be
used by default for all RSA, DSA, and symmetric cipher operations, otherwise
-OpenSSL should use its builtin software as per usual. The following code
+OpenSSL should use its built-in software as per usual. The following code
illustrates how to approach this;
ENGINE *e;
/* Release the structural reference from ENGINE_by_id() */
ENGINE_free(e);
-I<Automatically using builtin ENGINE implementations>
+I<Automatically using built-in ENGINE implementations>
Here we'll assume we want to load and register all ENGINE implementations
bundled with OpenSSL, such that for any cryptographic algorithm required by
driver or config files it needs to load, required network addresses,
smart-card identifiers, passwords to initialise protected devices,
logging information, etc etc. This class of commands typically needs to be
-passed to an ENGINE B<before> attempting to initialise it, ie. before
+passed to an ENGINE B<before> attempting to initialise it, i.e. before
calling ENGINE_init(). The other class of commands consist of settings or
operations that tweak certain behaviour or cause certain operations to take
place, and these commands may work either before or after ENGINE_init(), or
in some cases both. ENGINE implementations should provide indications of
-this in the descriptions attached to builtin control commands and/or in
+this in the descriptions attached to built-in control commands and/or in
external product documentation.
I<Issuing control commands to an ENGINE>
}
Note that ENGINE_ctrl_cmd_string() accepts a boolean argument that can
-relax the semantics of the function - if set non-zero it will only return
+relax the semantics of the function - if set nonzero it will only return
failure if the ENGINE supported the given command name but failed while
executing it, if the ENGINE doesn't support the command name it will simply
return success without doing anything. In this case we assume the user is
and input parameters of the control commands supported by an ENGINE using a
structural reference. Note that some control commands are defined by OpenSSL
itself and it will intercept and handle these control commands on behalf of the
-ENGINE, ie. the ENGINE's ctrl() handler is not used for the control command.
-openssl/engine.h defines an index, ENGINE_CMD_BASE, that all control commands
-implemented by ENGINEs should be numbered from. Any command value lower than
-this symbol is considered a "generic" command is handled directly by the
-OpenSSL core routines.
+ENGINE, i.e. the ENGINE's ctrl() handler is not used for the control command.
+F<< <openssl/engine.h> >> defines an index, ENGINE_CMD_BASE, that all control
+commands implemented by ENGINEs should be numbered from. Any command value
+lower than this symbol is considered a "generic" command is handled directly
+by the OpenSSL core routines.
It is using these "core" control commands that one can discover the control
commands implemented by a given ENGINE, specifically the commands:
operations via ENGINE_ctrl(), including passing to and/or from the control
commands data of any arbitrary type. These commands are supported in the
discovery mechanisms simply to allow applications to determine if an ENGINE
-supports certain specific commands it might want to use (eg. application "foo"
+supports certain specific commands it might want to use (e.g. application "foo"
might query various ENGINEs to see if they implement "FOO_GET_VENDOR_LOGO_GIF" -
and ENGINE could therefore decide whether or not to support this "foo"-specific
extension).
=item B<OPENSSL_ENGINES>
The path to the engines directory.
+Ignored in set-user-ID and set-group-ID programs.
=back
+=head1 RETURN VALUES
+
+ENGINE_get_first(), ENGINE_get_last(), ENGINE_get_next() and ENGINE_get_prev()
+return a valid B<ENGINE> structure or NULL if an error occurred.
+
+ENGINE_add() and ENGINE_remove() return 1 on success or 0 on error.
+
+ENGINE_by_id() returns a valid B<ENGINE> structure or NULL if an error occurred.
+
+ENGINE_init() and ENGINE_finish() return 1 on success or 0 on error.
+
+All ENGINE_get_default_TYPE() functions, ENGINE_get_cipher_engine() and
+ENGINE_get_digest_engine() return a valid B<ENGINE> structure on success or NULL
+if an error occurred.
+
+All ENGINE_set_default_TYPE() functions return 1 on success or 0 on error.
+
+ENGINE_set_default() returns 1 on success or 0 on error.
+
+ENGINE_get_table_flags() returns an unsigned integer value representing the
+global table flags which are used to control the registration behaviour of
+B<ENGINE> implementations.
+
+All ENGINE_register_TYPE() functions return 1 on success or 0 on error.
+
+ENGINE_register_complete() and ENGINE_register_all_complete() always return 1.
+
+ENGINE_ctrl() returns a positive value on success or others on error.
+
+ENGINE_cmd_is_executable() returns 1 if B<cmd> is executable or 0 otherwise.
+
+ENGINE_ctrl_cmd() and ENGINE_ctrl_cmd_string() return 1 on success or 0 on error.
+
+ENGINE_new() returns a valid B<ENGINE> structure on success or NULL if an error
+occurred.
+
+ENGINE_free() always returns 1.
+
+ENGINE_up_ref() returns 1 on success or 0 on error.
+
+ENGINE_set_id() and ENGINE_set_name() return 1 on success or 0 on error.
+
+All other B<ENGINE_set_*> functions return 1 on success or 0 on error.
+
+ENGINE_get_id() and ENGINE_get_name() return a string representing the identifier
+and the name of the ENGINE B<e> respectively.
+
+ENGINE_get_RSA(), ENGINE_get_DSA(), ENGINE_get_DH() and ENGINE_get_RAND()
+return corresponding method structures for each algorithms.
+
+ENGINE_get_destroy_function(), ENGINE_get_init_function(),
+ENGINE_get_finish_function(), ENGINE_get_ctrl_function(),
+ENGINE_get_load_privkey_function(), ENGINE_get_load_pubkey_function(),
+ENGINE_get_ciphers() and ENGINE_get_digests() return corresponding function
+pointers of the callbacks.
+
+ENGINE_get_cipher() returns a valid B<EVP_CIPHER> structure on success or NULL
+if an error occurred.
+
+ENGINE_get_digest() returns a valid B<EVP_MD> structure on success or NULL if an
+error occurred.
+
+ENGINE_get_flags() returns an integer representing the ENGINE flags which are
+used to control various behaviours of an ENGINE.
+
+ENGINE_get_cmd_defns() returns an B<ENGINE_CMD_DEFN> structure or NULL if it's
+not set.
+
+ENGINE_load_private_key() and ENGINE_load_public_key() return a valid B<EVP_PKEY>
+structure on success or NULL if an error occurred.
+
=head1 SEE ALSO
L<OPENSSL_init_crypto(3)>, L<RSA_new_method(3)>, L<DSA_new(3)>, L<DH_new(3)>,
=head1 HISTORY
+All of these functions were deprecated in OpenSSL 3.0.
+
ENGINE_cleanup() was deprecated in OpenSSL 1.1.0 by the automatic cleanup
done by OPENSSL_cleanup()
and should not be used.
=head1 COPYRIGHT
-Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2002-2021 The OpenSSL Project Authors. All Rights Reserved.
-Licensed under the OpenSSL license (the "License"). You may not use
+Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
projects / openssl.git / blobdiff