Ything-RepoMirrors/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2026-01-25 02:56:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Clean up ENGINE mentions

Browse Source 
Engines are removed and the documentation should reflect that, even with
deprecated and legacy API.

Resolves: https://github.com/openssl/project/issues/1366

Signed-off-by: Norbert Pocs <norbertp@openssl.org>

Reviewed-by: Eugene Syromiatnikov <esyr@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Saša Nedvědický <sashan@openssl.org>
Reviewed-by: Saša Nedvědický <sashan@openssl.org>
Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/29305)
This commit is contained in:
Norbert Pocs
2025-11-13 15:15:41 +01:00
committed by Neil Horman
parent 7c8e2bfcd5
commit adc73bfcb3
67 changed files with 282 additions and 531 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
doc/internal/man3/OPTIONS.pod
View File

@@ -124,7 +124,6 @@ be chosen from the following set:
'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,

12
doc/internal/man7/EVP_PKEY.pod
View File

@@ -30,15 +30,12 @@ and it can take one of the following forms:
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
@@ -135,8 +132,7 @@ the exported key data) must implement OSSL_FUNC_keymgmt_import().
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

6
doc/internal/man7/build.info.pod
View File

@@ -583,12 +583,6 @@ This is used with B<SCRIPTS>, to specify that some scripts should be
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

14
doc/man1/openssl-ciphers.pod.in
View File

@@ -358,8 +358,8 @@ Cipher suites using SHA256 or SHA384.
=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>
@@ -512,9 +512,8 @@ is used.
=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
@@ -523,9 +522,8 @@ distribution.
=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

3
doc/man1/openssl-cmds.pod.in
View File

@@ -19,7 +19,6 @@ dsaparam,
ec,
ecparam,
enc,
engine,
errstr,
gendsa,
genpkey,
@@ -149,6 +148,8 @@ In order to reduce cluttering of the global manual page namespace,
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.

2
doc/man1/openssl-genpkey.pod.in
View File

@@ -82,7 +82,7 @@ algorithm with a 128-bit key in CBC mode.
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,

8
doc/man1/openssl-pkcs12.pod.in
View File

@@ -245,20 +245,16 @@ by default.
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>

21
doc/man1/openssl-s_client.pod.in
View File

@@ -558,9 +558,8 @@ Send TLS_FALLBACK_SCSV in the ClientHello.
=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>
@@ -574,19 +573,15 @@ See L<SSL_CTX_set_max_send_fragment(3)> for further information.
=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>

21
doc/man1/openssl-s_server.pod.in
View File

@@ -563,9 +563,8 @@ Cannot be used in conjunction with B<-early_data>.
=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>
@@ -574,19 +573,15 @@ See L<SSL_CTX_set_max_send_fragment(3)> for further information.
=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>

10
doc/man1/openssl-ts.pod.in
View File

@@ -405,13 +405,6 @@ last timestamp response created. This number is incremented by 1 for
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>
@@ -639,7 +632,8 @@ seeding mechanism. The new seeding mechanism makes it unnecessary to
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

49
doc/man1/openssl.pod
View File

@@ -616,50 +616,6 @@ respectively.
=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
@@ -793,8 +749,9 @@ The interactive mode, which could be invoked by running C<openssl>
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

65
doc/man3/ASYNC_WAIT_CTX_new.pod
View File

@@ -70,8 +70,8 @@ descriptors. Calling ASYNC_WAIT_CTX_get_all_fds() with a NULL I<fd> value will
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
@@ -83,7 +83,7 @@ will be populated with the list of added and deleted fds respectively. Similarly
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.
@@ -94,41 +94,40 @@ that the job should be resumed). If no file descriptor is made available then an
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.
@@ -136,22 +135,22 @@ 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>
@@ -159,21 +158,21 @@ The request has been successfully submitted.
=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.
@@ -190,7 +189,7 @@ ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
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

21
doc/man3/ASYNC_start_job.pod
View File

