Commit 3c26849e172 for nodejs

commit 3c26849e1724c8789d8789229e3051f4e8110198
Author: Filip Skokan <panva.ip@gmail.com>
Date:   Mon Nov 16 14:24:25 2026 +0100

    doc: clarify crypto and Web Crypto options

    Document which digest and MAC options apply and how output lengths
    work. Clarify signature contexts and distinguish required parameters
    from optional defaults in Web Crypto.

    Signed-off-by: Filip Skokan <panva.ip@gmail.com>
    Assisted-by: Codex
    PR-URL: https://github.com/nodejs/node/pull/67565
    Reviewed-By: James M Snell <jasnell@gmail.com>
    Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 24388e91beb..cb8e2186c42 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -4258,34 +4258,24 @@ changes:

 * `algorithm` {string}
 * `options` {Object} [`stream.transform` options][]
-  * `customization` {string|ArrayBuffer|Buffer|TypedArray|DataView} For cSHAKE
-    hash functions, specifies the customization byte string. **Default:** an
-    empty byte string.
-  * `functionName` {string|ArrayBuffer|Buffer|TypedArray|DataView} For cSHAKE
-    hash functions, specifies the NIST function-name byte string. **Default:**
-    an empty byte string.
-  * `outputLength` {number} For XOF hash functions, specifies the desired
-    output length in bytes.
+  * `customization` {string|ArrayBuffer|Buffer|TypedArray|DataView} The
+    customization byte string for digests that support it, such as cSHAKE.
+  * `functionName` {string|ArrayBuffer|Buffer|TypedArray|DataView} The NIST
+    function-name byte string for digests that support it, such as cSHAKE.
+  * `outputLength` {number} For a fixed-length digest, an explicit value must
+    match the digest size in bytes.
 * Returns: {Hash}

 Creates and returns a `Hash` object that can be used to generate hash digests
-using the given `algorithm`. Optional `options` argument controls stream
+using the given `algorithm`. The optional `options` argument controls stream
 behavior. For XOF hash functions such as `'shake256'`, the `outputLength` option
 specifies the desired output length in bytes. It is required for XOF hash
 functions without a default output length.

-The `functionName` and `customization` options apply only to cSHAKE-128 and
-cSHAKE-256. They are supported only when Node.js is built with OpenSSL 4.0 or
-later and the selected provider supports the corresponding digest parameters.
-Strings are encoded as UTF-8, and neither strings nor byte values may contain
-NUL bytes. Both options default to an empty byte string. For OpenSSL's built-in
-providers, `functionName` is case-sensitive and must be `''`, `'TupleHash'`,
-`'ParallelHash'`, or `'KMAC'`. Other providers can impose different
-restrictions. With both options empty, cSHAKE produces the same output as the
-corresponding SHAKE function for the same output length. `cshake-128` and
-`cshake-256` default to output lengths of 32 and 64 bytes, respectively.
+The selected digest determines which options are supported in addition to the
+standard [`stream.transform` options][].

-When the data is small (< 5MB) and readily available, [`crypto.hash()`][] is usually faster.
+For readily available data up to 5 MB, [`crypto.hash()`][] can be faster.

 The available algorithms depend on the version and configuration of OpenSSL on
 the platform. Examples are `'sha256'` and `'sha512'`. Use
@@ -4464,15 +4454,13 @@ added:
     byte string for MACs that support it, such as KMAC.
   * `salt` {ArrayBuffer|Buffer|TypedArray|DataView} A salt byte string for MACs
     that support it, such as BLAKE2 MACs.
-  * `outputLength` {number} The requested provider output size in bytes. Must be
-    an unsigned 32-bit integer. Provider-specific restrictions also apply.
+  * `outputLength` {number} The requested MAC output size in bytes. Must be
+    an unsigned 32-bit integer. Algorithm-specific restrictions also apply.
 * Returns: {Mac}

-`algorithm` must be a non-empty provider MAC name. The MAC-specific properties
-listed above are extensions to the standard [`stream.transform` options][] and
-are passed only when the selected provider implementation advertises the
-corresponding parameter with the expected type. A supplied MAC-specific option
-that the selected implementation does not support causes an error.
+`algorithm` must be a non-empty MAC name. Use [`crypto.getMacs()`][] to list
+available algorithms. The selected MAC determines which options it accepts.
+Supplying an unsupported MAC-specific option causes an error.

 The following table summarizes the MAC-specific options accepted by MAC
 implementations in OpenSSL's built-in providers. The `key` argument is required
