crypto: support non-byte WebCrypto lengths and cSHAKE

Add shared bit-length helpers for WebCrypto operations that accept bit
sequences whose length is not byte-aligned.

Use the helpers for cSHAKE output, ECDH-derived bits, HMAC/KMAC key
generation/import/derivation, and KMAC sign/verify output. Preserve the
requested bit length in CryptoKey algorithm metadata while storing and
exporting rounded-up byte material with unused low bits cleared.

Keep byte-multiple validation for algorithms whose specs require it.

Extend the lower-end of KMAC's key length support.

Enable cSHAKE customization and functionName parameters.

Signed-off-by: Filip Skokan <panva.ip@gmail.com>
PR-URL: #63988
Backport-PR-URL: #64629
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

Author: panva

doc/api/webcrypto.md

@@ -1924,26 +1924,39 @@ added: v24.15.0
 
 <!-- YAML
 added: v24.7.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/63988
+    description: Named cSHAKE variants are now accepted.
 -->
 
 * Type: {ArrayBuffer|TypedArray|DataView|Buffer|undefined}
 
-The `functionName` member represents the function name, used by NIST to define
-functions based on cSHAKE.
-The Node.js Web Crypto API implementation only supports zero-length functionName
-which is equivalent to not providing functionName at all.
+The `functionName` member represents the NIST function-name byte string used to
+domain-separate functions built on top of cSHAKE. Accepted values are:
+
+* empty or `undefined`, in which case cSHAKE is equivalent to plain SHAKE
+* the ASCII byte sequence `'KMAC'`
+* the ASCII byte sequence `'TupleHash'`
+* the ASCII byte sequence `'ParallelHash'`
 
 #### `cShakeParams.customization`
 
 <!-- YAML
 added: v24.7.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/63988
+    description: Non-empty customization is now supported.
 -->
 
 * Type: {ArrayBuffer|TypedArray|DataView|Buffer|undefined}
 
-The `customization` member represents the customization string.
-The Node.js Web Crypto API implementation only supports zero-length customization
-which is equivalent to not providing customization at all.
+The `customization` member represents the customization data. Accepted
+values are:
+
+* empty or `undefined`, in which case cSHAKE is equivalent to plain SHAKE
+* up to 512 bytes of arbitrary data
 
 ### Class: `EcdhKeyDeriveParams`
 
@@ -2472,9 +2485,7 @@ added: v24.8.0
 added: v24.15.0
 -->
 
-* Type: {number}
-
-The length of the output in bytes. This must be a positive integer.
+* Type: {number} represents the requested output length in bits.
 
 #### `kmacParams.customization`
 

lib/internal/crypto/diffiehellman.js

@@ -3,11 +3,9 @@
 const {
   ArrayBufferPrototypeSlice,
   FunctionPrototypeCall,
-  MathCeil,
   ObjectDefineProperty,
   SafeSet,
   TypedArrayPrototypeGetBuffer,
-  Uint8Array,
 } = primordials;
 
 const { Buffer } = require('buffer');
@@ -65,7 +63,9 @@ const {
   getArrayBufferOrView,
   jobPromise,
   jobPromiseThen,
+  numBitsToBytes,
   toBuf,
+  truncateToBitLength,
   kHandle,
 } = require('internal/crypto/util');
 
@@ -365,7 +365,6 @@ function diffieHellman(options, callback) {
   job.run();
 }
 
