wip

Author: panva

benchmark/crypto/webcrypto-sync-fast-path-cipher.js

@@ -5,6 +5,7 @@ const {
   importSecretKey,
   isSupported,
   kThresholdSizeLabels,
+  kWebCryptoSyncFastPathThreshold,
   measureAsync,
   ptn,
   thresholdSize,
@@ -20,6 +21,8 @@ const keyAlgorithms = {
   'ChaCha20-Poly1305': { name: 'ChaCha20-Poly1305' },
 };
 
+const kAesCbcCtrEncryptSyncFastPathThreshold = 32 * 1024;
+
 function supportParams(algorithm) {
   switch (algorithm) {
     case 'AES-CBC':
@@ -90,22 +93,45 @@ function cipherParams(algorithm, size) {
   throw new Error(`Unknown cipher algorithm: ${algorithm}`);
 }
 
-function dataSize(algorithm, size) {
+function syncFastPathThreshold(algorithm, operation) {
+  return operation === 'encrypt' &&
+    (algorithm === 'AES-CBC' || algorithm === 'AES-CTR') ?
+    kAesCbcCtrEncryptSyncFastPathThreshold :
+    kWebCryptoSyncFastPathThreshold;
+}
+
+function measuredInputOverhead(algorithm, operation) {
   switch (algorithm) {
-    case 'AES-CBC':
-      return thresholdSize(size, { minimum: 16, multiple: 16 });
+    case 'AES-GCM':
+    case 'AES-OCB':
+    case 'ChaCha20-Poly1305':
+      return operation === 'decrypt' ? 32 : 16;
     default:
-      return thresholdSize(size);
+      return 0;
   }
 }
 
+function dataSize(algorithm, operation, size) {
+  const minimum = algorithm === 'AES-CBC' ? 16 : 1;
+  if (size === 'minimal')
+    return minimum;
+
+  const overhead = measuredInputOverhead(algorithm, operation);
+  const multiple = algorithm === 'AES-CBC' ? 16 : 1;
+  return thresholdSize(size, {
+    minimum: minimum + overhead,
+    multiple,
+    threshold: syncFastPathThreshold(algorithm, operation),
+  }) - overhead;
+}
+
 async function setupCipherOperation(algorithm, operation, size) {
   const key = await importSecretKey({
     algorithm: keyAlgorithms[algorithm],
     usages: ['encrypt', 'decrypt'],
     length: algorithm === 'ChaCha20-Poly1305' ? 32 : 16,
   });
-  const data = ptn(dataSize(algorithm, size));
+  const data = ptn(dataSize(algorithm, operation, size));
 
   const params = cipherParams(algorithm, size);
   if (operation === 'encrypt') {

benchmark/crypto/webcrypto-sync-fast-path-kdf.js

@@ -4,13 +4,13 @@ const common = require('../common.js');
 const {
   importSecretKey,
   kThresholdSizeLabels,
-  kWebCryptoSyncFastPathThreshold,
   measureAsync,
   ptn,
 } = require('./_webcrypto_sync_fast_path_common.js');
 
 const { subtle } = globalThis.crypto;
 
+const kHkdfSyncFastPathThreshold = 16 * 1024;
 const kOutputBytes = 32;
 
 const bench = common.createBenchmark(main, {
@@ -25,11 +25,11 @@ function aggregateSize(label) {
     case 'minimal':
       return kOutputBytes;
     case 'middle':
-      return kWebCryptoSyncFastPathThreshold / 2;
+      return kHkdfSyncFastPathThreshold / 2;
     case 'at-threshold':
-      return kWebCryptoSyncFastPathThreshold;
+      return kHkdfSyncFastPathThreshold;
     case 'after-threshold':
-      return kWebCryptoSyncFastPathThreshold + 1;
+      return kHkdfSyncFastPathThreshold + 1;
   }
   throw new Error(`Unknown HKDF size label: ${label}`);
 }

benchmark/crypto/webcrypto-sync-fast-path-mac.js

@@ -5,6 +5,7 @@ const {
   importSecretKey,
   isSupported,
   kThresholdSizeLabels,
+  kWebCryptoSyncFastPathThreshold,
   measureAsync,
   ptn,
   thresholdSize,
@@ -24,6 +25,8 @@ const signAlgorithms = {
   KMAC256: { name: 'KMAC256', outputLength: 256 },
 };
 
+const kKmacSyncFastPathThreshold = 16 * 1024;
+
 const algorithms = Object.keys(keyAlgorithms)
   .filter((name) => isSupported('sign', signAlgorithms[name]));
 
@@ -40,13 +43,38 @@ const bench = common.createBenchmark(main, {
   n: [1e3],
 });
 
+function outputByteLength(algorithm) {
+  return algorithm === 'HMAC' ? 32 : signAlgorithms[algorithm].outputLength / 8;
+}
+
+function syncFastPathThreshold(algorithm) {
+  return algorithm === 'HMAC' ?
+    kWebCryptoSyncFastPathThreshold : kKmacSyncFastPathThreshold;
+}
+
+function dataSize(algorithm, operation, size) {
+  if (size === 'minimal')
+    return 1;
+
+  let overhead = 0;
+  if (operation === 'verify')
+    overhead += outputByteLength(algorithm);
+  if (algorithm !== 'HMAC')
+    overhead += outputByteLength(algorithm);
+
+  return thresholdSize(size, {
+    minimum: overhead + 1,
+    threshold: syncFastPathThreshold(algorithm),
+  }) - overhead;
+}
+
 async function setupMacOperation(algorithm, operation, size) {
   const key = await importSecretKey({
     algorithm: keyAlgorithms[algorithm],
     usages: ['sign', 'verify'],
     length: 32,
   });
-  const data = ptn(thresholdSize(size));
+  const data = ptn(dataSize(algorithm, operation, size));
   const params = signAlgorithms[algorithm];
 
   if (operation === 'sign') {

lib/internal/crypto/aes.js

@@ -8,6 +8,7 @@ const {
 const {
   AESCipherJob,
   kCryptoJobWebCrypto,
+  kWebCryptoCipherEncrypt,
   kKeyVariantAES_CTR_128,
   kKeyVariantAES_CBC_128,
   kKeyVariantAES_GCM_128,
@@ -34,6 +35,8 @@ const {
   kWebCryptoDefaultSyncThreshold,
 } = require('internal/crypto/util');
 
+const kWebCryptoAesCbcCtrEncryptSyncThreshold = 32 * 1024;
+
 const {
   lazyDOMException,
 } = require('internal/util');
@@ -108,7 +111,10 @@ function getVariant(name, length) {
 }
 
 function asyncAesCtrCipher(mode, key, data, algorithm) {
-  const jobMode = data.byteLength <= kWebCryptoDefaultSyncThreshold ?
+  const threshold = mode === kWebCryptoCipherEncrypt ?
+    kWebCryptoAesCbcCtrEncryptSyncThreshold :
+    kWebCryptoDefaultSyncThreshold;
+  const jobMode = data.byteLength <= threshold ?
     getWebCryptoJobMode() : kCryptoJobWebCrypto;
   return jobPromise(() => new AESCipherJob(
     jobMode,
@@ -121,7 +127,10 @@ function asyncAesCtrCipher(mode, key, data, algorithm) {
 }
 
 function asyncAesCbcCipher(mode, key, data, algorithm) {
-  const jobMode = data.byteLength <= kWebCryptoDefaultSyncThreshold ?
+  const threshold = mode === kWebCryptoCipherEncrypt ?
+    kWebCryptoAesCbcCtrEncryptSyncThreshold :
+    kWebCryptoDefaultSyncThreshold;
+  const jobMode = data.byteLength <= threshold ?
     getWebCryptoJobMode() : kCryptoJobWebCrypto;
   return jobPromise(() => new AESCipherJob(
     jobMode,

lib/internal/crypto/hkdf.js

@@ -23,6 +23,7 @@ const { kMaxLength } = require('buffer');
 const {
   getWebCryptoJobModeForInputLength,
   jobPromise,
+  kWebCryptoHkdfSyncThreshold,
   normalizeHashName,
   toBuf,
   validateByteSource,
@@ -157,7 +158,8 @@ function hkdfDeriveBits(algorithm, baseKey, length) {
     return PromiseResolve(new ArrayBuffer(0));
 
   const jobMode = getWebCryptoJobModeForInputLength(
-    salt.byteLength + info.byteLength + length / 8);
+    salt.byteLength + info.byteLength + length / 8,
+    kWebCryptoHkdfSyncThreshold);
   return jobPromise(() => new HKDFJob(
     jobMode,
     normalizeHashName(hash.name),

lib/internal/crypto/mac.js

@@ -20,6 +20,7 @@ const {
   getWebCryptoJobModeForInputLength,
   hasAnyNotIn,
   jobPromise,
+  kWebCryptoKmacSyncThreshold,
   normalizeHashName,
 } = require('internal/crypto/util');
 
@@ -195,7 +196,8 @@ function kmacSignVerify(key, data, algorithm, signature) {
   const signatureLength = signature?.byteLength ?? 0;
   const outputByteLength = algorithm.outputLength / 8;
   const jobMode = getWebCryptoJobModeForInputLength(
-    data.byteLength + signatureLength + outputByteLength);
+    data.byteLength + signatureLength + outputByteLength,
+    kWebCryptoKmacSyncThreshold);
   return jobPromise(() => new KmacJob(
     jobMode,
     mode,

lib/internal/crypto/util.js

@@ -695,6 +695,8 @@ function cleanupWebCryptoResult(value) {
 }
 
 const kWebCryptoDefaultSyncThreshold = 64 * 1024;
+const kWebCryptoHkdfSyncThreshold = 16 * 1024;
+const kWebCryptoKmacSyncThreshold = 16 * 1024;
 const kWebCryptoRsaSyncMaxModulusLength = 4096;
 const kWebCryptoMaxSyncJobsPerTurn = 1;
 const kWebCryptoParallelPressureAsyncJobs = 1024;
@@ -733,8 +735,11 @@ function getWebCryptoJobMode() {
     kCryptoJobSyncWebCrypto : kCryptoJobWebCrypto;
 }
 
-function getWebCryptoJobModeForInputLength(byteLength) {
-  return byteLength <= kWebCryptoDefaultSyncThreshold ?
+function getWebCryptoJobModeForInputLength(
+  byteLength,
+  threshold = kWebCryptoDefaultSyncThreshold,
+) {
+  return byteLength <= threshold ?
     getWebCryptoJobMode() : kCryptoJobWebCrypto;
 }
 
@@ -1012,6 +1017,8 @@ module.exports = {
   kNamedCurveAliases,
   kSupportedAlgorithms,
   kWebCryptoDefaultSyncThreshold,
+  kWebCryptoHkdfSyncThreshold,
+  kWebCryptoKmacSyncThreshold,
   kWebCryptoRsaSyncMaxModulusLength,
   getWebCryptoJobMode,
   getWebCryptoJobModeForInputLength,

src/crypto/README.md

@@ -252,21 +252,99 @@ If the `CryptoJob` is processed as a Web Crypto API job, then
 `run()` returns a Promise. `kCryptoJobWebCrypto` dispatches the
 work to the libuv threadpool. `kCryptoJobSyncWebCrypto` performs
 the work synchronously on the current thread but still resolves or
-rejects the Promise using Web Crypto API semantics. This sync
-Web Crypto mode is used for selected small-input operations and
-selected low-cost public-key operations, plus Web Crypto symmetric
-and non-RSA asymmetric key generation. Sync Web Crypto selection is
-also limited by a small per-turn JavaScript budget so that sequential
-`await` usage can take the fast path while same-turn fanout falls back
-to asynchronous jobs.
-Operation-specific failures are rejected with an `OperationError`,
-and successful jobs resolve with the Web Crypto API result shape
-expected by the JavaScript implementation.
-
-The JavaScript Web Crypto layer keeps the thresholds close to the
-operation-specific call sites. The default small-input threshold is
-64 KiB. RSA public-key operations are only selected for sync Web Crypto
-mode with moduli up to 4096 bits.
+rejects the Promise using Web Crypto API semantics. Operation-specific
+failures are rejected with an `OperationError`, and successful jobs
+resolve with the Web Crypto API result shape expected by the
+JavaScript implementation.
+
+The JavaScript Web Crypto layer decides between `kCryptoJobWebCrypto`
+and `kCryptoJobSyncWebCrypto` before the native job is constructed.
+The decision must be made at that point because async jobs need
+threadsafe copies of BufferSource input, while sync Web Crypto jobs can
+borrow the caller's input for the duration of the immediate operation.
+A native job cannot safely start as sync and later fall back to async
+after it has been configured with sync-only input references.
+
+No Web Crypto operation is unconditionally sync. The sync path is only
+a fast-path candidate. A candidate still becomes async when its input
+is too large, when an operation-specific public-key limit rejects it,
+or when the same JavaScript turn has already consumed the sync budget.
+
+The default small-input threshold is 64 KiB. Call sites may use lower
+operation-specific thresholds when benchmarks show that parallel
+throughput is more sensitive to the synchronous first job. Current
+thresholds are:
+
+* 64 KiB by default.
+* 32 KiB for AES-CBC and AES-CTR encrypt.
+* 16 KiB for HKDF deriveBits.
+* 16 KiB for KMAC sign and verify.
+
+The byte length being compared is the amount of operation input that
+best predicts the native cost, not always a single Web Crypto argument:
+
+* Digest uses input data length plus output length.
+* AES-CBC, AES-CTR, and AES-KW use input data length.
+* AES-GCM, AES-OCB, and ChaCha20-Poly1305 use input data length plus
+  additional authenticated data length. For decrypt, input data already
+  includes the authentication tag.
+* HMAC uses input data length plus signature length for verify.
+* KMAC uses input data length plus signature length plus output length.
+* HKDF uses salt length plus info length plus derived output length.
+* ECDSA, EdDSA, and RSA verify use input data length.
+
+RSA public-key candidates are additionally limited to moduli up to
+4096 bits. RSA-OAEP encrypt can be a sync candidate under that modulus
+limit. RSA-OAEP decrypt, RSA sign, and RSA key generation remain
+async.
+
+Some candidates do not have a byte-size threshold because their input
+size is fixed or otherwise bounded by the operation. These include
+Web Crypto symmetric key generation, non-RSA asymmetric key generation,
+ML-KEM encapsulation and decapsulation, ECDH P-256 deriveBits, X25519
+deriveBits, X448 deriveBits, and RSA-OAEP encrypt with an allowed
+modulus size. These are still only sync candidates; same-turn fanout
+can force them async.
+
+The sync budget is intentionally small: at most one sync Web Crypto
+candidate is allowed in a JavaScript turn. Here "turn" means the
+continuous JavaScript execution slice before the next microtask
+checkpoint. When the first candidate reserves the sync slot, Node.js
+queues a microtask that resets the per-turn counter. Sequential
+`await` usage yields to the microtask queue between operations, so it
+can keep taking the sync fast path:
+
+```js
+await subtle.digest('SHA-256', data);
+await subtle.digest('SHA-256', data);
+```
+
+Same-turn fanout does not give the reset microtask a chance to run
+between job creations:
+
+```js
+const a = subtle.digest('SHA-256', data);
+const b = subtle.digest('SHA-256', data);
+await Promise.all([a, b]);
+```
+
+In that case the first eligible job may run sync, the second eligible
+job runs async, and a short async pressure window is enabled. The
+pressure window forces the next 1024 eligible candidates to async. If a
+single synchronous burst creates more jobs than that, the per-turn sync
+counter is still used, so the pressure window is re-armed instead of
+letting another sync job through.
+
+The pressure window is a heuristic, not a Web Crypto API requirement.
+It exists because a replenished Promise pipeline can otherwise run one
+sync job from each Promise reaction while still trying to measure or
+use parallel throughput. Once same-turn fanout has been observed, the
+workload is treated as throughput-oriented for a while and candidates
+are sent to the threadpool. This protects parallel throughput without
+requiring precise active-job accounting in the native layer, but it
+also means that a small fanout can make later otherwise-eligible jobs
+async until the pressure counter drains. Changes to this policy should
+be justified with serial and parallel Web Crypto benchmarks.
 
 For `CipherJob` types, the output is always an `ArrayBuffer`.