From 6a9bb91648c2f26586e8f817c6e84832c84b7360 Mon Sep 17 00:00:00 2001
From: Filip Skokan <panva.ip@gmail.com>
Date: Wed, 17 Jun 2026 16:48:54 +0200
Subject: [PATCH 1/4] crypto,https,tls: runtime-deprecate OpenSSL engine-based
 APIs (DEP0183)

Signed-off-by: Filip Skokan <panva.ip@gmail.com>
---
 doc/api/crypto.md                             |  6 ++++-
 doc/api/deprecations.md                       |  5 ++++-
 doc/api/https.md                              |  3 +++
 doc/api/tls.md                                |  7 ++++++
 lib/internal/crypto/util.js                   |  9 ++++++++
 lib/internal/tls/secure-context.js            |  3 +++
 .../addons/openssl-client-cert-engine/test.js |  6 +++++
 test/addons/openssl-key-engine/test.js        |  6 +++++
 test/parallel/test-crypto-dep0183.js          | 22 +++++++++++++++++++
 .../test-tls-clientcertengine-unsupported.js  |  9 ++++++++
 test/parallel/test-tls-error-stack.js         |  6 +++++
 .../test-tls-keyengine-unsupported.js         |  9 ++++++++
 12 files changed, 89 insertions(+), 2 deletions(-)
 create mode 100644 test/parallel/test-crypto-dep0183.js

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 00a77f38a6d3b3..57bd2c70f114f1 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -6057,6 +6057,9 @@ added: v15.6.0
 <!-- YAML
 added: v0.11.11
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/XXXX
+    description: Runtime deprecation.
   - version:
     - v22.4.0
     - v20.16.0
