doc,lib: align WebCrypto names with spec

panva · aduh95 · commit 5d2dc844d23e · 2026-06-25T16:07:32.000+02:00
Rename WebCrypto operation parameters and local variables to match the spec terminology. Use operation, algorithm, and key names consistently between the docs and implementation. Signed-off-by: Filip Skokan <panva.ip@gmail.com> PR-URL: #63518 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
diff --git a/doc/api/webcrypto.md b/doc/api/webcrypto.md
@@ -848,7 +848,7 @@ The algorithms currently supported include:
 * `'ML-KEM-768'`[^modern-algos]
 * `'ML-KEM-1024'`[^modern-algos]
 
-### `subtle.decapsulateKey(decapsulationAlgorithm, decapsulationKey, ciphertext, sharedKeyAlgorithm, extractable, usages)`
+### `subtle.decapsulateKey(decapsulationAlgorithm, decapsulationKey, ciphertext, sharedKeyAlgorithm, extractable, keyUsages)`
 
 <!-- YAML
 added: v24.7.0
@@ -861,7 +861,7 @@ added: v24.7.0
 * `ciphertext` {ArrayBuffer|TypedArray|DataView|Buffer}
 * `sharedKeyAlgorithm` {string|Algorithm|HmacImportParams|AesDerivedKeyParams|KmacImportParams}
 * `extractable` {boolean}
-* `usages` {string\[]} See [Key usages][].
+* `keyUsages` {string\[]} See [Key usages][].
 * Returns: {Promise} Fulfills with {CryptoKey} upon success.
 
 A message recipient uses their asymmetric private key to decrypt an
@@ -959,7 +959,7 @@ The algorithms currently supported include:
 * `'X25519'`
 * `'X448'`[^secure-curves]
 
-### `subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)`
+### `subtle.deriveKey(algorithm, baseKey, derivedKeyType, extractable, keyUsages)`
 
 <!-- YAML
 added: v15.0.0
@@ -978,7 +978,7 @@ changes:
 
 * `algorithm` {EcdhKeyDeriveParams|HkdfParams|Pbkdf2Params|Argon2Params}
 * `baseKey` {CryptoKey}
-* `derivedKeyAlgorithm` {string|Algorithm|HmacImportParams|AesDerivedKeyParams|KmacImportParams}
+* `derivedKeyType` {string|Algorithm|HmacImportParams|AesDerivedKeyParams|KmacImportParams}
 * `extractable` {boolean}
 * `keyUsages` {string\[]} See [Key usages][].
 * Returns: {Promise} Fulfills with a {CryptoKey} upon success.
@@ -987,11 +987,11 @@ changes:
 
 Using the method and parameters specified in `algorithm`, and the keying
 material provided by `baseKey`, this method attempts to generate
-a new {CryptoKey} based on the method and parameters in `derivedKeyAlgorithm`.
+a new {CryptoKey} based on the method and parameters in `derivedKeyType`.
 
 Calling this method is equivalent to calling [`subtle.deriveBits()`][] to
 generate raw keying material, then passing the result into the
-[`subtle.importKey()`][] method using the `derivedKeyAlgorithm`, `extractable`, and
+[`subtle.importKey()`][] method using the `derivedKeyType`, `extractable`, and
 `keyUsages` parameters as input.
 
 The algorithms currently supported include:
@@ -1070,7 +1070,7 @@ The algorithms currently supported include:
 * `'ML-KEM-768'`[^modern-algos]
 * `'ML-KEM-1024'`[^modern-algos]
 
-### `subtle.encapsulateKey(encapsulationAlgorithm, encapsulationKey, sharedKeyAlgorithm, extractable, usages)`
+### `subtle.encapsulateKey(encapsulationAlgorithm, encapsulationKey, sharedKeyAlgorithm, extractable, keyUsages)`
 
 <!-- YAML
 added: v24.7.0
@@ -1082,7 +1082,7 @@ added: v24.7.0
 * `encapsulationKey` {CryptoKey}
 * `sharedKeyAlgorithm` {string|Algorithm|HmacImportParams|AesDerivedKeyParams|KmacImportParams}
 * `extractable` {boolean}
