doc,lib: align WebCrypto names with spec

panva · aduh95 · commit eeb77d217c78 · 2026-05-27T11:35:48.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
@@ -849,7 +849,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
@@ -862,7 +862,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
@@ -960,7 +960,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
@@ -979,7 +979,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.
@@ -988,11 +988,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:
@@ -1071,7 +1071,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
@@ -1083,7 +1083,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.
@@ -1415,7 +1415,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
@@ -1435,8 +1435,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-->
 
@@ -1448,8 +1448,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.
 
@@ -1537,7 +1537,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
@@ -1556,18 +1556,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.
 
@@ -2795,19 +2795,19 @@ added: v25.9.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
@@ -73,10 +73,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
@@ -170,11 +170,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
@@ -59,10 +59,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`,
@@ -136,11 +136,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
@@ -49,10 +49,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`,
@@ -137,11 +137,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

-Original file line number
+Diff line change
+}
+}
 -functionaesGenerateKey(algorithm,extractable,keyUsages){
 +functionaesGenerateKey(algorithm,extractable,usages){
 const{ name, length }=algorithm;
 constcheckUsages=['wrapKey','unwrapKey'];
 if(name!=='AES-KW')
 ArrayPrototypePush(checkUsages,'encrypt','decrypt');
 -constusagesSet=newSafeSet(keyUsages);
 +constusagesSet=newSafeSet(usages);
 if(hasAnyNotIn(usagesSet,checkUsages)){
 throwlazyDOMException(
 'Unsupported key usage for an AES key',
 format,
 keyData,
 extractable,
 -keyUsages){
 +usages){
 const{ name }=algorithm;
 constcheckUsages=['wrapKey','unwrapKey'];
 if(name!=='AES-KW')
 ArrayPrototypePush(checkUsages,'encrypt','decrypt');
 -constusagesSet=newSafeSet(keyUsages);
 +constusagesSet=newSafeSet(usages);
 if(hasAnyNotIn(usagesSet,checkUsages)){
 throwlazyDOMException(
 'Unsupported key usage for an AES key',
-Original file line number
+Diff line change
+}
+}
 -functionecGenerateKey(algorithm,extractable,keyUsages){
 +functionecGenerateKey(algorithm,extractable,usages){
 const{ name, namedCurve }=algorithm;
 -constusageSet=newSafeSet(keyUsages);
 +constusageSet=newSafeSet(usages);
 switch(name){
 case'ECDSA':
 if(hasAnyNotIn(usageSet,['sign','verify'])){
 keyData,
 algorithm,
 extractable,
 -keyUsages,
 +usages,
 ){
 const{ name, namedCurve }=algorithm;
 lethandle;
 -constusagesSet=newSafeSet(keyUsages);
 +constusagesSet=newSafeSet(usages);
 switch(format){
 case'KeyObject': {
 verifyAcceptableEcKeyUse(