@@ -131,14 +131,15 @@ an application will have to periodically "poll" the job by attempting to restart
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
@@ -243,8 +244,8 @@ The following example demonstrates how to use most of the core async APIs:
/*
* 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) {

11
doc/man3/BIO_get_ex_new_index.pod
View File

@@ -7,7 +7,6 @@ BIO_set_app_data, BIO_get_app_data,
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,
@@ -65,10 +64,6 @@ see L<openssl_user_macros(7)>:
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
@@ -79,9 +74,6 @@ All functions with a I<TYPE> of B<DH>, B<DSA>, B<RSA> and B<EC_KEY> are deprecat
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.
@@ -119,13 +111,12 @@ L<CRYPTO_get_ex_new_index(3)>.
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

2
doc/man3/CMAC_CTX.pod
View File

@@ -69,7 +69,7 @@ CMAC_CTX_copy() copies the state from one B<CMAC_CTX> structure to another.
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

5
doc/man3/CMS_add1_signer.pod
View File

@@ -79,8 +79,7 @@ have a subject key identifier extension.
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
@@ -106,7 +105,7 @@ L<CMS_final(3)>,
=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

4
doc/man3/CMS_sign.pod
View File

@@ -67,9 +67,7 @@ omitted.
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

4
doc/man3/CRYPTO_get_ex_new_index.pod
View File

@@ -48,7 +48,6 @@ The specific structures are:
DH
DSA
EC_KEY
ENGINE
EVP_PKEY
RSA
SSL
@@ -166,7 +165,8 @@ CRYPTO_alloc_ex_data() was added in OpenSSL 3.0.
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

33
doc/man3/DH_set_method.pod
View File

@@ -30,36 +30,28 @@ Applications should instead use the provider APIs.
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_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 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_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)>).
@@ -72,8 +64,7 @@ B<DH_METHOD>s.
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
@@ -89,7 +80,7 @@ All of these functions were deprecated in OpenSSL 3.0.
=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

37
doc/man3/DSA_set_method.pod
View File

@@ -30,39 +30,29 @@ Applications should providers instead of method overrides.
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;
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 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.
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
@@ -72,8 +62,7 @@ B<DSA_METHOD>s.
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
@@ -89,7 +78,7 @@ All of these functions were deprecated in OpenSSL 3.0.
=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

4
doc/man3/ECDSA_sign.pod
View File

@@ -70,9 +70,7 @@ ECDSA_do_verify() is similar to ECDSA_verify() except the signature is
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

19
doc/man3/ENGINE_add.pod
View File

@@ -39,7 +39,8 @@ ENGINE_register_all_RSA, ENGINE_register_all_ciphers,
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
@@ -157,15 +158,19 @@ used instead.
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

3
doc/man3/ERR_put_error.pod
View File

@@ -107,8 +107,7 @@ with any sub-library code.
=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

7
doc/man3/EVP_CIPHER_CTX_get_cipher_data.pod
View File

@@ -16,12 +16,11 @@ inspect and modify EVP_CIPHER_CTX objects
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().

13
doc/man3/EVP_DigestInit.pod
View File

@@ -256,11 +256,12 @@ if the pointer is not NULL. At most B<EVP_MAX_MD_SIZE> bytes will be written.
=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()
@@ -545,7 +546,7 @@ EVP_MD_CTX_get_params() can be used with the following OSSL_PARAM keys:
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

3
doc/man3/EVP_DigestSignInit.pod
View File

@@ -113,8 +113,7 @@ If RSA-PSS is used and restrictions apply then the digest must match.
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

5
doc/man3/EVP_DigestVerifyInit.pod
View File

@@ -104,9 +104,8 @@ If RSA-PSS is used and restrictions apply then the digest must match.
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

5
doc/man3/EVP_EncryptInit.pod
View File

@@ -395,9 +395,8 @@ specified.
=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()

3
doc/man3/EVP_PKEY_CTX_get0_libctx.pod
View File

@@ -22,8 +22,7 @@ OSSL_LIB_CTX and property query string values respectively that were
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

4
doc/man3/EVP_PKEY_CTX_new.pod
View File

@@ -26,10 +26,10 @@ EVP_PKEY_CTX_is_a
=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

2
doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod
View File

@@ -111,8 +111,6 @@ desired length, and pass that buffer to L<EVP_PKEY_derive(3)> along with (a
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.

4
doc/man3/EVP_PKEY_CTX_set_tls1_prf_md.pod
View File

@@ -60,8 +60,6 @@ The output length of the PRF is specified by the length parameter in the
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.
@@ -102,7 +100,7 @@ OpenSSL 3.0.
=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

11
doc/man3/EVP_PKEY_asn1_get_count.pod
View File

@@ -39,16 +39,13 @@ The value of B<idx> must be between zero and EVP_PKEY_asn1_get_count()
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

5
doc/man3/EVP_PKEY_decrypt.pod
View File

@@ -80,16 +80,15 @@ Decrypt data using OAEP (for RSA keys):
#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)

5
doc/man3/EVP_PKEY_derive.pod
View File

@@ -81,13 +81,12 @@ Derive shared secret (for example DH or EC keys):
#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)

10
doc/man3/EVP_PKEY_encrypt.pod
View File

@@ -52,24 +52,21 @@ algorithm.
=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)
@@ -94,7 +91,6 @@ set 'eng = NULL;' to start with the default OpenSSL RSA implementation:
=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)>,

3
doc/man3/EVP_PKEY_get_default_digest_nid.pod
View File

@@ -27,8 +27,7 @@ I<pkey>. Note that some signature algorithms (i.e. Ed25519 and Ed448)
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

5
doc/man3/EVP_PKEY_keygen.pod
View File

@@ -177,11 +177,10 @@ Generate a key from a set of parameters:
#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)

25
doc/man3/EVP_PKEY_new.pod
View File

@@ -63,7 +63,7 @@ B<EVP_PKEY> is a generic structure to hold diverse types of asymmetric keys
(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
@@ -84,17 +84,17 @@ B<1>.
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>,
@@ -114,11 +114,10 @@ algorithm type).
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

8
doc/man3/EVP_PKEY_sign.pod
View File

@@ -164,7 +164,7 @@ Sign data using RSA with PKCS#1 padding and a SHA256 digest as input:
* 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)
@@ -209,7 +209,7 @@ input digest is assumed to have been computed using SHA256.
* 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)
@@ -256,7 +256,7 @@ B<RSA_PKCS1_PADDING>.
* 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)
@@ -301,7 +301,7 @@ functionality.
* 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)

8
doc/man3/EVP_PKEY_verify.pod
View File

@@ -174,7 +174,7 @@ Verify signature using PKCS#1 padding and a SHA256 digest as input:
* 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)
@@ -212,7 +212,7 @@ input digest is assumed to have been computed using SHA256.
* 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)
@@ -256,7 +256,7 @@ B<RSA_PKCS1_PADDING>.
* 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)
@@ -294,7 +294,7 @@ functionality.
* 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)

2
doc/man3/EVP_PKEY_verify_recover.pod
View File

@@ -90,7 +90,7 @@ Recover digest originally signed using PKCS#1 and SHA256 digest:
* 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)

2
doc/man3/EVP_SignInit.pod
View File

@@ -25,7 +25,7 @@ The EVP signature routines are a high-level interface to digital
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

6
doc/man3/EVP_VerifyInit.pod
View File

@@ -26,8 +26,8 @@ The EVP signature verification routines are a high-level interface to digital
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
@@ -104,7 +104,7 @@ The function EVP_VerifyFinal_ex() was added in OpenSSL 3.0.
=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

6
doc/man3/HMAC.pod
View File

@@ -95,9 +95,9 @@ stored in memory:
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

11
doc/man3/OPENSSL_config.pod
View File

@@ -41,15 +41,6 @@ and its use should be avoided.
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
@@ -77,7 +68,7 @@ deprecated in OpenSSL 1.1.0 by OPENSSL_init_crypto().
=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

8
doc/man3/OPENSSL_init_crypto.pod
View File

@@ -239,6 +239,14 @@ The OPENSSL_init_crypto(), OPENSSL_cleanup(), OPENSSL_atexit(),
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.

10
doc/man3/OPENSSL_load_builtin_modules.pod
View File

@@ -2,7 +2,8 @@
=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
@@ -10,7 +11,6 @@ OPENSSL_load_builtin_modules, ASN1_add_oid_module, ENGINE_add_conf_module - add
void OPENSSL_load_builtin_modules(void);
void ASN1_add_oid_module(void);
void ENGINE_add_conf_module(void);
=head1 DESCRIPTION
@@ -20,8 +20,6 @@ OpenSSL configuration code.
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
@@ -44,10 +42,6 @@ None of the functions return a value.
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.

9
doc/man3/OSSL_STORE_LOADER.pod
View File

@@ -156,7 +156,7 @@ L<OSSL_STORE_open_ex(3)>.
=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)>.
@@ -270,10 +270,9 @@ It returns 1 on success and 0 on error.
=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>.

3
doc/man3/OSSL_trace_enabled.pod
View File

@@ -53,8 +53,7 @@ OSSL_TRACE_ENABLED
=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.

13
doc/man3/OpenSSL_version.pod
View File

@@ -181,7 +181,7 @@ OpenSSL configuration files.
=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
@@ -245,13 +245,16 @@ L<crypto(7)>
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
@@ -261,7 +264,7 @@ C<0x0f> in released OpenSSL versions.
=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

7
doc/man3/RAND_set_rand_method.pod
View File

@@ -30,12 +30,8 @@ generation.
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>.
@@ -66,7 +62,6 @@ methods.
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)>

11
doc/man3/RSA_check_key.pod
View File

@@ -50,17 +50,6 @@ They return -1 if an error occurs while checking the key.
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

38
doc/man3/RSA_set_method.pod
View File

@@ -35,47 +35,37 @@ Applications should instead use the OSSL_PROVIDER APIs.
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.
@@ -149,11 +139,7 @@ and RSA_get_method() return pointers to the respective RSA_METHODs.
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
@@ -185,7 +171,7 @@ was replaced to always return NULL in OpenSSL 1.1.1.
=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

2
doc/man3/SSL_CTX_set_mode.pod
View File

@@ -105,7 +105,7 @@ in draft-ietf-tls-downgrade-scsv-00.
=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

19
doc/man3/SSL_CTX_set_split_send_fragment.pod
View File

@@ -32,17 +32,20 @@ SSL_SESSION_get_max_fragment_length - Control fragment size settings and pipelin
=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
@@ -187,7 +190,7 @@ and SSL_SESSION_get_max_fragment_length() functions were added in OpenSSL 1.1.1.
=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

6
doc/man3/SSL_CTX_use_certificate.pod
View File

@@ -106,8 +106,8 @@ key of the X.509 certificate B<x>. If the B<override> argument is 0, then
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
@@ -196,7 +196,7 @@ L<SSL_CTX_add_extra_chain_cert(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

2
doc/man3/SSL_get_all_async_fds.pod
View File

@@ -33,7 +33,7 @@ from the file descriptor). This function should only be called if the B<SSL>
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

4
doc/man3/SSL_get_error.pod
View File

@@ -135,10 +135,10 @@ Details depend on the application.
=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

32
doc/man3/SSL_set_async_callback.pod
View File

@@ -26,26 +26,26 @@ SSL_async_callback_fn
=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.
@@ -60,28 +60,28 @@ by calling SSL_set_async_callback().
=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.
@@ -121,7 +121,7 @@ SSL_get_async_status() were first added to OpenSSL 3.0.
=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

74
doc/man5/config.pod
View File

@@ -191,7 +191,6 @@ will be allowed but the desired configuration will B<not> be used.
providers = providers
alg_section = evp_properties
ssl_conf = ssl_configuration
engines = engines
random = random
[oids]
@@ -206,9 +205,6 @@ will be allowed but the desired configuration will B<not> be used.
[ssl_configuration]
... SSL/TLS configuration properties here ...
[engines]
... engine properties here ...
[random]
... random properties here ...
@@ -367,69 +363,6 @@ key types, as shown 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
@@ -548,11 +481,6 @@ F<sample>.
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.
@@ -586,6 +514,8 @@ and comments began with a semi-colon.
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)>,

11
doc/man7/EVP_PKEY-HMAC.pod
View File

@@ -46,10 +46,6 @@ supports the following parameters.
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
@@ -83,9 +79,14 @@ The name of a cipher to be used when generating the MAC.
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

24
doc/man7/evp.pod
View File

@@ -66,19 +66,16 @@ The L<B<EVP_Encode>I<XXX>|EVP_EncodeInit(3)> and
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.
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 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.
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
@@ -102,11 +99,10 @@ L<EVP_PKEY_verify(3)>,
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

4
doc/man7/fips_module.pod
View File

@@ -31,10 +31,6 @@ Low level cryptographic APIs (use the high level APIs, such as EVP, instead)
=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.)

13
doc/man7/openssl-env.pod
View File

@@ -77,12 +77,6 @@ than 1, outputs information about every processed feature.
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.
@@ -152,7 +146,7 @@ Traces CMP client and server activity.
=item B<CONF>
Show details about provider and engine configuration.
Show details about provider configuration.
=item B<DECODER>
@@ -319,6 +313,11 @@ under test output with the output for the TAP consumer.
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

2
doc/man7/ossl_store.pod
View File

@@ -28,7 +28,7 @@ from which an OpenSSL type can be retrieved.
=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.

13
doc/perlvars.pm
View File

@@ -115,19 +115,6 @@ $OpenSSL::safe::opt_config_item = ""
. "\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"