crypto: deprecate useless authentication tag APIs

doc/api/deprecations.md

@@ -1021,6 +1021,16 @@ accessed outside of Node.js core: `Socket.prototype._handle`,
 `Socket.prototype._healthCheck()`, `Socket.prototype._stopReceiving()`, and
 `dgram._createSocketHandle()`.
 
+<a id="DEP00XX"></a>
+### DEP00XX: Cipher.setAuthTag(), Decipher.getAuthTag()
+
+Type: Runtime
+
+With the current crypto API, having `Cipher.setAuthTag()` and
+`Decipher.getAuthTag()` is not helpful and both functions will throw an error
+when called. They have never been documented and will be removed in a future
+release.
+
 [`--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

lib/internal/crypto/cipher.js

@@ -31,7 +31,7 @@ const assert = require('assert');
 const LazyTransform = require('internal/streams/lazy_transform');
 
 const { inherits } = require('util');
-const { normalizeEncoding } = require('internal/util');
+const { deprecate, normalizeEncoding } = require('internal/util');
 
 // Lazy loaded for startup performance.
 let StringDecoder;
@@ -194,7 +194,7 @@ Cipher.prototype.getAuthTag = function getAuthTag() {
 };
 
 
-Cipher.prototype.setAuthTag = function setAuthTag(tagbuf) {
+function setAuthTag(tagbuf) {
   if (!isArrayBufferView(tagbuf)) {
     throw new ERR_INVALID_ARG_TYPE('buffer',
                                    ['Buffer', 'TypedArray', 'DataView'],
@@ -203,7 +203,14 @@ Cipher.prototype.setAuthTag = function setAuthTag(tagbuf) {
   if (!this._handle.setAuthTag(tagbuf))
     throw new ERR_CRYPTO_INVALID_STATE('setAuthTag');
   return this;
-};
+}
+
+Object.defineProperty(Cipher.prototype, 'setAuthTag', {
+  get: deprecate(() => setAuthTag,
+                 'Cipher.setAuthTag is deprecated and will be removed in a ' +
+                 'future version of Node.js.',
+                 'DEP00XX')
+});
 
 Cipher.prototype.setAAD = function setAAD(aadbuf, options) {
   if (!isArrayBufferView(aadbuf)) {
@@ -231,8 +238,23 @@ function addCipherPrototypeFunctions(constructor) {
   constructor.prototype.update = Cipher.prototype.update;
   constructor.prototype.final = Cipher.prototype.final;
   constructor.prototype.setAutoPadding = Cipher.prototype.setAutoPadding;
-  constructor.prototype.getAuthTag = Cipher.prototype.getAuthTag;
-  constructor.prototype.setAuthTag = Cipher.prototype.setAuthTag;
+  if (constructor === Cipheriv) {
+    constructor.prototype.getAuthTag = Cipher.prototype.getAuthTag;
+    Object.defineProperty(constructor.prototype, 'setAuthTag', {
+      get: deprecate(() => setAuthTag,
+                     'Cipher.setAuthTag is deprecated and will be removed in ' +
+                     'a future version of Node.js.',
+                     'DEP00XX')
+    });
+  } else {
+    constructor.prototype.setAuthTag = setAuthTag;
+    Object.defineProperty(constructor.prototype, 'getAuthTag', {
+      get: deprecate(() => constructor.prototype.getAuthTag,
+                     'Decipher.getAuthTag is deprecated and will be removed ' +
+                     'in a future version of Node.js.',
+                     'DEP00XX')
+    });
+  }
   constructor.prototype.setAAD = Cipher.prototype.setAAD;
 }
 

test/parallel/test-crypto-authenticated.js

@@ -207,27 +207,6 @@ for (const test of TEST_CASES) {
     assert.throws(function() { encrypt.getAuthTag(); }, errMessages.state);
   }
 
-  {
-    // trying to set tag on encryption object:
-    const encrypt = crypto.createCipheriv(test.algo,
-                                          Buffer.from(test.key, 'hex'),
-                                          Buffer.from(test.iv, 'hex'),
-                                          options);
-    assert.throws(() => { encrypt.setAuthTag(Buffer.from(test.tag, 'hex')); },
-                  errMessages.state);
-  }
-
-  {
-    if (!isCCM || !common.hasFipsCrypto) {
-      // trying to read tag from decryption object:
-      const decrypt = crypto.createDecipheriv(test.algo,
-                                              Buffer.from(test.key, 'hex'),
-                                              Buffer.from(test.iv, 'hex'),
-                                              options);
-      assert.throws(function() { decrypt.getAuthTag(); }, errMessages.state);
-    }
-  }
-
   {
     // trying to create cipher with incorrect IV length
     assert.throws(function() {

test/parallel/test-crypto-cipher-decipher.js

@@ -112,15 +112,6 @@ testCipher2(Buffer.from('0123456789abcdef'));
                'TypedArray, or DataView. Received type object'
     });
 
-  common.expectsError(
-    () => crypto.createCipher('aes-256-cbc', 'secret').setAuthTag(null),
-    {
-      code: 'ERR_INVALID_ARG_TYPE',
-      type: TypeError,
-      message: 'The "buffer" argument must be one of type Buffer, ' +
-               'TypedArray, or DataView. Received type object'
-    });
-
   common.expectsError(
     () => crypto.createCipher('aes-256-cbc', 'secret').setAAD(null),
     {
@@ -146,6 +137,15 @@ testCipher2(Buffer.from('0123456789abcdef'));
                'Received type object'
     });
 
+  common.expectsError(
+    () => crypto.createDecipher('aes-256-cbc', 'secret').setAuthTag(null),
+    {
+      code: 'ERR_INVALID_ARG_TYPE',
+      type: TypeError,
+      message: 'The "buffer" argument must be one of type Buffer, ' +
+               'TypedArray, or DataView. Received type object'
+    });
+
   common.expectsError(
     () => crypto.createDecipher('aes-256-cbc', null),
     {