Skip to content

Commit 8e8a727

Browse files
panvaRafaelGSS
panva
authored and
RafaelGSS
committed
doc: revise webcrypto.md types, interfaces, and added versions
PR-URL: #57376 Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Antoine du Hamel <[email protected]>
1 parent 03bdd93 commit 8e8a727

File tree

2 files changed

+55
-34
lines changed

2 files changed

+55
-34
lines changed

‎doc/api/webcrypto.md

Lines changed: 54 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -497,7 +497,7 @@ The possible usages are:
497497
Valid key usages depend on the key algorithm (identified by
498498
`cryptokey.algorithm.name`).
499499

500-
| Key Type | `'encrypt'` | `'decrypt'` | `'sign'` | `'verify'` | `'deriveKey'` | `'deriveBits'` | `'wrapKey'` | `'unwrapKey'` |
500+
| Supported Key Algorithm | `'encrypt'` | `'decrypt'` | `'sign'` | `'verify'` | `'deriveKey'` | `'deriveBits'` | `'wrapKey'` | `'unwrapKey'` |
501501
| ------------------------------------------------------- | ----------- | ----------- | -------- | ---------- | ------------- | -------------- | ----------- | ------------- |
502502
| `'AES-CBC'` | ✔ | ✔ | | | | | ✔ | ✔ |
503503
| `'AES-CTR'` | ✔ | ✔ | | | | | ✔ | ✔ |
@@ -556,7 +556,7 @@ added: v15.0.0
556556
* `algorithm`: {RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams}
557557
* `key`: {CryptoKey}
558558
* `data`: {ArrayBuffer|TypedArray|DataView|Buffer}
559-
* Returns: {Promise} Fulfills with an {ArrayBuffer}
559+
* Returns: {Promise} Fulfills with an {ArrayBuffer} upon success.
560560

561561
Using the method and parameters specified in `algorithm` and the keying
562562
material provided by `key`, `subtle.decrypt()` attempts to decipher the
@@ -588,10 +588,10 @@ changes:
588588

589589
<!--lint disable maximum-line-length remark-lint-->
590590

591-
* `algorithm`: {AlgorithmIdentifier|EcdhKeyDeriveParams|HkdfParams|Pbkdf2Params}
591+
* `algorithm`: {EcdhKeyDeriveParams|HkdfParams|Pbkdf2Params}
592592
* `baseKey`: {CryptoKey}
593593
* `length`: {number|null} **Default:** `null`
594-
* Returns: {Promise} Fulfills with an {ArrayBuffer}
594+
* Returns: {Promise} Fulfills with an {ArrayBuffer} upon success.
595595

596596
<!--lint enable maximum-line-length remark-lint-->
597597

@@ -628,12 +628,12 @@ changes:
628628

629629
<!--lint disable maximum-line-length remark-lint-->
630630

631-
* `algorithm`: {AlgorithmIdentifier|EcdhKeyDeriveParams|HkdfParams|Pbkdf2Params}
631+
* `algorithm`: {EcdhKeyDeriveParams|HkdfParams|Pbkdf2Params}
632632
* `baseKey`: {CryptoKey}
633-
* `derivedKeyAlgorithm`: {HmacKeyGenParams|AesKeyGenParams}
633+
* `derivedKeyAlgorithm`: {string|AlgorithmIdentifier|HmacImportParams|AesDerivedKeyParams}
634634
* `extractable`: {boolean}
635635
* `keyUsages`: {string\[]} See [Key usages][].
636-
* Returns: {Promise} Fulfills with a {CryptoKey}
636+
* Returns: {Promise} Fulfills with a {CryptoKey} upon success.
637637

638638
<!--lint enable maximum-line-length remark-lint-->
639639

@@ -660,9 +660,9 @@ The algorithms currently supported include:
660660
added: v15.0.0
661661
-->
662662

663-
* `algorithm`: {string|Object}
663+
* `algorithm`: {string|AlgorithmIdentifier}
664664
* `data`: {ArrayBuffer|TypedArray|DataView|Buffer}
665-
* Returns: {Promise} Fulfills with an {ArrayBuffer}
665+
* Returns: {Promise} Fulfills with an {ArrayBuffer} upon success.
666666

667667
Using the method identified by `algorithm`, `subtle.digest()` attempts to
668668
generate a digest of `data`. If successful, the returned promise is resolved
@@ -687,7 +687,7 @@ added: v15.0.0
687687
* `algorithm`: {RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams}
688688
* `key`: {CryptoKey}
689689
* `data`: {ArrayBuffer|TypedArray|DataView|Buffer}
690-
* Returns: {Promise} Fulfills with an {ArrayBuffer}
690+
* Returns: {Promise} Fulfills with an {ArrayBuffer} upon success.
691691

