crypto: use backend cSHAKE and KMAC

Require cSHAKE and KMAC output lengths and KMAC key lengths to be
multiples of 8 bits. KMAC keys must be at least 32 bits. Share these
restrictions between operations and supports.

Use OpenSSL's KMAC provider for all supported inputs and its cSHAKE
implementation for non-empty function names or customization strings.
Keep using SHAKE when both cSHAKE parameters are empty. Remove the
custom Keccak framing, partial-bit handling, and short-key fallback.

Document the OpenSSL 4.0 requirement for non-empty cSHAKE parameters and
reject customization strings containing null bytes. Keep the documented
512-byte customization limit and let backend failures reach callers.

Signed-off-by: Filip Skokan <panva.ip@gmail.com>
Assisted-by: Codex
PR-URL: #66237
Backport-PR-URL: #66391
Reviewed-By: Richard Lau <richard.lau@ibm.com>
Reviewed-By: Xuguang Mei <meixuguang@gmail.com>

Author: panva

doc/api/webcrypto.md

@@ -1830,6 +1830,9 @@ changes:
     description: Renamed `cShakeParams.length` to `cShakeParams.outputLength`.
 -->
 
+When both `functionName` and `customization` are empty or `undefined`, cSHAKE is
+equivalent to plain SHAKE.
+
 #### `cShakeParams.name`
 
 <!-- YAML
@@ -1844,7 +1847,8 @@ added: v24.7.0
 added: v25.9.0
 -->
 
-* Type: {number} represents the requested output length in bits.
+* Type: {number} represents the requested output length in bits. Must be a
+  multiple of 8.
 
 #### `cShakeParams.functionName`
 
@@ -1859,9 +1863,10 @@ 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. Accepted values are:
+domain-separate functions built on top of cSHAKE. Non-empty values require
+OpenSSL 4.0 or later. Accepted values are:
 
-* empty or `undefined`, in which case cSHAKE is equivalent to plain SHAKE
+* empty or `undefined`
 * the ASCII byte sequence `'KMAC'`
 * the ASCII byte sequence `'TupleHash'`
 * the ASCII byte sequence `'ParallelHash'`
@@ -1878,11 +1883,11 @@ changes:
 
 * Type: {ArrayBuffer|TypedArray|DataView|Buffer|undefined}
 
-The `customization` member represents the customization data. Accepted
-values are:
+The `customization` member represents the customization data. Non-empty values
+require OpenSSL 4.0 or later. Accepted values are:
 
-* empty or `undefined`, in which case cSHAKE is equivalent to plain SHAKE
-* up to 512 bytes of arbitrary data
+* empty or `undefined`
+* up to 512 bytes of data without null bytes
 
 ### Class: `EcdhKeyDeriveParams`
 
@@ -2332,7 +2337,7 @@ added: v24.8.0
 * Type: {number}
 
 The optional number of bits in the KMAC key. This is optional and should
-be omitted for most cases.
+be omitted for most cases. The key length must be at least 32 and a multiple of 8.
 
 #### `kmacImportParams.name`
 
@@ -2382,7 +2387,8 @@ added: v24.8.0
 
 The number of bits to generate for the KMAC key. If omitted,
 the length will be determined by the KMAC algorithm used.
-This is optional and should be omitted for most cases.
+This is optional and should be omitted for most cases. Must be at least 32 and a
+multiple of 8.
 
 #### `kmacKeyGenParams.name`
 
@@ -2416,7 +2422,8 @@ added: v24.8.0
 added: v25.9.0
 -->
 
-* Type: {number} represents the requested output length in bits.
+* Type: {number} represents the requested output length in bits. Must be a
+  multiple of 8.
 
 #### `kmacParams.customization`
 

lib/internal/crypto/hash.js

