crypto,https,tls: runtime-deprecate OpenSSL engine-based APIs (DEP0183)

Signed-off-by: Filip Skokan <panva.ip@gmail.com>
PR-URL: #63966
Reviewed-By: Richard Lau <richard.lau@ibm.com>
Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

Author: panva

doc/api/crypto.md

@@ -6086,18 +6086,24 @@ added: v15.6.0
 <!-- YAML
 added: v0.11.11
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/63966
+    description: Runtime deprecation.
   - version:
     - v22.4.0
     - v20.16.0
     pr-url: https://github.com/nodejs/node/pull/53329
     description: Custom engine support in OpenSSL 3 is deprecated.
 -->
 
+> Stability: 0 - 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.
+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.
 

doc/api/deprecations.md

@@ -4058,14 +4058,17 @@ 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/63966
+    description: Runtime deprecation.
   - version:
     - v22.4.0
     - v20.16.0
     pr-url: https://github.com/nodejs/node/pull/53329
     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

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/63966
+    description: The `clientCertEngine` option is runtime deprecated.
   - version:
     - v22.4.0
     - v20.16.0

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/63966
+    description: The `clientCertEngine`, `privateKeyEngine` and
+                 `privateKeyIdentifier` options are runtime deprecated.
   - version: REPLACEME
     pr-url: https://github.com/nodejs/node/pull/62217
     description: The `certificateCompression` option has been added.
@@ -2113,6 +2117,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/63966
+    description: The `clientCertEngine` option is runtime deprecated.
   - version:
     - v22.4.0
     - v20.16.0

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,

lib/internal/tls/secure-context.js

@@ -33,6 +33,7 @@ const {
 } = require('internal/validators');
 
 const {
+  emitOpenSSLEngineDeprecation,
   toBuf,
 } = require('internal/crypto/util');
 
@@ -271,6 +272,7 @@ function configSecureContext(context, options = kEmptyObject, name = 'options')
 
     if (typeof privateKeyIdentifier === 'string' &&
         typeof privateKeyEngine === 'string') {
+      emitOpenSSLEngineDeprecation();
       if (context.setEngineKey)
         context.setEngineKey(privateKeyIdentifier, privateKeyEngine);
       else
@@ -332,6 +334,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

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,

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,

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';
+  },
+);

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');