-let masks;
 // The ecdhDeriveBits function is part of the Web Crypto API and serves both
 // deriveKeys and deriveBits functions.
 function ecdhDeriveBits(algorithm, baseKey, length) {
@@ -409,27 +408,20 @@ function ecdhDeriveBits(algorithm, baseKey, length) {
     return bits;
 
   return jobPromiseThen(bits, (bits) => {
-    // If the length is not a multiple of 8 the nearest ceiled
-    // multiple of 8 is sliced.
-    const sliceLength = MathCeil(length / 8);
+    const sliceLength = numBitsToBytes(length);
 
     const { byteLength } = bits;
     // If the length is larger than the derived secret, throw.
     if (byteLength < sliceLength)
       throw lazyDOMException('derived bit length is too small', 'OperationError');
 
-    const slice = ArrayBufferPrototypeSlice(bits, 0, sliceLength);
-
-    const mod = length % 8;
-    if (mod === 0)
-      return slice;
-
-    // eslint-disable-next-line no-sparse-arrays
-    masks ||= [, 0b10000000, 0b11000000, 0b11100000, 0b11110000, 0b11111000, 0b11111100, 0b11111110];
+    if (length % 8 === 0) {
+      if (byteLength === sliceLength)
+        return bits;
+      return ArrayBufferPrototypeSlice(bits, 0, sliceLength);
+    }
 
-    const masked = new Uint8Array(slice);
-    masked[sliceLength - 1] = masked[sliceLength - 1] & masks[mod];
-    return TypedArrayPrototypeGetBuffer(masked);
+    return TypedArrayPrototypeGetBuffer(truncateToBitLength(length, bits));
   });
 }
 

lib/internal/crypto/hash.js

@@ -6,9 +6,11 @@ const {
   StringPrototypeReplace,
   StringPrototypeToLowerCase,
   Symbol,
+  TypedArrayPrototypeGetBuffer,
 } = primordials;
 
 const {
+  CShakeJob,
   Hash: _Hash,
   HashJob,
   Hmac: _Hmac,
@@ -21,7 +23,10 @@ const {
 const {
   getStringOption,
   jobPromise,
+  jobPromiseThen,
   normalizeHashName,
+  numBitsToBytes,
+  truncateToBitLength,
   validateMaxBufferLength,
   kHandle,
   getCachedHashId,
@@ -222,15 +227,41 @@ function asyncDigest(algorithm, data) {
     case 'SHA3-384':
       // Fall through
     case 'SHA3-512':
-      // Fall through
+      return jobPromise(() => new HashJob(
+        kCryptoJobWebCrypto,
+        normalizeHashName(algorithm.name),
+        data));
     case 'cSHAKE128':
       // Fall through
-    case 'cSHAKE256':
-      return jobPromise(() => new HashJob(
+    case 'cSHAKE256': {
+      const outputLength = algorithm.outputLength;
+      if (algorithm.functionName?.byteLength ||
+          algorithm.customization?.byteLength) {
+        if (CShakeJob === undefined) {
+          throw lazyDOMException(
+            'Non-empty CShakeParams functionName or customization is not supported',
+            'NotSupportedError');
+        }
+
+        return jobPromise(() => new CShakeJob(
+          kCryptoJobWebCrypto,
+          algorithm.name,
+          data,
+          algorithm.functionName,
+          algorithm.customization,
+          outputLength));
+      }
+
+      const bits = jobPromise(() => new HashJob(
         kCryptoJobWebCrypto,
         normalizeHashName(algorithm.name),
         data,
-        algorithm.outputLength));
+        numBitsToBytes(outputLength) * 8));
+      if (outputLength % 8 === 0)
+        return bits;
+      return jobPromiseThen(bits, (bits) =>
+        TypedArrayPrototypeGetBuffer(truncateToBitLength(outputLength, bits)));
+    }
     case 'TurboSHAKE128':
       // Fall through
     case 'TurboSHAKE256':

lib/internal/crypto/mac.js

@@ -18,6 +18,8 @@ const {
   getUsagesMask,
   jobPromise,
   normalizeHashName,
+  numBitsToBytes,
+  truncateToBitLength,
 } = require('internal/crypto/util');
 
 const {
@@ -40,6 +42,27 @@ const {
 
 const kUsages = ['sign', 'verify'];
 
+function normalizeKeyLength(handle, algorithm) {
+  let length = handle.getSymmetricKeySize() * 8;
+  if (length === 0 && algorithm.name === 'HMAC')
+    throw lazyDOMException('Zero-length key is not supported', 'DataError');
+
+  if (algorithm.length !== undefined) {
+    const byteLength = numBitsToBytes(algorithm.length);
+    if (byteLength !== handle.getSymmetricKeySize())
+      throw lazyDOMException('Invalid key length', 'DataError');
+
+    if (algorithm.length % 8 !== 0) {
+      handle = importSecretKey(
+        truncateToBitLength(algorithm.length, handle.export()));
+    }
+
+    length = algorithm.length;
+  }
+
+  return { handle, length };
+}
+
 function hmacGenerateKey(algorithm, extractable, usages) {
   const {
     hash,
@@ -93,7 +116,6 @@ function macImportKey(
   let length;
   switch (format) {
     case 'KeyObjectHandle': {
-      length = keyData.getSymmetricKeySize() * 8;
       handle = keyData;
       break;
     }
@@ -102,7 +124,6 @@ function macImportKey(
       if (format === 'raw' && !isHmac) {
         return undefined;
       }
-      length = keyData.byteLength * 8;
       handle = importSecretKey(keyData);
       break;
     }
@@ -120,20 +141,13 @@ function macImportKey(
       }
 
       handle = importJwkSecretKey(keyData);
-      length = handle.getSymmetricKeySize() * 8;
       break;
     }
     default:
       return undefined;
   }
 
-  if (length === 0)
-    throw lazyDOMException('Zero-length key is not supported', 'DataError');
-
-  if (algorithm.length !== undefined &&
-      algorithm.length !== length) {
-    throw lazyDOMException('Invalid key length', 'DataError');
-  }
+  ({ handle, length } = normalizeKeyLength(handle, algorithm)); // eslint-disable-line prefer-const
 
   const algorithmObject = {
     name: algorithm.name,
@@ -170,7 +184,8 @@ function kmacSignVerify(key, data, algorithm, signature) {
     getCryptoKeyHandle(key),
     algorithm.name,
     algorithm.customization,
-    algorithm.outputLength / 8,
+    getCryptoKeyAlgorithm(key).length,
+    algorithm.outputLength,
     data,
     signature));
 }

lib/internal/crypto/util.js

@@ -9,6 +9,7 @@ const {
   DataViewPrototypeGetBuffer,
   DataViewPrototypeGetByteLength,
   DataViewPrototypeGetByteOffset,
+  MathFloor,
   Number,
   ObjectDefineProperty,
   ObjectEntries,
@@ -549,6 +550,46 @@ function validateMaxBufferLength(data, name, max = kMaxBufferLength) {
   }
 }
 
+/**
+ * Converts a bit length to the number of bytes needed to contain it.
+ * Non-byte lengths are rounded up to the next byte.
+ * @param {number} length
+ * @returns {number}
+ */
+function numBitsToBytes(length) {
+  return MathFloor(length / 8) + MathFloor((7 + (length % 8)) / 8);
+}
+
+/**
+ * Copies `bytes` up to the byte length needed for `length` bits, then clears
+ * unused least-significant bits in the final byte.
+ * @param {number} length
+ * @param {ArrayBuffer|ArrayBufferView} bytes
+ * @returns {Uint8Array}
+ */
+function truncateToBitLength(length, bytes) {
+  const lengthBytes = numBitsToBytes(length);
+  const isView = ArrayBufferIsView(bytes);
+  const byteView = isView ?
+    new Uint8Array(
+      getDataViewOrTypedArrayBuffer(bytes),
+      getDataViewOrTypedArrayByteOffset(bytes),
+      getDataViewOrTypedArrayByteLength(bytes),
+    ) :
+    new Uint8Array(bytes, 0, ArrayBufferPrototypeGetByteLength(bytes));
+  const result = TypedArrayPrototypeSlice(
+    byteView,
+    0,
+    lengthBytes,
+  );
+
+  const remainder = length % 8;
+  if (remainder !== 0)
+    result[lengthBytes - 1] &= (0xff << (8 - remainder)) & 0xff;
+
+  return result;
+}
+
 let webidl;
 
 // Keep this as a regular object. The WebIDL converters read and spread these
@@ -608,12 +649,19 @@ function normalizeAlgorithm(algorithm, op) {
       // 3.
       if (idlType === 'BufferSource' && idlValue) {
         const isView = ArrayBufferIsView(idlValue);
-        normalizedAlgorithm[member] = TypedArrayPrototypeSlice(
+        const idlValueBytes = isView ?
           new Uint8Array(
-            isView ? getDataViewOrTypedArrayBuffer(idlValue) : idlValue,
-            isView ? getDataViewOrTypedArrayByteOffset(idlValue) : 0,
-            isView ? getDataViewOrTypedArrayByteLength(idlValue) : ArrayBufferPrototypeGetByteLength(idlValue),
-          ),
+            getDataViewOrTypedArrayBuffer(idlValue),
+            getDataViewOrTypedArrayByteOffset(idlValue),
+            getDataViewOrTypedArrayByteLength(idlValue),
+          ) :
+          new Uint8Array(
+            idlValue,
+            0,
+            ArrayBufferPrototypeGetByteLength(idlValue),
+          );
+        normalizedAlgorithm[member] = TypedArrayPrototypeSlice(
+          idlValueBytes,
         );
       } else if (idlType === 'HashAlgorithmIdentifier') {
         normalizedAlgorithm[member] = normalizeAlgorithm(idlValue, 'digest');
@@ -1003,6 +1051,8 @@ module.exports = {
   cleanupWebCryptoResult,
   prepareWebCryptoResult,
   validateMaxBufferLength,
+  numBitsToBytes,
+  truncateToBitLength,
   bigIntArrayToUnsignedBigInt,
   bigIntArrayToUnsignedInt,
   getBlockSize,