crypto: add SubtleCrypto.supports feature detection in Web Cryptography

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

@@ -101,6 +101,10 @@ Key Formats:
 * `'raw-secret'`
 * `'raw-seed'`
 
+Methods:
+
+* [`SubtleCrypto.supports()`][]
+
 ## Secure Curves in the Web Cryptography API
 
 > Stability: 1.1 - Active development
@@ -387,6 +391,76 @@ async function digest(data, algorithm = 'SHA-512') {
 }
 ```
 
+### Checking for runtime algorithm support
+
+[`SubtleCrypto.supports()`][] allows feature detection in Web Crypto API,
+which can be used to detect whether a given algorithm identifier
+(including its parameters) is supported for the given operation.
+
+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 { SubtleCrypto, crypto } = globalThis;
+
+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(
+  derivationAlg === 'Argon2id' ? 'raw-secret' : '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
@@ -591,6 +665,27 @@ added: v15.0.0
 added: v15.0.0
 -->
 
+### Static method: `SubtleCrypto.supports(operation, algorithm[, lengthOrAdditionalAlgorithm])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.1 - Active development
+
+<!--lint disable maximum-line-length remark-lint-->
+
+* `operation` {string} "encrypt", "decrypt", "sign", "verify", "digest", "generateKey", "deriveKey", "deriveBits", "importKey", "exportKey", "wrapKey", or "unwrapKey"
+* `algorithm` {string|Algorithm}
+* `lengthOrAdditionalAlgorithm` {null|number|string|Algorithm|undefined} Depending on the operation this is either ignored, the value of the length argument when operation is "deriveBits", the algorithm of key to be derived when operation is "deriveKey", the algorithm of key to be exported before wrapping when operation is "wrapKey", or the algorithm of key to be imported after unwrapping when operation is "unwrapKey". **Default:** `null` when operation is "deriveBits", `undefined` otherwise.
+* 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 its parameters) is supported for the given operation.
+
 ### `subtle.decrypt(algorithm, key, data)`
 
 <!-- YAML
@@ -1922,3 +2017,4 @@ The length (in bytes) of the random salt to use.
 [RFC 4122]: https://www.rfc-editor.org/rfc/rfc4122.txt
 [Secure Curves in the Web Cryptography API]: #secure-curves-in-the-web-cryptography-api
 [Web Crypto API]: https://www.w3.org/TR/WebCryptoAPI/
+[`SubtleCrypto.supports()`]: #static-method-subtlecryptosupportsoperation-algorithm-lengthoradditionalalgorithm

lib/internal/crypto/hkdf.js

@@ -170,4 +170,5 @@ module.exports = {
   hkdf,
   hkdfSync,
   hkdfDeriveBits,
+  validateHkdfDeriveBitsLength,
 };

lib/internal/crypto/pbkdf2.js

@@ -128,4 +128,5 @@ module.exports = {
   pbkdf2,
   pbkdf2Sync,
   pbkdf2DeriveBits,
+  validatePbkdf2DeriveBitsLength,
 };

lib/internal/crypto/webcrypto.js

@@ -47,6 +47,7 @@ const {
 } = require('internal/crypto/util');
 
 const {
+  emitExperimentalWarning,
   kEnumerableProperty,
   lazyDOMException,
 } = require('internal/util');
@@ -1026,7 +1027,147 @@ class SubtleCrypto {
   constructor() {
     throw new ERR_ILLEGAL_CONSTRUCTOR();
   }
+
+  // Implements https://wicg.github.io/webcrypto-modern-algos/#SubtleCrypto-method-supports
+  static supports(operation, algorithm, lengthOrAdditionalAlgorithm = null) {
+    emitExperimentalWarning('The supports Web Crypto API method');
+    if (this !== SubtleCrypto) throw new ERR_INVALID_THIS('SubtleCrypto constructor');
+    webidl ??= require('internal/crypto/webidl');
+    const prefix = "Failed to execute 'supports' on 'SubtleCrypto'";
+    webidl.requiredArguments(arguments.length, 2, { prefix });
+
+    operation = webidl.converters.DOMString(operation, {
+      prefix,
+      context: '1st argument',
+    });
+    algorithm = webidl.converters.AlgorithmIdentifier(algorithm, {
+      prefix,
+      context: '2nd argument',
+    });
+
+    switch (operation) {
+      case 'encrypt':
+      case 'decrypt':
+      case 'sign':
+      case 'verify':
+      case 'digest':
+      case 'generateKey':
+      case 'deriveKey':
+      case 'deriveBits':
+      case 'importKey':
+      case 'exportKey':
+      case 'wrapKey':
+      case 'unwrapKey':
+        break;
+      default:
+        return false;
+    }
+
+    let length;
+    let additionalAlgorithm;
+    if (operation === 'deriveKey') {
+      additionalAlgorithm = webidl.converters.AlgorithmIdentifier(lengthOrAdditionalAlgorithm, {
+        prefix,
+        context: '3rd argument',
+      });
+
+      if (!check('importKey', additionalAlgorithm)) {
+        return false;
+      }
+
+      try {
+        length = getKeyLength(normalizeAlgorithm(additionalAlgorithm, 'get key length'));
+      } catch {
+        return false;
+      }
+
+      operation = 'deriveBits';
+    } else if (operation === 'wrapKey') {
+      additionalAlgorithm = webidl.converters.AlgorithmIdentifier(lengthOrAdditionalAlgorithm, {
+        prefix,
+        context: '3rd argument',
+      });
+
+      if (!check('exportKey', additionalAlgorithm)) {
+        return false;
+      }
+    } else if (operation === 'unwrapKey') {
+      additionalAlgorithm = webidl.converters.AlgorithmIdentifier(lengthOrAdditionalAlgorithm, {
+        prefix,
+        context: '3rd argument',
+      });
+
+      if (!check('importKey', additionalAlgorithm)) {
+        return false;
+      }
+    } else if (operation === 'deriveBits') {
+      length = lengthOrAdditionalAlgorithm;
+      if (length !== null) {
+        length = webidl.converters['unsigned long'](length, {
+          prefix,
+          context: '3rd argument',
+        });
+      }
+    }
+
+    return check(operation, algorithm, length);
+  }
 }
+
+function check(op, alg, length) {
+  let normalizedAlgorithm;
+  try {
+    normalizedAlgorithm = normalizeAlgorithm(alg, op);
+  } catch {
+    if (op === 'wrapKey') {
+      return check('encrypt', alg);
+    }
+
+    if (op === 'unwrapKey') {
+      return check('decrypt', alg);
+    }
+
+    return false;
+  }
+
+  switch (op) {
+    case 'encrypt':
+    case 'decrypt':
+    case 'sign':
+    case 'verify':
+    case 'digest':
+    case 'generateKey':
+    case 'importKey':
+    case 'exportKey':
+    case 'wrapKey':
+    case 'unwrapKey':
+      return true;
+    case 'deriveBits': {
+      if (normalizedAlgorithm.name === 'HKDF') {
+        try {
+          require('internal/crypto/hkdf').validateHkdfDeriveBitsLength(length);
+        } catch {
+          return false;
+        }
+      }
+
+      if (normalizedAlgorithm.name === 'PBKDF2') {
+        try {
+          require('internal/crypto/pbkdf2').validatePbkdf2DeriveBitsLength(length);
+        } catch {
+          return false;
+        }
+      }
+
+      return true;
+    }
+    default: {
+      const assert = require('internal/assert');
+      assert.fail('Unreachable code');
+    }
+  }
+}
+
 const subtle = ReflectConstruct(function() {}, [], SubtleCrypto);
 
 class Crypto {