src: support outputLength in XOF hash functions

Aditi-1400 · Aditi-1400 · commit b9379c54566e · 2025-05-29T02:37:12.000+05:30
Support `outputLength` option in crypto.hash() for XOF hash
functions to align with the behaviour of crypto.createHash()
API
diff --git a/deps/ncrypto/ncrypto.cc b/deps/ncrypto/ncrypto.cc
@@ -4191,6 +4191,31 @@ DataPointer hashDigest(const Buffer<const unsigned char>& buf,
   return data.resize(result_size);
 }
 
+DataPointer xofHashDigest(const Buffer<const unsigned char>& buf,
+                          const EVP_MD* md,
+                          size_t output_length) {
+  if (md == nullptr) return {};
+
+  EVPMDCtxPointer ctx = EVPMDCtxPointer::New();
+  if (!ctx) return {};
+  if (EVP_DigestInit_ex(ctx, md, nullptr) != 1) {
+    return {};
+  }
+  if (EVP_DigestUpdate(ctx, buf.data, buf.len) != 1) {
+    return {};
+  }
+  auto data = DataPointer::Alloc(output_length);
+  if (!data) {
+    return {};
+  }
+  if (!EVP_DigestFinalXOF(
+          ctx, reinterpret_cast<unsigned char*>(data.get()), output_length)) {
+    return {};
+  }
+
+  return data;
+}
+
 // ============================================================================
 
 X509Name::X509Name() : name_(nullptr), total_(0) {}
diff --git a/deps/ncrypto/ncrypto.h b/deps/ncrypto/ncrypto.h
@@ -278,8 +278,13 @@ class Digest final {
   const EVP_MD* md_ = nullptr;
 };
 
+// Computes a fixed-length digest.
 DataPointer hashDigest(const Buffer<const unsigned char>& data,
                        const EVP_MD* md);
