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();
 }
 
-letmasks;
 // The ecdhDeriveBits function is part of the Web Crypto API and serves both
 // deriveKeys and deriveBits functions.
 functionecdhDeriveBits(algorithm,baseKey,length){
@@ -409,27 +408,20 @@ function ecdhDeriveBits(algorithm, baseKey, length) {
 returnbits;
 
 returnjobPromiseThen(bits,(bits)=>{
-// If the length is not a multiple of 8 the nearest ceiled
-// multiple of 8 is sliced.
-constsliceLength=MathCeil(length/8);
+constsliceLength=numBitsToBytes(length);
 
 const{ byteLength }=bits;
 // If the length is larger than the derived secret, throw.
 if(byteLength<sliceLength)
 throwlazyDOMException('derived bit length is too small','OperationError');
 
-constslice=ArrayBufferPrototypeSlice(bits,0,sliceLength);
-
-constmod=length%8;
-if(mod===0)
-returnslice;
-
-// eslint-disable-next-line no-sparse-arrays
-masks||=[,0b10000000,0b11000000,0b11100000,0b11110000,0b11111000,0b11111100,0b11111110];
+if(length%8===0){
+if(byteLength===sliceLength)
+returnbits;
+returnArrayBufferPrototypeSlice(bits,0,sliceLength);
+}
 
-constmasked=newUint8Array(slice);
-masked[sliceLength-1]=masked[sliceLength-1]&masks[mod];
-returnTypedArrayPrototypeGetBuffer(masked);
+returnTypedArrayPrototypeGetBuffer(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
+returnjobPromise(()=>newHashJob(
+kCryptoJobWebCrypto,
+normalizeHashName(algorithm.name),
+data));
 case'cSHAKE128':
 // Fall through
-case'cSHAKE256':
-returnjobPromise(()=>newHashJob(
+case'cSHAKE256': {
+constoutputLength=algorithm.outputLength;
+if(algorithm.functionName?.byteLength||
+algorithm.customization?.byteLength){
+if(CShakeJob===undefined){
+throwlazyDOMException(
+'Non-empty CShakeParams functionName or customization is not supported',
+'NotSupportedError');
+}
+
+returnjobPromise(()=>newCShakeJob(
+kCryptoJobWebCrypto,
+algorithm.name,
+data,
+algorithm.functionName,
+algorithm.customization,
+outputLength));
+}
+
+constbits=jobPromise(()=>newHashJob(
 kCryptoJobWebCrypto,
 normalizeHashName(algorithm.name),
 data,
-algorithm.outputLength));
+numBitsToBytes(outputLength)*8));
+if(outputLength%8===0)
+returnbits;
+returnjobPromiseThen(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 {
 
 constkUsages=['sign','verify'];
 
+functionnormalizeKeyLength(handle,algorithm){
+letlength=handle.getSymmetricKeySize()*8;
+if(length===0&&algorithm.name==='HMAC')
+throwlazyDOMException('Zero-length key is not supported','DataError');
+
+if(algorithm.length!==undefined){
+constbyteLength=numBitsToBytes(algorithm.length);
+if(byteLength!==handle.getSymmetricKeySize())
+throwlazyDOMException('Invalid key length','DataError');
+
+if(algorithm.length%8!==0){
+handle=importSecretKey(
+truncateToBitLength(algorithm.length,handle.export()));
+}
+
+length=algorithm.length;
+}
+
+return{ handle, length };
+}
+
 functionhmacGenerateKey(algorithm,extractable,usages){
 const{
  hash,
@@ -93,7 +116,6 @@ function macImportKey(
 letlength;
 switch(format){
 case'KeyObjectHandle': {
-length=keyData.getSymmetricKeySize()*8;
 handle=keyData;
 break;
 }
@@ -102,7 +124,6 @@ function macImportKey(
 if(format==='raw'&&!isHmac){
 returnundefined;
 }
-length=keyData.byteLength*8;
 handle=importSecretKey(keyData);
 break;
 }
@@ -120,20 +141,13 @@ function macImportKey(
 }
 
 handle=importJwkSecretKey(keyData);
-length=handle.getSymmetricKeySize()*8;
 break;
 }
 default:
 returnundefined;
 }
 
-if(length===0)
-throwlazyDOMException('Zero-length key is not supported','DataError');
-
-if(algorithm.length!==undefined&&
-algorithm.length!==length){
-throwlazyDOMException('Invalid key length','DataError');
-}
+({ handle, length }=normalizeKeyLength(handle,algorithm));// eslint-disable-line prefer-const
 
 constalgorithmObject={
 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}
+ */
+functionnumBitsToBytes(length){
+returnMathFloor(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}
+ */
+functiontruncateToBitLength(length,bytes){
+constlengthBytes=numBitsToBytes(length);
+constisView=ArrayBufferIsView(bytes);
+constbyteView=isView ?
+newUint8Array(
+getDataViewOrTypedArrayBuffer(bytes),
+getDataViewOrTypedArrayByteOffset(bytes),
+getDataViewOrTypedArrayByteLength(bytes),
+) :
+newUint8Array(bytes,0,ArrayBufferPrototypeGetByteLength(bytes));
+constresult=TypedArrayPrototypeSlice(
+byteView,
+0,
+lengthBytes,
+);
+
+constremainder=length%8;
+if(remainder!==0)
+result[lengthBytes-1]&=(0xff<<(8-remainder))&0xff;
+
+returnresult;
+}
+
 letwebidl;
 
 // 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){
 constisView=ArrayBufferIsView(idlValue);
-normalizedAlgorithm[member]=TypedArrayPrototypeSlice(
+constidlValueBytes=isView ?
 newUint8Array(
-isView ? getDataViewOrTypedArrayBuffer(idlValue) : idlValue,
-isView ? getDataViewOrTypedArrayByteOffset(idlValue) : 0,
-isView ? getDataViewOrTypedArrayByteLength(idlValue) : ArrayBufferPrototypeGetByteLength(idlValue),
-),
+getDataViewOrTypedArrayBuffer(idlValue),
+getDataViewOrTypedArrayByteOffset(idlValue),
+getDataViewOrTypedArrayByteLength(idlValue),
+) :
+newUint8Array(
+idlValue,
+0,
+ArrayBufferPrototypeGetByteLength(idlValue),
+);
+normalizedAlgorithm[member]=TypedArrayPrototypeSlice(
+idlValueBytes,
 );
 }elseif(idlType==='HashAlgorithmIdentifier'){
 normalizedAlgorithm[member]=normalizeAlgorithm(idlValue,'digest');
@@ -1003,6 +1051,8 @@ module.exports = {
  cleanupWebCryptoResult,
  prepareWebCryptoResult,
  validateMaxBufferLength,
+ numBitsToBytes,
+ truncateToBitLength,
  bigIntArrayToUnsignedBigInt,
  bigIntArrayToUnsignedInt,
  getBlockSize,