From: Norbert Pocs Date: Thu, 13 Nov 2025 14:15:41 +0000 (+0100) Subject: Docs: Clean up ENGINE mentions X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=adc73bfcb30ea78b74caec3785d81ad9a281bd9c;p=thirdparty%2Fopenssl.git Docs: Clean up ENGINE mentions 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 Reviewed-by: Eugene Syromiatnikov Reviewed-by: Tomas Mraz Reviewed-by: Saša Nedvědický Reviewed-by: Saša Nedvědický Reviewed-by: Neil Horman Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/openssl/pull/29305) --- diff --git a/doc/internal/man3/OPTIONS.pod b/doc/internal/man3/OPTIONS.pod index bad0bd92ad8..669823ee8f5 100644 --- a/doc/internal/man3/OPTIONS.pod +++ b/doc/internal/man3/OPTIONS.pod @@ -124,7 +124,6 @@ be chosen from the following set: 'u' An unsigned number that fits in the C 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 is what to display when the user uses the help option, diff --git a/doc/internal/man7/EVP_PKEY.pod b/doc/internal/man7/EVP_PKEY.pod index fd3c27c2db7..b8588b0dfb1 100644 --- a/doc/internal/man7/EVP_PKEY.pod +++ b/doc/internal/man7/EVP_PKEY.pod @@ -30,15 +30,12 @@ and it can take one of the following forms: This is the form that an B in OpenSSL prior to 3.0 had. The internal key in the B is a pointer to the low-level key -types, such as B, B and B, or an engine driven -structure, and is governed by an associated L and -an L. +types, such as B, B and B, and is governed by an associated +L and an L. The functions available through those two method structures get full access to the B and therefore have a lot of freedom to -modify whatever they want. This also means that an B 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 diff --git a/doc/internal/man7/build.info.pod b/doc/internal/man7/build.info.pod index 6f67aca7a55..de5bcb33c69 100644 --- a/doc/internal/man7/build.info.pod +++ b/doc/internal/man7/build.info.pod @@ -583,12 +583,6 @@ This is used with B, to specify that some scripts should be installed in the "misc" directory rather than the normal program directory. -=item B - -This is used with B, to specify what modules are engines and -should be installed in the engines directory instead of the modules -directory. - =item B This is used with B where libraries are involved, to specify diff --git a/doc/man1/openssl-ciphers.pod.in b/doc/man1/openssl-ciphers.pod.in index 9066db44333..24852e2dc9b 100644 --- a/doc/man1/openssl-ciphers.pod.in +++ b/doc/man1/openssl-ciphers.pod.in @@ -358,8 +358,8 @@ Cipher suites using SHA256 or SHA384. =item B -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 @@ -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 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 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 diff --git a/doc/man1/openssl-cmds.pod.in b/doc/man1/openssl-cmds.pod.in index 18c2ac03039..89890e43a92 100644 --- a/doc/man1/openssl-cmds.pod.in +++ b/doc/man1/openssl-cmds.pod.in @@ -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 command was removed in OpenSSL 4.0. + =head1 COPYRIGHT Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man1/openssl-genpkey.pod.in b/doc/man1/openssl-genpkey.pod.in index 6eb185ac6d1..76fc3ac134e 100644 --- a/doc/man1/openssl-genpkey.pod.in +++ b/doc/man1/openssl-genpkey.pod.in @@ -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, diff --git a/doc/man1/openssl-pkcs12.pod.in b/doc/man1/openssl-pkcs12.pod.in index 48a9d4d06fe..1f153bd3264 100644 --- a/doc/man1/openssl-pkcs12.pod.in +++ b/doc/man1/openssl-pkcs12.pod.in @@ -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|I -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 -then the rest of the URI is taken as key identifier for the given engine. =item B<-certfile> I diff --git a/doc/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in index 83b05812097..bc2d3c822f3 100644 --- a/doc/man1/openssl-s_client.pod.in +++ b/doc/man1/openssl-s_client.pod.in @@ -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 @@ -574,19 +573,15 @@ See L for further information. =item B<-split_send_frag> I -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 for further information. +This is used for pipelines. There is currently B for cipher +pipelining in libssl. See L for further +information. =item B<-max_pipelines> I -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 for further information. +This is used for pipelines. There is currently B for cipher +pipelining in libssl. See L for further +information. =item B<-read_buf> I diff --git a/doc/man1/openssl-s_server.pod.in b/doc/man1/openssl-s_server.pod.in index f16ed8d326f..dbf6a30da4d 100644 --- a/doc/man1/openssl-s_server.pod.in +++ b/doc/man1/openssl-s_server.pod.in @@ -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 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 for further information. +This is used for pipelines. There is currently B for cipher +pipelining in libssl. See L 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 for further information. +This is used for pipelines. There is currently B for cipher +pipelining in libssl. See L for further +information. =item B<-naccept> I<+int> diff --git a/doc/man1/openssl-ts.pod.in b/doc/man1/openssl-ts.pod.in index da8e9b6f837..d7493f6bb24 100644 --- a/doc/man1/openssl-ts.pod.in +++ b/doc/man1/openssl-ts.pod.in @@ -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 - -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 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 configuration option were removed in +OpenSSL 4.0. =head1 SEE ALSO diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod index 569c0ffe9f9..ea506b7c354 100644 --- a/doc/man1/openssl.pod +++ b/doc/man1/openssl.pod @@ -616,50 +616,6 @@ respectively. =back -=head2 Engine Options - -=over 4 - -=item B<-engine> I - -Load the engine identified by I 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. - -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 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 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 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, C 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 with no further arguments, was removed in OpenSSL 3.0, and running that program with no arguments is now equivalent to C. -The B command was removed in OpenSSL 4.0 altogether with -the engine support, use providers as a replacement. +The B command, the whole engine support together with the +C URI scheme was removed in OpenSSL 4.0; use providers as +a replacement. =head1 COPYRIGHT diff --git a/doc/man3/ASYNC_WAIT_CTX_new.pod b/doc/man3/ASYNC_WAIT_CTX_new.pod index d85c51e5556..accbeeaf194 100644 --- a/doc/man3/ASYNC_WAIT_CTX_new.pod +++ b/doc/man3/ASYNC_WAIT_CTX_new.pod @@ -70,8 +70,8 @@ descriptors. Calling ASYNC_WAIT_CTX_get_all_fds() with a NULL I 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 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 from the +Async aware code (e.g. providers) can get the current B from the job via L 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 value which is unique to the async aware -code. This could be any unique value but a good candidate might be the -B for the engine. The I 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 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 is freed, and gives the engine the opportunity to close +the B 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 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 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 -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 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 if it intends to enable the +callback mechanism. =item B -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 @@ -159,21 +158,21 @@ The request has been successfully submitted. =item B -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 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 diff --git a/doc/man3/ASYNC_start_job.pod b/doc/man3/ASYNC_start_job.pod index 89b34ae6a43..d641933fc1a 100644 --- a/doc/man3/ASYNC_start_job.pod +++ b/doc/man3/ASYNC_start_job.pod @@ -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. Bs 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) { diff --git a/doc/man3/BIO_get_ex_new_index.pod b/doc/man3/BIO_get_ex_new_index.pod index 95bdc793895..9b3c5ce6809 100644 --- a/doc/man3/BIO_get_ex_new_index.pod +++ b/doc/man3/BIO_get_ex_new_index.pod @@ -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: 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 of B, B, B and B 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 of B 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. 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 diff --git a/doc/man3/CMAC_CTX.pod b/doc/man3/CMAC_CTX.pod index fae4fd1516e..ae469ce9c2f 100644 --- a/doc/man3/CMAC_CTX.pod +++ b/doc/man3/CMAC_CTX.pod @@ -69,7 +69,7 @@ CMAC_CTX_copy() copies the state from one B structure to another. CMAC_Init() initializes the B structure for a new CMAC calculation with the specified key, key length, and cipher type. -Optionally, an B can be provided. +I B 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 diff --git a/doc/man3/CMS_add1_signer.pod b/doc/man3/CMS_add1_signer.pod index 606df6f6fd6..c7618f6f329 100644 --- a/doc/man3/CMS_add1_signer.pod +++ b/doc/man3/CMS_add1_signer.pod @@ -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 will be ignored and a hash required by the signing @@ -106,7 +105,7 @@ L, =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 diff --git a/doc/man3/CMS_sign.pod b/doc/man3/CMS_sign.pod index ce4f39f885c..772b59f2067 100644 --- a/doc/man3/CMS_sign.pod +++ b/doc/man3/CMS_sign.pod @@ -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 is set it will use the subject key diff --git a/doc/man3/CRYPTO_get_ex_new_index.pod b/doc/man3/CRYPTO_get_ex_new_index.pod index d2b44fd6943..b0c68cbd5cd 100644 --- a/doc/man3/CRYPTO_get_ex_new_index.pod +++ b/doc/man3/CRYPTO_get_ex_new_index.pod @@ -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 for B. Previously this parameter was of type B. -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 diff --git a/doc/man3/DH_set_method.pod b/doc/man3/DH_set_method.pod index d6da3810019..3b1e68115c1 100644 --- a/doc/man3/DH_set_method.pod +++ b/doc/man3/DH_set_method.pod @@ -30,36 +30,28 @@ Applications should instead use the provider APIs. A B 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 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 the default method for all DH structures created later. -B: This is true only whilst no ENGINE has been set -as a default for DH, so this function is no longer recommended. +B: 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 to perform all operations using the key B. -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 will -be used for the DH operations. If B 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 to perform all operations using the key +B. 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 for information on +constructing custom DH_METHOD objects. + +DH_new_method() allocates and initializes a DH structure. B 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). @@ -72,8 +64,7 @@ Bs. DH_set_default_method() returns no value. DH_set_method() returns nonzero if the provided B was successfully set as -the method for B (including unloading the ENGINE handle if the previous -method was supplied by an ENGINE). +the method for B. DH_new_method() returns NULL and sets an error code that can be obtained by L 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 diff --git a/doc/man3/DSA_set_method.pod b/doc/man3/DSA_set_method.pod index 6275859b2c5..6243c93d6b4 100644 --- a/doc/man3/DSA_set_method.pod +++ b/doc/man3/DSA_set_method.pod @@ -30,39 +30,29 @@ Applications should providers instead of method overrides. A B 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 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 the default method for all DSA structures created later. -B: 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: 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 to perform all operations using the key -B. 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 for information on constructing custom DSA_METHOD -objects; - -DSA_new_method() allocates and initializes a DSA structure so that B -will be used for the DSA operations. If B 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. 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 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 B +be NULL. =head1 RETURN VALUES @@ -72,8 +62,7 @@ Bs. DSA_set_default_method() returns no value. DSA_set_method() returns nonzero if the provided B was successfully set as -the method for B (including unloading the ENGINE handle if the previous -method was supplied by an ENGINE). +the method for B. DSA_new_method() returns NULL and sets an error code that can be obtained by L 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 diff --git a/doc/man3/ECDSA_sign.pod b/doc/man3/ECDSA_sign.pod index 88e851885a0..0f820b44bdb 100644 --- a/doc/man3/ECDSA_sign.pod +++ b/doc/man3/ECDSA_sign.pod @@ -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 structure. The remaining functions utilise the internal I and I 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 or I 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 is the private EC key and I is a pointer to B structure diff --git a/doc/man3/ENGINE_add.pod b/doc/man3/ENGINE_add.pod index e279bd3d637..4e471f15204 100644 --- a/doc/man3/ENGINE_add.pod +++ b/doc/man3/ENGINE_add.pod @@ -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 macro in -your source files before the inclusion of the C 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 macro (before the inclusion +of the C header) to get stub definitions of the +aforementioned functions. =head1 ENVIRONMENT diff --git a/doc/man3/ERR_put_error.pod b/doc/man3/ERR_put_error.pod index 56c73c13eff..9ba02a235e3 100644 --- a/doc/man3/ERR_put_error.pod +++ b/doc/man3/ERR_put_error.pod @@ -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 diff --git a/doc/man3/EVP_CIPHER_CTX_get_cipher_data.pod b/doc/man3/EVP_CIPHER_CTX_get_cipher_data.pod index efb2aca1b95..31797a7a1ae 100644 --- a/doc/man3/EVP_CIPHER_CTX_get_cipher_data.pod +++ b/doc/man3/EVP_CIPHER_CTX_get_cipher_data.pod @@ -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(). diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod index ddad2f8f883..804a76f73b2 100644 --- a/doc/man3/EVP_DigestInit.pod +++ b/doc/man3/EVP_DigestInit.pod @@ -256,11 +256,12 @@ if the pointer is not NULL. At most B bytes will be written. =item EVP_Digest() -A wrapper around the Digest Init_ex, Update and Final_ex functions. -Hashes I bytes of data at I using a digest I from ENGINE -I. The digest value is placed in I and its length is written at I -if the pointer is not NULL. At most B bytes will be written. -If I is NULL the default implementation of digest I is used. +A wrapper around the EVP_DigestInit_ex(), EVP_DigestUpdate() and +EVP_DigestFinal_ex() functions. +Hashes I bytes of data at I. The digest value is placed in I +and its length is written at I if the pointer is not NULL. At most +B bytes will be written. I B be NULL and the +default implementation of digest I 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 diff --git a/doc/man3/EVP_DigestSignInit.pod b/doc/man3/EVP_DigestSignInit.pod index 68baac639f2..dbdb87af727 100644 --- a/doc/man3/EVP_DigestSignInit.pod +++ b/doc/man3/EVP_DigestSignInit.pod @@ -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 parameter will be inferred from the supplied -digest I, and I will be NULL. Where supplied the ENGINE I will -be used for the signing and digest algorithm implementations. I may be NULL. +digest I, and I will be NULL. I B be NULL. EVP_DigestSignUpdate() hashes I bytes of data at I into the signature context I. This function can be called several times on the diff --git a/doc/man3/EVP_DigestVerifyInit.pod b/doc/man3/EVP_DigestVerifyInit.pod index dc694308f97..d195425e46c 100644 --- a/doc/man3/EVP_DigestVerifyInit.pod +++ b/doc/man3/EVP_DigestVerifyInit.pod @@ -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 parameter will be -inferred from the supplied digest B, and B will be NULL. Where -supplied the ENGINE B will be used for the signature verification and digest -algorithm implementations. B may be NULL. +inferred from the supplied digest B, and B will be NULL. +B B be NULL. EVP_DigestVerifyUpdate() hashes B bytes of data at B into the verification context B. This function can be called several times on the diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod index 3c62659319c..05801a17a5f 100644 --- a/doc/man3/EVP_EncryptInit.pod +++ b/doc/man3/EVP_EncryptInit.pod @@ -395,9 +395,8 @@ specified. =item EVP_EncryptInit_ex() -This legacy function is similar to EVP_EncryptInit_ex2() when I is NULL. -The implementation of the I from the I engine will be used if it -exists. +This legacy function is the same as EVP_EncryptInit_ex2() except B will +be NULL. I B be NULL. =item EVP_EncryptUpdate() diff --git a/doc/man3/EVP_PKEY_CTX_get0_libctx.pod b/doc/man3/EVP_PKEY_CTX_get0_libctx.pod index 81332b8c704..20645a3e862 100644 --- a/doc/man3/EVP_PKEY_CTX_get0_libctx.pod +++ b/doc/man3/EVP_PKEY_CTX_get0_libctx.pod @@ -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 operation. If the operation is performed by -en B, this function returns NULL. +ongoing B operation. =head1 RETURN VALUES diff --git a/doc/man3/EVP_PKEY_CTX_new.pod b/doc/man3/EVP_PKEY_CTX_new.pod index a15abc2c3e1..fff102a769a 100644 --- a/doc/man3/EVP_PKEY_CTX_new.pod +++ b/doc/man3/EVP_PKEY_CTX_new.pod @@ -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 key type and ENGINE I. +the I key type. I B be NULL. The EVP_PKEY_CTX_new_id() function allocates public key algorithm context -using the key type specified by I and ENGINE I. +using the key type specified by I. I B be NULL. The EVP_PKEY_CTX_new_from_name() function allocates a public key algorithm context using the library context I (see L), the diff --git a/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod b/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod index 81ee5c485b5..f16b3bcb5a9 100644 --- a/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod +++ b/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod @@ -111,8 +111,6 @@ desired length, and pass that buffer to L along with (a pointer initialized to) the desired length. Passing a B 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. diff --git a/doc/man3/EVP_PKEY_CTX_set_tls1_prf_md.pod b/doc/man3/EVP_PKEY_CTX_set_tls1_prf_md.pod index 9c204b8b328..333a910d3e1 100644 --- a/doc/man3/EVP_PKEY_CTX_set_tls1_prf_md.pod +++ b/doc/man3/EVP_PKEY_CTX_set_tls1_prf_md.pod @@ -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 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 diff --git a/doc/man3/EVP_PKEY_asn1_get_count.pod b/doc/man3/EVP_PKEY_asn1_get_count.pod index 3cb5faee6c3..f367c74b045 100644 --- a/doc/man3/EVP_PKEY_asn1_get_count.pod +++ b/doc/man3/EVP_PKEY_asn1_get_count.pod @@ -39,16 +39,13 @@ The value of B must be between zero and EVP_PKEY_asn1_get_count() EVP_PKEY_asn1_find() looks up the B with NID B. -If B isn't B, then it will look up an engine implementing a -B for the NID B and return that instead, -and also set B<*pe> to point at the engine that implements it. +If B isn't B, 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 with PEM type string B. -Just like EVP_PKEY_asn1_find(), if B isn't B, then it will -look up an engine implementing a B for the NID -B 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 isn't B, 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 diff --git a/doc/man3/EVP_PKEY_decrypt.pod b/doc/man3/EVP_PKEY_decrypt.pod index 7d6807d68b6..5e624e8c611 100644 --- a/doc/man3/EVP_PKEY_decrypt.pod +++ b/doc/man3/EVP_PKEY_decrypt.pod @@ -80,16 +80,15 @@ Decrypt data using OAEP (for RSA keys): #include 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) diff --git a/doc/man3/EVP_PKEY_derive.pod b/doc/man3/EVP_PKEY_derive.pod index 391d79875ab..792e2bbf4b5 100644 --- a/doc/man3/EVP_PKEY_derive.pod +++ b/doc/man3/EVP_PKEY_derive.pod @@ -81,13 +81,12 @@ Derive shared secret (for example DH or EC keys): #include 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) diff --git a/doc/man3/EVP_PKEY_encrypt.pod b/doc/man3/EVP_PKEY_encrypt.pod index c5d91e1c18b..1fb41f99f42 100644 --- a/doc/man3/EVP_PKEY_encrypt.pod +++ b/doc/man3/EVP_PKEY_encrypt.pod @@ -52,24 +52,21 @@ algorithm. =head1 EXAMPLES Encrypt data using OAEP (for RSA keys). See also L or -L for means to load a public key. You may also simply -set 'eng = NULL;' to start with the default OpenSSL RSA implementation: +L for means to load a public key. #include #include - #include 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, -L, L, L, L, diff --git a/doc/man3/EVP_PKEY_get_default_digest_nid.pod b/doc/man3/EVP_PKEY_get_default_digest_nid.pod index e22a3e7b471..726d129b52e 100644 --- a/doc/man3/EVP_PKEY_get_default_digest_nid.pod +++ b/doc/man3/EVP_PKEY_get_default_digest_nid.pod @@ -27,8 +27,7 @@ I. Note that some signature algorithms (i.e. Ed25519 and Ed448) do not use a digest during signing. In this case I will be set to NID_undef. This function is only reliable for legacy keys, which are keys with a B; these keys have typically -been loaded from engines, or created with L or -similar. +been created with L or similar. =head1 NOTES diff --git a/doc/man3/EVP_PKEY_keygen.pod b/doc/man3/EVP_PKEY_keygen.pod index 9cdea5b3622..82bfa5cad62 100644 --- a/doc/man3/EVP_PKEY_keygen.pod +++ b/doc/man3/EVP_PKEY_keygen.pod @@ -177,11 +177,10 @@ Generate a key from a set of parameters: #include 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) diff --git a/doc/man3/EVP_PKEY_new.pod b/doc/man3/EVP_PKEY_new.pod index 0a56600c2b6..a7a1777c2e9 100644 --- a/doc/man3/EVP_PKEY_new.pod +++ b/doc/man3/EVP_PKEY_new.pod @@ -63,7 +63,7 @@ B 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) or Bs. +providers through L. Conceptually, an B 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. -EVP_PKEY_dup() duplicates the I. The I must not be ENGINE based or -a raw key, otherwise the duplication will fail. +EVP_PKEY_dup() duplicates the I. The I must not be a raw key, +otherwise the duplication will fail. EVP_PKEY_free() decrements the reference count of I and, if the reference count is zero, frees it up. If I is NULL, nothing is done. -EVP_PKEY_new_raw_private_key_ex() allocates a new B. Unless an -engine should be used for the key type, a provider for the key is found using -the library context I and the property query string I. The -I 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. A provider for +the key is found using the library context I and the property query +string I. The I 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, C, C, @@ -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 is non-NULL then the new -B structure is associated with the engine I. The I 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, -B, B or B. +default property query are used instead. I B be NULL. The I +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, B, B or B. 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 diff --git a/doc/man3/EVP_PKEY_sign.pod b/doc/man3/EVP_PKEY_sign.pod index 300f77889fd..852da754e8b 100644 --- a/doc/man3/EVP_PKEY_sign.pod +++ b/doc/man3/EVP_PKEY_sign.pod @@ -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. * 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) diff --git a/doc/man3/EVP_PKEY_verify.pod b/doc/man3/EVP_PKEY_verify.pod index c0a097031a0..07f152ce463 100644 --- a/doc/man3/EVP_PKEY_verify.pod +++ b/doc/man3/EVP_PKEY_verify.pod @@ -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. * 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) diff --git a/doc/man3/EVP_PKEY_verify_recover.pod b/doc/man3/EVP_PKEY_verify_recover.pod index d859f68a465..10084d61c1a 100644 --- a/doc/man3/EVP_PKEY_verify_recover.pod +++ b/doc/man3/EVP_PKEY_verify_recover.pod @@ -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) diff --git a/doc/man3/EVP_SignInit.pod b/doc/man3/EVP_SignInit.pod index 553ce0e3477..4c3c15b7d07 100644 --- a/doc/man3/EVP_SignInit.pod +++ b/doc/man3/EVP_SignInit.pod @@ -25,7 +25,7 @@ The EVP signature routines are a high-level interface to digital signatures. EVP_SignInit_ex() sets up signing context I to use digest -I from B I. I must be created with +I. I B be NULL. I must be created with EVP_MD_CTX_new() before calling this function. EVP_SignUpdate() hashes I bytes of data at I into the diff --git a/doc/man3/EVP_VerifyInit.pod b/doc/man3/EVP_VerifyInit.pod index 04598046712..f242cceaf24 100644 --- a/doc/man3/EVP_VerifyInit.pod +++ b/doc/man3/EVP_VerifyInit.pod @@ -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 to use digest -I from ENGINE I. I must be created by calling -EVP_MD_CTX_new() before calling this function. +I. I B be created by calling EVP_MD_CTX_new() before calling +this function. I B be NULL. EVP_VerifyUpdate() hashes I bytes of data at I into the verification context I. 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 diff --git a/doc/man3/HMAC.pod b/doc/man3/HMAC.pod index ebe69d2db9d..53a3853eb2b 100644 --- a/doc/man3/HMAC.pod +++ b/doc/man3/HMAC.pod @@ -95,9 +95,9 @@ stored in memory: HMAC_Init_ex() initializes or reuses a B structure to use the hash function I and key I. If both are NULL, or if I is NULL and I is the same as the previous call, then the -existing key is -reused. I must have been created with HMAC_CTX_new() before the first use -of an B in this function. +existing key is reused. I must have been created with HMAC_CTX_new() +before the first use of an B in this function. I B +be NULL. If HMAC_Init_ex() is called with I NULL and I is not the same as the previous digest used by I then an error is returned diff --git a/doc/man3/OPENSSL_config.pod b/doc/man3/OPENSSL_config.pod index 60f1c5a6582..08827e98b7e 100644 --- a/doc/man3/OPENSSL_config.pod +++ b/doc/man3/OPENSSL_config.pod @@ -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 diff --git a/doc/man3/OPENSSL_init_crypto.pod b/doc/man3/OPENSSL_init_crypto.pod index 03cda784963..3ef6aba822a 100644 --- a/doc/man3/OPENSSL_init_crypto.pod +++ b/doc/man3/OPENSSL_init_crypto.pod @@ -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, B, +B, B, +B, B, +B OPENSSL_init_crypto() I were removed in +OpenSSL 4.0. + +B is defined to 0 since OpenSSL 4.0. + =head1 COPYRIGHT Copyright 2016-2024 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man3/OPENSSL_load_builtin_modules.pod b/doc/man3/OPENSSL_load_builtin_modules.pod index 126ef8331a2..90f6a92237a 100644 --- a/doc/man3/OPENSSL_load_builtin_modules.pod +++ b/doc/man3/OPENSSL_load_builtin_modules.pod @@ -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, L -=head1 HISTORY - -ENGINE_add_conf_module() was deprecated in OpenSSL 3.0. - =head1 COPYRIGHT Copyright 2004-2020 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man3/OSSL_STORE_LOADER.pod b/doc/man3/OSSL_STORE_LOADER.pod index ed64c930ca6..f88c15a8440 100644 --- a/doc/man3/OSSL_STORE_LOADER.pod +++ b/doc/man3/OSSL_STORE_LOADER.pod @@ -156,7 +156,7 @@ L. =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. @@ -270,10 +270,9 @@ It returns 1 on success and 0 on error. =back OSSL_STORE_LOADER_new() creates a new B. -It takes an B I and a string I. -I must I be set. -Both I and I are used as is and must therefore be alive as -long as the created loader is. +It takes a string I. I must I be set. +I B be NULL. I 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. diff --git a/doc/man3/OSSL_trace_enabled.pod b/doc/man3/OSSL_trace_enabled.pod index 273d7da799a..7ecb376b7cc 100644 --- a/doc/man3/OSSL_trace_enabled.pod +++ b/doc/man3/OSSL_trace_enabled.pod @@ -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 below), these functions are used to generate free text tracing output. diff --git a/doc/man3/OpenSSL_version.pod b/doc/man3/OpenSSL_version.pod index a795518f85b..d978eb35ee6 100644 --- a/doc/man3/OpenSSL_version.pod +++ b/doc/man3/OpenSSL_version.pod @@ -181,7 +181,7 @@ OpenSSL configuration files. =item OPENSSL_INFO_MODULES_DIR The configured C, 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 The macros and functions described here were added in OpenSSL 3.0, except for OPENSSL_VERSION_NUMBER and OpenSSL_version_num(). -The B setting of the library is no longer supported -since OpenSSL 4.0. - The B and B strings are no longer supported and, for compatibility reasons, will always return values indicating that engine support was disabled. +The B and B strings +were removed since OpenSSL 4.0. + +The B 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 diff --git a/doc/man3/RAND_set_rand_method.pod b/doc/man3/RAND_set_rand_method.pod index 0cd5ac41cee..33f27d3f1f1 100644 --- a/doc/man3/RAND_set_rand_method.pod +++ b/doc/man3/RAND_set_rand_method.pod @@ -30,12 +30,8 @@ generation. RAND_OpenSSL() returns the default B implementation by OpenSSL. This implementation ensures that the PRNG state is unique for each thread. -If an B 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 the method for PRNG use. If an -ENGINE was providing the method, it will be released first. +RAND_set_rand_method() makes B the method for PRNG use. RAND_get_rand_method() returns a pointer to the current B. @@ -66,7 +62,6 @@ methods. L, L, L, -L, L, L diff --git a/doc/man3/RSA_check_key.pod b/doc/man3/RSA_check_key.pod index a9e3d36aa67..25686c95b8f 100644 --- a/doc/man3/RSA_check_key.pod +++ b/doc/man3/RSA_check_key.pod @@ -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. -=head1 NOTES - -Unlike most other RSA functions, this function does B 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 -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 diff --git a/doc/man3/RSA_set_method.pod b/doc/man3/RSA_set_method.pod index 21cfeed27b4..cee191a6cd4 100644 --- a/doc/man3/RSA_set_method.pod +++ b/doc/man3/RSA_set_method.pod @@ -35,47 +35,37 @@ Applications should instead use the OSSL_PROVIDER APIs. An B 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 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 the default method for all RSA structures created later. -B: 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: 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 to perform all operations using the key -B. 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. 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. -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 that are set for B's current RSA_METHOD. See the BUGS section. -RSA_new_method() allocates and initializes an RSA structure so that -B will be used for the RSA operations. If B 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 must be NULL and the RSA_METHOD controlled by RSA_set_default_method() +is used. RSA_flags() returns the B that are set for B'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 +that was replaced. The return type may be replaced with a B 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 diff --git a/doc/man3/SSL_CTX_set_mode.pod b/doc/man3/SSL_CTX_set_mode.pod index 325e086c548..a7707b33917 100644 --- a/doc/man3/SSL_CTX_set_mode.pod +++ b/doc/man3/SSL_CTX_set_mode.pod @@ -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. =item SSL_MODE_DTLS_SCTP_LABEL_LENGTH_BUG diff --git a/doc/man3/SSL_CTX_set_split_send_fragment.pod b/doc/man3/SSL_CTX_set_split_send_fragment.pod index 8f92ec1ec76..22433e5e37c 100644 --- a/doc/man3/SSL_CTX_set_split_send_fragment.pod +++ b/doc/man3/SSL_CTX_set_split_send_fragment.pod @@ -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 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 diff --git a/doc/man3/SSL_CTX_use_certificate.pod b/doc/man3/SSL_CTX_use_certificate.pod index 2a9227c2ae5..3d5049c2863 100644 --- a/doc/man3/SSL_CTX_use_certificate.pod +++ b/doc/man3/SSL_CTX_use_certificate.pod @@ -106,8 +106,8 @@ key of the X.509 certificate B. If the B argument is 0, then B, B and B are set only if all were not previously set. If B is non-0, then the certificate, private key and chain certs are always set. If B is NULL, then the public key of B 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 =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 diff --git a/doc/man3/SSL_get_all_async_fds.pod b/doc/man3/SSL_get_all_async_fds.pod index 82749249ea6..e5323fe2538 100644 --- a/doc/man3/SSL_get_all_async_fds.pod +++ b/doc/man3/SSL_get_all_async_fds.pod @@ -33,7 +33,7 @@ from the file descriptor). This function should only be called if the B object is currently waiting for asynchronous work to complete (i.e. B has been received - see L). 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 parameter may be NULL in which case no file descriptors are returned but I<*numfds> is still populated. It is the callers diff --git a/doc/man3/SSL_get_error.pod b/doc/man3/SSL_get_error.pod index 794598facb3..a599a9eee68 100644 --- a/doc/man3/SSL_get_error.pod +++ b/doc/man3/SSL_get_error.pod @@ -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 or L 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 or L. The TLS/SSL I/O diff --git a/doc/man3/SSL_set_async_callback.pod b/doc/man3/SSL_set_async_callback.pod index db858a00ce5..6f4c21eccb9 100644 --- a/doc/man3/SSL_set_async_callback.pod +++ b/doc/man3/SSL_set_async_callback.pod @@ -26,26 +26,26 @@ SSL_async_callback_fn =head1 DESCRIPTION SSL_CTX_set_async_callback() sets an asynchronous callback function. All B -objects generated based on this B will get this callback. If an engine -supports the callback mechanism, it will be automatically called if -B 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 will get this callback. If a +provider supports the callback mechanism, it will be automatically called if +B 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 object, so that when an engine completes a cryptography +asynchronous B 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 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 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 and makes an asynchronous SSL call +Application sets B 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 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 diff --git a/doc/man5/config.pod b/doc/man5/config.pod index 7a8480bd102..36159c7820c 100644 --- a/doc/man5/config.pod +++ b/doc/man5/config.pod @@ -191,7 +191,6 @@ will be allowed but the desired configuration will B 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 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 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 - -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 - -This loads and adds an ENGINE from the given path. It is equivalent to -sending the ctrls B with the path argument followed by B -with value B<2> and B 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 - -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 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 - -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 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 in the initialization section names the section @@ -548,11 +481,6 @@ F. The path to the config file, or the empty string for none. Ignored in set-user-ID and set-group-ID programs. -=item B - -The path to the engines directory. -Ignored in set-user-ID and set-group-ID programs. - =item B 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 parameter was removed in OpenSSL 4.0. + =head1 SEE ALSO L, L, L, diff --git a/doc/man7/EVP_PKEY-HMAC.pod b/doc/man7/EVP_PKEY-HMAC.pod index 84b647e5305..eafc5aec1e0 100644 --- a/doc/man7/EVP_PKEY-HMAC.pod +++ b/doc/man7/EVP_PKEY-HMAC.pod @@ -46,10 +46,6 @@ supports the following parameters. The name of a cipher to be used when generating the MAC. -=item "engine" (B) - -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, L, L +=head1 HISTORY + +The CMAC parameter I (B) 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 diff --git a/doc/man7/evp.pod b/doc/man7/evp.pod index 9e0dc58e851..80d9db633a8 100644 --- a/doc/man7/evp.pod +++ b/doc/man7/evp.pod @@ -66,19 +66,16 @@ The LI|EVP_EncodeInit(3)> and LI|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 @@ -102,11 +99,10 @@ L, L, L, L, -L =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 diff --git a/doc/man7/fips_module.pod b/doc/man7/fips_module.pod index f32c65081e1..d42acaba45c 100644 --- a/doc/man7/fips_module.pod +++ b/doc/man7/fips_module.pod @@ -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.) diff --git a/doc/man7/openssl-env.pod b/doc/man7/openssl-env.pod index 541edc27f0b..de0545d5b45 100644 --- a/doc/man7/openssl-env.pod +++ b/doc/man7/openssl-env.pod @@ -77,12 +77,6 @@ than 1, outputs information about every processed feature. This variable is not considered security-sensitive. -=item B - -Specifies the directory from which dynamic engines are loaded. - -This variable is considered a security-sensitive environment variable. - =item B, B, B If built with debugging, this allows memory allocation to fail. @@ -152,7 +146,7 @@ Traces CMP client and server activity. =item B -Show details about provider and engine configuration. +Show details about provider configuration. =item B @@ -319,6 +313,11 @@ under test output with the output for the TAP consumer. This variable was not considered security-sensitive. +=item B + +This variable, support for which was removed in OpenSSL 4.0, specified the +directory from which dynamic engines were loaded. + =back =head1 COPYRIGHT diff --git a/doc/man7/ossl_store.pod b/doc/man7/ossl_store.pod index d6fdae8f22b..5e16a10f2f9 100644 --- a/doc/man7/ossl_store.pod +++ b/doc/man7/ossl_store.pod @@ -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. See L for more information. diff --git a/doc/perlvars.pm b/doc/perlvars.pm index d4443f13c7c..ae3dfad5457 100644 --- a/doc/perlvars.pm +++ b/doc/perlvars.pm @@ -115,19 +115,6 @@ $OpenSSL::safe::opt_config_item = "" . "\n" . "See L."; -# 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]\n"; - $OpenSSL::safe::opt_engine_item = "" - . "=item B<-engine> I\n" - . "\n" - . "See L.\n" - . "This option is deprecated."; -} - # Trusted certs options $OpenSSL::safe::opt_trust_synopsis = "" . "[B<-CAfile> I]\n"