+// Computes a variable-length digest for XOF algorithms (e.g. SHAKE128).
+DataPointer xofHashDigest(const Buffer<const unsigned char>& data,
+                          const EVP_MD* md,
+                          size_t length);
 
 class Cipher final {
  public:
diff --git a/doc/api/crypto.md b/doc/api/crypto.md
@@ -4203,7 +4203,7 @@ A convenient alias for [`crypto.webcrypto.getRandomValues()`][]. This
 implementation is not compliant with the Web Crypto spec, to write
 web-compatible code use [`crypto.webcrypto.getRandomValues()`][] instead.
 
-### `crypto.hash(algorithm, data[, outputEncoding])`
+### `crypto.hash(algorithm, data[, options])`
 
 <!-- YAML
 added:
@@ -4219,8 +4219,12 @@ added:
   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.
-* `outputEncoding` {string|undefined}  [Encoding][encoding] used to encode the
-  returned digest. **Default:** `'hex'`.
+* `options` {Object|string}
+  * `outputEncoding` {string|undefined}  [Encoding][encoding] used to encode the
+    returned digest. **Default:** `'hex'`.
+  * `outputLength` {number|undefined} For XOF hash functions such as 'shake256',
+    the outputLength option can be used to specify the desired output length in bytes.
+    **Default:** `undefined`
 * Returns: {string|Buffer}
 
 A utility for creating one-shot hash digests of data. It can be faster than
diff --git a/lib/internal/crypto/hash.js b/lib/internal/crypto/hash.js
@@ -193,11 +193,24 @@ async function asyncDigest(algorithm, data) {
   throw lazyDOMException('Unrecognized algorithm name', 'NotSupportedError');
 }
 
-function hash(algorithm, input, outputEncoding = 'hex') {
+function hash(algorithm, input, options = {}) {
   validateString(algorithm, 'algorithm');
   if (typeof input !== 'string' && !isArrayBufferView(input)) {
     throw new ERR_INVALID_ARG_TYPE('input', ['Buffer', 'TypedArray', 'DataView', 'string'], input);
   }
+  let outputEncoding = 'hex';
+  let outputLength;
+
+  if (options !== null && typeof options !== 'function') {
+    if (typeof options === 'string') {
+      outputEncoding = options;
+    } else if (typeof options === 'object') {
+      ({ outputEncoding = 'hex', outputLength } = options);
+    } else {
+      throw new ERR_INVALID_ARG_TYPE('options', ['object', 'string'], options);
+    }
+  }
+
   let normalized = outputEncoding;
   // Fast case: if it's 'hex', we don't need to validate it further.
   if (outputEncoding !== 'hex') {
@@ -213,8 +226,14 @@ function hash(algorithm, input, outputEncoding = 'hex') {
       }
     }
   }
+  if (outputLength !== undefined) {
+    validateUint32(outputLength, 'outputLength');
+    if (outputLength === 0) {
+      return normalized === 'buffer' ? Buffer.alloc(0) : '';
+    }
+  }
   return oneShotDigest(algorithm, getCachedHashId(algorithm), getHashCache(),
-                       input, normalized, encodingsMap[normalized]);
+                       input, normalized, encodingsMap[normalized], outputLength);
 }
 
 module.exports = {
diff --git a/src/crypto/crypto_hash.cc b/src/crypto/crypto_hash.cc
@@ -208,17 +208,18 @@ const EVP_MD* GetDigestImplementation(Environment* env,
 }
 
 // crypto.digest(algorithm, algorithmId, algorithmCache,
-//               input, outputEncoding, outputEncodingId)
+//               input, outputEncoding, outputEncodingId, outputLength)
 void Hash::OneShotDigest(const FunctionCallbackInfo<Value>& args) {
   Environment* env = Environment::GetCurrent(args);
   Isolate* isolate = env->isolate();
-  CHECK_EQ(args.Length(), 6);
+  CHECK_EQ(args.Length(), 7);
   CHECK(args[0]->IsString());                                  // algorithm
   CHECK(args[1]->IsInt32());                                   // algorithmId
   CHECK(args[2]->IsObject());                                  // algorithmCache
   CHECK(args[3]->IsString() || args[3]->IsArrayBufferView());  // input
   CHECK(args[4]->IsString());                                  // outputEncoding
   CHECK(args[5]->IsUint32() || args[5]->IsUndefined());  // outputEncodingId
+  CHECK(args[6]->IsUint32() || args[6]->IsUndefined());  // outputLength
 
   const EVP_MD* md = GetDigestImplementation(env, args[0], args[1], args[2]);
   if (md == nullptr) [[unlikely]] {
@@ -230,21 +231,39 @@ void Hash::OneShotDigest(const FunctionCallbackInfo<Value>& args) {
 
   enum encoding output_enc = ParseEncoding(isolate, args[4], args[5], HEX);
 
-  DataPointer output = ([&] {
+  DataPointer output = ([&]() -> DataPointer {
+    Utf8Value utf8(isolate, args[3]);
+    ncrypto::Buffer<const unsigned char> buf;
     if (args[3]->IsString()) {
-      Utf8Value utf8(isolate, args[3]);
-      ncrypto::Buffer<const unsigned char> buf{
+      buf = {
           .data = reinterpret_cast<const unsigned char*>(utf8.out()),
           .len = utf8.length(),
       };
-      return ncrypto::hashDigest(buf, md);
+    } else {
+      ArrayBufferViewContents<unsigned char> input(args[3]);
+      buf = {
+          .data = reinterpret_cast<const unsigned char*>(input.data()),
+          .len = input.length(),
+      };
     }
 
-    ArrayBufferViewContents<unsigned char> input(args[3]);
-    ncrypto::Buffer<const unsigned char> buf{
-        .data = reinterpret_cast<const unsigned char*>(input.data()),
-        .len = input.length(),
-    };
+    if (!args[6]->IsUndefined()) {
+      bool isXOF = (EVP_MD_flags(md) & EVP_MD_FLAG_XOF) != 0;
+      int output_length = args[6].As<Uint32>()->Value();
+      if (isXOF) {
+        return ncrypto::xofHashDigest(buf, md, output_length);
+      }
+      if (output_length != EVP_MD_get_size(md)) {
+        Utf8Value method(isolate, args[0]);
+        std::string message = "Output length " + std::to_string(output_length) +
+                              " is invalid for ";
+        message += method.ToString() + ", which does not support XOF";
+        ThrowCryptoError(env, ERR_get_error(), message.c_str());
+        return {};
+      }
+      // Does not support XOF but output length matches expected digest size.
+      // Compute digest as usual.
+    }
     return ncrypto::hashDigest(buf, md);
   })();
 
diff --git a/test/parallel/test-crypto-oneshot-hash-xof.js b/test/parallel/test-crypto-oneshot-hash-xof.js
@@ -0,0 +1,95 @@
+'use strict';
+// This tests crypto.hash() works.
+const common = require('../common');
+
+if (!common.hasCrypto) common.skip('missing crypto');
+
+const assert = require('assert');
+const crypto = require('crypto');
+
+// Test XOF hash functions and the outputLength option.
+{
+  // Default outputLengths.
+  assert.strictEqual(
+    crypto.hash('shake128', '', 'hex'),
+    crypto.createHash('shake128').update('').digest('hex')
+  );
+
+  assert.strictEqual(
+    crypto.hash('shake256', '', 'hex'),
+    crypto.createHash('shake256').update('').digest('hex')
+  );
+
+  // Short outputLengths.
+  assert.strictEqual(crypto.hash('shake128', '', { encoding: 'hex', outputLength: 0 }),
+                     crypto.createHash('shake128', { outputLength: 0 })
+                     .update('').digest('hex'));
+
+  assert.strictEqual(
+    crypto.hash('shake128', '', { outputEncoding: 'hex', outputLength: 5 }),
+    crypto.createHash('shake128', { outputLength: 5 }).update('').digest('hex')
+  );
+  // Check length
+  assert.strictEqual(
+    crypto.hash('shake128', '', { outputEncoding: 'hex', outputLength: 5 }).length,
+    crypto.createHash('shake128', { outputLength: 5 }).update('').digest('hex')
+      .length
+  );
+
+  assert.strictEqual(
+    crypto.hash('shake128', '', { outputEncoding: 'hex', outputLength: 15 }),
+    crypto.createHash('shake128', { outputLength: 15 }).update('').digest('hex')
+  );
+  // Check length
+  assert.strictEqual(
+    crypto.hash('shake128', '', { outputEncoding: 'hex', outputLength: 15 }).length,
+    crypto.createHash('shake128', { outputLength: 15 }).update('').digest('hex')
+      .length
+  );
+
+  assert.strictEqual(
+    crypto.hash('shake256', '', { outputEncoding: 'hex', outputLength: 16 }),
+    crypto.createHash('shake256', { outputLength: 16 }).update('').digest('hex')
+  );
+  // Check length
+  assert.strictEqual(
+    crypto.hash('shake256', '', { outputEncoding: 'hex', outputLength: 16 }).length,
+    crypto.createHash('shake256', { outputLength: 16 }).update('').digest('hex')
+      .length
+  );
+
+  // Large outputLengths.
+  assert.strictEqual(
+    crypto.hash('shake128', '', { outputEncoding: 'hex', outputLength: 128 }),
+    crypto
+      .createHash('shake128', { outputLength: 128 }).update('')
+      .digest('hex')
+  );
+  // Check length without encoding
+  assert.strictEqual(
+    crypto.hash('shake128', '', { outputLength: 128 }).length,
+    crypto
+      .createHash('shake128', { outputLength: 128 }).update('')
+      .digest('hex').length
+  );
+  assert.strictEqual(
+    crypto.hash('shake256', '', { outputLength: 128 }),
+    crypto
+      .createHash('shake256', { outputLength: 128 }).update('')
+      .digest('hex')
+  );
+
+  const actual = crypto.hash('shake256', 'The message is shorter than the hash!', { outputLength: 1024 * 1024 });
+  const expected = crypto
+    .createHash('shake256', {
+      outputLength: 1024 * 1024,
+    })
+    .update('The message is shorter than the hash!')
+    .digest('hex');
+  assert.strictEqual(actual, expected);
+
+  // Non-XOF hash functions should accept valid outputLength options as well.
+  assert.strictEqual(crypto.hash('sha224', '', 'hex', 28),
+                     'd14a028c2a3a2bc9476102bb288234c4' +
+                     '15a2b01f828ea62ac5b3e42f');
+}
diff --git a/test/parallel/test-crypto-oneshot-hash.js b/test/parallel/test-crypto-oneshot-hash.js
@@ -20,7 +20,7 @@ const fs = require('fs');
   assert.throws(() => { crypto.hash('sha1', invalid); }, { code: 'ERR_INVALID_ARG_TYPE' });
 });
 
-[null, true, 1, () => {}, {}].forEach((invalid) => {
+[0, 1, NaN, true, Symbol(0)].forEach((invalid) => {
   assert.throws(() => { crypto.hash('sha1', 'test', invalid); }, { code: 'ERR_INVALID_ARG_TYPE' });
 });
 
