'u' An unsigned number that fits in the C<unsigned long> type
'c' File in PEM, DER, or S/MIME format
'F' A file in PEM or DER format
- 'E' Like 'F' but also allows ENGINE
'f' Any file format
The B<helpstr> is what to display when the user uses the help option,
This is the form that an B<EVP_PKEY> in OpenSSL prior to 3.0 had. The
internal key in the B<EVP_PKEY> is a pointer to the low-level key
-types, such as B<RSA>, B<DSA> and B<EC>, or an engine driven
-structure, and is governed by an associated L<EVP_PKEY_METHOD(3)> and
-an L<EVP_PKEY_ASN1_METHOD(3)>.
+types, such as B<RSA>, B<DSA> and B<EC>, and is governed by an associated
+L<EVP_PKEY_METHOD(3)> and an L<EVP_PKEY_ASN1_METHOD(3)>.
The functions available through those two method structures get full
access to the B<EVP_PKEY> and therefore have a lot of freedom to
-modify whatever they want. This also means that an B<EVP_PKEY> is a
-shared structure between libcrypto and any ENGINE that serves such
-methods.
+modify whatever they want.
=item provider-native origin
If such caching isn't supported, the operations that can be performed
with that key are limited to the same backend as the origin key
-(ENGINE for legacy origin keys, provider for provider side origin
-keys).
+(only provider by now).
=head3 Exporting implementation details
installed in the "misc" directory rather than the normal program
directory.
-=item B<engine>
-
-This is used with B<MODULES>, to specify what modules are engines and
-should be installed in the engines directory instead of the modules
-directory.
-
=item B<weak>
This is used with B<DEPEND> where libraries are involved, to specify
=item B<aGOST>
-Cipher suites using GOST R 34.10 (either 2001 or 94) for authentication.
-(needs a provider supporting GOST algorithms)
+Cipher suites using GOST R 34.10 (either 2001 or 94) for authentication
+(needs a provider supporting GOST algorithms).
=item B<aGOST01>
=head2 GOST cipher suites from draft-chudov-cryptopro-cptls, extending TLS v1.0
-Note: these ciphers require an engine which including GOST cryptographic
-algorithms, such as the B<gost> engine, which isn't part of the OpenSSL
-distribution.
+Note: these ciphers require a GOST provider which isn't part of OpenSSL and a
+3rd party implementation is a work in progress.
TLS_GOSTR341094_WITH_28147_CNT_IMIT GOST94-GOST89-GOST89
TLS_GOSTR341001_WITH_28147_CNT_IMIT GOST2001-GOST89-GOST89
=head2 GOST cipher suites, extending TLS v1.2
-Note: these ciphers require an engine which including GOST cryptographic
-algorithms, such as the B<gost> engine, which isn't part of the OpenSSL
-distribution.
+Note: these ciphers require a GOST provider which isn't part of OpenSSL and a
+3rd party implementation is a work in progress.
TLS_GOSTR341112_256_WITH_28147_CNT_IMIT GOST2012-GOST8912-GOST8912
TLS_GOSTR341112_256_WITH_NULL_GOSTR3411 GOST2012-NULL-GOST12
ec,
ecparam,
enc,
-engine,
errstr,
gendsa,
genpkey,
the manual page entries without the 'openssl-' prefix have been
deprecated in OpenSSL 3.0 and will be removed in OpenSSL 4.0.
+The B<engine> command was removed in OpenSSL 4.0.
+
=head1 COPYRIGHT
Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
Public key algorithm to use such as RSA, DSA, DH or DHX. If used this option must
precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm>
-are mutually exclusive. Engines or providers may add algorithms in addition to
+are mutually exclusive. Providers may add algorithms in addition to
the standard built-in ones.
Valid built-in algorithm names for private key generation are RSA, RSA-PSS, EC,
This specifies the input filename or URI.
Standard input is used by default.
-With the B<-export> option this is a file with certificates and a key,
-or a URI that refers to a key accessed via an engine.
+With the B<-export> option this is a file with certificates and a key.
The order of credentials in a file doesn't matter but one private key and
its corresponding certificate should be present. If additional
certificates are present they will also be included in the PKCS#12 output file.
=item B<-inkey> I<filename>|I<uri>
-The private key input for PKCS12 output.
+The input filename for the private key for PKCS12 output.
If this option is not specified then the input file (B<-in> argument) must
contain a private key.
-If no engine is used, the argument is taken as a file.
-If the B<-engine> option is used or the URI has prefix C<org.openssl.engine:>
-then the rest of the URI is taken as key identifier for the given engine.
=item B<-certfile> I<filename>
=item B<-async>
Switch on asynchronous mode. Cryptographic operations will be performed
-asynchronously. This will only have an effect if an asynchronous capable engine
-is also used via the B<-engine> option. For test purposes the dummy async engine
-(dasync) can be used (if available).
+asynchronously. This will only have an effect if an asynchronous capable
+provider is also used.
=item B<-maxfraglen> I<len>
=item B<-split_send_frag> I<int>
-The size used to split data for encrypt pipelines. If more data is written in
-one go than this value then it will be split into multiple pipelines, up to the
-maximum number of pipelines defined by max_pipelines. This only has an effect if
-a suitable cipher suite has been negotiated, an engine that supports pipelining
-has been loaded, and max_pipelines is greater than 1. See
-L<SSL_CTX_set_split_send_fragment(3)> for further information.
+This is used for pipelines. There is currently B<no support> for cipher
+pipelining in libssl. See L<SSL_CTX_set_max_send_fragment(3)> for further
+information.
=item B<-max_pipelines> I<int>
-The maximum number of encrypt/decrypt pipelines to be used. This will only have
-an effect if an engine has been loaded that supports pipelining (e.g. the dasync
-engine) and a suitable cipher suite has been negotiated. The default value is 1.
-See L<SSL_CTX_set_max_pipelines(3)> for further information.
+This is used for pipelines. There is currently B<no support> for cipher
+pipelining in libssl. See L<SSL_CTX_set_max_send_fragment(3)> for further
+information.
=item B<-read_buf> I<int>
=item B<-async>
Switch on asynchronous mode. Cryptographic operations will be performed
-asynchronously. This will only have an effect if an asynchronous capable engine
-is also used via the B<-engine> option. For test purposes the dummy async engine
-(dasync) can be used (if available).
+asynchronously. This will only have an effect if an asynchronous capable
+provider is also used via the B<-provider> option.
=item B<-max_send_frag> I<+int>
=item B<-split_send_frag> I<+int>
-The size used to split data for encrypt pipelines. If more data is written in
-one go than this value then it will be split into multiple pipelines, up to the
-maximum number of pipelines defined by max_pipelines. This only has an effect if
-a suitable cipher suite has been negotiated, an engine that supports pipelining
-has been loaded, and max_pipelines is greater than 1. See
-L<SSL_CTX_set_split_send_fragment(3)> for further information.
+This is used for pipelines. There is currently B<no support> for cipher
+pipelining in libssl. See L<SSL_CTX_set_max_send_fragment(3)> for further
+information.
=item B<-max_pipelines> I<+int>
-The maximum number of encrypt/decrypt pipelines to be used. This will only have
-an effect if an engine has been loaded that supports pipelining (e.g. the dasync
-engine) and a suitable cipher suite has been negotiated. The default value is 1.
-See L<SSL_CTX_set_max_pipelines(3)> for further information.
+This is used for pipelines. There is currently B<no support> for cipher
+pipelining in libssl. See L<SSL_CTX_set_max_send_fragment(3)> for further
+information.
=item B<-naccept> I<+int>
each response. If the file does not exist at the time of response
generation a new file is created with serial number 1. (Mandatory)
-=item B<crypto_device>
-
-Specifies the OpenSSL engine that will be set as the default for
-all available algorithms. The default value is built-in, you can specify
-any other engines supported by OpenSSL (e.g. use chil for the NCipher HSM).
-(Optional)
-
=item B<signer_cert>
TSA signing certificate in PEM format. The same as the B<-signer>
define a RANDFILE for saving and restoring randomness. This option is
retained mainly for compatibility reasons.
-The B<-engine> option was removed in OpenSSL 4.0.
+The B<-engine> option and B<crypto_device> configuration option were removed in
+OpenSSL 4.0.
=head1 SEE ALSO
=back
-=head2 Engine Options
-
-=over 4
-
-=item B<-engine> I<id>
-
-Load the engine identified by I<id> and use all the methods it implements
-(algorithms, key storage, etc.), unless specified otherwise in the
-command-specific documentation or it is configured to do so, as described in
-L<config(5)/Engine Configuration>.
-
-The engine will be used for key ids specified with B<-key> and similar
-options when an option like B<-keyform engine> is given.
-
-A special case is the C<loader_attic> engine, which
-is meant just for internal OpenSSL testing purposes and
-supports loading keys, parameters, certificates, and CRLs from files.
-When this engine is used, files with such credentials are read via this engine.
-Using the C<file:> schema is optional; a plain file (path) name will do.
-
-=back
-
-Options specifying keys, like B<-key> and similar, can use the generic
-OpenSSL engine key loading URI scheme C<org.openssl.engine:> to retrieve
-private keys and public keys. The URI syntax is as follows, in simplified
-form:
-
- org.openssl.engine:{engineid}:{keyid}
-
-Where C<{engineid}> is the identity/name of the engine, and C<{keyid}> is a
-key identifier that's acceptable by that engine. For example, when using an
-engine that interfaces against a PKCS#11 implementation, the generic key URI
-would be something like this (this happens to be an example for the PKCS#11
-engine that's part of OpenSC):
-
- -key org.openssl.engine:pkcs11:label_some-private-key
-
-As a third possibility, for engines and providers that have implemented
-their own L<OSSL_STORE_LOADER(3)>, C<org.openssl.engine:> should not be
-necessary. For a PKCS#11 implementation that has implemented such a loader,
-the PKCS#11 URI as defined in RFC 7512 should be possible to use directly:
-
- -key pkcs11:object=some-private-key;pin-value=1234
-
=head2 Provider Options
=over 4
with no further arguments, was removed in OpenSSL 3.0, and running
that program with no arguments is now equivalent to C<openssl help>.
-The B<engine> command was removed in OpenSSL 4.0 altogether with
-the engine support, use providers as a replacement.
+The B<engine> command, the whole engine support together with the
+C<org.openssl.engine> URI scheme was removed in OpenSSL 4.0; use providers as
+a replacement.
=head1 COPYRIGHT
return no file descriptors but will still populate I<*numfds>. Therefore,
application code is typically expected to call this function twice: once to get
the number of fds, and then again when sufficient memory has been allocated. If
-only one asynchronous engine is being used then normally this call will only
-ever return one fd. If multiple asynchronous engines are being used then more
+only one asynchronous provider is being used then normally this call will only
+ever return one fd. If multiple asynchronous providers are being used then more
could be returned.
The function ASYNC_WAIT_CTX_get_changed_fds() can be used to detect if any fds
to ASYNC_WAIT_CTX_get_all_fds() either of these can be NULL, but if they are not
NULL then the caller is responsible for ensuring sufficient memory is allocated.
-Implementers of async aware code (e.g. engines) are encouraged to return a
+Implementers of async aware code (e.g. providers) are encouraged to return a
stable fd for the lifetime of the B<ASYNC_WAIT_CTX> in order to reduce the
"churn" of regularly changing fds - although no guarantees of this are provided
to applications.
application will have to periodically "poll" the job by attempting to restart it
to see if it is ready to continue.
-Async aware code (e.g.
engines) can get the current B<ASYNC_WAIT_CTX> from the
+Async aware code (e.g.
providers) can get the current B<ASYNC_WAIT_CTX> from the
job via L<ASYNC_get_wait_ctx(3)> and provide a file descriptor to use for
waiting on by calling ASYNC_WAIT_CTX_set_wait_fd(). Typically this would be done
-by an engine immediately prior to calling ASYNC_pause_job() and not by end user
-code. An existing association with a file descriptor can be obtained using
+by a provider immediately prior to calling ASYNC_pause_job() and not by end
+user code. An existing association with a file descriptor can be obtained using
ASYNC_WAIT_CTX_get_fd() and cleared using ASYNC_WAIT_CTX_clear_fd(). Both of
these functions requires a I<key> value which is unique to the async aware
-code. This could be any unique value but a good candidate might be the
-B<ENGINE *> for the engine. The I<custom_data> parameter can be any value, and
-will be returned in a subsequent call to ASYNC_WAIT_CTX_get_fd(). The
+code. This could be any unique value. The I<custom_data> parameter can be any
+value, and will be returned in a subsequent call to ASYNC_WAIT_CTX_get_fd(). The
ASYNC_WAIT_CTX_set_wait_fd() function also expects a pointer to a "cleanup"
routine. This can be NULL but if provided will automatically get called when
-the B<ASYNC_WAIT_CTX> is freed, and gives the engine the opportunity to close
+the B<ASYNC_WAIT_CTX> is freed, and gives the provider the opportunity to close
the fd or any other resources. Note: The "cleanup" routine does not get called
if the fd is cleared directly via a call to ASYNC_WAIT_CTX_clear_fd().
-An example of typical usage might be an async capable engine. User code would
-initiate cryptographic operations. The engine would initiate those operations
+An example of typical usage might be an async capable provider. User code would
+initiate cryptographic operations. The provider would initiate those operations
asynchronously and then call ASYNC_WAIT_CTX_set_wait_fd() followed by
ASYNC_pause_job() to return control to the user code. The user code can then
perform other tasks or wait for the job to be ready by calling "select" or other
-similar function on the wait file descriptor. The engine can signal to the user
-code that the job should be resumed by making the wait file descriptor
-"readable". Once resumed the engine should clear the wake signal on the wait
+similar function on the wait file descriptor. The provider can signal to the
+user code that the job should be resumed by making the wait file descriptor
+"readable". Once resumed the provider should clear the wake signal on the wait
file descriptor.
As well as a file descriptor, user code may also be notified via a callback. The
callback and data pointers are stored within the B<ASYNC_WAIT_CTX> along with an
-additional status field that can be used for the notification of retries from an
-engine. This additional method can be used when the user thinks that a file
+additional status field that can be used for the notification of retries from a
+provider. This additional method can be used when the user thinks that a file
descriptor is too costly in terms of CPU cycles or in some context where a file
descriptor is not appropriate.
ASYNC_WAIT_CTX_set_callback() sets the callback and the callback argument. The
-callback will be called to notify user code when an engine completes a
+callback will be called to notify user code when a provider completes a
cryptography operation. It is a requirement that the callback function is small
and nonblocking as it will be run in the context of a polling mechanism or an
interrupt.
ASYNC_WAIT_CTX_get_callback() returns the callback set in the B<ASYNC_WAIT_CTX>
structure.
-ASYNC_WAIT_CTX_set_status() allows an engine to set the current engine status.
-The possible status values are the following:
+ASYNC_WAIT_CTX_set_status() allows a provider to set the current provider
+status. The possible status values are the following:
=over 4
=item B<ASYNC_STATUS_UNSUPPORTED>
-The engine does not support the callback mechanism. This is the default value.
-The engine must call ASYNC_WAIT_CTX_set_status() to set the status to some value
-other than B<ASYNC_STATUS_UNSUPPORTED> if it intends to enable the callback
-mechanism.
+The provider does not support the callback mechanism. This is the default value.
+The provider must call ASYNC_WAIT_CTX_set_status() to set the status to some
+value other than B<ASYNC_STATUS_UNSUPPORTED> if it intends to enable the
+callback mechanism.
=item B<ASYNC_STATUS_ERR>
-The engine has a fatal problem with this request. The user code should clean up
-this session.
+The provider has a fatal problem with this request. The user code should clean
+up this session.
=item B<ASYNC_STATUS_OK>
=item B<ASYNC_STATUS_EAGAIN>
-The engine has some problem which will be recovered soon, such as a buffer is
+The provider has some problem which will be recovered soon, such as a buffer is
full, so user code should resume the job.
=back
ASYNC_WAIT_CTX_get_status() allows user code to obtain the current status value.
If the status is any value other than B<ASYNC_STATUS_OK> then the user code
-should not expect to receive a callback from the engine even if one has been
+should not expect to receive a callback from the provider even if one has been
set.
An example of the usage of the callback method might be the following. User
-code would initiate cryptographic operations, and the engine code would dispatch
-this operation to hardware, and if the dispatch is successful, then the engine
-code would call ASYNC_pause_job() to return control to the user code. After
-that, user code can perform other tasks. When the hardware completes the
+code would initiate cryptographic operations, and the provider code would
+dispatch this operation to hardware, and if the dispatch is successful, then the
+provider code would call ASYNC_pause_job() to return control to the user code.
+After that, user code can perform other tasks. When the hardware completes the
operation, normally it is detected by a polling function or an interrupt, as the
user code set a callback by calling ASYNC_WAIT_CTX_set_callback() previously,
then the registered callback will be called.
ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd,
ASYNC_WAIT_CTX_set_callback, ASYNC_WAIT_CTX_get_callback and
ASYNC_WAIT_CTX_set_status all return 1 on success or 0 on error.
-ASYNC_WAIT_CTX_get_status() returns the engine status.
+ASYNC_WAIT_CTX_get_status() returns the provider status.
=head1 NOTES
it to see if it is ready to continue.
B<ASYNC_WAIT_CTX>s also have a "callback" mechanism to notify applications. The
-callback is set by an application, and it will be automatically called when an
-engine completes a cryptography operation, so that the application can resume
-the paused work flow without polling. An engine could be written to look whether
-the callback has been set. If it has then it would use the callback mechanism
-in preference to the file descriptor notifications. If a callback is not set
-then the engine may use file descriptor based notifications. Please note that
-not all engines may support the callback mechanism, so the callback may not be
-used even if it has been set. See ASYNC_WAIT_CTX_new() for more details.
+callback is set by an application, and it will be automatically called when a
+provider completes a cryptography operation, so that the application can resume
+the paused work flow without polling. A provider could be written to look
+whether the callback has been set. If it has then it would use the callback
+mechanism in preference to the file descriptor notifications. If a callback is
+not set then the provider may use file descriptor based notifications. Please
+note that not all providers may support the callback mechanism, so the callback
+may not be used even if it has been set. See ASYNC_WAIT_CTX_new() for more
+details.
The ASYNC_block_pause() function will prevent the currently active job from
pausing. The block will remain in place until a subsequent call to
/*
* Create a way to inform the calling thread when this job is ready
* to resume, in this example we're using file descriptors.
- * For offloading the task to an asynchronous ENGINE it's not necessary,
- * the ENGINE should handle that internally.
+ * For offloading the task to an asynchronous provider it's not necessary,
+ * the provider should handle that internally.
*/
if (pipe(pipefds) != 0) {
DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data,
DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data,
EC_KEY_get_ex_new_index, EC_KEY_set_ex_data, EC_KEY_get_ex_data,
-ENGINE_get_ex_new_index, ENGINE_set_ex_data, ENGINE_get_ex_data,
EVP_PKEY_get_ex_new_index, EVP_PKEY_set_ex_data, EVP_PKEY_get_ex_data,
RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data,
RSA_set_app_data, RSA_get_app_data,
void *RSA_get_ex_data(RSA *type, int idx);
int RSA_set_app_data(RSA *type, void *arg);
void *RSA_get_app_data(RSA *type);
- int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,
- CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);
- int ENGINE_set_ex_data(ENGINE *type, int idx, void *arg);
- void *ENGINE_get_ex_data(ENGINE *type, int idx);
=head1 DESCRIPTION
Applications should instead use EVP_PKEY_set_ex_data(),
EVP_PKEY_get_ex_data() and EVP_PKEY_get_ex_new_index().
-All functions with a I<TYPE> of B<ENGINE> are deprecated.
-Applications using engines should be replaced by providers.
-
These functions handle application-specific data for OpenSSL data
structures.
The functions DH_get_ex_new_index(), DH_set_ex_data(), DH_get_ex_data(),
DSA_get_ex_new_index(), DSA_set_ex_data(), DSA_get_ex_data(),
EC_KEY_get_ex_new_index(), EC_KEY_set_ex_data(), EC_KEY_get_ex_data(),
-ENGINE_get_ex_new_index(), ENGINE_set_ex_data(), ENGINE_get_ex_data(),
RSA_get_ex_new_index(), RSA_set_ex_data(), RSA_get_ex_data(),
RSA_set_app_data() and RSA_get_app_data() were deprecated in OpenSSL 3.0.
=head1 COPYRIGHT
-Copyright 2015-2021 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-2025 The OpenSSL Project Authors. All Rights Reserved.
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
CMAC_Init() initializes the B<CMAC_CTX> structure for a new CMAC calculation
with the specified key, key length, and cipher type.
-Optionally, an B<ENGINE> can be provided.
+I<impl> B<must> be NULL.
CMAC_Update() processes data to be included in the CMAC calculation.
This function can be called multiple times to update the context with
If present the SMIMECapabilities attribute indicates support for the following
algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192
bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2.
-If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is
-not loaded.
+If any of these algorithms is not available then it will not be included.
Note that, in the case signedAttributes are not used, for some hash-less signing
schemes the given hash B<md> will be ignored and a hash required by the signing
=head1 COPYRIGHT
-Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2014-2025 The OpenSSL Project Authors. All Rights Reserved.
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
If present the SMIMECapabilities attribute indicates support for the following
algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192
bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2.
-If any of these algorithms is not available then it will not be included:
-for example the GOST algorithms will not be included if the GOST ENGINE is
-not loaded.
+If any of these algorithms is not available then it will not be included.
OpenSSL will by default identify signing certificates using issuer name
and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
DH
DSA
EC_KEY
- ENGINE
EVP_PKEY
RSA
SSL
The signature of the dup_func() callback was changed in OpenSSL 3.0 to use the
type B<void **> for B<from_d>. Previously this parameter was of type B<void *>.
-Support for ENGINE "exdata" was deprecated in OpenSSL 3.0.
+Support for ENGINE "exdata" was deprecated in OpenSSL 3.0 and removed in
+OpenSSL 4.0.
=head1 COPYRIGHT
A B<DH_METHOD> specifies the functions that OpenSSL uses for Diffie-Hellman
operations. By modifying the method, alternative implementations
-such as hardware accelerators may be used. IMPORTANT: See the NOTES section for
-important information about how these DH API functions are affected by the use
-of B<ENGINE> API calls.
+such as hardware accelerators may be used.
Initially, the default DH_METHOD is the OpenSSL internal implementation, as
returned by DH_OpenSSL().
DH_set_default_method() makes B<meth> the default method for all DH
structures created later.
-B<NB>: This is true only whilst no ENGINE has been set
-as a default for DH, so this function is no longer recommended.
+B<NB>:
This function is not thread-safe and should not be called at the same time
as other OpenSSL functions.
DH_get_default_method() returns a pointer to the current default DH_METHOD.
-However, the meaningfulness of this result is dependent on whether the ENGINE
-API is being used, so this function is no longer recommended.
-
-DH_set_method() selects B<meth> to perform all operations using the key B<dh>.
-This will replace the DH_METHOD used by the DH key and if the previous method
-was supplied by an ENGINE, the handle to that ENGINE will be released during the
-change. It is possible to have DH keys that only work with certain DH_METHOD
-implementations (e.g. from an ENGINE module that supports embedded
-hardware-protected keys), and in such cases attempting to change the DH_METHOD
-for the key can have unexpected results.
-
-DH_new_method() allocates and initializes a DH structure so that B<engine> will
-be used for the DH operations. If B<engine> is NULL, the default ENGINE for DH
-operations is used, and if no default ENGINE is set, the DH_METHOD controlled by
-DH_set_default_method() is used.
+
+DH_set_method() selects B<meth> to perform all operations using the key
+B<dh>. This will replace the DH_METHOD used by the DH key.
+It is possible to have DH keys that only work with certain DH_METHOD
+implementations, and in such cases attempting to change the DH_METHOD for the
+key can have unexpected results. See L<DH_meth_new(3)> for information on
+constructing custom DH_METHOD objects.
+
+DH_new_method() allocates and initializes a DH structure. B<engine> must
+be NULL and the DH_METHOD controlled by DH_set_default_method() is used.
A new DH_METHOD object may be constructed using DH_meth_new() (see
L<DH_meth_new(3)>).
DH_set_default_method() returns no value.
DH_set_method() returns nonzero if the provided B<meth> was successfully set as
-the method for B<dh> (including unloading the ENGINE handle if the previous
-method was supplied by an ENGINE).
+the method for B<dh>.
DH_new_method() returns NULL and sets an error code that can be obtained by
L<ERR_get_error(3)> if the allocation fails. Otherwise it
=head1 COPYRIGHT
-Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2025 The OpenSSL Project Authors. All Rights Reserved.
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
A B<DSA_METHOD> specifies the functions that OpenSSL uses for DSA
operations. By modifying the method, alternative implementations
-such as hardware accelerators may be used. IMPORTANT: See the NOTES section for
-important information about how these DSA API functions are affected by the use
-of B<ENGINE> API calls.
+such as hardware accelerators may be used.
Initially, the default DSA_METHOD is the OpenSSL internal implementation,
as returned by DSA_OpenSSL().
DSA_set_default_method() makes B<meth> the default method for all DSA
structures created later.
-B<NB>: This is true only whilst no ENGINE has
-been set as a default for DSA, so this function is no longer recommended.
-This function is not thread-safe and should not be called at the same time
+B<NB>: This function is not thread-safe and should not be called at the same time
as other OpenSSL functions.
DSA_get_default_method() returns a pointer to the current default
-DSA_METHOD. However, the meaningfulness of this result is dependent on
-whether the ENGINE API is being used, so this function is no longer
-recommended.
+DSA_METHOD.
DSA_set_method() selects B<meth> to perform all operations using the key
-B<rsa>. This will replace the DSA_METHOD used by the DSA key and if the
-previous method was supplied by an ENGINE, the handle to that ENGINE will
-be released during the change. It is possible to have DSA keys that only
-work with certain DSA_METHOD implementations (e.g. from an ENGINE module
-that supports embedded hardware-protected keys), and in such cases
-attempting to change the DSA_METHOD for the key can have unexpected
-results. See L<DSA_meth_new(3)> for information on constructing custom DSA_METHOD
-objects;
-
-DSA_new_method() allocates and initializes a DSA structure so that B<engine>
-will be used for the DSA operations. If B<engine> is NULL, the default engine
-for DSA operations is used, and if no default ENGINE is set, the DSA_METHOD
-controlled by DSA_set_default_method() is used.
+B<dsa>. This will replace the DSA_METHOD used by the DSA key.
+It is possible to have DSA keys that only work with certain DSA_METHOD
+implementations, and in such cases attempting to change the DSA_METHOD for the
+key can have unexpected results. See L<DSA_meth_new(3)> for information on
+constructing custom DSA_METHOD objects.
+
+DSA_new_method() allocates and initializes a DSA structure so that the
+DSA_METHOD controlled by DSA_set_default_method() is used. I<engine> B<must>
+be NULL.
=head1 RETURN VALUES
DSA_set_default_method() returns no value.
DSA_set_method() returns nonzero if the provided B<meth> was successfully set as
-the method for B<dsa> (including unloading the ENGINE handle if the previous
-method was supplied by an ENGINE).
+the method for B<dsa>.
DSA_new_method() returns NULL and sets an error code that can be
obtained by L<ERR_get_error(3)> if the allocation
=head1 COPYRIGHT
-Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2025 The OpenSSL Project Authors. All Rights Reserved.
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
presented in the form of a pointer to an B<ECDSA_SIG> structure.
The remaining functions utilise the internal I<kinv> and I<r> values used
-during signature computation. Most applications will never need to call these
-and some external ECDSA ENGINE implementations may not support them at all if
-either I<kinv> or I<r> is not NULL.
+during signature computation. Most applications will never need to call these.
ECDSA_sign_setup() may be used to precompute parts of the signing operation.
I<eckey> is the private EC key and I<ctx> is a pointer to B<BN_CTX> structure
ENGINE_register_all_digests, ENGINE_set_table_flags, ENGINE_unregister_DH,
ENGINE_unregister_DSA,
ENGINE_unregister_RAND, ENGINE_unregister_RSA, ENGINE_unregister_ciphers,
-ENGINE_unregister_digests
+ENGINE_get_ex_new_index, ENGINE_set_ex_data, ENGINE_get_ex_data,
+ENGINE_unregister_digests, ENGINE_add_conf_module
- ENGINE cryptographic module support
=head1 SYNOPSIS
EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id,
UI_METHOD *ui_method, void *callback_data);
void ENGINE_cleanup(void);
+ void ENGINE_add_conf_module(void);
+ int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,
+ CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);
+ int ENGINE_set_ex_data(ENGINE *type, int idx, void *arg);
+ void *ENGINE_get_ex_data(ENGINE *type, int idx);
=head1 DESCRIPTION
-All of these functions were removed since OpenSSL 4.0. Please remove them from
-your source code as soon as possible. If you are not able to remove the symbols
-easily and still want to be able to compile your code (with empty and broken
-ENGINE), you are able to do so by defining B<OPENSSL_ENGINE_STUB> macro in
-your source files before the inclusion of the C<openssl/engine.h> header.
-Please use provider API instead of ENGINEs.
+All of these functions were removed since OpenSSL 4.0. If there is still a need
+for these definitions to present (despite the support for engines being absent),
+it is possible to define the B<OPENSSL_ENGINE_STUB> macro (before the inclusion
+of the C<openssl/engine.h> header) to get stub definitions of the
+aforementioned functions.
=head1 ENVIRONMENT
=head3 Other pieces of software
Other pieces of software that may want to use OpenSSL's error reporting
-system, such as engines or applications, must normally get their own
-numbers.
+system, such as applications, must normally get their own numbers.
=over 4
The EVP_CIPHER_CTX_get_cipher_data() function returns a pointer to the cipher
data relevant to EVP_CIPHER_CTX. The contents of this data is specific to the
-particular implementation of the cipher. For example this data can be used by
-engines to store engine specific information. The data is automatically
-allocated and freed by OpenSSL, so applications and engines should not normally
+particular implementation of the cipher. The data is automatically
+allocated and freed by OpenSSL, so applications should not normally
free this directly (but see below).
-The EVP_CIPHER_CTX_set_cipher_data() function allows an application or engine to
+The EVP_CIPHER_CTX_set_cipher_data() function allows an application to
replace the cipher data with new data. A pointer to any existing cipher data is
returned from this function. If the old data is no longer required then it
should be freed through a call to OPENSSL_free().
=item EVP_Digest()
-A wrapper around the Digest Init_ex, Update and Final_ex functions.
-Hashes I<count> bytes of data at I<data> using a digest I<type> from ENGINE
-I<impl>. The digest value is placed in I<md> and its length is written at I<size>
-if the pointer is not NULL. At most B<EVP_MAX_MD_SIZE> bytes will be written.
-If I<impl> is NULL the default implementation of digest I<type> is used.
+A wrapper around the EVP_DigestInit_ex(), EVP_DigestUpdate() and
+EVP_DigestFinal_ex() functions.
+Hashes I<count> bytes of data at I<data>. The digest value is placed in I<md>
+and its length is written at I<size> if the pointer is not NULL. At most
+B<EVP_MAX_MD_SIZE> bytes will be written. I<impl> B<must> be NULL and the
+default implementation of digest I<type> is used.
=item EVP_DigestInit_ex2()
Gets the digest Message Integrity Check algorithm string. This is used when
creating S/MIME multipart/signed messages, as specified in RFC 3851.
-It may be used by external engines or providers.
+It may be used by external providers.
=back
EVP_DigestSignInit() works in the same way as EVP_DigestSignInit_ex()
except that the I<mdname> parameter will be inferred from the supplied
-digest I<type>, and I<props> will be NULL. Where supplied the ENGINE I<e> will
-be used for the signing and digest algorithm implementations. I<e> may be NULL.
+digest I<type>, and I<props> will be NULL. I<e> B<must> be NULL.
EVP_DigestSignUpdate() hashes I<cnt> bytes of data at I<d> into the
signature context I<ctx>. This function can be called several times on the
EVP_DigestVerifyInit() works in the same way as
EVP_DigestVerifyInit_ex() except that the B<mdname> parameter will be
-inferred from the supplied digest B<type>, and B<props> will be NULL. Where
-supplied the ENGINE B<e> will be used for the signature verification and digest
-algorithm implementations. B<e> may be NULL.
+inferred from the supplied digest B<type>, and B<props> will be NULL.
+B<e> B<must> be NULL.
EVP_DigestVerifyUpdate() hashes B<cnt> bytes of data at B<d> into the
verification context B<ctx>. This function can be called several times on the
=item EVP_EncryptInit_ex()
-This legacy function is similar to EVP_EncryptInit_ex2() when I<impl> is NULL.
-The implementation of the I<type> from the I<impl> engine will be used if it
-exists.
+This legacy function is the same as EVP_EncryptInit_ex2() except B<params> will
+be NULL. I<impl> B<must> be NULL.
=item EVP_EncryptUpdate()
associated with the EVP_PKEY_CTX when it was constructed.
EVP_PKEY_CTX_get0_provider() returns the provider associated with the
-ongoing B<EVP_PKEY_CTX> operation. If the operation is performed by
-en B<ENGINE>, this function returns NULL.
+ongoing B<EVP_PKEY_CTX> operation.
=head1 RETURN VALUES
=head1 DESCRIPTION
The EVP_PKEY_CTX_new() function allocates public key algorithm context using
-the I<pkey> key type and ENGINE I<e>.
+the I<pkey> key type. I<e> B<must> be NULL.
The EVP_PKEY_CTX_new_id() function allocates public key algorithm context
-using the key type specified by I<id> and ENGINE I<e>.
+using the key type specified by I<id>. I<e> B<must> be NULL.
The EVP_PKEY_CTX_new_from_name() function allocates a public key algorithm
context using the library context I<libctx> (see L<OSSL_LIB_CTX(3)>), the
pointer initialized to) the desired length. Passing a B<NULL> buffer to obtain
the length is allowed when using EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY.
-Optimised versions of HKDF can be implemented in an ENGINE.
-
=head1 RETURN VALUES
All these functions return 1 for success and 0 or a negative value for failure.
EVP_PKEY_derive() function. Since the output length is variable, setting
the buffer to B<NULL> is not meaningful for the TLS PRF.
-Optimised versions of the TLS PRF can be implemented in an ENGINE.
-
=head1 RETURN VALUES
All these functions return 1 for success and 0 or a negative value for failure.
=head1 COPYRIGHT
-Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2016-2025 The OpenSSL Project Authors. All Rights Reserved.
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
EVP_PKEY_asn1_find() looks up the B<EVP_PKEY_ASN1_METHOD> with NID
B<type>.
-If B<pe> isn't B<NULL>, then it will look up an engine implementing a
-B<EVP_PKEY_ASN1_METHOD> for the NID B<type> and return that instead,
-and also set B<*pe> to point at the engine that implements it.
+If B<pe> isn't B<NULL>, then NULL will be placed at the given address, as
+ENGINEs were removed, therefore none can be found.
EVP_PKEY_asn1_find_str() looks up the B<EVP_PKEY_ASN1_METHOD> with PEM
type string B<str>.
-Just like EVP_PKEY_asn1_find(), if B<pe> isn't B<NULL>, then it will
-look up an engine implementing a B<EVP_PKEY_ASN1_METHOD> for the NID
-B<type> and return that instead, and also set B<*pe> to point at the
-engine that implements it.
+Just like EVP_PKEY_asn1_find(), if B<pe> isn't B<NULL>, then NULL will be placed
+at the given address, as ENGINEs were removed, therefore none can be found.
EVP_PKEY_asn1_get0_info() returns the public key ID, base public key
ID (both NIDs), any flags, the method description and PEM type string
#include <openssl/rsa.h>
EVP_PKEY_CTX *ctx;
- ENGINE *eng;
unsigned char *out, *in;
size_t outlen, inlen;
EVP_PKEY *key;
/*
- * NB: assumes key, eng, in, inlen are already set up
+ * NB: assumes key, in, inlen are already set up
* and that key is an RSA private key
*/
- ctx = EVP_PKEY_CTX_new(key, eng);
+ ctx = EVP_PKEY_CTX_new(key, NULL);
if (!ctx)
/* Error occurred */
if (EVP_PKEY_decrypt_init(ctx) <= 0)
#include <openssl/rsa.h>
EVP_PKEY_CTX *ctx;
- ENGINE *eng;
unsigned char *skey;
size_t skeylen;
EVP_PKEY *pkey, *peerkey;
- /* NB: assumes pkey, eng, peerkey have been already set up */
+ /* NB: assumes pkey, peerkey have been already set up */
- ctx = EVP_PKEY_CTX_new(pkey, eng);
+ ctx = EVP_PKEY_CTX_new(pkey, NULL);
if (!ctx)
/* Error occurred */
if (EVP_PKEY_derive_init(ctx) <= 0)
=head1 EXAMPLES
Encrypt data using OAEP (for RSA keys). See also L<PEM_read_PUBKEY(3)> or
-L<d2i_X509(3)> for means to load a public key. You may also simply
-set 'eng = NULL;' to start with the default OpenSSL RSA implementation:
+L<d2i_X509(3)> for means to load a public key.
#include <openssl/evp.h>
#include <openssl/rsa.h>
- #include <openssl/engine.h>
EVP_PKEY_CTX *ctx;
- ENGINE *eng;
unsigned char *out, *in;
size_t outlen, inlen;
EVP_PKEY *key;
/*
- * NB: assumes eng, key, in, inlen are already set up,
+ * NB: assumes key, in, inlen are already set up,
* and that key is an RSA public key
*/
- ctx = EVP_PKEY_CTX_new(key, eng);
+ ctx = EVP_PKEY_CTX_new(key, NULL);
if (!ctx)
/* Error occurred */
if (EVP_PKEY_encrypt_init(ctx) <= 0)
=head1 SEE ALSO
L<d2i_X509(3)>,
-L<ENGINE_by_id(3)>,
L<EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_decrypt(3)>,
L<EVP_PKEY_sign(3)>,
do not use a digest during signing. In this case I<pnid> will be set
to NID_undef. This function is only reliable for legacy keys, which
are keys with a B<EVP_PKEY_ASN1_METHOD>; these keys have typically
-been loaded from engines, or created with L<EVP_PKEY_assign_RSA(3)> or
-similar.
+been created with L<EVP_PKEY_assign_RSA(3)> or similar.
=head1 NOTES
#include <openssl/rsa.h>
EVP_PKEY_CTX *ctx;
- ENGINE *eng;
EVP_PKEY *pkey = NULL, *param;
- /* Assumed param, eng are set up already */
- ctx = EVP_PKEY_CTX_new(param, eng);
+ /* Assumed param is set up already */
+ ctx = EVP_PKEY_CTX_new(param, NULL);
if (!ctx)
/* Error occurred */
if (EVP_PKEY_keygen_init(ctx) <= 0)
(also known as "key pairs"), and can be used for diverse operations, like
signing, verifying signatures, key derivation, etc. The asymmetric keys
themselves are often referred to as the "internal key", and are handled by
-backends, such as providers (through L<EVP_KEYMGMT(3)>) or B<ENGINE>s.
+providers through L<EVP_KEYMGMT(3)>.
Conceptually, an B<EVP_PKEY> internal key may hold a private key, a public
key, or both (a keypair), and along with those, key parameters if the key type
EVP_PKEY_up_ref() increments the reference count of I<key>.
-EVP_PKEY_dup() duplicates the I<key>. The I<key> must not be ENGINE based or
-a raw key, otherwise the duplication will fail.
+EVP_PKEY_dup() duplicates the I<key>. The I<key> must not be a raw key,
+otherwise the duplication will fail.
EVP_PKEY_free() decrements the reference count of I<key> and, if the reference
count is zero, frees it up. If I<key> is NULL, nothing is done.
-EVP_PKEY_new_raw_private_key_ex() allocates a new B<EVP_PKEY>. Unless an
-engine should be used for the key type, a provider for the key is found using
-the library context I<libctx> and the property query string I<propq>. The
-I<keytype> argument indicates what kind of key this is. The value should be a
-string for a public key algorithm that supports raw private keys, e.g., one of:
+EVP_PKEY_new_raw_private_key_ex() allocates a new B<EVP_PKEY>. A provider for
+the key is found using the library context I<libctx> and the property query
+string I<propq>. The I<keytype> argument indicates what kind of key this is.
+The value should be a string for a public key algorithm that supports raw
+private keys, e.g., one of:
C<ED25519>,
C<ED448>,
C<X25519>,
EVP_PKEY_new_raw_private_key() does the same as
EVP_PKEY_new_raw_private_key_ex() except that the default library context and
-default property query are used instead. If I<e> is non-NULL then the new
-B<EVP_PKEY> structure is associated with the engine I<e>. The I<type> argument
-indicates what kind of key this is. The value should be a NID for a public key
-algorithm that supports raw private keys, i.e. one of B<EVP_PKEY_X25519>,
-B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>.
+default property query are used instead. I<e> B<must> be NULL. The I<type>
+argument indicates what kind of key this is. The value should be a NID for a
+public key algorithm that supports raw private keys, i.e. one of
+B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>.
EVP_PKEY_new_raw_private_key_ex() and EVP_PKEY_new_raw_private_key() may also
be used with most MACs implemented as public key algorithms, so key types such
* step. signing_key must be an RSA private key and md must
* point to the SHA-256 digest to be signed.
*/
- ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
+ ctx = EVP_PKEY_CTX_new(signing_key, NULL);
if (ctx == NULL)
/* Error occurred */
if (EVP_PKEY_sign_init(ctx) <= 0)
* step. signing_key must be an RSA private key and md must
* point to the SHA-256 digest to be signed.
*/
- ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
+ ctx = EVP_PKEY_CTX_new(signing_key, NULL);
alg = EVP_SIGNATURE_fetch(NULL, "RSA-SHA256", NULL);
if (ctx == NULL)
* in must point to data to be digested and signed, and
* inlen must be the size of the data in bytes.
*/
- ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
+ ctx = EVP_PKEY_CTX_new(signing_key, NULL);
alg = EVP_SIGNATURE_fetch(NULL, "RSA-SHA256", NULL);
if (ctx == NULL || alg == NULL)
* in must point to data to be digested and signed, and
* inlen must be the size of the data in bytes.
*/
- ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
+ ctx = EVP_PKEY_CTX_new(signing_key, NULL);
alg = EVP_SIGNATURE_fetch(NULL, "RSA-SHA256", NULL);
if (ctx == NULL || alg == NULL)
* NB: assumes verify_key, sig, siglen md and mdlen are already set up
* and that verify_key is an RSA public key
*/
- ctx = EVP_PKEY_CTX_new(verify_key, NULL /* no engine */);
+ ctx = EVP_PKEY_CTX_new(verify_key, NULL);
if (ctx == NULL)
/* Error occurred */
if (EVP_PKEY_verify_init(ctx) <= 0)
* NB: assumes verify_key, sig, siglen, md and mdlen are already set up
* and that verify_key is an RSA public key
*/
- ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
+ ctx = EVP_PKEY_CTX_new(signing_key, NULL);
alg = EVP_SIGNATURE_fetch(NULL, "RSA-SHA256", NULL);
if (ctx == NULL)
* in must point to data to be digested and signed, and
* inlen must be the size of the data in bytes.
*/
- ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
+ ctx = EVP_PKEY_CTX_new(signing_key, NULL);
alg = EVP_SIGNATURE_fetch(NULL, "RSA-SHA256", NULL);
if (ctx == NULL || alg == NULL)
* in must point to data to be digested and signed, and
* inlen must be the size of the data in bytes.
*/
- ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
+ ctx = EVP_PKEY_CTX_new(signing_key, NULL);
alg = EVP_SIGNATURE_fetch(NULL, "RSA-SHA256", NULL);
if (ctx == NULL || alg == NULL)
* NB: assumes verify_key, sig and siglen are already set up
* and that verify_key is an RSA public key
*/
- ctx = EVP_PKEY_CTX_new(verify_key, NULL /* no engine */);
+ ctx = EVP_PKEY_CTX_new(verify_key, NULL);
if (!ctx)
/* Error occurred */
if (EVP_PKEY_verify_recover_init(ctx) <= 0)
signatures.
EVP_SignInit_ex() sets up signing context I<ctx> to use digest
-I<type> from B<ENGINE> I<impl>. I<ctx> must be created with
+I<type>. I<impl> B<must> be NULL. I<ctx> must be created with
EVP_MD_CTX_new() before calling this function.
EVP_SignUpdate() hashes I<cnt> bytes of data at I<d> into the
signatures.
EVP_VerifyInit_ex() sets up verification context I<ctx> to use digest
-I<type> from ENGINE I<impl>. I<ctx> must be created by calling
-EVP_MD_CTX_new() before calling this function.
+I<type>. I<ctx> B<must> be created by calling EVP_MD_CTX_new() before calling
+this function. I<impl> B<must> be NULL.
EVP_VerifyUpdate() hashes I<cnt> bytes of data at I<d> into the
verification context I<ctx>. This function can be called several times on the
=head1 COPYRIGHT
-Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2025 The OpenSSL Project Authors. All Rights Reserved.
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
HMAC_Init_ex() initializes or reuses a B<HMAC_CTX> structure to use the hash
function I<evp_md> and key I<key>. If both are NULL, or if I<key> is NULL
and I<evp_md> is the same as the previous call, then the
-existing key is
-reused. I<ctx> must have been created with HMAC_CTX_new() before the first use
-of an B<HMAC_CTX> in this function.
+existing key is reused. I<ctx> must have been created with HMAC_CTX_new()
+before the first use of an B<HMAC_CTX> in this function. I<impl> B<must>
+be NULL.
If HMAC_Init_ex() is called with I<key> NULL and I<evp_md> is not the
same as the previous digest used by I<ctx> then an error is returned
Applications should instead call CONF_modules_load() during
initialization (that is before starting any threads).
-There are several reasons why calling the OpenSSL configuration routines is
-advisable. For example, to load dynamic ENGINEs from shared libraries (DSOs).
-However, very few applications currently support the control interface and so
-very few can load and use dynamic ENGINEs. Equally in future more sophisticated
-ENGINEs will require certain control operations to customize them. If an
-application calls OPENSSL_config() it doesn't need to know or care about
-ENGINE control operations because they can be performed by editing a
-configuration file.
-
=head1 ENVIRONMENT
=over 4
=head1 COPYRIGHT
-Copyright 2004-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2004-2025 The OpenSSL Project Authors. All Rights Reserved.
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
OPENSSL_thread_stop(), OPENSSL_INIT_new(), OPENSSL_INIT_set_config_appname()
and OPENSSL_INIT_free() functions were added in OpenSSL 1.1.0.
+B<OPENSSL_INIT_ENGINE_RDRAND>, B<OPENSSL_INIT_ENGINE_DYNAMIC>,
+B<OPENSSL_INIT_ENGINE_OPENSSL>, B<OPENSSL_INIT_ENGINE_CRYPTODEV>,
+B<OPENSSL_INIT_ENGINE_CAPI>, B<OPENSSL_INIT_ENGINE_PADLOCK>,
+B<OPENSSL_INIT_ENGINE_AFALG> OPENSSL_init_crypto() I<opts> were removed in
+OpenSSL 4.0.
+
+B<OPENSSL_INIT_ENGINE_ALL_BUILTIN> is defined to 0 since OpenSSL 4.0.
+
=head1 COPYRIGHT
Copyright 2016-2024 The OpenSSL Project Authors. All Rights Reserved.
=head1 NAME
-OPENSSL_load_builtin_modules, ASN1_add_oid_module, ENGINE_add_conf_module - add standard configuration modules
+OPENSSL_load_builtin_modules, ASN1_add_oid_module
+- add standard configuration modules
=head1 SYNOPSIS
void OPENSSL_load_builtin_modules(void);
void ASN1_add_oid_module(void);
- void ENGINE_add_conf_module(void);
=head1 DESCRIPTION
ASN1_add_oid_module() adds just the ASN1 OBJECT module.
-ENGINE_add_conf_module() adds just the ENGINE configuration module.
-
=head1 NOTES
If the simple configuration function OPENSSL_config() is called then
L<config(5)>, L<OPENSSL_config(3)>
-=head1 HISTORY
-
-ENGINE_add_conf_module() was deprecated in OpenSSL 3.0.
-
=head1 COPYRIGHT
Copyright 2004-2020 The OpenSSL Project Authors. All Rights Reserved.
=head2 Legacy Types and Functions (deprecated)
-These functions help applications and engines to create loaders for
+These functions help applications to create loaders for
schemes they support. These are all deprecated and discouraged in favour of
provider implementations, see L<provider-storemgmt(7)>.
=back
OSSL_STORE_LOADER_new() creates a new B<OSSL_STORE_LOADER>.
-It takes an B<ENGINE> I<e> and a string I<scheme>.
-I<scheme> must I<always> be set.
-Both I<e> and I<scheme> are used as is and must therefore be alive as
-long as the created loader is.
+It takes a string I<scheme>. I<scheme> must I<always> be set.
+I<e> B<must> be NULL. I<scheme> is used as is and must therefore be alive
+as long as the created loader is.
OSSL_STORE_LOADER_get0_scheme() returns the scheme of the I<store_loader>.
=head1 DESCRIPTION
The functions described here are mainly interesting for those who provide
-OpenSSL functionality, either in OpenSSL itself or in engine modules
-or similar.
+OpenSSL functionality, either in OpenSSL itself or in a provider or similar.
If the tracing facility is enabled (see L</Configure Tracing> below),
these functions are used to generate free text tracing output.
=item OPENSSL_INFO_MODULES_DIR
The configured C<MODULESDIR>, which is the default location for
-dynamically loadable OpenSSL modules other than engines.
+dynamically loadable OpenSSL modules.
=item OPENSSL_INFO_DSO_EXTENSION
The macros and functions described here were added in OpenSSL 3.0,
except for OPENSSL_VERSION_NUMBER and OpenSSL_version_num().
-The B<ENGINESDIR> setting of the library is no longer supported
-since OpenSSL 4.0.
-
The B<OPENSSL_ENGINES_DIR> and B<OPENSSL_INFO_ENGINES_DIR> strings
are no longer supported and, for compatibility reasons, will always
return values indicating that engine support was disabled.
+The B<OPENSSL_ENGINES_DIR> and B<OPENSSL_INFO_ENGINES_DIR> strings
+were removed since OpenSSL 4.0.
+
+The B<ENGINESDIR> setting of the library is no longer supported
+since OpenSSL 4.0.
+
=head1 BUGS
There was a discrepancy between this manual and commentary + code
=head1 COPYRIGHT
-Copyright 2018-2022 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2018-2025 The OpenSSL Project Authors. All Rights Reserved.
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
RAND_OpenSSL() returns the default B<RAND_METHOD> implementation by OpenSSL.
This implementation ensures that the PRNG state is unique for each thread.
-If an B<ENGINE> is loaded that provides the RAND API, however, it will
-be used instead of the method returned by RAND_OpenSSL(). This is deprecated
-in OpenSSL 3.0.
-RAND_set_rand_method() makes B<meth> the method for PRNG use. If an
-ENGINE was providing the method, it will be released first.
+RAND_set_rand_method() makes B<meth> the method for PRNG use.
RAND_get_rand_method() returns a pointer to the current B<RAND_METHOD>.
L<EVP_RAND(3)>,
L<RAND_set_DRBG_type(3)>,
L<RAND_bytes(3)>,
-L<ENGINE_by_id(3)>,
L<EVP_RAND(7)>,
L<RAND(7)>
If the key is invalid or an error occurred, the reason code can be
obtained using L<ERR_get_error(3)>.
-=head1 NOTES
-
-Unlike most other RSA functions, this function does B<not> work
-transparently with any underlying ENGINE implementation because it uses the
-key data in the RSA structure directly. An ENGINE implementation can
-override the way key data is stored and handled, and can even provide
-support for HSM keys - in which case the RSA structure may contain B<no>
-key data at all! If the ENGINE in question is only being used for
-acceleration or analysis purposes, then in all likelihood the RSA key data
-is complete and untouched, but this can't be assumed in the general case.
-
=head1 BUGS
A method of verifying the RSA key using opaque RSA API functions might need
An B<RSA_METHOD> specifies the functions that OpenSSL uses for RSA
operations. By modifying the method, alternative implementations such as
-hardware accelerators may be used. IMPORTANT: See the NOTES section for
-important information about how these RSA API functions are affected by the
-use of B<ENGINE> API calls.
+hardware accelerators may be used.
Initially, the default RSA_METHOD is the OpenSSL internal implementation,
as returned by RSA_PKCS1_OpenSSL().
RSA_set_default_method() makes B<meth> the default method for all RSA
structures created later.
-B<NB>: This is true only whilst no ENGINE has
-been set as a default for RSA, so this function is no longer recommended.
-This function is not thread-safe and should not be called at the same time
+B<NB>: This function is not thread-safe and should not be called at the same time
as other OpenSSL functions.
RSA_get_default_method() returns a pointer to the current default
-RSA_METHOD. However, the meaningfulness of this result is dependent on
-whether the ENGINE API is being used, so this function is no longer
-recommended.
+RSA_METHOD.
RSA_set_method() selects B<meth> to perform all operations using the key
-B<rsa>. This will replace the RSA_METHOD used by the RSA key and if the
-previous method was supplied by an ENGINE, the handle to that ENGINE will
-be released during the change. It is possible to have RSA keys that only
-work with certain RSA_METHOD implementations (e.g. from an ENGINE module
-that supports embedded hardware-protected keys), and in such cases
+B<rsa>. This will replace the RSA_METHOD used by the RSA key.
+It is possible to have RSA keys that only
+work with certain RSA_METHOD implementations, and in such cases
attempting to change the RSA_METHOD for the key can have unexpected
results.
RSA_get_method() returns a pointer to the RSA_METHOD being used by B<rsa>.
-This method may or may not be supplied by an ENGINE implementation, but if
-it is, the return value can only be guaranteed to be valid as long as the
+The return value can only be guaranteed to be valid as long as the
RSA key itself is valid and does not have its implementation changed by
RSA_set_method().
RSA_flags() returns the B<flags> that are set for B<rsa>'s current
RSA_METHOD. See the BUGS section.
-RSA_new_method() allocates and initializes an RSA structure so that
-B<engine> will be used for the RSA operations. If B<engine> is NULL, the
-default ENGINE for RSA operations is used, and if no default ENGINE is set,
-the RSA_METHOD controlled by RSA_set_default_method() is used.
+RSA_new_method() allocates and initializes an RSA structure.
+B<engine> must be NULL and the RSA_METHOD controlled by RSA_set_default_method()
+is used.
RSA_flags() returns the B<flags> that are set for B<rsa>'s current method.
RSA_set_default_method() returns no value.
RSA_set_method() returns a pointer to the old RSA_METHOD implementation
-that was replaced. However, this return value should probably be ignored
-because if it was supplied by an ENGINE, the pointer could be invalidated
-at any time if the ENGINE is unloaded (in fact it could be unloaded as a
-result of the RSA_set_method() function releasing its handle to the
-ENGINE). For this reason, the return type may be replaced with a B<void>
+that was replaced. The return type may be replaced with a B<void>
declaration in a future release.
RSA_new_method() returns NULL and sets an error code that can be obtained
=head1 COPYRIGHT
-Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2025 The OpenSSL Project Authors. All Rights Reserved.
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
=item SSL_MODE_ASYNC
Enable asynchronous processing. TLS I/O operations may indicate a retry with
-SSL_ERROR_WANT_ASYNC with this mode set if an asynchronous capable engine is
+SSL_ERROR_WANT_ASYNC with this mode set if an asynchronous capable provider is
used to perform cryptographic operations. See L<SSL_get_error(3)>.
=item SSL_MODE_DTLS_SCTP_LABEL_LENGTH_BUG
=head1 DESCRIPTION
-Some engines are able to process multiple simultaneous crypto operations. This
+Previous versions of libssl supported the concept of cipher pipelining. There is
+no support for this in OpenSSL 4.0. In previous versions some engines were
+able to process multiple simultaneous crypto operations. This
capability could be utilised to parallelise the processing of a single
connection. For example a single write can be split into multiple records and
-each one encrypted independently and in parallel. Note: this will only work in
-TLS1.1+. There is no support in SSLv3, TLSv1.0 or DTLS (any version). This
+each one encrypted independently and in parallel. Note: this would only work in
+TLS1.1+. There was no support in SSLv3, TLSv1.0 or DTLS (any version). This
capability is known as "pipelining" within OpenSSL.
-In order to benefit from the pipelining capability. You need to have an engine
-that provides ciphers that support this. The OpenSSL "dasync" engine provides
-AES128-SHA based ciphers that have this capability. However, these are for
-development and test purposes only.
+In order to benefit from the pipelining capability, you would need to have an
+engine that provides ciphers that support this. Since OpenSSL 4.0 engines are no
+longer supported and therefore pipelining is not supported either. In some
+future version it may be that this capability is added back via the provider
+mechanism.
SSL_CTX_set_max_send_fragment() and SSL_set_max_send_fragment() set the
B<max_send_fragment> parameter for SSL_CTX and SSL objects respectively. This
=head1 COPYRIGHT
-Copyright 2016-2023 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2016-2025 The OpenSSL Project Authors. All Rights Reserved.
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
B<x>, B<pkey> and B<chain> are set only if all were not previously set.
If B<override> is non-0, then the certificate, private key and chain certs
are always set. If B<pkey> is NULL, then the public key of B<x> is used as
-the private key. This is intended to be used with hardware (via the ENGINE
-interface) that stores the private key securely, such that it cannot be
+the private key. This is intended to be used with hardware
+that stores the private key securely, such that it cannot be
accessed by OpenSSL. The reference count of the public key is incremented
(twice if there is no private key); it is not copied nor duplicated. This
allows all private key validations checks to succeed without an actual
=head1 COPYRIGHT
-Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2025 The OpenSSL Project Authors. All Rights Reserved.
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
object is currently waiting for asynchronous work to complete (i.e.
B<SSL_ERROR_WANT_ASYNC> has been received - see L<SSL_get_error(3)>). Typically
the list will only contain one file descriptor. However, if multiple asynchronous
-capable engines are in use then more than one is possible. The number of file
+capable providers are in use then more than one is possible. The number of file
descriptors returned is stored in I<*numfds> and the file descriptors themselves
are in I<*fds>. The I<fds> parameter may be NULL in which case no file
descriptors are returned but I<*numfds> is still populated. It is the callers
=item SSL_ERROR_WANT_ASYNC
-The operation did not complete because an asynchronous engine is still
+The job did not complete because an asynchronous provider is still
processing data. This will only occur if the mode has been set to SSL_MODE_ASYNC
using L<SSL_CTX_set_mode(3)> or L<SSL_set_mode(3)> and an asynchronous capable
-engine is being used. An application can determine whether the engine has
+provider is being used. An application can determine whether the job has
completed its processing using select() or poll() on the asynchronous wait file
descriptor. This file descriptor is available by calling
L<SSL_get_all_async_fds(3)> or L<SSL_get_changed_async_fds(3)>. The TLS/SSL I/O
=head1 DESCRIPTION
SSL_CTX_set_async_callback() sets an asynchronous callback function. All B<SSL>
-objects generated based on this B<SSL_CTX> will get this callback. If an engine
-supports the callback mechanism, it will be automatically called if
-B<SSL_MODE_ASYNC> has been set and an asynchronous capable engine completes a
-cryptography operation to notify the application to resume the paused work flow.
+objects generated based on this B<SSL_CTX> will get this callback. If a
+provider supports the callback mechanism, it will be automatically called if
+B<SSL_MODE_ASYNC> has been set and the provider completes a cryptography
+operation to notify the application to resume the paused work flow.
SSL_CTX_set_async_callback_arg() sets the callback argument.
SSL_set_async_callback() allows an application to set a callback in an
-asynchronous B<SSL> object, so that when an engine completes a cryptography
+asynchronous B<SSL> object, so that when an provider completes a cryptography
operation, the callback will be called to notify the application to resume the
paused work flow.
SSL_set_async_callback_arg() sets an argument for the B<SSL> object when the
above callback is called.
-SSL_get_async_status() returns the engine status. This function facilitates the
-communication from the engine to the application. During an SSL session,
-cryptographic operations are dispatched to an engine. The engine status is very
-useful for an application to know if the operation has been successfully
-dispatched. If the engine does not support this additional callback method,
+SSL_get_async_status() returns the provider status. This function facilitates
+the communication from the provider to the application. During an SSL session,
+cryptographic operations are dispatched to a provider. The provider status is
+very useful for an application to know if the operation has been successfully
+dispatched. If the provider does not support this additional callback method,
B<ASYNC_STATUS_UNSUPPORTED> will be returned. See ASYNC_WAIT_CTX_set_status()
for a description of all of the status values.
=item 2.
-Application sets B<SSL_MODE_ASYNC> and makes an asynchronous SSL call
+Application sets B<SSL_MODE_ASYNC> and makes an asynchronous SSL call.
=item 3.
-OpenSSL submits the asynchronous request to the engine. If a retry occurs at
+OpenSSL submits the asynchronous request to the provider. If a retry occurs at
this point then the status within the B<ASYNC_WAIT_CTX> would be set and the
async callback function would be called (goto Step 7).
=item 4.
-The OpenSSL engine pauses the current job and returns, so that the
+The OpenSSL provider pauses the current job and returns, so that the
application can continue processing other connections.
=item 5.
At a future point in time (probably via a polling mechanism or via an
-interrupt) the engine will become aware that the asynchronous request has
+interrupt) the provider will become aware that the asynchronous request has
finished processing.
=item 6.
-The engine will call the application's callback passing the callback data as
+The provider will call the application's callback passing the callback data as
a parameter.
=item 7.
=head1 COPYRIGHT
-Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved.
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
providers = providers
alg_section = evp_properties
ssl_conf = ssl_configuration
- engines = engines
random = random
[oids]
[ssl_configuration]
... SSL/TLS configuration properties here ...
- [engines]
- ... engine properties here ...
-
[random]
... random properties here ...
RSA.Certificate = server-rsa.pem
ECDSA.Certificate = server-ecdsa.pem
-=head2 Engine Configuration
-
-The name B<engines> in the initialization section names the section
-containing the list of ENGINE configurations.
-As with the providers, each name in this section identifies an engine
-with the configuration for that engine.
-The engine-specific section is used to specify how to load the engine,
-activate it, and set other parameters.
-
-Within an engine section, the following names have meaning:
-
-=over 4
-
-=item B<engine_id>
-
-This is used to specify an alternate name, overriding the default name
-specified in the list of engines. If present, it must be first.
-For example:
-
- [engines]
- foo = foo_engine
-
- [foo_engine]
- engine_id = myfoo
-
-=item B<dynamic_path>
-
-This loads and adds an ENGINE from the given path. It is equivalent to
-sending the ctrls B<SO_PATH> with the path argument followed by B<LIST_ADD>
-with value B<2> and B<LOAD> to the dynamic ENGINE. If this is not the
-required behaviour then alternative ctrls can be sent directly to the
-dynamic ENGINE using ctrl commands.
-
-=item B<init>
-
-This specifies whether to initialize the ENGINE. If the value is B<0> the
-ENGINE will not be initialized, if the value is B<1> an attempt is made
-to initialize
-the ENGINE immediately. If the B<init> command is not present then an
-attempt will be made to initialize the ENGINE after all commands in its
-section have been processed.
-
-=item B<default_algorithms>
-
-This sets the default algorithms an ENGINE will supply using the function
-ENGINE_set_default_string().
-
-=back
-
-All other names are taken to be the name of a ctrl command that is
-sent to the ENGINE, and the value is the argument passed with the command.
-The special value B<EMPTY> means no value is sent with the command.
-For example:
-
- [engines]
- foo = foo_engine
-
- [foo_engine]
- dynamic_path = /some/path/fooengine.so
- some_ctrl = some_value
- default_algorithms = ALL
- other_ctrl = EMPTY
-
=head2 Random Configuration
The name B<random> in the initialization section names the section
The path to the config file, or the empty string for none.
Ignored in set-user-ID and set-group-ID programs.
-=item B<OPENSSL_ENGINES>
-
-The path to the engines directory.
-Ignored in set-user-ID and set-group-ID programs.
-
=item B<OPENSSL_MODULES>
The path to the directory with OpenSSL modules, such as providers.
This function was deprecated in OpenSSL 3.0; applications with
configuration files using that syntax will have to be modified.
+The I<engines> parameter was removed in OpenSSL 4.0.
+
=head1 SEE ALSO
L<openssl-x509(1)>, L<openssl-req(1)>, L<openssl-ca(1)>,
The name of a cipher to be used when generating the MAC.
-=item "engine" (B<OSSL_PKEY_PARAM_ENGINE>) <UTF8 string>
-
-The name of an engine to be used for the specified cipher (if any).
-
=back
=head2 Common MAC key generation parameters
L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>
+=head1 HISTORY
+
+The CMAC parameter I<engine> (B<OSSL_PKEY_PARAM_ENGINE>) was removed in
+OpenSSL 4.0.
+
=head1 COPYRIGHT
-Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2020-2025 The OpenSSL Project Authors. All Rights Reserved.
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
L<B<EVP_Decode>I<XXX>|EVP_EncodeInit(3)> functions implement base64 encoding
and decoding.
-All the symmetric algorithms (ciphers), digests and asymmetric algorithms
-(public key algorithms) can be replaced by ENGINE modules providing alternative
-implementations. If ENGINE implementations of ciphers or digests are registered
-as defaults, then the various EVP functions will automatically use those
-implementations automatically in preference to built in software
-implementations. For more information, consult the engine(3) man page.
-
-Although low-level algorithm specific functions exist for many algorithms
-their use is discouraged. They cannot be used with an ENGINE and ENGINE
-versions of new algorithms cannot be accessed using the low-level functions.
-Also makes code harder to adapt to new algorithms and some options are not
-cleanly supported at the low-level and some operations are more efficient
-using the high-level interface.
+Providers can supply implementations for a wide range of cryptographic
+operations, including symmetric algorithms (ciphers), digests, asymmetric
+algorithms (public key algorithms), key management, parameter generation,
+and more. For more information, consult the provider(7) man page.
+
+Although low-level algorithm specific functions exist for many algorithms,
+their use is discouraged. They do not call into providers such as the fips
+provider and thus they are not FIPS 140-3 validated. If an accelerated
+implementation of an algorithm is provided through a third party provider
+the low level API will not use that implementation either.
=head1 SEE ALSO
L<EVP_PKEY_verify_recover(3)>,
L<EVP_PKEY_derive(3)>,
L<EVP_BytesToKey(3)>,
-L<ENGINE_by_id(3)>
=head1 COPYRIGHT
-Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2025 The OpenSSL Project Authors. All Rights Reserved.
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
=item *
-Engines
-
-=item *
-
Any functions that create or modify custom "METHODS" (for example
EVP_MD_meth_new(), EVP_CIPHER_meth_new(), EVP_PKEY_meth_new(), RSA_meth_new(),
EC_KEY_METHOD_new(), etc.)
This variable is not considered security-sensitive.
-=item B<OPENSSL_ENGINES>
-
-Specifies the directory from which dynamic engines are loaded.
-
-This variable is considered a security-sensitive environment variable.
-
=item B<OPENSSL_MALLOC_FAILURES>, B<OPENSSL_MALLOC_FD>, B<OPENSSL_MALLOC_SEED>
If built with debugging, this allows memory allocation to fail.
=item B<CONF>
-Show details about provider and engine configuration.
+Show details about provider configuration.
=item B<DECODER>
This variable was not considered security-sensitive.
+=item B<OPENSSL_ENGINES>
+
+This variable, support for which was removed in OpenSSL 4.0, specified the
+directory from which dynamic engines were loaded.
+
=back
=head1 COPYRIGHT
=head2 URI schemes and loaders
Support for a URI scheme is called a STORE "loader", and can be added
-dynamically from the calling application or from a loadable engine.
+dynamically from the calling application or from a loadable provider.
Support for the 'file' scheme is built into C<libcrypto>.
See L<ossl_store-file(7)> for more information.
. "\n"
. "See L<openssl(1)/Configuration Option>.";
-# Engine option
-$OpenSSL::safe::opt_engine_synopsis = "";
-$OpenSSL::safe::opt_engine_item = "";
-if (!$disabled{"deprecated-3.0"}) {
- $OpenSSL::safe::opt_engine_synopsis = ""
- . "[B<-engine> I<id>]\n";
- $OpenSSL::safe::opt_engine_item = ""
- . "=item B<-engine> I<id>\n"
- . "\n"
- . "See L<openssl(1)/Engine Options>.\n"
- . "This option is deprecated.";
-}
-
# Trusted certs options
$OpenSSL::safe::opt_trust_synopsis = ""
. "[B<-CAfile> I<file>]\n"
projects / thirdparty / openssl.git / commitdiff
