diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 2f11a947d0b98e..49afd4e6164d01 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -303,7 +303,7 @@ console.log(cert.verifySpkac(Buffer.from(spkac))); // Prints: true or false ``` -## Class: `Cipher` +## Class: `Cipheriv` * `autoPadding` {boolean} **Default:** `true` -* Returns: {Cipher} The same `Cipher` instance for method chaining. +* Returns: {Cipher} The same `Cipheriv` instance for method chaining. -When using block encryption algorithms, the `Cipher` class will automatically +When using block encryption algorithms, the `Cipheriv` class will automatically add padding to the input data to the appropriate block size. To disable the default padding call `cipher.setAutoPadding(false)`. @@ -635,7 +635,7 @@ The `cipher.update()` method can be called multiple times with new data until [`cipher.final()`][] is called. Calling `cipher.update()` after [`cipher.final()`][] will result in an error being thrown. -## Class: `Decipher` +## Class: `Decipheriv` + +Type: Runtime + +Instantiating the [`Cipheriv`][] and [`Decipheriv`][] classes exported by the `node:crypto` +module is deprecated. + [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf [RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3 [RFC 8247 Section 2.4]: https://www.rfc-editor.org/rfc/rfc8247#section-2.4 @@ -3854,8 +3868,8 @@ deprecated, as their values are guaranteed to be identical to that of `process.f [`Buffer.from(array)`]: buffer.md#static-method-bufferfromarray [`Buffer.from(buffer)`]: buffer.md#static-method-bufferfrombuffer [`Buffer.isBuffer()`]: buffer.md#static-method-bufferisbufferobj -[`Cipher`]: crypto.md#class-cipher -[`Decipher`]: crypto.md#class-decipher +[`Cipheriv`]: crypto.md#class-cipheriv +[`Decipheriv`]: crypto.md#class-decipheriv [`REPLServer.clearBufferedCommand()`]: repl.md#replserverclearbufferedcommand [`ReadStream.open()`]: fs.md#class-fsreadstream [`Server.getConnections()`]: net.md#servergetconnectionscallback diff --git a/lib/crypto.js b/lib/crypto.js index 943f7e49741348..8e0c39f756a72b 100644 --- a/lib/crypto.js +++ b/lib/crypto.js @@ -88,9 +88,7 @@ const { diffieHellman, } = require('internal/crypto/diffiehellman'); const { - Cipher, Cipheriv, - Decipher, Decipheriv, privateDecrypt, privateEncrypt, @@ -224,9 +222,7 @@ module.exports = { // Classes Certificate, - Cipher, Cipheriv, - Decipher, Decipheriv, DiffieHellman, DiffieHellmanGroup, diff --git a/lib/internal/crypto/cipher.js b/lib/internal/crypto/cipher.js index c303e2fa311a0e..8c6ea80e557a38 100644 --- a/lib/internal/crypto/cipher.js +++ b/lib/internal/crypto/cipher.js @@ -58,7 +58,10 @@ const assert = require('internal/assert'); const LazyTransform = require('internal/streams/lazy_transform'); -const { normalizeEncoding } = require('internal/util'); +const { + normalizeEncoding, + deprecateInstantiation, +} = require('internal/util'); const { StringDecoder } = require('string_decoder'); @@ -138,20 +141,12 @@ function createCipherWithIV(cipher, key, options, decipher, iv) { // the Cipher class is defined using the legacy function syntax rather than // ES6 classes. -function Cipher(cipher, password, options) { - if (!(this instanceof Cipher)) - return new Cipher(cipher, password, options); -} - -ObjectSetPrototypeOf(Cipher.prototype, LazyTransform.prototype); -ObjectSetPrototypeOf(Cipher, LazyTransform); - -Cipher.prototype._transform = function _transform(chunk, encoding, callback) { +function _transform(chunk, encoding, callback) { this.push(this[kHandle].update(chunk, encoding)); callback(); }; -Cipher.prototype._flush = function _flush(callback) { +function _flush(callback) { try { this.push(this[kHandle].final()); } catch (e) { @@ -161,7 +156,7 @@ Cipher.prototype._flush = function _flush(callback) { callback(); }; -Cipher.prototype.update = function update(data, inputEncoding, outputEncoding) { +function update(data, inputEncoding, outputEncoding) { if (typeof data === 'string') { validateEncoding(data, inputEncoding); } else if (!isArrayBufferView(data)) { @@ -179,8 +174,7 @@ Cipher.prototype.update = function update(data, inputEncoding, outputEncoding) { return ret; }; - -Cipher.prototype.final = function final(outputEncoding) { +function final(outputEncoding) { const ret = this[kHandle].final(); if (outputEncoding && outputEncoding !== 'buffer') { @@ -191,21 +185,19 @@ Cipher.prototype.final = function final(outputEncoding) { return ret; }; - -Cipher.prototype.setAutoPadding = function setAutoPadding(ap) { +function setAutoPadding(ap) { if (!this[kHandle].setAutoPadding(!!ap)) throw new ERR_CRYPTO_INVALID_STATE('setAutoPadding'); return this; }; -Cipher.prototype.getAuthTag = function getAuthTag() { +function getAuthTag() { const ret = this[kHandle].getAuthTag(); if (ret === undefined) throw new ERR_CRYPTO_INVALID_STATE('getAuthTag'); return ret; }; - function setAuthTag(tagbuf, encoding) { tagbuf = getArrayBufferOrView(tagbuf, 'buffer', encoding); if (!this[kHandle].setAuthTag(tagbuf)) @@ -213,7 +205,7 @@ function setAuthTag(tagbuf, encoding) { return this; } -Cipher.prototype.setAAD = function setAAD(aadbuf, options) { +function setAAD(aadbuf, options) { const encoding = getStringOption(options, 'encoding'); const plaintextLength = getUIntOption(options, 'plaintextLength'); aadbuf = getArrayBufferOrView(aadbuf, 'aadbuf', encoding); @@ -228,52 +220,39 @@ Cipher.prototype.setAAD = function setAAD(aadbuf, options) { // ES6 classes. function Cipheriv(cipher, key, iv, options) { - if (!(this instanceof Cipheriv)) - return new Cipheriv(cipher, key, iv, options); + if (!(this instanceof Cipheriv)) { + return deprecateInstantiation(Cipheriv, 'DEP0190', cipher, key, iv, options); + } ReflectApply(createCipherWithIV, this, [cipher, key, options, true, iv]); } function addCipherPrototypeFunctions(constructor) { - constructor.prototype._transform = Cipher.prototype._transform; - constructor.prototype._flush = Cipher.prototype._flush; - constructor.prototype.update = Cipher.prototype.update; - constructor.prototype.final = Cipher.prototype.final; - constructor.prototype.setAutoPadding = Cipher.prototype.setAutoPadding; + constructor.prototype._transform = _transform; + constructor.prototype._flush = _flush; + constructor.prototype.update = update; + constructor.prototype.final = final; + constructor.prototype.setAutoPadding = setAutoPadding; if (constructor === Cipheriv) { - constructor.prototype.getAuthTag = Cipher.prototype.getAuthTag; + constructor.prototype.getAuthTag = getAuthTag; } else { constructor.prototype.setAuthTag = setAuthTag; } - constructor.prototype.setAAD = Cipher.prototype.setAAD; + constructor.prototype.setAAD = setAAD; } ObjectSetPrototypeOf(Cipheriv.prototype, LazyTransform.prototype); ObjectSetPrototypeOf(Cipheriv, LazyTransform); addCipherPrototypeFunctions(Cipheriv); -// The Decipher class is part of the legacy Node.js crypto API. It exposes -// a stream-based encryption/decryption model. For backwards compatibility -// the Decipher class is defined using the legacy function syntax rather than -// ES6 classes. - -function Decipher(cipher, password, options) { - if (!(this instanceof Decipher)) - return new Decipher(cipher, password, options); -} - -ObjectSetPrototypeOf(Decipher.prototype, LazyTransform.prototype); -ObjectSetPrototypeOf(Decipher, LazyTransform); -addCipherPrototypeFunctions(Decipher); - // The Decipheriv class is part of the legacy Node.js crypto API. It exposes // a stream-based encryption/decryption model. For backwards compatibility // the Decipheriv class is defined using the legacy function syntax rather than // ES6 classes. - function Decipheriv(cipher, key, iv, options) { - if (!(this instanceof Decipheriv)) - return new Decipheriv(cipher, key, iv, options); + if (!(this instanceof Decipheriv)) { + return deprecateInstantiation(Decipheriv, 'DEP0190', cipher, key, iv, options); + } ReflectApply(createCipherWithIV, this, [cipher, key, options, false, iv]); } diff --git a/tools/doc/type-parser.mjs b/tools/doc/type-parser.mjs index 84019d56f73700..a79bf6596def3f 100644 --- a/tools/doc/type-parser.mjs +++ b/tools/doc/type-parser.mjs @@ -75,8 +75,8 @@ const customTypesMap = { 'cluster.Worker': 'cluster.html#class-worker', - 'Cipher': 'crypto.html#class-cipher', - 'Decipher': 'crypto.html#class-decipher', + 'Cipheriv': 'crypto.html#class-cipheriv', + 'Decipheriv': 'crypto.html#class-decipheriv', 'DiffieHellman': 'crypto.html#class-diffiehellman', 'DiffieHellmanGroup': 'crypto.html#class-diffiehellmangroup', 'ECDH': 'crypto.html#class-ecdh',