diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 4d4226b22719..24388e91bebf 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..017d4f0b491e 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'); -}