Skip to content

Commit d8a9ab4

Browse files
panvapanva
authored
doc: revise webcrypto.md types, interfaces, and added versions
PR-URL: #57376 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
1 parent dba6fdc commit d8a9ab4

File tree

2 files changed

+55
-34
lines changed

2 files changed

+55
-34
lines changed

‎doc/api/webcrypto.md

+54-34
Original file line numberDiff line numberDiff line change
@@ -499,7 +499,7 @@ The possible usages are:
499499
Valid key usages depend on the key algorithm (identified by
500500
`cryptokey.algorithm.name`).
501501

502-
| Key Type | `'encrypt'` | `'decrypt'` | `'sign'` | `'verify'` | `'deriveKey'` | `'deriveBits'` | `'wrapKey'` | `'unwrapKey'` |
502+
| Supported Key Algorithm | `'encrypt'` | `'decrypt'` | `'sign'` | `'verify'` | `'deriveKey'` | `'deriveBits'` | `'wrapKey'` | `'unwrapKey'` |
503503
| ------------------------------------------------------- | ----------- | ----------- | -------- | ---------- | ------------- | -------------- | ----------- | ------------- |
504504
| `'AES-CBC'` | ✔ | ✔ | | | | | ✔ | ✔ |
505505
| `'AES-CTR'` | ✔ | ✔ | | | | | ✔ | ✔ |
@@ -558,7 +558,7 @@ added: v15.0.0
558558
* `algorithm`: {RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams}
559559
* `key`: {CryptoKey}
560560
* `data`: {ArrayBuffer|TypedArray|DataView|Buffer}
561-
* Returns: {Promise} Fulfills with an {ArrayBuffer}
561+
* Returns: {Promise} Fulfills with an {ArrayBuffer} upon success.
562562

563563
Using the method and parameters specified in `algorithm` and the keying
564564
material provided by `key`, `subtle.decrypt()` attempts to decipher the
@@ -593,10 +593,10 @@ changes:
593593

594594
<!--lint disable maximum-line-length remark-lint-->
595595

596-
* `algorithm`: {AlgorithmIdentifier|EcdhKeyDeriveParams|HkdfParams|Pbkdf2Params}
596+
* `algorithm`: {EcdhKeyDeriveParams|HkdfParams|Pbkdf2Params}
597597
* `baseKey`: {CryptoKey}
598598
* `length`: {number|null} **Default:** `null`
599-
* Returns: {Promise} Fulfills with an {ArrayBuffer}
599+
* Returns: {Promise} Fulfills with an {ArrayBuffer} upon success.
600600

601601
<!--lint enable maximum-line-length remark-lint-->
602602

@@ -633,12 +633,12 @@ changes:
633633

634634
<!--lint disable maximum-line-length remark-lint-->
635635

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

643643
<!--lint enable maximum-line-length remark-lint-->
644644

@@ -665,9 +665,9 @@ The algorithms currently supported include:
665665
added: v15.0.0
666666
-->
667667

668-
* `algorithm`: {string|Object}
668+
* `algorithm`: {string|AlgorithmIdentifier}
669669
* `data`: {ArrayBuffer|TypedArray|DataView|Buffer}
670-
* Returns: {Promise} Fulfills with an {ArrayBuffer}
670+
* Returns: {Promise} Fulfills with an {ArrayBuffer} upon success.
671671

672672
Using the method identified by `algorithm`, `subtle.digest()` attempts to
673673
generate a digest of `data`. If successful, the returned promise is resolved
@@ -692,7 +692,7 @@ added: v15.0.0
692692
* `algorithm`: {RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams}
693693
* `key`: {CryptoKey}
694694
* `data`: {ArrayBuffer|TypedArray|DataView|Buffer}
695-
* Returns: {Promise} Fulfills with an {ArrayBuffer}
695+
* Returns: {Promise} Fulfills with an {ArrayBuffer} upon success.
696696

697697
Using the method and parameters specified by `algorithm` and the keying
698698
material provided by `key`, `subtle.encrypt()` attempts to encipher `data`.
@@ -724,7 +724,7 @@ changes:
724724

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

729729
Exports the given key into the specified format, if supported.
730730

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