-* `usages` {string\[]} See [Key usages][].
+* `keyUsages` {string\[]} See [Key usages][].
 * Returns: {Promise} Fulfills with {EncapsulatedKey} upon success.
 
 Uses a message recipient's asymmetric public key to encrypt a temporary symmetric key.
@@ -1414,7 +1414,7 @@ The algorithms currently supported include:
 * `'RSA-PSS'`
 * `'RSASSA-PKCS1-v1_5'`
 
-### `subtle.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgo, unwrappedKeyAlgo, extractable, keyUsages)`
+### `subtle.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgorithm, unwrappedKeyAlgorithm, extractable, keyUsages)`
 
 <!-- YAML
 added: v15.0.0
@@ -1434,8 +1434,8 @@ changes:
 
 <!--lint disable maximum-line-length remark-lint-->
 
-* `unwrapAlgo` {string|Algorithm|RsaOaepParams|AesCtrParams|AesCbcParams|AeadParams}
-* `unwrappedKeyAlgo` {string|Algorithm|RsaHashedImportParams|EcKeyImportParams|HmacImportParams|KmacImportParams}
+* `unwrapAlgorithm` {string|Algorithm|RsaOaepParams|AesCtrParams|AesCbcParams|AeadParams}
+* `unwrappedKeyAlgorithm` {string|Algorithm|RsaHashedImportParams|EcKeyImportParams|HmacImportParams|KmacImportParams}
 
 <!--lint enable maximum-line-length remark-lint-->
 
@@ -1447,8 +1447,8 @@ In cryptography, "wrapping a key" refers to exporting and then encrypting the
 keying material. This method attempts to decrypt a wrapped
 key and create a {CryptoKey} instance. It is equivalent to calling
 [`subtle.decrypt()`][] first on the encrypted key data (using the `wrappedKey`,
-`unwrapAlgo`, and `unwrappingKey` arguments as input) then passing the results
-to the [`subtle.importKey()`][] method using the `unwrappedKeyAlgo`,
+`unwrapAlgorithm`, and `unwrappingKey` arguments as input) then passing the results
+to the [`subtle.importKey()`][] method using the `unwrappedKeyAlgorithm`,
 `extractable`, and `keyUsages` arguments as inputs. If successful, the returned
 promise is resolved with a {CryptoKey} object.
 
@@ -1536,7 +1536,7 @@ The algorithms currently supported include:
 * `'RSA-PSS'`
 * `'RSASSA-PKCS1-v1_5'`
 
-### `subtle.wrapKey(format, key, wrappingKey, wrapAlgo)`
+### `subtle.wrapKey(format, key, wrappingKey, wrapAlgorithm)`
 
 <!-- YAML
 added: v15.0.0
@@ -1555,18 +1555,18 @@ changes:
   `'raw-public'`[^modern-algos], or `'raw-seed'`[^modern-algos].
 * `key` {CryptoKey}
 * `wrappingKey` {CryptoKey}
-* `wrapAlgo` {string|Algorithm|RsaOaepParams|AesCtrParams|AesCbcParams|AeadParams}
+* `wrapAlgorithm` {string|Algorithm|RsaOaepParams|AesCtrParams|AesCbcParams|AeadParams}
 * Returns: {Promise} Fulfills with an {ArrayBuffer} upon success.
 
 <!--lint enable maximum-line-length remark-lint-->
 
 In cryptography, "wrapping a key" refers to exporting and then encrypting the
 keying material. This method exports the keying material into
 the format identified by `format`, then encrypts it using the method and
-parameters specified by `wrapAlgo` and the keying material provided by
+parameters specified by `wrapAlgorithm` and the keying material provided by
 `wrappingKey`. It is the equivalent to calling [`subtle.exportKey()`][] using
 `format` and `key` as the arguments, then passing the result to the
-[`subtle.encrypt()`][] method using `wrappingKey` and `wrapAlgo` as inputs. If
+[`subtle.encrypt()`][] method using `wrappingKey` and `wrapAlgorithm` as inputs. If
 successful, the returned promise will be resolved with an {ArrayBuffer}
 containing the encrypted key data.
 
