crypto: deprecate Decipher.finaltol

PR-URL: https://github.com/nodejs/node/pull/19353
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>

doc/api/deprecations.md

@@ -950,6 +950,15 @@ deprecated if the assigned value is not a string, boolean, or number. In the
 future, such assignment may result in a thrown error. Please convert the
 property to a string before assigning it to `process.env`.
 
+<a id="DEP0105"></a>
+### DEP0105: decipher.finaltol
+
+Type: Runtime
+
+`decipher.finaltol()` has never been documented and is currently an alias for
+[`decipher.final()`][]. In the future, this API will likely be removed, and it
+is recommended to use [`decipher.final()`][] instead.
+
 [`--pending-deprecation`]: cli.html#cli_pending_deprecation
 [`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size
 [`Buffer.from(array)`]: buffer.html#buffer_class_method_buffer_from_array
@@ -971,6 +980,7 @@ property to a string before assigning it to `process.env`.
 [`crypto.DEFAULT_ENCODING`]: crypto.html#crypto_crypto_default_encoding
 [`crypto.fips`]: crypto.html#crypto_crypto_fips
 [`crypto.pbkdf2()`]: crypto.html#crypto_crypto_pbkdf2_password_salt_iterations_keylen_digest_callback
+[`decipher.final()`]: crypto.html#crypto_decipher_final_outputencoding
 [`decipher.setAuthTag()`]: crypto.html#crypto_decipher_setauthtag_buffer
 [`domain`]: domain.html
 [`ecdh.setPublicKey()`]: crypto.html#crypto_ecdh_setpublickey_publickey_encoding

lib/internal/crypto/cipher.js

@@ -30,7 +30,7 @@ const LazyTransform = require('internal/streams/lazy_transform');
 const { StringDecoder } = require('string_decoder');
 
 const { inherits } = require('util');
-const { normalizeEncoding } = require('internal/util');
+const { deprecate, normalizeEncoding } = require('internal/util');
 
 function rsaPublic(method, defaultPadding) {
   return function(options, buffer) {
@@ -217,6 +217,10 @@ Cipheriv.prototype.setAuthTag = Cipher.prototype.setAuthTag;
 Cipheriv.prototype.setAAD = Cipher.prototype.setAAD;
 
 
+const finaltol = deprecate(Cipher.prototype.final,
+                           'crypto.Decipher.finaltol is deprecated. Use ' +
+                           'crypto.Decipher.final instead.', 'DEP0105');
+
 function Decipher(cipher, password, options) {
   if (!(this instanceof Decipher))
     return new Decipher(cipher, password, options);
@@ -245,7 +249,7 @@ Decipher.prototype._transform = Cipher.prototype._transform;
 Decipher.prototype._flush = Cipher.prototype._flush;
 Decipher.prototype.update = Cipher.prototype.update;
 Decipher.prototype.final = Cipher.prototype.final;
-Decipher.prototype.finaltol = Cipher.prototype.final;
+Decipher.prototype.finaltol = finaltol;
 Decipher.prototype.setAutoPadding = Cipher.prototype.setAutoPadding;
 Decipher.prototype.getAuthTag = Cipher.prototype.getAuthTag;
 Decipher.prototype.setAuthTag = Cipher.prototype.setAuthTag;
@@ -288,7 +292,7 @@ Decipheriv.prototype._transform = Cipher.prototype._transform;
 Decipheriv.prototype._flush = Cipher.prototype._flush;
 Decipheriv.prototype.update = Cipher.prototype.update;
 Decipheriv.prototype.final = Cipher.prototype.final;
-Decipheriv.prototype.finaltol = Cipher.prototype.final;
+Decipheriv.prototype.finaltol = finaltol;
 Decipheriv.prototype.setAutoPadding = Cipher.prototype.setAutoPadding;
 Decipheriv.prototype.getAuthTag = Cipher.prototype.getAuthTag;
 Decipheriv.prototype.setAuthTag = Cipher.prototype.setAuthTag;

test/parallel/test-crypto-deprecated.js

@@ -9,7 +9,9 @@ const tls = require('tls');
 
 common.expectWarning('DeprecationWarning', [
   'crypto.Credentials is deprecated. Use tls.SecureContext instead.',
-  'crypto.createCredentials is deprecated. Use tls.createSecureContext instead.'
+  'crypto.createCredentials is deprecated. Use tls.createSecureContext ' +
+  'instead.',
+  'crypto.Decipher.finaltol is deprecated. Use crypto.Decipher.final instead.'
 ]);
 
 // Accessing the deprecated function is enough to trigger the warning event.
@@ -18,3 +20,15 @@ common.expectWarning('DeprecationWarning', [
 // mapped to the correct non-deprecated function.
 assert.strictEqual(crypto.Credentials, tls.SecureContext);
 assert.strictEqual(crypto.createCredentials, tls.createSecureContext);
+
+{
+  const cipher = crypto.createCipheriv('aes-128-cbc', '0000000000000000',
+                                       '0000000000000000');
+  const ciphertext = cipher.update('Node.js', 'utf8', 'hex') +
+                     cipher.final('hex');
+  const decipher = crypto.createDecipheriv('aes-128-cbc', '0000000000000000',
+                                           '0000000000000000');
+  const plaintext = decipher.update(ciphertext, 'hex', 'utf8') +
+                    decipher.finaltol('utf8');
+  assert.strictEqual(plaintext, 'Node.js');
+}