Commit 08b5347
doc: warn about short GCM tags visibly
As was pointed out by Félix Charette (@Sideni), the existing runtime
deprecation warning may not provide enough visibility of the underlying
issue. This commit adds a (not so pretty) warning to the documentation
of the relevant API function `setAuthTag()`. The warning will be removed
when `DEP0182` will be moved to End-of-Life status, presumably with the
next major release.
Refs: #52327
Refs: #17523
PR-URL: #61082
Reviewed-By: Filip Skokan <panva.ip@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Beth Griggs <bethanyngriggs@gmail.com>1 parent 990da35 commit 08b5347
1 file changed
Lines changed: 16 additions & 1 deletion
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -962,6 +962,15 @@ for `CCM` mode or before [`decipher.final()`][] for `GCM` and `OCB` modes and | |||
| 962 | 962 | `chacha20-poly1305`. | |
| 963 | 963 | `decipher.setAuthTag()` can only be called once. | |
| 964 | 964 | ||
| 965 | + Because the `node:crypto` module was originally designed to closely mirror | ||
| 966 | + OpenSSL's behavior, this function permits short GCM authentication tags unless | ||
| 967 | + an explicit authentication tag length was passed to | ||
| 968 | + [`crypto.createDecipheriv()`][] when the `decipher` object was created. This | ||
| 969 | + behavior is deprecated and subject to change (see [DEP0182][]). <strong class="critical"> | ||
| 970 | + In the meantime, applications should either set the `authTagLength` option when | ||
| 971 | + calling `createDecipheriv()` or check the actual | ||
| 972 | + authentication tag length before passing it to `setAuthTag()`.</strong> | ||
| 973 | + | ||
| 965 | 974 | When passing a string as the authentication tag, please consider | |
| 966 | 975 | [caveats when using strings as inputs to cryptographic APIs][]. | |
| 967 | 976 | ||
@@ -3352,8 +3361,13 @@ The `options` argument controls stream behavior and is optional except when a | |||
| 3352 | 3361 | cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) is used. In that case, the | |
| 3353 | 3362 | `authTagLength` option is required and specifies the length of the | |
| 3354 | 3363 | authentication tag in bytes, see [CCM mode][]. | |
| 3355 | - For AES-GCM and `chacha20-poly1305`, the `authTagLength` option defaults to 16 | ||
| 3364 | + For `chacha20-poly1305`, the `authTagLength` option defaults to 16 | ||
| 3356 | 3365 | bytes and must be set to a different value if a different length is used. | |
| 3366 | + For AES-GCM, the `authTagLength` option has no default value when decrypting, | ||
| 3367 | + and `setAuthTag()` will accept arbitrarily short authentication tags. This | ||
| 3368 | + behavior is deprecated and subject to change (see [DEP0182][]). <strong class="critical"> | ||
| 3369 | + In the meantime, applications should either set the `authTagLength` option or | ||
| 3370 | + check the actual authentication tag length before passing it to `setAuthTag()`.</strong> | ||
| 3357 | 3371 | ||
| 3358 | 3372 | The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On | |
| 3359 | 3373 | recent OpenSSL releases, `openssl list -cipher-algorithms` will | |
@@ -6508,6 +6522,7 @@ See the [list of SSL OP Flags][] for details. | |||
| 6508 | 6522 | [CVE-2021-44532]: https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-44532 | |
| 6509 | 6523 | [Caveats]: #support-for-weak-or-compromised-algorithms | |
| 6510 | 6524 | [Crypto constants]: #crypto-constants | |
| 6525 | + [DEP0182]: deprecations.md#dep0182-short-gcm-authentication-tags-without-explicit-authtaglength | ||
| 6511 | 6526 | [FIPS module configuration file]: https://www.openssl.org/docs/man3.0/man5/fips_config.html | |
| 6512 | 6527 | [FIPS provider from OpenSSL 3]: https://www.openssl.org/docs/man3.0/man7/crypto.html#FIPS-provider | |
| 6513 | 6528 | [HTML 5.2]: https://www.w3.org/TR/html52/changes.html#features-removed | |
0 commit comments