From 64fec4e0fe21625eea457e83d8565add4b97edf6 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Sun, 15 Nov 2026 16:34:54 +0000 Subject: [PATCH 1/2] 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 --- doc/api/crypto.md | 10 +++++++ doc/api/deprecations.md | 26 +++++++++++------ lib/crypto.js | 14 +++------- lib/internal/crypto/hash.js | 26 ++++++++++++----- test/parallel/test-crypto-dep0181.js | 19 ------------- .../test-crypto-hash-hmac-constructor.js | 28 +++++++++++++++++++ test/parallel/test-crypto-hash.js | 18 ------------ 7 files changed, 79 insertions(+), 62 deletions(-) delete mode 100644 test/parallel/test-crypto-dep0181.js create mode 100644 test/parallel/test-crypto-hash-hmac-constructor.js diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 4d4226b22719..eeabeac594ee 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -1882,6 +1882,11 @@ console.log(aliceSecret === bobSecret); * Extends: {stream.Transform} @@ -2096,6 +2101,11 @@ This can be called many times with new data as it is streamed. * Extends: {stream.Transform} diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index fc333e937d6b..80309ec3b09b 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -4031,6 +4031,9 @@ npx codemod@latest @nodejs/dirent-path-to-parent-path -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. -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 401343650e5c..8c2fe29642a6 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 d0d780ee4071..35d57e2ae634 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 ed7dfa93469f..000000000000 --- 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 000000000000..9054d2f6a918 --- /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 7039b2c75d5c..8e5f0eb47fa3 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'); -} From 391630a15d1ab7bd9ba86d8324f03eebecef27aa Mon Sep 17 00:00:00 2001 From: James M Snell Date: Sun, 15 Nov 2026 08:37:56 -0800 Subject: [PATCH 2/2] Apply batched suggestions from code review Co-authored-by: James M Snell --- doc/api/crypto.md | 4 ++-- doc/api/deprecations.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/api/crypto.md b/doc/api/crypto.md index eeabeac594ee..24388e91bebf 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -1884,7 +1884,7 @@ console.log(aliceSecret === bobSecret); added: v0.1.92 changes: - version: REPLACEME - pr-url: https://github.com/nodejs/node/pull/00000 + pr-url: https://github.com/nodejs/node/pull/67490 description: Calling the `Hash` constructor directly now throws an `ERR_ILLEGAL_CONSTRUCTOR` error. --> @@ -2103,7 +2103,7 @@ This can be called many times with new data as it is streamed. added: v0.1.94 changes: - version: REPLACEME - pr-url: https://github.com/nodejs/node/pull/00000 + pr-url: https://github.com/nodejs/node/pull/67490 description: Calling the `Hmac` constructor directly now throws an `ERR_ILLEGAL_CONSTRUCTOR` error. --> diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 80309ec3b09b..017d4f0b491e 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -4032,7 +4032,7 @@ npx codemod@latest @nodejs/dirent-path-to-parent-path