@@ -6,12 +6,10 @@ const {
   StringPrototypeReplace,
   StringPrototypeToLowerCase,
   Symbol,
-  TypedArrayPrototypeGetBuffer,
   TypedArrayPrototypeIncludes,
 } = primordials;
 
 const {
-  CShakeJob,
   Hash: _Hash,
   HashJob,
   Hmac: _Hmac,
@@ -24,10 +22,7 @@ const {
 const {
   getStringOption,
   jobPromise,
-  jobPromiseThen,
   normalizeHashName,
-  numBitsToBytes,
-  truncateToBitLength,
   validateAlgorithm,
   validateMaxBufferLength,
   kHandle,
@@ -43,7 +38,6 @@ const {
 } = require('internal/crypto/keys');
 
 const {
-  lazyDOMException,
   normalizeEncoding,
   encodingsMap,
   getDeprecationWarningEmitter,
@@ -284,30 +278,20 @@ function asyncDigest(algorithm, data) {
       const outputLength = algorithm.outputLength;
       if (getOptionalByteLength(algorithm.functionName) ||
           getOptionalByteLength(algorithm.customization)) {
-        if (CShakeJob === undefined) {
-          throw lazyDOMException(
-            'Non-empty CShakeParams functionName or customization is not supported',
-            'NotSupportedError');
-        }
-
-        return jobPromise(() => new CShakeJob(
+        return jobPromise(() => new HashJob(
           kCryptoJobWebCrypto,
-          algorithm.name,
+          StringPrototypeToLowerCase(algorithm.name),
           data,
+          outputLength,
           algorithm.functionName,
-          algorithm.customization,
-          outputLength));
+          algorithm.customization));
       }
 
-      const bits = jobPromise(() => new HashJob(
+      return jobPromise(() => new HashJob(
         kCryptoJobWebCrypto,
         normalizeHashName(algorithm.name),
         data,
-        numBitsToBytes(outputLength) * 8));
-      if (outputLength % 8 === 0)
-        return bits;
-      return jobPromiseThen(bits, (bits) =>
-        TypedArrayPrototypeGetBuffer(truncateToBitLength(outputLength, bits)));
+        outputLength));
     }
     case 'TurboSHAKE128':
       // Fall through

lib/internal/crypto/mac.js

@@ -193,7 +193,6 @@ function kmacSignVerify(key, data, algorithm, signature) {
     getCryptoKeyHandle(key),
     algorithm.name,
     algorithm.customization,
-    getCryptoKeyAlgorithm(key).length,
     algorithm.outputLength,
     data,
     signature));

lib/internal/crypto/util.js

@@ -721,7 +721,7 @@ function validateMaxBufferLength(data, name, max = kMaxBufferLength) {
 }
 
 function validateKmacKeyLength(length) {
-  if ((length < 32 || length % 8) && isFips())
+  if (length < 32 || length % 8 !== 0)
     throw lazyDOMException('Invalid key length', 'NotSupportedError');
 }
 

lib/internal/crypto/webcrypto.js

@@ -23,7 +23,6 @@ const {
 } = primordials;
 
 const {
-  CShakeJob,
   kWebCryptoKeyFormatRaw,
   kWebCryptoKeyFormatPKCS8,
   kWebCryptoKeyFormatSPKI,
@@ -72,7 +71,6 @@ const {
   prepareWebCryptoResult,
   validateAlgorithm,
   validateMaxBufferLength,
-  getOptionalByteLength,
 } = require('internal/crypto/util');
 
 const {
@@ -1923,15 +1921,7 @@ function check(op, alg, length) {
   }
 
   switch (op) {
-    case 'digest': {
-      if ((normalizedAlgorithm.name === 'cSHAKE128' ||
-           normalizedAlgorithm.name === 'cSHAKE256') &&
-          (getOptionalByteLength(normalizedAlgorithm.functionName) ||
-           getOptionalByteLength(normalizedAlgorithm.customization))) {
-        return CShakeJob !== undefined;
-      }
-      return true;
-    }
+    case 'digest':
     case 'decapsulate':
     case 'decrypt':
     case 'encapsulate':

lib/internal/crypto/webidl.js

@@ -11,15 +11,13 @@ const {
   StringPrototypeCharCodeAt,
   StringPrototypeSplit,
   StringPrototypeToLowerCase,
+  TypedArrayPrototypeIncludes,
 } = primordials;
 
 const {
   lazyDOMException,
   kEmptyObject,
 } = require('internal/util');
-const {
-  isUint32,
-} = require('internal/validators');
 const {
   getCryptoKeyAlgorithm,
   getCryptoKeyType,
@@ -30,9 +28,9 @@ const {
   validateMaxBufferLength,
   getBufferSourceByteLength,
   getBufferSourceBytes,
+  getHashes,
   isFips,
   kNamedCurveAliases,
-  numBitsToBytes,
   validateKmacKeyLength,
 } = require('internal/crypto/util');
 const {
@@ -317,20 +315,20 @@ function validateZeroLength(parameterName) {
 }
 
 function validateCShakeOutputLength(V) {
-  if (!isUint32(numBitsToBytes(V) * 8)) {
+  if (V % 8 !== 0) {
     throw lazyDOMException(
       'Invalid CShakeParams outputLength',
-      'OperationError');
+      'NotSupportedError');
   }
 }
 
 const kCShakeFunctionNames = ['KMAC', 'TupleHash', 'ParallelHash'];
 
-function validateCShakeFunctionName(V) {
+function validateCShakeFunctionName(V, dict) {
   const length = getBufferSourceByteLength(V);
   if (length === 0) return;
 
-  if (!isFips()) {
+  if (ArrayPrototypeIncludes(getHashes(), StringPrototypeToLowerCase(dict.name))) {
     const bytes = getBufferSourceBytes(V);
     for (let i = 0; i < kCShakeFunctionNames.length; i++) {
       const functionName = kCShakeFunctionNames[i];
@@ -349,12 +347,17 @@ function validateCShakeFunctionName(V) {
     'NotSupportedError');
 }
 
-function validateCShakeCustomization(V) {
-  if (isFips() && getBufferSourceByteLength(V) !== 0)
+function validateCShakeCustomization(V, dict) {
+  if (getBufferSourceByteLength(V) === 0) return;
+  if (!ArrayPrototypeIncludes(getHashes(), StringPrototypeToLowerCase(dict.name)))
     throw lazyDOMException(
       'Unsupported CShakeParams customization',
       'NotSupportedError');
   validateMaxBufferLength(V, 'CShakeParams.customization', 512);
+  if (TypedArrayPrototypeIncludes(getBufferSourceBytes(V), 0))
+    throw lazyDOMException(
+      'Unsupported CShakeParams customization',
+      'NotSupportedError');
 }
 
 converters.RsaPssParams = createAlgorithmDictionaryConverter(
@@ -814,7 +817,7 @@ converters.KmacParams = createAlgorithmDictionaryConverter(
         converter: (V, opts) =>
           converters['unsigned long'](V, enforceRangeOptions(opts)),
         validator: (V) => {
-          if ((V === 0 || V % 8) && isFips())
+          if (V % 8 !== 0 || (V === 0 && isFips()))
             throw lazyDOMException(
               'Invalid KmacParams outputLength',
               'NotSupportedError');