FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

crypto: deprecate implicitly shortened GCM tags · nodejs/node@8f61b65 · GitHub

/ node Public

Commit 8f61b65

Browse files
tniessen
authored
crypto: deprecate implicitly shortened GCM tags
This introduces a doc-only deprecation of using GCM authentication tags that are shorter than the cipher's block size, unless the user specified the authTagLength option. Refs: #52327 PR-URL: #52345 Reviewed-By: Filip Skokan <panva.ip@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>
1 parent c82f3c9 commit 8f61b65

6 files changed

Lines changed: 107 additions & 2 deletions

File tree

‎doc/api/crypto.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -891,6 +891,11 @@ When passing a string as the `buffer`, please consider
891891
<!-- YAML
892892
added: v1.0.0
893893
changes:
894+
- version: REPLACEME
895+
pr-url: https://github.com/nodejs/node/pull/52345
896+
description: Using GCM tag lengths other than 128 bits without specifying
897+
the `authTagLength` option when creating `decipher` is
898+
deprecated.
894899
- version: v15.0.0
895900
pr-url: https://github.com/nodejs/node/pull/35093
896901
description: The buffer argument can be a string or ArrayBuffer and is

‎doc/api/deprecations.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3619,6 +3619,25 @@ Calling `Hmac` class directly with `Hmac()` or `new Hmac()` is
36193619
deprecated due to being internals, not intended for public use.
36203620
Please use the [`crypto.createHmac()`][] method to create Hmac instances.
36213621

3622+
### DEP0182: Short GCM authentication tags without explicit `authTagLength`
3623+
3624+
<!-- YAML
3625+
changes:
3626+
- version: REPLACEME
3627+
pr-url: https://github.com/nodejs/node/pull/52345
3628+
description: Documentation-only deprecation.
3629+
-->
3630+
3631+
Type: Documentation-only (supports [`--pending-deprecation`][])
3632+
3633+
Applications that intend to use authentication tags that are shorter than the
3634+
default authentication tag length should set the `authTagLength` option of the
3635+
[`crypto.createDecipheriv()`][] function to the appropriate length.
3636+
3637+
For ciphers in GCM mode, the [`decipher.setAuthTag()`][] function accepts
3638+
authentication tags of any valid length (see [DEP0090](#DEP0090)). This behavior
3639+
is deprecated to better align with recommendations per [NIST SP 800-38D][].
3640+
36223641
[NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
36233642
[RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3
36243643
[RFC 8247 Section 2.4]: https://www.rfc-editor.org/rfc/rfc8247#section-2.4

‎src/crypto/crypto_cipher.cc‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -697,6 +697,19 @@ void CipherBase::SetAuthTag(const FunctionCallbackInfo<Value>& args) {
697697
env, "Invalid authentication tag length: %u", tag_len);
698698
}
699699

700+
if (mode == EVP_CIPH_GCM_MODE && cipher->auth_tag_len_ == kNoAuthTagLength &&
701+
tag_len != 16 && env->options()->pending_deprecation &&
702+
env->EmitProcessEnvWarning()) {
703+
if (ProcessEmitDeprecationWarning(
704+
env,
705+
"Using AES-GCM authentication tags of less than 128 bits without "
706+
"specifying the authTagLength option when initializing decryption "
707+
"is deprecated.",
708+
"DEP0182")
709+
.IsNothing())
710+
return;
711+
}
712+
700713
cipher->auth_tag_len_ = tag_len;
701714
cipher->auth_tag_state_ = kAuthTagKnown;
702715
CHECK_LE(cipher->auth_tag_len_, sizeof(cipher->auth_tag_));

‎test/common/index.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -659,12 +659,12 @@ function _expectWarning(name, expected, code) {
659659
expected = [[expected, code]];
660660
} else if (!Array.isArray(expected)) {
661661
expected = Object.entries(expected).map(([a, b]) => [b, a]);
662-
} else if (!(Array.isArray(expected[0]))) {
662+
} else if (expected.length !== 0 && !Array.isArray(expected[0])) {
663663
expected = [[expected[0], expected[1]]];
664664
}
665665
// Deprecation codes are mandatory, everything else is not.
666666
if (name === 'DeprecationWarning') {
667-
expected.forEach(([_, code]) => assert(code, expected));
667+
expected.forEach(([_, code]) => assert(code, `Missing deprecation code: ${expected}`));
668668
}
669669
return mustCall((warning) => {
670670
const expectedProperties = expected.shift();

‎test/parallel/test-crypto-gcm-explicit-short-tag.js‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
// Flags: --pending-deprecation
2+
'use strict';
3+
4+
const common = require('../common');
5+
if (!common.hasCrypto)
6+
common.skip('missing crypto');
7+
8+
const assert = require('assert');
9+
const { createDecipheriv, randomBytes } = require('crypto');
10+
11+
common.expectWarning({
12+
DeprecationWarning: []
13+
});
14+
15+
const key = randomBytes(32);
16+
const iv = randomBytes(16);
17+
18+
{
19+
// Full 128-bit tag.
20+
21+
const tag = randomBytes(16);
22+
createDecipheriv('aes-256-gcm', key, iv).setAuthTag(tag);
23+
}
24+
25+
{
26+
// Shortened tag with explicit length option.
27+
28+
const tag = randomBytes(12);
29+
createDecipheriv('aes-256-gcm', key, iv, {
30+
authTagLength: tag.byteLength
31+
}).setAuthTag(tag);
32+
}
33+
34+
{
35+
// Shortened tag with explicit but incorrect length option.
36+
37+
const tag = randomBytes(12);
38+
assert.throws(() => {
39+
createDecipheriv('aes-256-gcm', key, iv, {
40+
authTagLength: 14
41+
}).setAuthTag(tag);
42+
}, {
43+
name: 'TypeError',
44+
message: 'Invalid authentication tag length: 12',
45+
code: 'ERR_CRYPTO_INVALID_AUTH_TAG'
46+
});
47+
}

‎test/parallel/test-crypto-gcm-implicit-short-tag.js‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
// Flags: --pending-deprecation
2+
'use strict';
3+
const common = require('../common');
4+
if (!common.hasCrypto)
5+
common.skip('missing crypto');
6+
7+
const { createDecipheriv, randomBytes } = require('crypto');
8+
9+
common.expectWarning({
10+
DeprecationWarning: [
11+
['Using AES-GCM authentication tags of less than 128 bits without ' +
12+
'specifying the authTagLength option when initializing decryption is ' +
13+
'deprecated.',
14+
'DEP0182'],
15+
]
16+
});
17+
18+
const key = randomBytes(32);
19+
const iv = randomBytes(16);
20+
const tag = randomBytes(12);
21+
createDecipheriv('aes-256-gcm', key, iv).setAuthTag(tag);

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL