crypto: add SHAKE Web Cryptography digest algorithms

PR-URL: #59365
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Ethan Arrowood <[email protected]>
Reviewed-By: Yagiz Nizipli <[email protected]>
Reviewed-By: Joyee Cheung <[email protected]>

Author: panva

doc/api/webcrypto.md

@@ -2,6 +2,9 @@
 
 <!-- YAML
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/59365
+    description: SHAKE algorithms are now supported.
   - version: REPLACEME
     pr-url: https://github.com/nodejs/node/pull/59365
     description: ML-DSA algorithms are now supported.
@@ -91,6 +94,8 @@ WICG proposal:
 
 Algorithms:
 
+* `'cSHAKE128'`
+* `'cSHAKE256'`
 * `'ML-DSA-44'`[^openssl35]
 * `'ML-DSA-65'`[^openssl35]
 * `'ML-DSA-87'`[^openssl35]
@@ -472,6 +477,8 @@ implementation and the APIs supported for each:
 | `'AES-CTR'`                  | ✔             | ✔           | ✔           | ✔         | ✔         | ✔         | ✔           |              |             |        |          |          |
 | `'AES-GCM'`                  | ✔             | ✔           | ✔           | ✔         | ✔         | ✔         | ✔           |              |             |        |          |          |
 | `'AES-KW'`                   | ✔             | ✔           | ✔           |           |           | ✔         | ✔           |              |             |        |          |          |
+| `'cSHAKE128'`[^modern-algos] |               |             |             |           |           |           |             |              |             |        |          | ✔        |
+| `'cSHAKE256'`[^modern-algos] |               |             |             |           |           |           |             |              |             |        |          | ✔        |
 | `'ECDH'`                     | ✔             | ✔           | ✔           |           |           |           |             | ✔            | ✔           |        |          |          |
 | `'ECDSA'`                    | ✔             | ✔           | ✔           |           |           |           |             |              |             | ✔      | ✔        |          |
 | `'Ed25519'`                  | ✔             | ✔           | ✔           |           |           |           |             |              |             | ✔      | ✔        |          |
@@ -800,9 +807,13 @@ The algorithms currently supported include:
 
 <!-- YAML
 added: v15.0.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/59365
+    description: SHAKE algorithms are now supported.
 -->
 
-* `algorithm` {string|Algorithm}
+* `algorithm` {string|Algorithm|CShakeParams}
 * `data` {ArrayBuffer|TypedArray|DataView|Buffer}
 * Returns: {Promise} Fulfills with an {ArrayBuffer} upon success.
 
@@ -812,6 +823,8 @@ with an {ArrayBuffer} containing the computed digest.
 
 If `algorithm` is provided as a {string}, it must be one of:
 
+* `'cSHAKE128'`[^modern-algos]
+* `'cSHAKE256'`[^modern-algos]
 * `'SHA-1'`
 * `'SHA-256'`
 * `'SHA-384'`
@@ -1423,6 +1436,53 @@ the message.
 The Node.js Web Crypto API implementation only supports zero-length context
 which is equivalent to not providing context at all.
 
+### Class: `CShakeParams`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+#### `cShakeParams.customization`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* 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.
+
+#### `cShakeParams.functionName`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {ArrayBuffer|TypedArray|DataView|Buffer|undefined}
+
+The `functionName` member represents 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.
+
+#### `cShakeParams.length`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {number} represents the requested output length in bits.
+
+#### `cShakeParams.name`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {string} Must be `'cSHAKE128'`[^modern-algos] or `'cSHAKE256'`[^modern-algos]
+
 ### Class: `EcdhKeyDeriveParams`
 
 <!-- YAML

lib/internal/crypto/hash.js

@@ -211,10 +211,15 @@ async function asyncDigest(algorithm, data) {
     case 'SHA-384':
       // Fall through
     case 'SHA-512':
+      // Fall through
+    case 'cSHAKE128':
+      // Fall through
+    case 'cSHAKE256':
       return jobPromise(() => new HashJob(
         kCryptoJobAsync,
         normalizeHashName(algorithm.name),
-        data));
+        data,
+        algorithm.length));
   }
 
   throw lazyDOMException('Unrecognized algorithm name', 'NotSupportedError');

lib/internal/crypto/hashnames.js

@@ -49,6 +49,14 @@ const kHashNames = {
     [kHashContextJwkRsaOaep]: 'RSA-OAEP-512',
     [kHashContextJwkHmac]: 'HS512',
   },
+  shake128: {
+    [kHashContextNode]: 'shake128',
+    [kHashContextWebCrypto]: 'cSHAKE128',
+  },
+  shake256: {
+    [kHashContextNode]: 'shake256',
+    [kHashContextWebCrypto]: 'cSHAKE256',
+  },
 };
 
 {

lib/internal/crypto/mac.js

@@ -62,7 +62,7 @@ async function hmacGenerateKey(algorithm, extractable, keyUsages) {
 
   return new InternalCryptoKey(
     key,
-    { name, length, hash: { name: hash.name } },
+    { name, length, hash },
     ArrayFrom(usageSet),
     extractable);
 }

lib/internal/crypto/rsa.js

@@ -161,7 +161,7 @@ async function rsaKeyGenerate(
     name,
     modulusLength,
     publicExponent,
-    hash: { name: hash.name },
+    hash,
   };
 
   let publicUsages;

lib/internal/crypto/util.js

@@ -285,6 +285,8 @@ const experimentalAlgorithms = ObjectEntries({
     importKey: null,
     exportKey: null,
   },
+  'cSHAKE128': { digest: 'CShakeParams' },
+  'cSHAKE256': { digest: 'CShakeParams' },
 });
 
 for (const { 0: algorithm, 1: nid } of [
@@ -338,6 +340,10 @@ const simpleAlgorithmDictionaries = {
   RsaOaepParams: { label: 'BufferSource' },
   RsaHashedImportParams: { hash: 'HashAlgorithmIdentifier' },
   EcKeyImportParams: {},
+  CShakeParams: {
+    functionName: 'BufferSource',
+    customization: 'BufferSource',
+  },
 };
 
 function validateMaxBufferLength(data, name) {

lib/internal/crypto/webidl.js

@@ -192,6 +192,16 @@ converters.object = (V, opts) => {
 
 const isNonSharedArrayBuffer = isArrayBuffer;
 
+function ensureSHA(V, label) {
+  if (
+    typeof V === 'string' ?
+      !V.toLowerCase().startsWith('sha') :
+      V.name?.toLowerCase?.().startsWith('sha') === false
+  )
+    throw lazyDOMException(
+      `Only SHA hashes are supported in ${label}`, 'NotSupportedError');
+}
+
 converters.Uint8Array = (V, opts = kEmptyObject) => {
   if (!ArrayBufferIsView(V) ||
     TypedArrayPrototypeGetSymbolToStringTag(V) !== 'Uint8Array') {
@@ -393,6 +403,7 @@ converters.RsaHashedKeyGenParams = createDictionaryConverter(
     {
       key: 'hash',
       converter: converters.HashAlgorithmIdentifier,
+      validator: (V, dict) => ensureSHA(V, 'RsaHashedKeyGenParams'),
       required: true,
     },
   ]);
@@ -403,6 +414,7 @@ converters.RsaHashedImportParams = createDictionaryConverter(
     {
       key: 'hash',
       converter: converters.HashAlgorithmIdentifier,
+      validator: (V, dict) => ensureSHA(V, 'RsaHashedImportParams'),
       required: true,
     },
   ]);
@@ -449,6 +461,7 @@ converters.HmacKeyGenParams = createDictionaryConverter(
     {
       key: 'hash',
       converter: converters.HashAlgorithmIdentifier,
+      validator: (V, dict) => ensureSHA(V, 'HmacKeyGenParams'),
       required: true,
     },
     {
@@ -503,6 +516,7 @@ converters.EcdsaParams = createDictionaryConverter(
     {
       key: 'hash',
       converter: converters.HashAlgorithmIdentifier,
+      validator: (V, dict) => ensureSHA(V, 'EcdsaParams'),
       required: true,
     },
   ]);
@@ -513,6 +527,7 @@ converters.HmacImportParams = createDictionaryConverter(
     {
       key: 'hash',
       converter: converters.HashAlgorithmIdentifier,
+      validator: (V, dict) => ensureSHA(V, 'HmacImportParams'),
       required: true,
     },
     {
@@ -573,6 +588,7 @@ converters.HkdfParams = createDictionaryConverter(
     {
       key: 'hash',
       converter: converters.HashAlgorithmIdentifier,
+      validator: (V, dict) => ensureSHA(V, 'HkdfParams'),
       required: true,
     },
     {
@@ -587,12 +603,40 @@ converters.HkdfParams = createDictionaryConverter(
     },
   ]);
 
+converters.CShakeParams = createDictionaryConverter(
+  'CShakeParams', [
+    ...new SafeArrayIterator(dictAlgorithm),
+    {
+      key: 'length',
+      converter: (V, opts) =>
+        converters['unsigned long'](V, { ...opts, enforceRange: true }),
+      validator: (V, opts) => {
+        // The Web Crypto spec allows for SHAKE output length that are not multiples of
+        // 8. We don't.
+        if (V % 8)
+          throw lazyDOMException('Unsupported CShakeParams length', 'NotSupportedError');
+      },
+      required: true,
+    },
+    {
+      key: 'functionName',
+      converter: converters.BufferSource,
+      validator: validateZeroLength('CShakeParams.functionName'),
+    },
+    {
+      key: 'customization',
+      converter: converters.BufferSource,
+      validator: validateZeroLength('CShakeParams.customization'),
+    },
+  ]);
+
 converters.Pbkdf2Params = createDictionaryConverter(
   'Pbkdf2Params', [
     ...new SafeArrayIterator(dictAlgorithm),
     {
       key: 'hash',
       converter: converters.HashAlgorithmIdentifier,
+      validator: (V, dict) => ensureSHA(V, 'Pbkdf2Params'),
       required: true,
     },
     {

test/parallel/test-webcrypto-derivebits-hkdf.js

@@ -306,7 +306,6 @@ async function testDeriveBitsBadHash(
           hash: 'PBKDF2'
         },
         baseKeys[size], 256), {
-        message: /Unrecognized algorithm name/,
         name: 'NotSupportedError',
       }),
   ]);
@@ -437,10 +436,7 @@ async function testDeriveKeyBadHash(
         keyType,
         true,
         usages),
-      {
-        message: /Unrecognized algorithm name/,
-        name: 'NotSupportedError',
-      }),
+      { name: 'NotSupportedError' }),
     assert.rejects(
       subtle.deriveKey(
         {
@@ -451,10 +447,7 @@ async function testDeriveKeyBadHash(
         keyType,
         true,
         usages),
-      {
-        message: /Unrecognized algorithm name/,
-        name: 'NotSupportedError',
-      }),
+      { name: 'NotSupportedError' }),
   ]);
 }