crypto: add SubtleCrypto.supports feature detection in Web Crypto API

Author: panva

doc/api/webcrypto.md

@@ -351,6 +351,74 @@ async function digest(data, algorithm = 'SHA-512') {
 }
 ```
 
+### Checking for runtime algorithm support
+
+> Stability: 1.0 - Early development. SubleCrypto.supports is an experimental
+> implementation based on [Modern Algorithms in the Web Cryptography API][] as
+> of 8 January 2025
+
+This example derives a key from a password using Argon2, if available,
+or PBKDF2, otherwise; and then encrypts and decrypts some text with it
+using AES-OCB, if available, and AES-GCM, otherwise.
+
+```mjs
+const password = 'correct horse battery staple';
+const derivationAlg =
+  SubtleCrypto.supports?.('importKey', 'Argon2id') ?
+    'Argon2id' :
+    'PBKDF2';
+const encryptionAlg =
+  SubtleCrypto.supports?.('importKey', 'AES-OCB') ?
+    'AES-OCB' :
+    'AES-GCM';
+const passwordKey = await crypto.subtle.importKey(
+  'raw',
+  new TextEncoder().encode(password),
+  derivationAlg,
+  false,
+  ['deriveKey'],
+);
+const nonce = crypto.getRandomValues(new Uint8Array(16));
+const derivationParams =
+  derivationAlg === 'Argon2id' ?
+    {
+      nonce,
+      parallelism: 4,
+      memory: 2 ** 21,
+      passes: 1,
+    } :
+    {
+      salt: nonce,
+      iterations: 100_000,
+      hash: 'SHA-256',
+    };
+const key = await crypto.subtle.deriveKey(
+  {
+    name: derivationAlg,
+    ...derivationParams,
+  },
+  passwordKey,
+  {
+    name: encryptionAlg,
+    length: 256,
+  },
+  false,
+  ['encrypt', 'decrypt'],
+);
+const plaintext = 'Hello, world!';
+const iv = crypto.getRandomValues(new Uint8Array(16));
+const encrypted = await crypto.subtle.encrypt(
+  { name: encryptionAlg, iv },
+  key,
+  new TextEncoder().encode(plaintext),
+);
+const decrypted = new TextDecoder().decode(await crypto.subtle.decrypt(
+  { name: encryptionAlg, iv },
+  key,
+  encrypted,
+));
+```
+
 ## Algorithm matrix
 
 The table details the algorithms supported by the Node.js Web Crypto API
@@ -549,6 +617,28 @@ added: v15.0.0
 added: v15.0.0
 -->
 
+### Static method: `SubtleCrypto.supports(operation, algorithm[, lengthOrAdditionalAlgorithm])`
+
+> Stability: 1.0 - Early development. An experimental implementation of SubtleCrypto.supports from
+> [Modern Algorithms in the Web Cryptography API][] as of 8 January 2025
+
+<!-- YAML
+added: REPLACEME
+-->
+
+<!--lint disable maximum-line-length remark-lint-->
+
+* `operation`: {string} "encrypt", "decrypt", "sign", "verify", "digest", "generateKey", "deriveKey", "deriveBits", "importKey", "exportKey", "wrapKey" or "unwrapKey"
+* `algorithm`: {AesCbcParams|AesCtrParams|AesGcmParams|AesKeyGenParams|AlgorithmIdentifier|EcdhKeyDeriveParams|EcdsaParams|EcKeyGenParams|EcKeyImportParams|Ed448Params|HkdfParams|HmacImportParams|HmacKeyGenParams|Pbkdf2Params|RsaHashedImportParams|RsaHashedKeyGenParams|RsaOaepParams|RsaPssParams|string}
+* `lengthOrAdditionalAlgorithm`: Depending on the operation this is either ignored, the value of the SubtleCrypto method's length argument, the algorithm of key to be derived when operation is "deriveKey", the algorithm of key to be exported before wrapping when operation is "wrapKey", and the algorithm of key to be imported after unwrapping when operation is "unwrapKey"
+* Returns: {boolean} Indicating whether the implementation supports the given operation
+
+<!--lint enable maximum-line-length remark-lint-->
+
+Allows feature detection in Web Crypto API, which can be used to detect whether
+a given algorithm identifier (including any of its parameters) is supported for
+the given operation.
+
 ### `subtle.decrypt(algorithm, key, data)`
 
 <!-- YAML
@@ -1653,6 +1743,7 @@ The length (in bytes) of the random salt to use.
 
 [JSON Web Key]: https://tools.ietf.org/html/rfc7517
 [Key usages]: #cryptokeyusages
+[Modern Algorithms in the Web Cryptography API]: https://twiss.github.io/webcrypto-modern-algos/
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
 [RFC 4122]: https://www.rfc-editor.org/rfc/rfc4122.txt
 [Secure Curves in the Web Cryptography API]: https://wicg.github.io/webcrypto-secure-curves/

lib/internal/crypto/aes.js

@@ -4,7 +4,6 @@ const {
   ArrayBufferIsView,
   ArrayBufferPrototypeSlice,
   ArrayFrom,
-  ArrayPrototypeIncludes,
   ArrayPrototypePush,
   MathFloor,
   PromiseReject,
@@ -35,10 +34,7 @@ const {
 const {
   hasAnyNotIn,
   jobPromise,
-  validateByteLength,
   validateKeyOps,
-  validateMaxBufferLength,
-  kAesKeyLengths,
   kHandle,
   kKeyObject,
 } = require('internal/crypto/util');
@@ -58,7 +54,6 @@ const {
   generateKey: _generateKey,
 } = require('internal/crypto/keygen');
 
-const kTagLengths = [32, 64, 96, 104, 112, 120, 128];
 const generateKey = promisify(_generateKey);
 
 function getAlgorithmName(name, length) {
@@ -108,20 +103,7 @@ function getVariant(name, length) {
   }
 }
 
-function validateAesCtrAlgorithm(algorithm) {
-  validateByteLength(algorithm.counter, 'algorithm.counter', 16);
-  // The length must specify an integer between 1 and 128. While
-  // there is no default, this should typically be 64.
-  if (algorithm.length === 0 || algorithm.length > 128) {
-    throw lazyDOMException(
-      'AES-CTR algorithm.length must be between 1 and 128',
-      'OperationError');
-  }
-}
-
 function asyncAesCtrCipher(mode, key, data, algorithm) {
-  validateAesCtrAlgorithm(algorithm);
-
   return jobPromise(() => new AESCipherJob(
     kCryptoJobAsync,
     mode,
@@ -132,12 +114,7 @@ function asyncAesCtrCipher(mode, key, data, algorithm) {
     algorithm.length));
 }
 
-function validateAesCbcAlgorithm(algorithm) {
-  validateByteLength(algorithm.iv, 'algorithm.iv', 16);
-}
-
 function asyncAesCbcCipher(mode, key, data, algorithm) {
-  validateAesCbcAlgorithm(algorithm);
   return jobPromise(() => new AESCipherJob(
     kCryptoJobAsync,
     mode,
@@ -156,23 +133,8 @@ function asyncAesKwCipher(mode, key, data) {
     getVariant('AES-KW', key.algorithm.length)));
 }
 
-function validateAesGcmAlgorithm(algorithm) {
-  if (!ArrayPrototypeIncludes(kTagLengths, algorithm.tagLength)) {
-    throw lazyDOMException(
-      `${algorithm.tagLength} is not a valid AES-GCM tag length`,
-      'OperationError');
-  }
-
-  validateMaxBufferLength(algorithm.iv, 'algorithm.iv');
-
-  if (algorithm.additionalData !== undefined) {
-    validateMaxBufferLength(algorithm.additionalData, 'algorithm.additionalData');
-  }
-}
-
 function asyncAesGcmCipher(mode, key, data, algorithm) {
   algorithm.tagLength ??= 128;
-  validateAesGcmAlgorithm(algorithm);
 
   const tagByteLength = MathFloor(algorithm.tagLength / 8);
   let tag;
@@ -220,16 +182,7 @@ function aesCipher(mode, key, data, algorithm) {
   }
 }
 
-function validateAesGenerateKeyAlgorithm(algorithm) {
-  if (!ArrayPrototypeIncludes(kAesKeyLengths, algorithm.length)) {
-    throw lazyDOMException(
-      'AES key length must be 128, 192, or 256 bits',
-      'OperationError');
-  }
-}
-
 async function aesGenerateKey(algorithm, extractable, keyUsages) {
-  validateAesGenerateKeyAlgorithm(algorithm);
   const { name, length } = algorithm;
 
   const checkUsages = ['wrapKey', 'unwrapKey'];

lib/internal/crypto/cfrg.js

@@ -329,15 +329,7 @@ function cfrgImportKey(
     extractable);
 }
 
-function validateEdDSASignVerifyAlgorithm(algorithm) {
-  if (algorithm.name === 'Ed448' && algorithm.context?.byteLength) {
-    throw lazyDOMException(
-      'Non zero-length context is not yet supported.', 'NotSupportedError');
-  }
-}
-
 function eddsaSignVerify(key, data, algorithm, signature) {
-  validateEdDSASignVerifyAlgorithm(algorithm);
   const mode = signature === undefined ? kSignJobModeSign : kSignJobModeVerify;
   const type = mode === kSignJobModeSign ? 'private' : 'public';
 

lib/internal/crypto/diffiehellman.js

@@ -297,22 +297,9 @@ function diffieHellman(options) {
 }
 
 let masks;
-
-function validateEcdhDeriveBitsAlgorithmAndLength(algorithm, length) {
-  if (algorithm.public.type !== 'public') {
-    throw lazyDOMException(
-      'algorithm.public must be a public key', 'InvalidAccessError');
-  }
-
-  if (algorithm.name !== algorithm.public.algorithm.name) {
-    throw lazyDOMException(`algorithm.public must be an ${algorithm.name} key`, 'InvalidAccessError');
-  }
-}
-
 // The ecdhDeriveBits function is part of the Web Crypto API and serves both
 // deriveKeys and deriveBits functions.
 async function ecdhDeriveBits(algorithm, baseKey, length) {
-  validateEcdhDeriveBitsAlgorithmAndLength(algorithm, length);
   const { 'public': key } = algorithm;
 
   if (baseKey.type !== 'private') {

lib/internal/crypto/ec.js

@@ -1,7 +1,6 @@
 'use strict';
 
 const {
-  ObjectPrototypeHasOwnProperty,
   SafeSet,
 } = primordials;
 
@@ -76,16 +75,7 @@ function createECPublicKeyRaw(namedCurve, keyData) {
   return new PublicKeyObject(handle);
 }
 
-function validateEcKeyAlgorithm(algorithm) {
-  if (!ObjectPrototypeHasOwnProperty(kNamedCurveAliases, algorithm.namedCurve)) {
-    throw lazyDOMException(
-      'Unrecognized namedCurve',
-      'NotSupportedError');
-  }
-}
-
 async function ecGenerateKey(algorithm, extractable, keyUsages) {
-  validateEcKeyAlgorithm(algorithm);
   const { name, namedCurve } = algorithm;
 
   const usageSet = new SafeSet(keyUsages);
@@ -158,7 +148,6 @@ function ecImportKey(
   extractable,
   keyUsages,
 ) {
-  validateEcKeyAlgorithm(algorithm);
   const { name, namedCurve } = algorithm;
 
   let keyObject;

lib/internal/crypto/hkdf.js

@@ -138,7 +138,7 @@ function hkdfSync(hash, key, salt, info, length) {
 }
 
 const hkdfPromise = promisify(hkdf);
-function validateHkdfDeriveBitsAlgorithmAndLength(algorithm, length) {
+function validateHkdfDeriveBitsLength(length) {
   if (length === null)
     throw lazyDOMException('length cannot be null', 'OperationError');
   if (length % 8) {
@@ -149,7 +149,7 @@ function validateHkdfDeriveBitsAlgorithmAndLength(algorithm, length) {
 }
 
 async function hkdfDeriveBits(algorithm, baseKey, length) {
-  validateHkdfDeriveBitsAlgorithmAndLength(algorithm, length);
+  validateHkdfDeriveBitsLength(length);
   const { hash, salt, info } = algorithm;
 
   if (length === 0)
@@ -170,4 +170,5 @@ module.exports = {
   hkdf,
   hkdfSync,
   hkdfDeriveBits,
+  validateHkdfDeriveBitsLength,
 };

lib/internal/crypto/keygen.js

@@ -33,10 +33,6 @@ const {
   parsePrivateKeyEncoding,
 } = require('internal/crypto/keys');
 
-const {
-  kAesKeyLengths,
-} = require('internal/crypto/util');
-
 const {
   customPromisifyArgs,
   kEmptyObject,
@@ -355,7 +351,7 @@ function generateKeyJob(mode, keyType, options) {
       validateInteger(length, 'options.length', 8, 2 ** 31 - 1);
       break;
     case 'aes':
-      validateOneOf(length, 'options.length', kAesKeyLengths);
+      validateOneOf(length, 'options.length', [128, 192, 256]);
       break;
     default:
       throw new ERR_INVALID_ARG_VALUE(

lib/internal/crypto/mac.js

@@ -40,24 +40,7 @@ const {
 
 const generateKey = promisify(_generateKey);
 
-function validateHmacGenerateKeyAlgorithm(algorithm) {
-  if (algorithm.length !== undefined) {
-    if (algorithm.length === 0)
-      throw lazyDOMException(
-        'Zero-length key is not supported',
-        'OperationError');
-
-    // The Web Crypto spec allows for key lengths that are not multiples of 8. We don't.
-    if (algorithm.length % 8) {
-      throw lazyDOMException(
-        'Unsupported algorithm.length',
-        'NotSupportedError');
-    }
-  }
-}
-
 async function hmacGenerateKey(algorithm, extractable, keyUsages) {
-  validateHmacGenerateKeyAlgorithm(algorithm);
   const { hash, name } = algorithm;
   let { length } = algorithm;
 
@@ -96,27 +79,13 @@ function getAlgorithmName(hash) {
   }
 }
 
-function validateHmacImportKeyAlgorithm(algorithm) {
-  if (algorithm.length !== undefined) {
-    if (algorithm.length === 0) {
-      throw lazyDOMException('Zero-length key is not supported', 'DataError');
-    }
-
-    // The Web Crypto spec allows for key lengths that are not multiples of 8. We don't.
-    if (algorithm.length % 8) {
-      throw lazyDOMException('Unsupported algorithm.length', 'NotSupportedError');
-    }
-  }
-}
-
 function hmacImportKey(
   format,
   keyData,
   algorithm,
   extractable,
   keyUsages,
 ) {
-  validateHmacImportKeyAlgorithm(algorithm);
   const usagesSet = new SafeSet(keyUsages);
   if (hasAnyNotIn(usagesSet, ['sign', 'verify'])) {
     throw lazyDOMException(