@@ -2794,19 +2794,19 @@ added: v24.18.0
 [Web Crypto API]: https://www.w3.org/TR/WebCryptoAPI/
 [`SubtleCrypto.supports()`]: #static-method-subtlecryptosupportsoperation-algorithm-lengthoradditionalalgorithm
 [`subtle.decapsulateBits()`]: #subtledecapsulatebitsdecapsulationalgorithm-decapsulationkey-ciphertext
-[`subtle.decapsulateKey()`]: #subtledecapsulatekeydecapsulationalgorithm-decapsulationkey-ciphertext-sharedkeyalgorithm-extractable-usages
+[`subtle.decapsulateKey()`]: #subtledecapsulatekeydecapsulationalgorithm-decapsulationkey-ciphertext-sharedkeyalgorithm-extractable-keyusages
 [`subtle.decrypt()`]: #subtledecryptalgorithm-key-data
 [`subtle.deriveBits()`]: #subtlederivebitsalgorithm-basekey-length
-[`subtle.deriveKey()`]: #subtlederivekeyalgorithm-basekey-derivedkeyalgorithm-extractable-keyusages
+[`subtle.deriveKey()`]: #subtlederivekeyalgorithm-basekey-derivedkeytype-extractable-keyusages
 [`subtle.digest()`]: #subtledigestalgorithm-data
 [`subtle.encapsulateBits()`]: #subtleencapsulatebitsencapsulationalgorithm-encapsulationkey
-[`subtle.encapsulateKey()`]: #subtleencapsulatekeyencapsulationalgorithm-encapsulationkey-sharedkeyalgorithm-extractable-usages
+[`subtle.encapsulateKey()`]: #subtleencapsulatekeyencapsulationalgorithm-encapsulationkey-sharedkeyalgorithm-extractable-keyusages
 [`subtle.encrypt()`]: #subtleencryptalgorithm-key-data
 [`subtle.exportKey()`]: #subtleexportkeyformat-key
 [`subtle.generateKey()`]: #subtlegeneratekeyalgorithm-extractable-keyusages
 [`subtle.getPublicKey()`]: #subtlegetpublickeykey-keyusages
 [`subtle.importKey()`]: #subtleimportkeyformat-keydata-algorithm-extractable-keyusages
 [`subtle.sign()`]: #subtlesignalgorithm-key-data
-[`subtle.unwrapKey()`]: #subtleunwrapkeyformat-wrappedkey-unwrappingkey-unwrapalgo-unwrappedkeyalgo-extractable-keyusages
+[`subtle.unwrapKey()`]: #subtleunwrapkeyformat-wrappedkey-unwrappingkey-unwrapalgorithm-unwrappedkeyalgorithm-extractable-keyusages
 [`subtle.verify()`]: #subtleverifyalgorithm-key-signature-data
-[`subtle.wrapKey()`]: #subtlewrapkeyformat-key-wrappingkey-wrapalgo
+[`subtle.wrapKey()`]: #subtlewrapkeyformat-key-wrappingkey-wrapalgorithm
diff --git a/lib/internal/crypto/aes.js b/lib/internal/crypto/aes.js
@@ -175,14 +175,14 @@ function aesCipher(mode, key, data, algorithm) {
   }
 }
 