741-
| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
741+
| Supported Key Algorithm | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
742742
| ------------------------------------------------------- | -------- | --------- | ------- | ------- |
743743
| `'AES-CBC'` | | | ✔ | ✔ |
744744
| `'AES-CTR'` | | | ✔ | ✔ |
@@ -748,9 +748,7 @@ specification.
748748
| `'ECDSA'` | ✔ | ✔ | ✔ | ✔ |
749749
| `'Ed25519'` | ✔ | ✔ | ✔ | ✔ |
750750
| `'Ed448'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | ✔ |
751-
| `'HDKF'` | | | | |
752751
| `'HMAC'` | | | ✔ | ✔ |
753-
| `'PBKDF2'` | | | | |
754752
| `'RSA-OAEP'` | ✔ | ✔ | ✔ | |
755753
| `'RSA-PSS'` | ✔ | ✔ | ✔ | |
756754
| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | |
@@ -763,13 +761,13 @@ added: v15.0.0
763761

764762
<!--lint disable maximum-line-length remark-lint-->
765763

766-
* `algorithm`: {AlgorithmIdentifier|RsaHashedKeyGenParams|EcKeyGenParams|HmacKeyGenParams|AesKeyGenParams}
764+
* `algorithm`: {string|AlgorithmIdentifier|RsaHashedKeyGenParams|EcKeyGenParams|HmacKeyGenParams|AesKeyGenParams}
767765

768766
<!--lint enable maximum-line-length remark-lint-->
769767

770768
* `extractable`: {boolean}
771769
* `keyUsages`: {string\[]} See [Key usages][].
772-
* Returns: {Promise} Fulfills with a {CryptoKey|CryptoKeyPair}
770+
* Returns: {Promise} Fulfills with a {CryptoKey|CryptoKeyPair} upon success.
773771

774772
Using the method and parameters provided in `algorithm`, `subtle.generateKey()`
775773
attempts to generate new keying material. Depending the method used, the method
@@ -817,13 +815,13 @@ changes:
817815

818816
<!--lint disable maximum-line-length remark-lint-->
819817

820-
* `algorithm`: {AlgorithmIdentifier|RsaHashedImportParams|EcKeyImportParams|HmacImportParams}
818+
* `algorithm`: {string|AlgorithmIdentifier|RsaHashedImportParams|EcKeyImportParams|HmacImportParams}
821819

822820
<!--lint enable maximum-line-length remark-lint-->
823821

824822
* `extractable`: {boolean}
825823
* `keyUsages`: {string\[]} See [Key usages][].
826-
* Returns: {Promise} Fulfills with a {CryptoKey}
824+
* Returns: {Promise} Fulfills with a {CryptoKey} upon success.
827825

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

835833
The algorithms currently supported include:
836834

837-
| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
835+
| Supported Key Algorithm | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
838836
| ------------------------------------------------------- | -------- | --------- | ------- | ------- |
839837
| `'AES-CBC'` | | | ✔ | ✔ |
840838
| `'AES-CTR'` | | | ✔ | ✔ |
@@ -867,10 +865,10 @@ changes:
867865

868866
<!--lint disable maximum-line-length remark-lint-->
869867

870-
* `algorithm`: {AlgorithmIdentifier|RsaPssParams|EcdsaParams|Ed448Params}
868+
* `algorithm`: {string|AlgorithmIdentifier|RsaPssParams|EcdsaParams|Ed448Params}
871869
* `key`: {CryptoKey}
872870
* `data`: {ArrayBuffer|TypedArray|DataView|Buffer}
873-
* Returns: {Promise} Fulfills with an {ArrayBuffer}
871+
* Returns: {Promise} Fulfills with an {ArrayBuffer} upon success.
874872

875873
<!--lint enable maximum-line-length remark-lint-->
876874

@@ -900,14 +898,14 @@ added: v15.0.0
900898

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

903-
* `unwrapAlgo`: {AlgorithmIdentifier|RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams}
904-
* `unwrappedKeyAlgo`: {AlgorithmIdentifier|RsaHashedImportParams|EcKeyImportParams|HmacImportParams}
901+
* `unwrapAlgo`: {string|AlgorithmIdentifier|RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams}
902+
* `unwrappedKeyAlgo`: {string|AlgorithmIdentifier|RsaHashedImportParams|EcKeyImportParams|HmacImportParams}
905903

906904
<!--lint enable maximum-line-length remark-lint-->
907905

908906
* `extractable`: {boolean}
909907
* `keyUsages`: {string\[]} See [Key usages][].
910-
* Returns: {Promise} Fulfills with a {CryptoKey}
908+
* Returns: {Promise} Fulfills with a {CryptoKey} upon success.
911909

912910
In cryptography, "wrapping a key" refers to exporting and then encrypting the
913911
keying material. The `subtle.unwrapKey()` method attempts to decrypt a wrapped
@@ -957,11 +955,11 @@ changes:
957955

958956
<!--lint disable maximum-line-length remark-lint-->
959957

960-
* `algorithm`: {AlgorithmIdentifier|RsaPssParams|EcdsaParams|Ed448Params}
958+
* `algorithm`: {string|AlgorithmIdentifier|RsaPssParams|EcdsaParams|Ed448Params}
961959
* `key`: {CryptoKey}
962960
* `signature`: {ArrayBuffer|TypedArray|DataView|Buffer}
963961
* `data`: {ArrayBuffer|TypedArray|DataView|Buffer}
964-
* Returns: {Promise} Fulfills with a {boolean}
962+
* Returns: {Promise} Fulfills with a {boolean} upon success.
965963

966964
<!--lint enable maximum-line-length remark-lint-->
967965

@@ -990,8 +988,8 @@ added: v15.0.0
990988
* `format`: {string} Must be one of `'raw'`, `'pkcs8'`, `'spki'`, or `'jwk'`.
991989
* `key`: {CryptoKey}
992990
* `wrappingKey`: {CryptoKey}
993-
* `wrapAlgo`: {AlgorithmIdentifier|RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams}
994-
* Returns: {Promise} Fulfills with an {ArrayBuffer}
991+
* `wrapAlgo`: {string|AlgorithmIdentifier|RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams}
992+
* Returns: {Promise} Fulfills with an {ArrayBuffer} upon success.
995993

996994
<!--lint enable maximum-line-length remark-lint-->
997995

@@ -1022,21 +1020,43 @@ are simple JavaScript dictionary objects.
10221020
### Class: `AlgorithmIdentifier`
10231021

10241022
<!-- YAML
1025-
added:
1026-
- v18.4.0
1027-
- v16.17.0
1023+
added: v15.0.0
10281024
-->
10291025

10301026
#### `algorithmIdentifier.name`
10311027

10321028
<!-- YAML
1033-
added:
1034-
- v18.4.0
1035-
- v16.17.0
1029+
added: v15.0.0
10361030
-->
10371031

10381032
* Type: {string}
10391033

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

10421062
<!-- YAML

‎tools/doc/type-parser.mjs

+1
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)