@@ -6068,7 +6071,8 @@ changes:
 * `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.
+Use of this API is deprecated because custom engine support has been deprecated
+since 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 77f15f9b8dd002..20627a8fbc92a9 100644
--- a/doc/api/deprecations.md
+++ b/doc/api/deprecations.md
@@ -4058,6 +4058,9 @@ that are shorter than the default authentication tag length (i.e., shorter than
 
 <!-- YAML
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/XXXX
+    description: Runtime deprecation.
   - version:
     - v22.4.0
     - v20.16.0
@@ -4065,7 +4068,7 @@ changes:
     description: Documentation-only deprecation.
 -->
 
-Type: Documentation-only
+Type: Runtime
 
 OpenSSL 3 has deprecated support for custom engines with a recommendation to
 switch to its new provider model. The `clientCertEngine` option for
diff --git a/doc/api/https.md b/doc/api/https.md
index 85e6a77c7ff262..b5f6c3c5d8ce2a 100644
--- a/doc/api/https.md
+++ b/doc/api/https.md
@@ -423,6 +423,9 @@ a `timeout` of 5 seconds.
 <!-- YAML
 added: v0.3.6
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/XXXX
+    description: The `clientCertEngine` option is runtime deprecated.
   - version:
     - v22.4.0
     - v20.16.0
diff --git a/doc/api/tls.md b/doc/api/tls.md
index a1a8c98d987784..936a5735427a55 100644
--- a/doc/api/tls.md
+++ b/doc/api/tls.md
@@ -1895,6 +1895,10 @@ argument.
 <!-- YAML
 added: v0.11.13
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/XXXX
+    description: The `clientCertEngine`, `privateKeyEngine` and
+                 `privateKeyIdentifier` options are runtime deprecated.
   - version:
     - v22.9.0
     - v20.18.0
@@ -2104,6 +2108,9 @@ permissible, use 2048 bits or larger for stronger security.
 <!-- YAML
 added: v0.3.2
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/XXXX
+    description: The `clientCertEngine` option is runtime deprecated.
   - version:
     - v22.4.0
     - v20.16.0
diff --git a/lib/internal/crypto/util.js b/lib/internal/crypto/util.js
index 74d86de3f1b9e1..993acdb86718f7 100644
--- a/lib/internal/crypto/util.js
+++ b/lib/internal/crypto/util.js
@@ -78,6 +78,7 @@ const {
   cachedResult,
   emitExperimentalWarning,
   filterDuplicateStrings,
+  getDeprecationWarningEmitter,
   lazyDOMException,
   setOwnProperty,
 } = require('internal/util');
@@ -131,6 +132,11 @@ const getCiphers = cachedResult(() => filterDuplicateStrings(_getCiphers()));
 const getHashes = cachedResult(() => filterDuplicateStrings(_getHashes()));
 const getCurves = cachedResult(() => filterDuplicateStrings(_getCurves()));
 
+const emitOpenSSLEngineDeprecation = getDeprecationWarningEmitter(
+  'DEP0183',
+  'OpenSSL engine-based APIs are deprecated.',
+);
+
 function setEngine(id, flags) {
   validateString(id, 'id');
   if (flags)
@@ -141,6 +147,8 @@ function setEngine(id, flags) {
   if (flags === 0)
     flags = ENGINE_METHOD_ALL;
 
+  emitOpenSSLEngineDeprecation();
+
   if (typeof _setEngine !== 'function')
     throw new ERR_CRYPTO_CUSTOM_ENGINE_NOT_SUPPORTED();
   if (!_setEngine(id, flags))
@@ -955,6 +963,7 @@ module.exports = {
   getCurves,
   getDataViewOrTypedArrayBuffer,
   getHashes,
+  emitOpenSSLEngineDeprecation,
   kHandle,
   setEngine,
   toBuf,
diff --git a/lib/internal/tls/secure-context.js b/lib/internal/tls/secure-context.js
index 84e74105fdbba9..200101c0bcd2ea 100644
--- a/lib/internal/tls/secure-context.js
+++ b/lib/internal/tls/secure-context.js
@@ -33,6 +33,7 @@ const {
 } = require('internal/validators');
 
 const {
+  emitOpenSSLEngineDeprecation,
   toBuf,
 } = require('internal/crypto/util');
 
@@ -233,6 +234,7 @@ function configSecureContext(context, options = kEmptyObject, name = 'options')
 
     if (typeof privateKeyIdentifier === 'string' &&
         typeof privateKeyEngine === 'string') {
+      emitOpenSSLEngineDeprecation();
       if (context.setEngineKey)
         context.setEngineKey(privateKeyIdentifier, privateKeyEngine);
       else
@@ -294,6 +296,7 @@ function configSecureContext(context, options = kEmptyObject, name = 'options')
   }
 
   if (typeof clientCertEngine === 'string') {
+    emitOpenSSLEngineDeprecation();
     if (typeof context.setClientCertEngine !== 'function')
       throw new ERR_CRYPTO_CUSTOM_ENGINE_NOT_SUPPORTED();
     else
diff --git a/test/addons/openssl-client-cert-engine/test.js b/test/addons/openssl-client-cert-engine/test.js
index 648600c99cd852..4f7c7d7ac0f1fe 100644
--- a/test/addons/openssl-client-cert-engine/test.js
+++ b/test/addons/openssl-client-cert-engine/test.js
@@ -21,6 +21,12 @@ const agentKey = fs.readFileSync(fixture.path('/keys/agent1-key.pem'));
 const agentCert = fs.readFileSync(fixture.path('/keys/agent1-cert.pem'));
 const agentCa = fs.readFileSync(fixture.path('/keys/ca1-cert.pem'));
 
+common.expectWarning({
+  DeprecationWarning: {
+    DEP0183: 'OpenSSL engine-based APIs are deprecated.',
+  },
+});
+
 const serverOptions = {
   key: agentKey,
   cert: agentCert,
diff --git a/test/addons/openssl-key-engine/test.js b/test/addons/openssl-key-engine/test.js
index 58885e46728788..92b7bb558ad752 100644
--- a/test/addons/openssl-key-engine/test.js
+++ b/test/addons/openssl-key-engine/test.js
@@ -21,6 +21,12 @@ const agentKey = fs.readFileSync(fixture.path('/keys/agent1-key.pem'));
 const agentCert = fs.readFileSync(fixture.path('/keys/agent1-cert.pem'));
 const agentCa = fs.readFileSync(fixture.path('/keys/ca1-cert.pem'));
 
+common.expectWarning({
+  DeprecationWarning: {
+    DEP0183: 'OpenSSL engine-based APIs are deprecated.',
+  },
+});
+
 const serverOptions = {
   key: agentKey,
   cert: agentCert,
diff --git a/test/parallel/test-crypto-dep0183.js b/test/parallel/test-crypto-dep0183.js
new file mode 100644
index 00000000000000..c0b9a8e9f6797a
--- /dev/null
+++ b/test/parallel/test-crypto-dep0183.js
@@ -0,0 +1,22 @@
+'use strict';
+
+const common = require('../common');
+if (!common.hasCrypto)
+  common.skip('missing crypto');
+
+const assert = require('assert');
+const crypto = require('crypto');
+
+common.expectWarning({
+  DeprecationWarning: {
+    DEP0183: 'OpenSSL engine-based APIs are deprecated.',
+  },
+});
+
+assert.throws(
+  () => crypto.setEngine('nodejs-test-invalid-engine'),
+  (err) => {
+    return err.code === 'ERR_CRYPTO_CUSTOM_ENGINE_NOT_SUPPORTED' ||
+           err.code === 'ERR_CRYPTO_ENGINE_UNKNOWN';
+  },
+);
diff --git a/test/parallel/test-tls-clientcertengine-unsupported.js b/test/parallel/test-tls-clientcertengine-unsupported.js
index 0d24005dc0a150..aa0bf4a18d6a62 100644
--- a/test/parallel/test-tls-clientcertengine-unsupported.js
+++ b/test/parallel/test-tls-clientcertengine-unsupported.js
@@ -6,6 +6,15 @@ if (!common.hasCrypto)
   common.skip('missing crypto');
 
 const assert = require('assert');
+
+common.expectWarning({
+  'internal/test/binding':
+    'These APIs are for internal testing only. Do not use them.',
+  'DeprecationWarning': {
+    DEP0183: 'OpenSSL engine-based APIs are deprecated.',
+  },
+});
+
 // Monkey-patch SecureContext
 const { internalBinding } = require('internal/test/binding');
 const binding = internalBinding('crypto');
diff --git a/test/parallel/test-tls-error-stack.js b/test/parallel/test-tls-error-stack.js
index 02021b060ecb83..baa2851ee8da23 100644
--- a/test/parallel/test-tls-error-stack.js
+++ b/test/parallel/test-tls-error-stack.js
@@ -8,6 +8,12 @@ if (!common.hasCrypto)
 const assert = require('assert');
 const tls = require('tls');
 
+common.expectWarning({
+  DeprecationWarning: {
+    DEP0183: 'OpenSSL engine-based APIs are deprecated.',
+  },
+});
+
 assert.throws(() => {
   tls.createSecureContext({ clientCertEngine: 'x' });
 }, (err) => {
diff --git a/test/parallel/test-tls-keyengine-unsupported.js b/test/parallel/test-tls-keyengine-unsupported.js
index 5fcfe495d516db..3473fe533f226e 100644
--- a/test/parallel/test-tls-keyengine-unsupported.js
+++ b/test/parallel/test-tls-keyengine-unsupported.js
@@ -6,6 +6,15 @@ if (!common.hasCrypto)
   common.skip('missing crypto');
 
 const assert = require('assert');
+
+common.expectWarning({
+  'internal/test/binding':
+    'These APIs are for internal testing only. Do not use them.',
+  'DeprecationWarning': {
+    DEP0183: 'OpenSSL engine-based APIs are deprecated.',
+  },
+});
+
 // Monkey-patch SecureContext
 const { internalBinding } = require('internal/test/binding');
 const binding = internalBinding('crypto');

From c983e9eff44eb569d0c19759cf793935efb2f9f3 Mon Sep 17 00:00:00 2001
From: Filip Skokan <panva.ip@gmail.com>
Date: Wed, 17 Jun 2026 16:51:54 +0200
Subject: [PATCH 2/4] fixup! crypto,https,tls: runtime-deprecate OpenSSL
 engine-based APIs (DEP0183)

---
 doc/api/crypto.md       | 2 +-
 doc/api/deprecations.md | 2 +-
 doc/api/https.md        | 2 +-
 doc/api/tls.md          | 4 ++--
 4 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 57bd2c70f114f1..b5c94339e75510 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -6058,7 +6058,7 @@ added: v15.6.0
 added: v0.11.11
 changes:
   - version: REPLACEME
-    pr-url: https://github.com/nodejs/node/pull/XXXX
+    pr-url: https://github.com/nodejs/node/pull/63966
     description: Runtime deprecation.
   - version:
     - v22.4.0
diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
index 20627a8fbc92a9..67f6e5f273742b 100644
--- a/doc/api/deprecations.md
+++ b/doc/api/deprecations.md
@@ -4059,7 +4059,7 @@ that are shorter than the default authentication tag length (i.e., shorter than
 <!-- YAML
 changes:
   - version: REPLACEME
-    pr-url: https://github.com/nodejs/node/pull/XXXX
+    pr-url: https://github.com/nodejs/node/pull/63966
     description: Runtime deprecation.
   - version:
     - v22.4.0
diff --git a/doc/api/https.md b/doc/api/https.md
index b5f6c3c5d8ce2a..634bba15d604d2 100644
--- a/doc/api/https.md
+++ b/doc/api/https.md
@@ -424,7 +424,7 @@ a `timeout` of 5 seconds.
 added: v0.3.6
 changes:
   - version: REPLACEME
-    pr-url: https://github.com/nodejs/node/pull/XXXX
+    pr-url: https://github.com/nodejs/node/pull/63966
     description: The `clientCertEngine` option is runtime deprecated.
   - version:
     - v22.4.0
diff --git a/doc/api/tls.md b/doc/api/tls.md
index 936a5735427a55..d07a2bce36624e 100644
--- a/doc/api/tls.md
+++ b/doc/api/tls.md
@@ -1896,7 +1896,7 @@ argument.
 added: v0.11.13
 changes:
   - version: REPLACEME
-    pr-url: https://github.com/nodejs/node/pull/XXXX
+    pr-url: https://github.com/nodejs/node/pull/63966
     description: The `clientCertEngine`, `privateKeyEngine` and
                  `privateKeyIdentifier` options are runtime deprecated.
   - version:
@@ -2109,7 +2109,7 @@ permissible, use 2048 bits or larger for stronger security.
 added: v0.3.2
 changes:
   - version: REPLACEME
-    pr-url: https://github.com/nodejs/node/pull/XXXX
+    pr-url: https://github.com/nodejs/node/pull/63966
     description: The `clientCertEngine` option is runtime deprecated.
   - version:
     - v22.4.0

From cc3cb4f57ab4c0e6ef57444e8a63277a5ab46c88 Mon Sep 17 00:00:00 2001
From: Filip Skokan <panva.ip@gmail.com>
Date: Wed, 17 Jun 2026 17:41:29 +0200
Subject: [PATCH 3/4] fixup! crypto,https,tls: runtime-deprecate OpenSSL
 engine-based APIs (DEP0183)

---
 doc/api/crypto.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index b5c94339e75510..29815b576d55da 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -6067,6 +6067,8 @@ changes:
     description: Custom engine support in OpenSSL 3 is deprecated.
 -->
 
+> Stability: 0 - Deprecated
+
 * `engine` {string}
 * `flags` {crypto.constants} **Default:** `crypto.constants.ENGINE_METHOD_ALL`
 

From 640e80379c33c8b1965ae8bc64d568040a73a1d3 Mon Sep 17 00:00:00 2001
From: Filip Skokan <panva.ip@gmail.com>
Date: Wed, 17 Jun 2026 17:45:02 +0200
Subject: [PATCH 4/4] fixup! crypto,https,tls: runtime-deprecate OpenSSL
 engine-based APIs (DEP0183)

---
 test/parallel/test-tls-error-stack.js | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/test/parallel/test-tls-error-stack.js b/test/parallel/test-tls-error-stack.js
index baa2851ee8da23..0a952a46bdd473 100644
--- a/test/parallel/test-tls-error-stack.js
+++ b/test/parallel/test-tls-error-stack.js
@@ -8,6 +8,10 @@ if (!common.hasCrypto)
 const assert = require('assert');
 const tls = require('tls');
 
+const secureContext = tls.createSecureContext();
+if (typeof secureContext.context.setClientCertEngine !== 'function')
+  common.skip('OpenSSL dropped engine support');
+
 common.expectWarning({
   DeprecationWarning: {
     DEP0183: 'OpenSSL engine-based APIs are deprecated.',
@@ -17,9 +21,6 @@ common.expectWarning({
 assert.throws(() => {
   tls.createSecureContext({ clientCertEngine: 'x' });
 }, (err) => {
-  if (err.code === 'ERR_CRYPTO_CUSTOM_ENGINE_NOT_SUPPORTED')
-    common.skip('OpenSSL dropped engine support');
-
   return err.name === 'Error' &&
          /could not load the shared library/.test(err.message) &&
          Array.isArray(err.opensslErrorStack) &&