doc: revised webcrypto.md

nodejs · Mar 8, 2025 · 75a464e · 75a464e
1 parent 617a053
commit 75a464e
Show file tree

Hide file tree

Showing 2 changed files with 43 additions and 22 deletions.
diff --git a/doc/api/webcrypto.md b/doc/api/webcrypto.md
@@ -499,7 +499,7 @@ The possible usages are:
 Valid key usages depend on the key algorithm (identified by
 `cryptokey.algorithm.name`).
 
-| Key Type                                                | `'encrypt'` | `'decrypt'` | `'sign'` | `'verify'` | `'deriveKey'` | `'deriveBits'` | `'wrapKey'` | `'unwrapKey'` |
+| Supported Key Algorithm                                 | `'encrypt'` | `'decrypt'` | `'sign'` | `'verify'` | `'deriveKey'` | `'deriveBits'` | `'wrapKey'` | `'unwrapKey'` |
 | ------------------------------------------------------- | ----------- | ----------- | -------- | ---------- | ------------- | -------------- | ----------- | ------------- |
 | `'AES-CBC'`                                             | ✔           | ✔           |          |            |               |                | ✔           | ✔             |
 | `'AES-CTR'`                                             | ✔           | ✔           |          |            |               |                | ✔           | ✔             |
@@ -593,7 +593,7 @@ changes:
 
 <!--lint disable maximum-line-length remark-lint-->
 
-* `algorithm`: {AlgorithmIdentifier|EcdhKeyDeriveParams|HkdfParams|Pbkdf2Params}
+* `algorithm`: {EcdhKeyDeriveParams|HkdfParams|Pbkdf2Params}
 * `baseKey`: {CryptoKey}
 * `length`: {number|null} **Default:** `null`
 * Returns: {Promise} Fulfills with an {ArrayBuffer}
@@ -633,9 +633,9 @@ changes:
 
 <!--lint disable maximum-line-length remark-lint-->
 
-* `algorithm`: {AlgorithmIdentifier|EcdhKeyDeriveParams|HkdfParams|Pbkdf2Params}
+* `algorithm`: {EcdhKeyDeriveParams|HkdfParams|Pbkdf2Params}
 * `baseKey`: {CryptoKey}
-* `derivedKeyAlgorithm`: {HmacKeyGenParams|AesKeyGenParams}
+* `derivedKeyAlgorithm`: {string|AlgorithmIdentifier|HmacImportParams|AesDerivedKeyParams}
 * `extractable`: {boolean}
 * `keyUsages`: {string\[]} See [Key usages][].
 * Returns: {Promise} Fulfills with a {CryptoKey}
@@ -665,7 +665,7 @@ The algorithms currently supported include:
 added: v15.0.0
 -->
 
-* `algorithm`: {string|Object}
+* `algorithm`: {string|AlgorithmIdentifier}
 * `data`: {ArrayBuffer|TypedArray|DataView|Buffer}
 * Returns: {Promise} Fulfills with an {ArrayBuffer}
 
@@ -738,7 +738,7 @@ When `format` is `'jwk'` and the export is successful, the returned promise
 will be resolved with a JavaScript object conforming to the [JSON Web Key][]
 specification.
 
-| Key Type                                                | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
+| Supported Key Algorithm                                 | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
 | ------------------------------------------------------- | -------- | --------- | ------- | ------- |
 | `'AES-CBC'`                                             |          |           | ✔       | ✔       |
 | `'AES-CTR'`                                             |          |           | ✔       | ✔       |
@@ -748,9 +748,7 @@ specification.
 | `'ECDSA'`                                               | ✔        | ✔         | ✔       | ✔       |
 | `'Ed25519'`                                             | ✔        | ✔         | ✔       | ✔       |
 | `'Ed448'` <span class="experimental-inline"></span>[^1] | ✔        | ✔         | ✔       | ✔       |
-| `'HDKF'`                                                |          |           |         |         |
 | `'HMAC'`                                                |          |           | ✔       | ✔       |
-| `'PBKDF2'`                                              |          |           |         |         |
 | `'RSA-OAEP'`                                            | ✔        | ✔         | ✔       |         |
 | `'RSA-PSS'`                                             | ✔        | ✔         | ✔       |         |
 | `'RSASSA-PKCS1-v1_5'`                                   | ✔        | ✔         | ✔       |         |
@@ -763,7 +761,7 @@ added: v15.0.0
 
 <!--lint disable maximum-line-length remark-lint-->
 
-* `algorithm`: {AlgorithmIdentifier|RsaHashedKeyGenParams|EcKeyGenParams|HmacKeyGenParams|AesKeyGenParams}
+* `algorithm`: {string|AlgorithmIdentifier|RsaHashedKeyGenParams|EcKeyGenParams|HmacKeyGenParams|AesKeyGenParams}
 
 <!--lint enable maximum-line-length remark-lint-->
 
@@ -817,7 +815,7 @@ changes:
 
 <!--lint disable maximum-line-length remark-lint-->
 