@@ -4489,20 +4477,13 @@ for every MAC. The table lists only MAC-specific options; standard
 | Poly1305   | None                                    | None                                    | Each key must be used for only one message.                            |
 | SipHash    | None                                    | `outputLength`                          |                                                                        |

-`outputLength` configures the output size of the provider MAC. It is never
-implemented by computing a longer tag and truncating it. A value of `0` is
-passed to the provider and is accepted only when that provider can initialize
-and finalize the MAC with a zero-byte output. When `outputLength` is omitted,
-the provider's default output size is used and must be nonzero.
+`outputLength` configures the size of the tag computed by the MAC. KMAC, for
+example, incorporates the requested length into the tag computation. A value
+of `0` is accepted only for MACs that support an empty tag. When omitted, the
+default output size is used and must be nonzero.

 The `key` must contain bytes or be a [`KeyObject`][] of type `secret`. Key
-length and other key requirements are determined by the selected provider
-implementation.
-
-Available algorithms and their accepted parameters depend on the OpenSSL
-version, loaded providers, and active default property query. Use
-[`crypto.getMacs()`][] to list fetchable MAC names. A listed name can still
-require options or a key with provider-specific properties.
+length and other key requirements depend on the selected MAC algorithm.

 ### `crypto.createPrivateKey(key)`

@@ -5780,23 +5761,14 @@ added:
 > Stability: 1.2 - Release candidate

 * Returns: {string\[]} A fresh array containing the sorted, lowercase names
-  and aliases of fetchable MAC implementations.
-
-Returns MAC names exposed by loaded OpenSSL providers that match the active
-default property query. Duplicate names and numeric OID aliases are omitted.
-On builds without OpenSSL `EVP_MAC` support, this function returns an empty
-array.
+  and aliases of available MAC algorithms.

-The returned names describe implementations that OpenSSL can fetch. They do not
-guarantee that [`crypto.createMac()`][] can initialize the MAC without
-additional options. A provider can require additional parameters or a key with
-algorithm-specific properties, and it can expose parameters that this API does
-not support.
+A listed MAC can require additional options or a key of a specific length.
+See [`crypto.createMac()`][] for the options that apply to each MAC family.

 After a successful FIPS mode change made with [`crypto.setFips()`][], subsequent
 calls reflect the new mode, and newly created `Mac` objects use it. Existing
