crypto: deprecate useless authentication tag APIs

[tniessen]

These APIs were probably exposed by accident (maybe Cipher and Decipher had the same prototype at some point?). getAuthTag and setAuthTag are not a usual getter/setter pair: Getting the authentication tag only makes sense in the context of encryption, setting it only makes sense in the context of encryption. Currently, both functions throw. Neither has been documented publicly.

It seems appropriate to skip a documentation-only deprecation here since the functions have never been documented, at least not on these classes, and using them will only throw an error. The deprecation warning is triggered on property access, not just when calling the function, to make sure that people don't rely on the mere existence of the functions.

cc @nodejs/crypto @nodejs/security @nodejs/tsc

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

[nodejs-github-bot]

@tniessen build started: https://ci.nodejs.org/blue/organizations/jenkins/node-test-pull-request-lite-pipeline/detail/node-test-pull-request-lite-pipeline/425/pipeline

[ryzokuken]

LGTM. I wonder how these crept in 😅

[Trott]

@nodejs/security-wg

[tniessen]

Full CI: https://ci.nodejs.org/job/node-test-pull-request/16198/
Resumed: https://ci.nodejs.org/job/node-test-pull-request/16248/

[mcollina]

LGTM

[lirantal]

doesn't look like we'll be breaking major modules, though I was able to find some dependents on it (i.e: https://github.com/garbados/comdb)

[tniessen]

@lirantal Are you sure? Why do you think they depend on these functions?

[lirantal]

I spotted this https://github.com/garbados/comdb/blob/9d36dd730bd70de71ebcb1986db51595f967f786/lib/crypt.js#L77

I did a simple github code search for it and there are a few occurrences but probably not a big deal.

[tniessen]

@lirantal There are two getAuthTag functions and two setAuthTag functions, and one of each is useless. Those are the ones that will be deprecated by this PR. The other two are perfectly fine and it would indeed be a big deal to deprecate them, and there is no reason to do so.

[lirantal]

@tniessen wasn't very clear on that, thanks.

[ChALkeR]

499263  ssh2-streams-0.2.1.tgz/lib/ssh.js:4731:    instance.setAuthTag(data);
499263  ssh2-streams-0.2.1.tgz/lib/ssh.js:5348:      var authTag = encrypter.getAuthTag();
94592   passport-azure-ad-3.0.12.tgz/lib/cookieContentHandler.js:136:  var authTag = cipher.getAuthTag().toString('hex');
94592   passport-azure-ad-3.0.12.tgz/lib/cookieContentHandler.js:151:  decipher.setAuthTag(authTag);
94592   passport-azure-ad-3.0.12.tgz/lib/jwe.js:404:      decipher.setAuthTag(authTag);
80158   node-jose-1.0.0.tgz/lib/algorithms/aes-gcm.js:184:    var tag = cipher.getAuthTag();
80158   node-jose-1.0.0.tgz/lib/algorithms/aes-gcm.js:333:    cipher.setAuthTag(tag);
41405   http_ece-1.0.5.tgz/ece.js:338:  gcm.setAuthTag(buffer.slice(buffer.length - TAG_LENGTH));
41405   http_ece-1.0.5.tgz/ece.js:424:  var tag = gcm.getAuthTag();
31213   openpgp-3.1.0.tgz/src/crypto/gcm.js:84:        const ct = Buffer.concat([en.update(pt), en.final(), en.getAuthTag()]); // append auth tag to ciphertext
31213   openpgp-3.1.0.tgz/src/crypto/gcm.js:94:        de.setAuthTag(ct.slice(ct.length - tagLength, ct.length)); // read auth tag at end of ciphertext
14050   encrypted-attr-1.1.0.tgz/lib/encrypted-attr.js:45:           gcm.getAuthTag().toString('base64').slice(0, 22)
14050   encrypted-attr-1.1.0.tgz/lib/encrypted-attr.js:86:    gcm.setAuthTag(tag)
…

Are those going to be affected?

Some of those (if not all) might be using cipher-base/browserify-aes (or similar) though, which also define those methods.

[tniessen]

@ChALkeR The functions which will be deprecated by this PR will throw every time they are called, so it is unlikely that someone uses them (for legitimate reasons). The occurrences you listed should be unaffected.

[tniessen]

Rebased, old HEAD was e1d76163029d403aeddb83c38883c730675a906f.

[tniessen]

Landed in 34f56e2, 39dd3a4.