-* `algorithm`: {AlgorithmIdentifier|RsaHashedImportParams|EcKeyImportParams|HmacImportParams}
+* `algorithm`: {string|AlgorithmIdentifier|RsaHashedImportParams|EcKeyImportParams|HmacImportParams}
 
 <!--lint enable maximum-line-length remark-lint-->
 
@@ -834,7 +832,7 @@ If importing a `'PBKDF2'` key, `extractable` must be `false`.
 
 The algorithms currently supported include:
 
-| Key Type                                                | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
+| Supported Key Algorithm                                 | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
 | ------------------------------------------------------- | -------- | --------- | ------- | ------- |
 | `'AES-CBC'`                                             |          |           | ✔       | ✔       |
 | `'AES-CTR'`                                             |          |           | ✔       | ✔       |
@@ -867,7 +865,7 @@ changes:
 
 <!--lint disable maximum-line-length remark-lint-->
 
-* `algorithm`: {AlgorithmIdentifier|RsaPssParams|EcdsaParams|Ed448Params}
+* `algorithm`: {string|AlgorithmIdentifier|RsaPssParams|EcdsaParams|Ed448Params}
 * `key`: {CryptoKey}
 * `data`: {ArrayBuffer|TypedArray|DataView|Buffer}
 * Returns: {Promise} Fulfills with an {ArrayBuffer}
@@ -900,8 +898,8 @@ added: v15.0.0
 
 <!--lint disable maximum-line-length remark-lint-->
 
-* `unwrapAlgo`: {AlgorithmIdentifier|RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams}
-* `unwrappedKeyAlgo`: {AlgorithmIdentifier|RsaHashedImportParams|EcKeyImportParams|HmacImportParams}
+* `unwrapAlgo`: {string|AlgorithmIdentifier|RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams}
+* `unwrappedKeyAlgo`: {string|AlgorithmIdentifier|RsaHashedImportParams|EcKeyImportParams|HmacImportParams}
 
 <!--lint enable maximum-line-length remark-lint-->
 
@@ -957,7 +955,7 @@ changes:
 
 <!--lint disable maximum-line-length remark-lint-->
 
-* `algorithm`: {AlgorithmIdentifier|RsaPssParams|EcdsaParams|Ed448Params}
+* `algorithm`: {string|AlgorithmIdentifier|RsaPssParams|EcdsaParams|Ed448Params}
 * `key`: {CryptoKey}
 * `signature`: {ArrayBuffer|TypedArray|DataView|Buffer}
 * `data`: {ArrayBuffer|TypedArray|DataView|Buffer}
@@ -990,7 +988,7 @@ added: v15.0.0
 * `format`: {string} Must be one of `'raw'`, `'pkcs8'`, `'spki'`, or `'jwk'`.
 * `key`: {CryptoKey}
 * `wrappingKey`: {CryptoKey}
-* `wrapAlgo`: {AlgorithmIdentifier|RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams}
+* `wrapAlgo`: {string|AlgorithmIdentifier|RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams}
 * Returns: {Promise} Fulfills with an {ArrayBuffer}
 
 <!--lint enable maximum-line-length remark-lint-->
@@ -1022,21 +1020,43 @@ are simple JavaScript dictionary objects.
 ### Class: `AlgorithmIdentifier`
 
 <!-- YAML
-added:
-  - v18.4.0
-  - v16.17.0
+added: v15.0.0
 -->
 
 #### `algorithmIdentifier.name`
 
 <!-- YAML
-added:
-  - v18.4.0
-  - v16.17.0
+added: v15.0.0
 -->
 
 * Type: {string}
 
+### Class: `AesDerivedKeyParams`
+
+<!-- YAML
+added: v15.0.0
+-->
+
+#### `aesDerivedKeyParams.name`
+
+<!-- YAML
+added: v15.0.0
+-->
+
+* Type: {string} Must be one of `'AES-CBC'`, `'AES-CTR'`, `'AES-GCM'`, or
+  `'AES-KW'`
+
+#### `aesDerivedKeyParams.length`
+
+<!-- YAML
+added: v15.0.0
+-->
+
+* Type: {number}
+
+The length of the AES key to be derived. This must be either `128`, `192`,
+or `256`.
+
 ### Class: `AesCbcParams`
 
 <!-- YAML

diff --git a/tools/doc/type-parser.mjs b/tools/doc/type-parser.mjs
@@ -95,6 +95,7 @@ const customTypesMap = {
   'AlgorithmIdentifier': 'webcrypto.html#class-algorithmidentifier',
   'AesCtrParams': 'webcrypto.html#class-aesctrparams',
   'AesCbcParams': 'webcrypto.html#class-aescbcparams',
+  'AesDerivedKeyParams': 'webcrypto.html#class-aesderivedkeyparams',
   'AesGcmParams': 'webcrypto.html#class-aesgcmparams',
   'EcdhKeyDeriveParams': 'webcrypto.html#class-ecdhkeyderiveparams',
   'HkdfParams': 'webcrypto.html#class-hkdfparams',