692692
Using the method and parameters specified by `algorithm` and the keying
693693
material provided by `key`, `subtle.encrypt()` attempts to encipher `data`.
@@ -719,7 +719,7 @@ changes:
719719

720720
* `format`: {string} Must be one of `'raw'`, `'pkcs8'`, `'spki'`, or `'jwk'`.
721721
* `key`: {CryptoKey}
722-
* Returns: {Promise} Fulfills with an {ArrayBuffer|Object}.
722+
* Returns: {Promise} Fulfills with an {ArrayBuffer|Object} upon success.
723723

724724
Exports the given key into the specified format, if supported.
725725

@@ -733,7 +733,7 @@ When `format` is `'jwk'` and the export is successful, the returned promise
733733
will be resolved with a JavaScript object conforming to the [JSON Web Key][]
734734
specification.
735735

736-
| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
736+
| Supported Key Algorithm | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
737737
| ------------------------------------------------------- | -------- | --------- | ------- | ------- |
738738
| `'AES-CBC'` | | | ✔ | ✔ |
739739
| `'AES-CTR'` | | | ✔ | ✔ |
@@ -743,9 +743,7 @@ specification.
743743
| `'ECDSA'` | ✔ | ✔ | ✔ | ✔ |
744744
| `'Ed25519'` | ✔ | ✔ | ✔ | ✔ |
745745
| `'Ed448'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | ✔ |
746-
| `'HDKF'` | | | | |
747746
| `'HMAC'` | | | ✔ | ✔ |
748-
| `'PBKDF2'` | | | | |
749747
| `'RSA-OAEP'` | ✔ | ✔ | ✔ | |
750748
| `'RSA-PSS'` | ✔ | ✔ | ✔ | |
751749
| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | |
@@ -758,13 +756,13 @@ added: v15.0.0
758756

759757
<!--lint disable maximum-line-length remark-lint-->
760758

761-
* `algorithm`: {AlgorithmIdentifier|RsaHashedKeyGenParams|EcKeyGenParams|HmacKeyGenParams|AesKeyGenParams}
759+
* `algorithm`: {string|AlgorithmIdentifier|RsaHashedKeyGenParams|EcKeyGenParams|HmacKeyGenParams|AesKeyGenParams}
762760

763761
<!--lint enable maximum-line-length remark-lint-->
764762

765763
* `extractable`: {boolean}
766764
* `keyUsages`: {string\[]} See [Key usages][].
767-
* Returns: {Promise} Fulfills with a {CryptoKey|CryptoKeyPair}
765+
* Returns: {Promise} Fulfills with a {CryptoKey|CryptoKeyPair} upon success.
768766

769767
Using the method and parameters provided in `algorithm`, `subtle.generateKey()`
770768
attempts to generate new keying material. Depending the method used, the method
@@ -812,13 +810,13 @@ changes:
812810

813811
<!--lint disable maximum-line-length remark-lint-->
814812

815-
* `algorithm`: {AlgorithmIdentifier|RsaHashedImportParams|EcKeyImportParams|HmacImportParams}
813+
* `algorithm`: {string|AlgorithmIdentifier|RsaHashedImportParams|EcKeyImportParams|HmacImportParams}
816814

817815
<!--lint enable maximum-line-length remark-lint-->
818816

819817
* `extractable`: {boolean}
820818
* `keyUsages`: {string\[]} See [Key usages][].
821-
* Returns: {Promise} Fulfills with a {CryptoKey}
819+
* Returns: {Promise} Fulfills with a {CryptoKey} upon success.
822820

823821
The `subtle.importKey()` method attempts to interpret the provided `keyData`
824822
as the given `format` to create a {CryptoKey} instance using the provided
@@ -829,7 +827,7 @@ If importing a `'PBKDF2'` key, `extractable` must be `false`.
829827

830828
The algorithms currently supported include:
831829

832-
| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
830+
| Supported Key Algorithm | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
833831
| ------------------------------------------------------- | -------- | --------- | ------- | ------- |
834832
| `'AES-CBC'` | | | ✔ | ✔ |
835833
| `'AES-CTR'` | | | ✔ | ✔ |
@@ -862,10 +860,10 @@ changes:
862860

863861
<!--lint disable maximum-line-length remark-lint-->
864862

865-
* `algorithm`: {AlgorithmIdentifier|RsaPssParams|EcdsaParams|Ed448Params}
863+
* `algorithm`: {string|AlgorithmIdentifier|RsaPssParams|EcdsaParams|Ed448Params}
866864
* `key`: {CryptoKey}
867865
* `data`: {ArrayBuffer|TypedArray|DataView|Buffer}
868-
* Returns: {Promise} Fulfills with an {ArrayBuffer}
866+
* Returns: {Promise} Fulfills with an {ArrayBuffer} upon success.
869867

870868
<!--lint enable maximum-line-length remark-lint-->
871869

@@ -895,14 +893,14 @@ added: v15.0.0
895893

896894
<!--lint disable maximum-line-length remark-lint-->
897895

898-
* `unwrapAlgo`: {AlgorithmIdentifier|RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams}
899-
* `unwrappedKeyAlgo`: {AlgorithmIdentifier|RsaHashedImportParams|EcKeyImportParams|HmacImportParams}
896+
* `unwrapAlgo`: {string|AlgorithmIdentifier|RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams}
897+
* `unwrappedKeyAlgo`: {string|AlgorithmIdentifier|RsaHashedImportParams|EcKeyImportParams|HmacImportParams}
900898

901899
<!--lint enable maximum-line-length remark-lint-->
902900

903901
* `extractable`: {boolean}
904902
* `keyUsages`: {string\[]} See [Key usages][].
905-
* Returns: {Promise} Fulfills with a {CryptoKey}
903+
* Returns: {Promise} Fulfills with a {CryptoKey} upon success.
906904

907905
In cryptography, "wrapping a key" refers to exporting and then encrypting the
908906
keying material. The `subtle.unwrapKey()` method attempts to decrypt a wrapped
@@ -952,11 +950,11 @@ changes:
952950

953951
<!--lint disable maximum-line-length remark-lint-->
954952

955-
* `algorithm`: {AlgorithmIdentifier|RsaPssParams|EcdsaParams|Ed448Params}
953+
* `algorithm`: {string|AlgorithmIdentifier|RsaPssParams|EcdsaParams|Ed448Params}
956954
* `key`: {CryptoKey}
957955
* `signature`: {ArrayBuffer|TypedArray|DataView|Buffer}
958956
* `data`: {ArrayBuffer|TypedArray|DataView|Buffer}
959-
* Returns: {Promise} Fulfills with a {boolean}
957+
* Returns: {Promise} Fulfills with a {boolean} upon success.
960958

961959
<!--lint enable maximum-line-length remark-lint-->
962960

@@ -985,8 +983,8 @@ added: v15.0.0
985983
* `format`: {string} Must be one of `'raw'`, `'pkcs8'`, `'spki'`, or `'jwk'`.
986984
* `key`: {CryptoKey}
987985
* `wrappingKey`: {CryptoKey}
988-
* `wrapAlgo`: {AlgorithmIdentifier|RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams}
989-
* Returns: {Promise} Fulfills with an {ArrayBuffer}
986+
* `wrapAlgo`: {string|AlgorithmIdentifier|RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams}
987+
* Returns: {Promise} Fulfills with an {ArrayBuffer} upon success.
990988

991989
<!--lint enable maximum-line-length remark-lint-->
992990

@@ -1017,21 +1015,43 @@ are simple JavaScript dictionary objects.
10171015
### Class: `AlgorithmIdentifier`
10181016

10191017
<!-- YAML
1020-
added:
1021-
- v18.4.0
1022-
- v16.17.0
1018+
added: v15.0.0
10231019
-->
10241020

10251021
#### `algorithmIdentifier.name`
10261022

10271023
<!-- YAML
1028-
added:
1029-
- v18.4.0
1030-
- v16.17.0
1024+
added: v15.0.0
10311025
-->
10321026

10331027
* Type: {string}
10341028

1029+
### Class: `AesDerivedKeyParams`
1030+
1031+
<!-- YAML
1032+
added: v15.0.0
1033+
-->
1034+
1035+
#### `aesDerivedKeyParams.name`
1036+
1037+
<!-- YAML
1038+
added: v15.0.0
1039+
-->
1040+
1041+
* Type: {string} Must be one of `'AES-CBC'`, `'AES-CTR'`, `'AES-GCM'`, or
1042+
`'AES-KW'`
1043+
1044+
#### `aesDerivedKeyParams.length`
1045+
1046+
<!-- YAML
1047+
added: v15.0.0
1048+
-->
1049+
1050+
* Type: {number}
1051+
1052+
The length of the AES key to be derived. This must be either `128`, `192`,
1053+
or `256`.
1054+
10351055
### Class: `AesCbcParams`
10361056

10371057
<!-- YAML

‎tools/doc/type-parser.mjs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,7 @@ const customTypesMap = {
9595
'AlgorithmIdentifier': 'webcrypto.html#class-algorithmidentifier',
9696
'AesCtrParams': 'webcrypto.html#class-aesctrparams',
9797
'AesCbcParams': 'webcrypto.html#class-aescbcparams',
98+
'AesDerivedKeyParams': 'webcrypto.html#class-aesderivedkeyparams',
9899
'AesGcmParams': 'webcrypto.html#class-aesgcmparams',
99100
'EcdhKeyDeriveParams': 'webcrypto.html#class-ecdhkeyderiveparams',
100101
'HkdfParams': 'webcrypto.html#class-hkdfparams',

0 commit comments

Comments
 (0)