Skip to content

doc,lib: align WebCrypto names with spec #63518

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
panva wants to merge 1 commit into
base: main
Choose a base branch
from
Open

doc,lib: align WebCrypto names with spec #63518

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 22 additions & 22 deletions doc/api/webcrypto.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -850,7 +850,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
Expand All @@ -863,7 +863,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
Expand Down Expand Up @@ -961,7 +961,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
Expand All @@ -980,7 +980,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.
Expand All @@ -989,11 +989,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:
Expand Down Expand Up @@ -1073,7 +1073,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
Expand All @@ -1085,7 +1085,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.
Expand Down Expand Up @@ -1419,7 +1419,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
Expand All @@ -1439,8 +1439,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-->

Expand All @@ -1452,8 +1452,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.

Expand Down Expand Up @@ -1541,7 +1541,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
Expand All @@ -1560,18 +1560,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.

Expand Down Expand Up @@ -2815,19 +2815,19 @@ added:
[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
8 changes: 4 additions & 4 deletions lib/internal/crypto/aes.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand All @@ -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',
Expand Down
8 changes: 4 additions & 4 deletions lib/internal/crypto/cfrg.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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(
Expand Down
8 changes: 4 additions & 4 deletions lib/internal/crypto/chacha20_poly1305.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`,
Expand All @@ -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`,
Expand Down
8 changes: 4 additions & 4 deletions lib/internal/crypto/ec.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'])) {
Expand Down Expand Up @@ -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(
Expand Down
12 changes: 6 additions & 6 deletions lib/internal/crypto/mac.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand All @@ -67,7 +67,7 @@ function hmacGenerateKey(algorithm, extractable, keyUsages) {
extractable));
}

function kmacGenerateKey(algorithm, extractable, keyUsages) {
function kmacGenerateKey(algorithm, extractable, usages) {
const {
name,
length = {
Expand All @@ -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`,
Expand All @@ -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`,
Expand Down
8 changes: 4 additions & 4 deletions lib/internal/crypto/ml_dsa.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`,
Expand Down Expand Up @@ -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(
Expand Down
8 changes: 4 additions & 4 deletions lib/internal/crypto/ml_kem.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`,
Expand Down Expand Up @@ -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(
Expand Down
Loading
Loading