-function aesGenerateKey(algorithm, extractable, keyUsages) {
+function aesGenerateKey(algorithm, extractable, usages) {
   const { name, length } = algorithm;
 
   const checkUsages = ['wrapKey', 'unwrapKey'];
   if (name !== 'AES-KW')
     ArrayPrototypePush(checkUsages, 'encrypt', 'decrypt');
 
-  const usagesSet = new SafeSet(keyUsages);
+  const usagesSet = new SafeSet(usages);
   if (hasAnyNotIn(usagesSet, checkUsages)) {
     throw lazyDOMException(
       'Unsupported key usage for an AES key',
@@ -207,13 +207,13 @@ function aesImportKey(
   format,
   keyData,
   extractable,
-  keyUsages) {
+  usages) {
   const { name } = algorithm;
   const checkUsages = ['wrapKey', 'unwrapKey'];
   if (name !== 'AES-KW')
     ArrayPrototypePush(checkUsages, 'encrypt', 'decrypt');
 
-  const usagesSet = new SafeSet(keyUsages);
+  const usagesSet = new SafeSet(usages);
   if (hasAnyNotIn(usagesSet, checkUsages)) {
     throw lazyDOMException(
       'Unsupported key usage for an AES key',
diff --git a/lib/internal/crypto/cfrg.js b/lib/internal/crypto/cfrg.js
@@ -75,10 +75,10 @@ function verifyAcceptableCfrgKeyUse(name, isPublic, usages) {
   }
 }
 
-function cfrgGenerateKey(algorithm, extractable, keyUsages) {
+function cfrgGenerateKey(algorithm, extractable, usages) {
   const { name } = algorithm;
 
-  const usageSet = new SafeSet(keyUsages);
+  const usageSet = new SafeSet(usages);
   switch (name) {
     case 'Ed25519':
       // Fall through
@@ -172,11 +172,11 @@ function cfrgImportKey(
   keyData,
   algorithm,
   extractable,
-  keyUsages) {
+  usages) {
 
   const { name } = algorithm;
   let handle;
-  const usagesSet = new SafeSet(keyUsages);
+  const usagesSet = new SafeSet(usages);
   switch (format) {
     case 'KeyObject': {
       verifyAcceptableCfrgKeyUse(
diff --git a/lib/internal/crypto/chacha20_poly1305.js b/lib/internal/crypto/chacha20_poly1305.js
@@ -47,12 +47,12 @@ function c20pCipher(mode, key, data, algorithm) {
     algorithm.additionalData));
 }
 
-function c20pGenerateKey(algorithm, extractable, keyUsages) {
+function c20pGenerateKey(algorithm, extractable, usages) {
   const { name } = algorithm;
 
   const checkUsages = ['encrypt', 'decrypt', 'wrapKey', 'unwrapKey'];
 
-  const usagesSet = new SafeSet(keyUsages);
+  const usagesSet = new SafeSet(usages);
   if (hasAnyNotIn(usagesSet, checkUsages)) {
     throw lazyDOMException(
       `Unsupported key usage for a ${algorithm.name} key`,
@@ -77,11 +77,11 @@ function c20pImportKey(
   format,
   keyData,
   extractable,
-  keyUsages) {
+  usages) {
   const { name } = algorithm;
   const checkUsages = ['encrypt', 'decrypt', 'wrapKey', 'unwrapKey'];
 
-  const usagesSet = new SafeSet(keyUsages);
+  const usagesSet = new SafeSet(usages);
   if (hasAnyNotIn(usagesSet, checkUsages)) {
     throw lazyDOMException(
       `Unsupported key usage for a ${algorithm.name} key`,
diff --git a/lib/internal/crypto/ec.js b/lib/internal/crypto/ec.js
@@ -77,10 +77,10 @@ function verifyAcceptableEcKeyUse(name, isPublic, usages) {
   }
 }
 
-function ecGenerateKey(algorithm, extractable, keyUsages) {
+function ecGenerateKey(algorithm, extractable, usages) {
   const { name, namedCurve } = algorithm;
 
-  const usageSet = new SafeSet(keyUsages);
+  const usageSet = new SafeSet(usages);
   switch (name) {
     case 'ECDSA':
       if (hasAnyNotIn(usageSet, ['sign', 'verify'])) {
@@ -178,12 +178,12 @@ function ecImportKey(
   keyData,
   algorithm,
   extractable,
-  keyUsages,
+  usages,
 ) {
   const { name, namedCurve } = algorithm;
 
   let handle;
-  const usagesSet = new SafeSet(keyUsages);
+  const usagesSet = new SafeSet(usages);
   switch (format) {
     case 'KeyObject': {
       verifyAcceptableEcKeyUse(
diff --git a/lib/internal/crypto/mac.js b/lib/internal/crypto/mac.js
@@ -40,14 +40,14 @@ const {
   validateJwk,
 } = require('internal/crypto/webcrypto_util');
 
-function hmacGenerateKey(algorithm, extractable, keyUsages) {
+function hmacGenerateKey(algorithm, extractable, usages) {
   const {
     hash,
     name,
     length = getBlockSize(hash.name),
   } = algorithm;
 
-  const usageSet = new SafeSet(keyUsages);
+  const usageSet = new SafeSet(usages);
   if (hasAnyNotIn(usageSet, ['sign', 'verify'])) {
     throw lazyDOMException(
       'Unsupported key usage for an HMAC key',
@@ -67,7 +67,7 @@ function hmacGenerateKey(algorithm, extractable, keyUsages) {
     extractable));
 }
 
-function kmacGenerateKey(algorithm, extractable, keyUsages) {
+function kmacGenerateKey(algorithm, extractable, usages) {
   const {
     name,
     length = {
@@ -77,7 +77,7 @@ function kmacGenerateKey(algorithm, extractable, keyUsages) {
     }[name],
   } = algorithm;
 
-  const usageSet = new SafeSet(keyUsages);
+  const usageSet = new SafeSet(usages);
   if (hasAnyNotIn(usageSet, ['sign', 'verify'])) {
     throw lazyDOMException(
       `Unsupported key usage for ${name} key`,
@@ -102,10 +102,10 @@ function macImportKey(
   keyData,
   algorithm,
   extractable,
-  keyUsages,
+  usages,
 ) {
   const isHmac = algorithm.name === 'HMAC';
-  const usagesSet = new SafeSet(keyUsages);
+  const usagesSet = new SafeSet(usages);
   if (hasAnyNotIn(usagesSet, ['sign', 'verify'])) {
     throw lazyDOMException(
       `Unsupported key usage for ${algorithm.name} key`,
diff --git a/lib/internal/crypto/ml_dsa.js b/lib/internal/crypto/ml_dsa.js
@@ -63,10 +63,10 @@ function verifyAcceptableMlDsaKeyUse(name, isPublic, usages) {
   }
 }
 
-function mlDsaGenerateKey(algorithm, extractable, keyUsages) {
+function mlDsaGenerateKey(algorithm, extractable, usages) {
   const { name } = algorithm;
 
-  const usageSet = new SafeSet(keyUsages);
+  const usageSet = new SafeSet(usages);
   if (hasAnyNotIn(usageSet, ['sign', 'verify'])) {
     throw lazyDOMException(
       `Unsupported key usage for an ${name} key`,
@@ -144,11 +144,11 @@ function mlDsaImportKey(
   keyData,
   algorithm,
   extractable,
-  keyUsages) {
+  usages) {
 
   const { name } = algorithm;
   let handle;
-  const usagesSet = new SafeSet(keyUsages);
+  const usagesSet = new SafeSet(usages);
   switch (format) {
     case 'KeyObject': {
       verifyAcceptableMlDsaKeyUse(
diff --git a/lib/internal/crypto/ml_kem.js b/lib/internal/crypto/ml_kem.js
@@ -51,10 +51,10 @@ const {
   validateJwk,
 } = require('internal/crypto/webcrypto_util');
 
-function mlKemGenerateKey(algorithm, extractable, keyUsages) {
+function mlKemGenerateKey(algorithm, extractable, usages) {
   const { name } = algorithm;
 
-  const usageSet = new SafeSet(keyUsages);
+  const usageSet = new SafeSet(usages);
   if (hasAnyNotIn(usageSet, ['encapsulateKey', 'encapsulateBits', 'decapsulateKey', 'decapsulateBits'])) {
     throw lazyDOMException(
       `Unsupported key usage for an ${name} key`,
@@ -143,11 +143,11 @@ function mlKemImportKey(
   keyData,
   algorithm,
   extractable,
-  keyUsages) {
+  usages) {
 
   const { name } = algorithm;
   let handle;
-  const usagesSet = new SafeSet(keyUsages);
+  const usagesSet = new SafeSet(usages);
   switch (format) {
     case 'KeyObject': {
       verifyAcceptableMlKemKeyUse(
diff --git a/lib/internal/crypto/rsa.js b/lib/internal/crypto/rsa.js
diff --git a/lib/internal/crypto/webcrypto.js b/lib/internal/crypto/webcrypto.js
