From df4762722c6f9f052ee28dd587620ffcdc803206 Mon Sep 17 00:00:00 2001
From: Richard Lau <rlau@redhat.com>
Date: Fri, 7 Jun 2024 17:10:47 +0100
Subject: [PATCH] doc: doc-only deprecate OpenSSL engine-based APIs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

OpenSSL 3 deprecated support for custom engines with a recommendation
to switch to its new provider model.

PR-URL: https://github.com/nodejs/node/pull/53329
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Mohammed Keyvanzadeh <mohammadkeyvanzade94@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
---
 doc/api/crypto.md       |  5 +++++
 doc/api/deprecations.md | 19 +++++++++++++++++++
 doc/api/https.md        |  6 +++++-
 doc/api/tls.md          | 17 +++++++++++++----
 4 files changed, 42 insertions(+), 5 deletions(-)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 758a04584c4a0e..429703660f6d5e 100644
--- a/doc/api/crypto.md
+++ b/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.
 
diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
index b409d52dbf5654..d9aba0ed7b0c81 100644
--- a/doc/api/deprecations.md
+++ b/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
diff --git a/doc/api/https.md b/doc/api/https.md
index c3dfe3466643e7..a10c08dc75900b 100644
--- a/doc/api/https.md
+++ b/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`.
diff --git a/doc/api/tls.md b/doc/api/tls.md
index d39daa684f2a0b..ed9c3a489be847 100644
--- a/doc/api/tls.md
+++ b/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