Commit 6c835918fbf for nodejs
commit 6c835918fbf81e6995ec29f4c14576dd9af432e0
Author: James M Snell <jasnell@gmail.com>
Date: Tue Nov 17 08:40:55 2026 -0800
crypto: move DEP0179 and DEP0181 to End-of-Life
Calling the Hash or Hmac constructors directly, with or without new,
now throws ERR_ILLEGAL_CONSTRUCTOR. Instances must be created with
crypto.createHash() and crypto.createHmac().
The classes remain exported from node:crypto so that instanceof checks
continue to work. Internally, instances are constructed through a
private symbol, and the createHash() and createHmac() factories now
live alongside the classes in internal/crypto/hash.
Both have been runtime deprecations since v22.0.0.
Refs: https://github.com/nodejs/node/pull/51880
Refs: https://github.com/nodejs/node/pull/52071
Assisted-by: Claude
Signed-off-by: James M Snell <jasnell@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/67490
Reviewed-By: Filip Skokan <panva.ip@gmail.com>
Reviewed-By: Tim Perry <pimterry@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 4d4226b2271..24388e91beb 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -1882,6 +1882,11 @@ console.log(aliceSecret === bobSecret);
<!-- YAML
added: v0.1.92
+changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/67490
+ description: Calling the `Hash` constructor directly now throws an
+ `ERR_ILLEGAL_CONSTRUCTOR` error.
-->
* Extends: {stream.Transform}
@@ -2096,6 +2101,11 @@ This can be called many times with new data as it is streamed.
<!-- YAML
added: v0.1.94
+changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/67490
+ description: Calling the `Hmac` constructor directly now throws an
+ `ERR_ILLEGAL_CONSTRUCTOR` error.
-->
* Extends: {stream.Transform}
diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
index b31bfffc11b..f5fce8865a2 100644
--- a/doc/api/deprecations.md
+++ b/doc/api/deprecations.md
@@ -4031,6 +4031,9 @@ npx codemod@latest @nodejs/dirent-path-to-parent-path
<!-- YAML
changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/67490
+ description: End-of-Life.
- version: v22.0.0
pr-url: https://github.com/nodejs/node/pull/51880
description: Runtime deprecation.
@@ -4041,11 +4044,13 @@ changes:
description: Documentation-only deprecation.
-->
-Type: Runtime
+Type: End-of-Life
-Calling `Hash` class directly with `Hash()` or `new Hash()` is
-deprecated due to being internals, not intended for public use.
-Please use the [`crypto.createHash()`][] method to create Hash instances.
+Calling `Hash` class directly with `Hash()` or `new Hash()` throws an
+`ERR_ILLEGAL_CONSTRUCTOR` error. The constructor is internal and not intended
+for public use. Use the [`crypto.createHash()`][] method to create Hash
+instances. The class remains exported, so `instanceof crypto.Hash` checks
+continue to work.
### DEP0180: `fs.Stats` constructor
@@ -4068,6 +4073,9 @@ deprecated due to being internals, not intended for public use.
<!-- YAML
changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/67490
+ description: End-of-Life.
- version: v22.0.0
pr-url: https://github.com/nodejs/node/pull/52071
description: Runtime deprecation.
@@ -4076,11 +4084,13 @@ changes:
description: Documentation-only deprecation.
-->
-Type: Runtime
+Type: End-of-Life
-Calling `Hmac` class directly with `Hmac()` or `new Hmac()` is
-deprecated due to being internals, not intended for public use.
-Please use the [`crypto.createHmac()`][] method to create Hmac instances.
+Calling `Hmac` class directly with `Hmac()` or `new Hmac()` throws an
+`ERR_ILLEGAL_CONSTRUCTOR` error. The constructor is internal and not intended
+for public use. Use the [`crypto.createHmac()`][] method to create Hmac
+instances. The class remains exported, so `instanceof crypto.Hmac` checks
+continue to work.
### DEP0182: Short GCM authentication tags without explicit `authTagLength`
diff --git a/lib/crypto.js b/lib/crypto.js
index 401343650e5..8c2fe29642a 100644
--- a/lib/crypto.js
+++ b/lib/crypto.js
@@ -111,6 +111,8 @@ const {
const {
Hash,
Hmac,
+ createHash,
+ createHmac,
hash,
} = require('internal/crypto/hash');
const {
@@ -160,10 +162,6 @@ function lazyOwnsProcessState() {
// These helper functions are needed because the constructors can
// use new, in which case V8 cannot inline the recursive constructor call
-function createHash(algorithm, options) {
- return new Hash(algorithm, options);
-}
-
function createCipheriv(cipher, key, iv, options) {
return new Cipheriv(cipher, key, iv, options);
}
@@ -184,10 +182,6 @@ function createECDH(curve) {
return new ECDH(curve);
}
-function createHmac(hmac, key, options) {
- return new Hmac(hmac, key, options);
-}
-
function createMac(algorithm, key, options) {
return new Mac(algorithm, key, options);
}
@@ -267,8 +261,8 @@ module.exports = {
DiffieHellman,
DiffieHellmanGroup,
ECDH,
- Hash: deprecate(Hash, 'crypto.Hash constructor is deprecated.', 'DEP0179'),
- Hmac: deprecate(Hmac, 'crypto.Hmac constructor is deprecated.', 'DEP0181'),
+ Hash,
+ Hmac,
KeyObject,
Sign,
Verify,
diff --git a/lib/internal/crypto/hash.js b/lib/internal/crypto/hash.js
index d0d780ee407..35d57e2ae63 100644
--- a/lib/internal/crypto/hash.js
+++ b/lib/internal/crypto/hash.js
@@ -50,6 +50,7 @@ const {
codes: {
ERR_CRYPTO_HASH_FINALIZED,
ERR_CRYPTO_HASH_UPDATE_FAILED,
+ ERR_ILLEGAL_CONSTRUCTOR,
ERR_INVALID_ARG_TYPE,
ERR_INVALID_ARG_VALUE,
ERR_UNKNOWN_ENCODING,
@@ -71,6 +72,7 @@ const LazyTransform = require('internal/streams/lazy_transform');
const kState = Symbol('kState');
const kFinalized = Symbol('kFinalized');
+const kPrivateConstructor = Symbol('kPrivateConstructor');
const emitHmacDigestDeprecation = getDeprecationWarningEmitter(
'DEP0206',
@@ -88,9 +90,9 @@ function normalizeCShakeParameter(value, name) {
return value;
}
-function Hash(algorithm, options) {
- if (!new.target)
- return new Hash(algorithm, options);
+function Hash(privateSymbol, algorithm, options) {
+ if (privateSymbol !== kPrivateConstructor)
+ throw new ERR_ILLEGAL_CONSTRUCTOR();
const isCopy = algorithm instanceof _Hash;
if (!isCopy)
validateString(algorithm, 'algorithm');
@@ -145,7 +147,7 @@ Hash.prototype.copy = function copy(options) {
if (state[kFinalized])
throw new ERR_CRYPTO_HASH_FINALIZED();
- return new Hash(this[kHandle], options);
+ return new Hash(kPrivateConstructor, this[kHandle], options);
};
Hash.prototype._transform = function _transform(chunk, encoding, callback) {
@@ -198,9 +200,9 @@ Hash.prototype.digest = function digest(outputEncoding) {
return ret;
};
-function Hmac(hmac, key, options) {
- if (!(this instanceof Hmac))
- return new Hmac(hmac, key, options);
+function Hmac(privateSymbol, hmac, key, options) {
+ if (privateSymbol !== kPrivateConstructor)
+ throw new ERR_ILLEGAL_CONSTRUCTOR();
validateString(hmac, 'hmac');
const encoding = getStringOption(options, 'encoding');
key = prepareSecretKey(key, encoding);
@@ -241,6 +243,14 @@ Hmac.prototype._flush = function _flush(callback) {
};
Hmac.prototype._transform = Hash.prototype._transform;
+function createHash(algorithm, options) {
+ return new Hash(kPrivateConstructor, algorithm, options);
+}
+
+function createHmac(hmac, key, options) {
+ return new Hmac(kPrivateConstructor, hmac, key, options);
+}
+
// Implementation for WebCrypto subtle.digest()
function asyncDigest(algorithm, data) {
@@ -382,5 +392,7 @@ module.exports = {
Hash,
Hmac,
asyncDigest,
+ createHash,
+ createHmac,
hash,
};
diff --git a/test/parallel/test-crypto-dep0181.js b/test/parallel/test-crypto-dep0181.js
deleted file mode 100644
index ed7dfa93469..00000000000
--- a/test/parallel/test-crypto-dep0181.js
+++ /dev/null
@@ -1,19 +0,0 @@
-'use strict';
-
-const common = require('../common');
-if (!common.hasCrypto)
- common.skip('missing crypto');
-
-const assert = require('assert');
-const crypto = require('crypto');
-
-common.expectWarning({
- DeprecationWarning: {
- DEP0181: 'crypto.Hmac constructor is deprecated.',
- },
-});
-
-const Hmac = crypto.Hmac;
-const instance = crypto.Hmac('sha256', '0123456789abcdef');
-assert(instance instanceof Hmac, 'Hmac is expected to return a new instance' +
- ' when called without `new`');
diff --git a/test/parallel/test-crypto-hash-hmac-constructor.js b/test/parallel/test-crypto-hash-hmac-constructor.js
new file mode 100644
index 00000000000..9054d2f6a91
--- /dev/null
+++ b/test/parallel/test-crypto-hash-hmac-constructor.js
@@ -0,0 +1,28 @@
+'use strict';
+
+const common = require('../common');
+if (!common.hasCrypto)
+ common.skip('missing crypto');
+
+const assert = require('assert');
+const crypto = require('crypto');
+
+// The Hash and Hmac constructors are not intended for public use. Instances
+// must be created with crypto.createHash() and crypto.createHmac().
+const illegalConstructor = {
+ code: 'ERR_ILLEGAL_CONSTRUCTOR',
+ name: 'TypeError',
+};
+
+assert.throws(() => crypto.Hash('sha256'), illegalConstructor);
+assert.throws(() => new crypto.Hash('sha256'), illegalConstructor);
+assert.throws(() => crypto.Hmac('sha256', 'key'), illegalConstructor);
+assert.throws(() => new crypto.Hmac('sha256', 'key'), illegalConstructor);
+
+// The classes remain exported so that instanceof checks keep working.
+{
+ const hash = crypto.createHash('sha256');
+ assert(hash instanceof crypto.Hash);
+ assert(hash.copy() instanceof crypto.Hash);
+ assert(crypto.createHmac('sha256', 'key') instanceof crypto.Hmac);
+}
diff --git a/test/parallel/test-crypto-hash.js b/test/parallel/test-crypto-hash.js
index 7039b2c75d5..8e5f0eb47fa 100644
--- a/test/parallel/test-crypto-hash.js
+++ b/test/parallel/test-crypto-hash.js
@@ -6,13 +6,6 @@ if (!common.hasCrypto) {
common.skip('missing crypto');
}
-common.expectWarning({
- DeprecationWarning: [
- ['crypto.Hash constructor is deprecated.',
- 'DEP0179'],
- ]
-});
-
const assert = require('assert');
const crypto = require('crypto');
const fs = require('fs');
@@ -183,13 +176,6 @@ assert.throws(
}
);
-{
- const Hash = crypto.Hash;
- const instance = crypto.Hash('sha256');
- assert(instance instanceof Hash, 'Hash is expected to return a new instance' +
- ' when called without `new`');
-}
-
// Test XOF hash functions and the outputLength option.
if (!isBoringSSL) {
const invalidXofLength = {
@@ -301,7 +287,3 @@ if (!isBoringSSL) {
assert.strictEqual(a.digest('hex'), b.digest('hex'));
assert.strictEqual(c.digest('hex'), d.digest('hex'));
}
-
-{
- crypto.Hash('sha256');
-}