-`Mac` objects continue using the provider implementation selected when they
-were created.
+`Mac` objects continue using the implementation selected when they were created.

 ```mjs
 const { getMacs } = await import('node:crypto');
@@ -5846,47 +5818,33 @@ changes:
     description: The `outputLength` option was added for XOF hash functions.
 -->

-* `algorithm` {string|undefined}
+* `algorithm` {string}
 * `data` {string|Buffer|TypedArray|DataView} When `data` is a
   string, it will be encoded as UTF-8 before being hashed. If a different
   input encoding is desired for a string input, user could encode the string
   into a `TypedArray` using either `TextEncoder` or `Buffer.from()` and passing
   the encoded `TypedArray` into this API instead.
 * `options` {Object|string}
-  * `customization` {string|ArrayBuffer|Buffer|TypedArray|DataView} For cSHAKE
-    hash functions, specifies the customization byte string. **Default:** an
-    empty byte string.
-  * `functionName` {string|ArrayBuffer|Buffer|TypedArray|DataView} For cSHAKE
-    hash functions, specifies the NIST function-name byte string. **Default:**
-    an empty byte string.
+  * `customization` {string|ArrayBuffer|Buffer|TypedArray|DataView} The
+    customization byte string for digests that support it, such as cSHAKE.
+  * `functionName` {string|ArrayBuffer|Buffer|TypedArray|DataView} The NIST
+    function-name byte string for digests that support it, such as cSHAKE.
   * `outputEncoding` {string} [Encoding][encoding] used to encode the
     returned digest. **Default:** `'hex'`.
-  * `outputLength` {number} For XOF hash functions such as 'shake256',
-    specifies the desired output length in bytes. This option is required for
-    XOF hash functions without a default output length.
+  * `outputLength` {number} The requested digest length in bytes. Required for
+    XOF hash functions without a default output length, such as SHAKE. For a
+    fixed-length digest, an explicit value must match the digest size.
 * Returns: {string|Buffer}

 A utility for creating one-shot hash digests of data. It can be faster than
-the object-based `crypto.createHash()` when hashing a smaller amount of data
-(<= 5MB) that's readily available. If the data can be big or if it is streamed,
-it's still recommended to use `crypto.createHash()` instead.
+[`crypto.createHash()`][] for readily available data up to 5 MB. Use
+[`crypto.createHash()`][] for large inputs or streamed data.

 The available algorithms depend on the version and configuration of OpenSSL on
 the platform. Examples are `'sha256'` and `'sha512'`. Use
 [`crypto.getHashes()`][] to obtain the list of hash algorithms available to the
 Node.js process.

-The `functionName` and `customization` options apply only to cSHAKE-128 and
-cSHAKE-256. They are supported only when Node.js is built with OpenSSL 4.0 or
-later and the selected provider supports the corresponding digest parameters.
-Strings are encoded as UTF-8, and neither strings nor byte values may contain
-NUL bytes. Both options default to an empty byte string. For OpenSSL's built-in
-providers, `functionName` is case-sensitive and must be `''`, `'TupleHash'`,
-`'ParallelHash'`, or `'KMAC'`. Other providers can impose different
-restrictions. With both options empty, cSHAKE produces the same output as the
-corresponding SHAKE function for the same output length. `cshake-128` and
-`cshake-256` default to output lengths of 32 and 64 bytes, respectively.
-
 If `options` is a string, then it specifies the `outputEncoding`.

 Example:
@@ -7213,8 +7171,8 @@ Calculates and returns the signature for `data` using the given private key and
 algorithm. If `algorithm` is `null` or `undefined`, then the algorithm is
 dependent upon the key type.

-`algorithm` is required to be `null` or `undefined` for Ed25519, Ed448, and
-ML-DSA.
+`algorithm` is required to be `null` or `undefined` for Ed25519, Ed448, ML-DSA,
+and SLH-DSA.

 [`crypto.getHashes()`][] lists algorithms available to the hashing APIs, but
 the key type and signature scheme determine whether a listed digest can be
@@ -7242,10 +7200,11 @@ passed:
   `crypto.constants.RSA_PSS_SALTLEN_DIGEST` sets the salt length to the digest
   size, `crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN` (default) sets it to the
   maximum permissible value.
-* `context` {ArrayBuffer|Buffer|TypedArray|DataView} For Ed25519[^openssl32]
-  (using Ed25519ctx from [RFC 8032][]), Ed448, ML-DSA, and SLH-DSA,
-  this option specifies the optional context to differentiate signatures
-  generated for different purposes with the same key.
+* `context` {Buffer|TypedArray|DataView} An optional byte string of up to 255
+  bytes for Ed25519[^openssl32], Ed448, ML-DSA, and SLH-DSA. It separates
+  signatures generated for different purposes with the same key. An empty
+  context is equivalent to omitting the option. For Ed25519, a non-empty
+  context selects Ed25519ctx from [RFC 8032][].

 If the `callback` function is provided this function uses libuv's threadpool.

@@ -7359,8 +7318,8 @@ Verifies the given signature for `data` using the given key and algorithm. If
 `algorithm` is `null` or `undefined`, then the algorithm is dependent upon the
 key type.

-`algorithm` is required to be `null` or `undefined` for Ed25519, Ed448, and
-ML-DSA.
+`algorithm` is required to be `null` or `undefined` for Ed25519, Ed448, ML-DSA,
+and SLH-DSA.

 [`crypto.getHashes()`][] lists algorithms available to the hashing APIs, but
 the key type and signature scheme determine whether a listed digest can be
@@ -7388,10 +7347,11 @@ passed:
   `crypto.constants.RSA_PSS_SALTLEN_DIGEST` sets the salt length to the digest
   size, `crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN` (default) sets it to the
   maximum permissible value.
-* `context` {ArrayBuffer|Buffer|TypedArray|DataView} For Ed25519[^openssl32]
-  (using Ed25519ctx from [RFC 8032][]), Ed448, ML-DSA, and SLH-DSA,
-  this option specifies the optional context to differentiate signatures
-  generated for different purposes with the same key.
+* `context` {Buffer|TypedArray|DataView} An optional byte string of up to 255
+  bytes for Ed25519[^openssl32], Ed448, ML-DSA, and SLH-DSA. Use the same
+  context that was used to sign the data. An empty context is equivalent to
+  omitting the option. For Ed25519, a non-empty context selects Ed25519ctx
+  from [RFC 8032][].

 The `signature` argument is the previously calculated signature for the `data`.

diff --git a/doc/api/webcrypto.md b/doc/api/webcrypto.md
index 98df2850931..91b6db403a9 100644
--- a/doc/api/webcrypto.md
+++ b/doc/api/webcrypto.md
@@ -996,7 +996,7 @@ Using the method identified by `algorithm`, this method attempts to
 generate a digest of `data`. If successful, the returned promise is resolved
 with an {ArrayBuffer} containing the computed digest.

-If `algorithm` is provided as a {string}, it must be one of:
+The supported algorithm names are:

 * `'cSHAKE128'`[^modern-algos]
 * `'cSHAKE256'`[^modern-algos]
@@ -1015,6 +1015,10 @@ If `algorithm` is provided as a {string}, it must be one of:
 If `algorithm` is provided as an {Object}, it must have a `name` property
 whose value is one of the above.

+For cSHAKE, TurboSHAKE, and KangarooTwelve algorithms, `algorithm` must be a
+{CShakeParams}, {TurboShakeParams}, or {KangarooTwelveParams} object,
+respectively, with the required `outputLength` property.
+
 ### `subtle.encapsulateBits(encapsulationAlgorithm, encapsulationKey)`

 <!-- YAML
@@ -1869,8 +1873,7 @@ added:
  - v24.15.0
 -->

-* Type: {number} represents the requested output length in bits. Must be a
-  multiple of 8.
+* Type: {number} The required output length in bits. Must be a multiple of 8.

 #### `cShakeParams.functionName`

@@ -1886,9 +1889,9 @@ changes:

 * Type: {ArrayBuffer|TypedArray|DataView|Buffer|undefined}

-The `functionName` member represents the NIST function-name byte string used to
-domain-separate functions built on top of cSHAKE. Non-empty values require
-OpenSSL 4.0 or later. Accepted values are:
+The optional `functionName` member represents the NIST function-name byte string
+used to domain-separate functions built on top of cSHAKE. It defaults to an empty
+byte string. Accepted values are:

 * empty or `undefined`
 * the ASCII byte sequence `'KMAC'`
@@ -1909,11 +1912,8 @@ changes:

 * Type: {ArrayBuffer|TypedArray|DataView|Buffer|undefined}

-The `customization` member represents the customization data. Non-empty values
-require OpenSSL 4.0 or later. Accepted values are:
-
-* empty or `undefined`
-* up to 512 bytes of data without null bytes
+The optional `customization` member is a byte string of at most 512 bytes without
+null bytes. It defaults to an empty byte string.

 ### Class: `EcdhKeyDeriveParams`

@@ -2335,8 +2335,8 @@ changes:

 * Type: {ArrayBuffer|TypedArray|DataView|Buffer|undefined}

-The optional customization string for KangarooTwelve. It must not exceed 512
-bytes.
+The optional customization byte string for KangarooTwelve. It must not exceed
+512 bytes and defaults to an empty byte string.

 #### `kangarooTwelveParams.name`

@@ -2356,7 +2356,8 @@ added:
  - v24.18.0
 -->

-* Type: {number} represents the requested output length in bits.
+* Type: {number} The required output length in bits. Must be a nonzero
+  multiple of 8.

 ### Class: `KmacImportParams`

@@ -2446,7 +2447,7 @@ changes:
     description: Renamed `kmacParams.length` to `kmacParams.outputLength`.
 -->

-#### `kmacParams.algorithm`
+#### `kmacParams.name`

 <!-- YAML
 added: v24.8.0
@@ -2462,8 +2463,7 @@ added:
  - v24.15.0
 -->

-* Type: {number} represents the requested output length in bits. Must be a
-  multiple of 8.
+* Type: {number} The required output length in bits. Must be a multiple of 8.

 #### `kmacParams.customization`

@@ -2473,7 +2473,7 @@ added: v24.8.0

 * Type: {ArrayBuffer|TypedArray|DataView|Buffer|undefined}

-The `customization` member represents the optional customization string.
+The optional customization byte string. It defaults to an empty byte string.

 ### Class: `Pbkdf2Params`

@@ -2770,7 +2770,8 @@ added:
  - v24.18.0
 -->

-* Type: {number} represents the requested output length in bits.
+* Type: {number} The required output length in bits. Must be a nonzero
+  multiple of 8.

 [^secure-curves]: See [Secure Curves in the Web Cryptography API][]