Skip to content

doc: warn about short GCM tags visibly #61082

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nodejs-github-bot merged 1 commit into from
Dec 18, 2025
+16 −1
Merged

doc: warn about short GCM tags visibly #61082

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 16 additions & 1 deletion doc/api/crypto.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -962,6 +962,15 @@ for `CCM` mode or before [`decipher.final()`][] for `GCM` and `OCB` modes and
`chacha20-poly1305`.
`decipher.setAuthTag()` can only be called once.

Because the `node:crypto` module was originally designed to closely mirror
OpenSSL's behavior, this function permits short GCM authentication tags unless
an explicit authentication tag length was passed to
[`crypto.createDecipheriv()`][] when the `decipher` object was created. This
behavior is deprecated and subject to change (see [DEP0182][]). <strong class="critical">
In the meantime, applications should either set the `authTagLength` option when
calling `createDecipheriv()` or check the actual
authentication tag length before passing it to `setAuthTag()`.</strong>

When passing a string as the authentication tag, please consider
[caveats when using strings as inputs to cryptographic APIs][].

Expand Down Expand Up @@ -3352,8 +3361,13 @@ The `options` argument controls stream behavior and is optional except when a
cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) is used. In that case, the
`authTagLength` option is required and specifies the length of the
authentication tag in bytes, see [CCM mode][].
For AES-GCM and `chacha20-poly1305`, the `authTagLength` option defaults to 16
For `chacha20-poly1305`, the `authTagLength` option defaults to 16
bytes and must be set to a different value if a different length is used.
For AES-GCM, the `authTagLength` option has no default value when decrypting,
and `setAuthTag()` will accept arbitrarily short authentication tags. This
behavior is deprecated and subject to change (see [DEP0182][]). <strong class="critical">
In the meantime, applications should either set the `authTagLength` option or
check the actual authentication tag length before passing it to `setAuthTag()`.</strong>

The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On
recent OpenSSL releases, `openssl list -cipher-algorithms` will
Expand Down Expand Up @@ -6508,6 +6522,7 @@ See the [list of SSL OP Flags][] for details.
[CVE-2021-44532]: https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-44532
[Caveats]: #support-for-weak-or-compromised-algorithms
[Crypto constants]: #crypto-constants
[DEP0182]: deprecations.md#dep0182-short-gcm-authentication-tags-without-explicit-authtaglength
[FIPS module configuration file]: https://www.openssl.org/docs/man3.0/man5/fips_config.html
[FIPS provider from OpenSSL 3]: https://www.openssl.org/docs/man3.0/man7/crypto.html#FIPS-provider
[HTML 5.2]: https://www.w3.org/TR/html52/changes.html#features-removed
Expand Down
Loading