doc: doc-only deprecate OpenSSL engine-based APIs

OpenSSL 3 deprecated support for custom engines with a recommendation
to switch to its new provider model.
PR-URL: #53329
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Mohammed Keyvanzadeh <mohammadkeyvanzade94@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>

Author: richardlau

doc/api/crypto.md

@@ -5270,12 +5270,17 @@ added: v15.6.0
 
 <!-- YAML
 added: v0.11.11
+changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/53329
+ description: Custom engine support in OpenSSL 3 is deprecated.
 -->
 
 *`engine` {string}
 *`flags` {crypto.constants} **Default:**`crypto.constants.ENGINE_METHOD_ALL`
 
 Load and set the `engine` for some or all OpenSSL functions (selected by flags).
+Support for custom engines in OpenSSL is deprecated from OpenSSL 3.
 
 `engine` could be either an id or a path to the engine's shared library.
 

doc/api/deprecations.md

@@ -3638,6 +3638,23 @@ For ciphers in GCM mode, the [`decipher.setAuthTag()`][] function accepts
 authentication tags of any valid length (see [DEP0090](#DEP0090)). This behavior
 is deprecated to better align with recommendations per [NIST SP 800-38D][].
 
+### DEP0183: OpenSSL engine-based APIs
+
+<!-- YAML
+changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/53329
+ description: Documentation-only deprecation.
+-->
+
+Type: Documentation-only
+
+OpenSSL 3 has deprecated support for custom engines with a recommendation to
+switch to its new provider model. The `clientCertEngine` option for
+`https.request()`, [`tls.createSecureContext()`][], and [`tls.createServer()`][];
+the `privateKeyEngine` and `privateKeyIdentifier` for [`tls.createSecureContext()`][];
+and [`crypto.setEngine()`][] all depend on this functionality from OpenSSL.
+
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
 [RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3
 [RFC 8247 Section 2.4]: https://www.rfc-editor.org/rfc/rfc8247#section-2.4
@@ -3680,6 +3697,7 @@ is deprecated to better align with recommendations per [NIST SP 800-38D][].
 [`crypto.pbkdf2()`]: crypto.md#cryptopbkdf2password-salt-iterations-keylen-digest-callback
 [`crypto.randomBytes()`]: crypto.md#cryptorandombytessize-callback
 [`crypto.scrypt()`]: crypto.md#cryptoscryptpassword-salt-keylen-options-callback
+[`crypto.setEngine()`]: crypto.md#cryptosetengineengine-flags
 [`decipher.final()`]: crypto.md#decipherfinaloutputencoding
 [`decipher.setAuthTag()`]: crypto.md#deciphersetauthtagbuffer-encoding
 [`diagnostics_channel.subscribe(name, onMessage)`]: diagnostics_channel.md#diagnostics_channelsubscribename-onmessage
@@ -3758,6 +3776,7 @@ is deprecated to better align with recommendations per [NIST SP 800-38D][].
 [`tls.TLSSocket`]: tls.md#class-tlstlssocket
 [`tls.checkServerIdentity()`]: tls.md#tlscheckserveridentityhostname-cert
 [`tls.createSecureContext()`]: tls.md#tlscreatesecurecontextoptions
+[`tls.createServer()`]: tls.md#tlscreateserveroptions-secureconnectionlistener
 [`url.format()`]: url.md#urlformaturlobject
 [`url.parse()`]: url.md#urlparseurlstring-parsequerystring-slashesdenotehost
 [`url.resolve()`]: url.md#urlresolvefrom-to

doc/api/https.md

@@ -342,6 +342,10 @@ a `timeout` of 5 seconds.
 <!-- YAML
 added: v0.3.6
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/53329
+ description: The `clientCertEngine` option depends on custom engine
+ support in OpenSSL which is deprecated in OpenSSL 3.
  - version:
  - v16.7.0
  - v14.18.0
@@ -377,7 +381,7 @@ changes:
 Makes a request to a secure web server.
 
 The following additional `options` from [`tls.connect()`][] are also accepted:
-`ca`, `cert`, `ciphers`, `clientCertEngine`, `crl`, `dhparam`, `ecdhCurve`,
+`ca`, `cert`, `ciphers`, `clientCertEngine` (deprecated), `crl`, `dhparam`, `ecdhCurve`,
 `honorCipherOrder`, `key`, `passphrase`, `pfx`, `rejectUnauthorized`,
 `secureOptions`, `secureProtocol`, `servername`, `sessionIdContext`,
 `highWaterMark`.

doc/api/tls.md

@@ -1799,6 +1799,11 @@ argument.
 <!-- YAML
 added: v0.11.13
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/53329
+ description: The `clientCertEngine`, `privateKeyEngine` and
+ `privateKeyIdentifier` options depend on custom engine
+ support in OpenSSL which is deprecated in OpenSSL 3.
  - version:
  - v19.8.0
  - v18.16.0
@@ -1886,7 +1891,7 @@ changes:
  ciphers can be obtained via [`tls.getCiphers()`][]. Cipher names must be
  uppercased in order for OpenSSL to accept them.
 *`clientCertEngine` {string} Name of an OpenSSL engine which can provide the
- client certificate.
+ client certificate.**Deprecated.**
 *`crl` {string|string\[]|Buffer|Buffer\[]} PEM formatted CRLs (Certificate
  Revocation Lists).
 *`dhparam` {string|Buffer} `'auto'` or custom Diffie-Hellman parameters,
@@ -1914,11 +1919,11 @@ changes:
  decrypted with `object.passphrase` if provided, or `options.passphrase` if
  it is not.
 *`privateKeyEngine` {string} Name of an OpenSSL engine to get private key
- from. Should be used together with `privateKeyIdentifier`.
+ from. Should be used together with `privateKeyIdentifier`.**Deprecated.**
 *`privateKeyIdentifier` {string} Identifier of a private key managed by
  an OpenSSL engine. Should be used together with `privateKeyEngine`.
  Should not be set together with `key`, because both options define a
- private key in different ways.
+ private key in different ways.**Deprecated.**
 *`maxVersion` {string} Optionally set the maximum TLS version to allow. One
  of `'TLSv1.3'`, `'TLSv1.2'`, `'TLSv1.1'`, or `'TLSv1'`. Cannot be specified
  along with the `secureProtocol` option; use one or the other.
@@ -2055,6 +2060,10 @@ where `secureSocket` has the same API as `pair.cleartext`.
 <!-- YAML
 added: v0.3.2
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/53329
+ description: The `clientCertEngine` option depends on custom engine
+ support in OpenSSL which is deprecated in OpenSSL 3.
  - version:
  - v20.4.0
  - v18.19.0
@@ -2102,7 +2111,7 @@ changes:
  protocols, an error will be thrown. This option cannot be used with the
 `ALPNProtocols` option, and setting both options will throw an error.
 *`clientCertEngine` {string} Name of an OpenSSL engine which can provide the
- client certificate.
+ client certificate.**Deprecated.**
 *`enableTrace` {boolean} If `true`, [`tls.TLSSocket.enableTrace()`][] will be
  called on new connections. Tracing can be enabled after the secure
  connection is established, but this option must be used to trace the secure