Skip to content

Commit d44ccb3

Browse files
panvatargos
panva
authored and
targos
committed
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 e05e0e5 commit d44ccb3

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
@@ -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
@@ -590,10 +590,10 @@ changes:
590590

591591
<!--lint disable maximum-line-length remark-lint-->
592592

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

598598
<!--lint enable maximum-line-length remark-lint-->
599599

@@ -630,12 +630,12 @@ changes:
630630

631631
<!--lint disable maximum-line-length remark-lint-->
632632

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

640640
<!--lint enable maximum-line-length remark-lint-->
641641

@@ -662,9 +662,9 @@ The algorithms currently supported include:
662662
added: v15.0.0
663663
-->
664664

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

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

694694
Using the method and parameters specified by `algorithm` and the keying
695695
material provided by `key`, `subtle.encrypt()` attempts to encipher `data`.
@@ -721,7 +721,7 @@ changes:
721721

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

726726
Exports the given key into the specified format, if supported.
727727

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

738-
| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
738+
| Supported Key Algorithm | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
739739
| ------------------------------------------------------- | -------- | --------- | ------- | ------- |
740740
| `'AES-CBC'` | | | ✔ | ✔ |
741741
| `'AES-CTR'` | | | ✔ | ✔ |
@@ -745,9 +745,7 @@ specification.
745745
| `'ECDSA'` | ✔ | ✔ | ✔ | ✔ |
746746
| `'Ed25519'` | ✔ | ✔ | ✔ | ✔ |
747747
| `'Ed448'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | ✔ |
748-
| `'HDKF'` | | | | |
749748
| `'HMAC'` | | | ✔ | ✔ |
750-
| `'PBKDF2'` | | | | |
751749
| `'RSA-OAEP'` | ✔ | ✔ | ✔ | |
752750
| `'RSA-PSS'` | ✔ | ✔ | ✔ | |
753751
| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | |
@@ -760,13 +758,13 @@ added: v15.0.0
760758

761759
<!--lint disable maximum-line-length remark-lint-->
762760

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

765763
<!--lint enable maximum-line-length remark-lint-->
766764

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

771769
Using the method and parameters provided in `algorithm`, `subtle.generateKey()`
772770
attempts to generate new keying material. Depending the method used, the method
@@ -814,13 +812,13 @@ changes:
814812

815813
<!--lint disable maximum-line-length remark-lint-->
816814

817-
* `algorithm`: {AlgorithmIdentifier|RsaHashedImportParams|EcKeyImportParams|HmacImportParams}
815+
* `algorithm`: {string|AlgorithmIdentifier|RsaHashedImportParams|EcKeyImportParams|HmacImportParams}
818816

819817
<!--lint enable maximum-line-length remark-lint-->
820818

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

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

832830
The algorithms currently supported include:
833831

834-
| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
832+
| Supported Key Algorithm | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
835833
| ------------------------------------------------------- | -------- | --------- | ------- | ------- |
836834
| `'AES-CBC'` | | | ✔ | ✔ |
837835
| `'AES-CTR'` | | | ✔ | ✔ |
@@ -864,10 +862,10 @@ changes:
864862

865863
<!--lint disable maximum-line-length remark-lint-->
866864

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

872870
<!--lint enable maximum-line-length remark-lint-->
873871

@@ -897,14 +895,14 @@ added: v15.0.0
897895

898896
<!--lint disable maximum-line-length remark-lint-->
899897

900-
* `unwrapAlgo`: {AlgorithmIdentifier|RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams}
901-
* `unwrappedKeyAlgo`: {AlgorithmIdentifier|RsaHashedImportParams|EcKeyImportParams|HmacImportParams}
898+
* `unwrapAlgo`: {string|AlgorithmIdentifier|RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams}
899+
* `unwrappedKeyAlgo`: {string|AlgorithmIdentifier|RsaHashedImportParams|EcKeyImportParams|HmacImportParams}
902900

903901
<!--lint enable maximum-line-length remark-lint-->
904902

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

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

955953
<!--lint disable maximum-line-length remark-lint-->
956954

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

963961
<!--lint enable maximum-line-length remark-lint-->
964962

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

993991
<!--lint enable maximum-line-length remark-lint-->
994992

@@ -1019,21 +1017,43 @@ are simple JavaScript dictionary objects.
10191017
### Class: `AlgorithmIdentifier`
10201018

10211019
<!-- YAML
1022-
added:
1023-
- v18.4.0
1024-
- v16.17.0
1020+
added: v15.0.0
10251021
-->
10261022

10271023
#### `algorithmIdentifier.name`
10281024

10291025
<!-- YAML
1030-
added:
1031-
- v18.4.0
1032-
- v16.17.0
1026+
added: v15.0.0
10331027
-->
10341028

10351029
* Type: {string}
10361030

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

10391059
<!-- 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)