Skip to content

Commit 3627616

Browse files
panvadanielleadams
panva
authored and
danielleadams
committedOct 11, 2022
doc,crypto: mark experimental algorithms more visually
PR-URL: #44892 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>
·
v18.20.8v18.11.0
1 parent a33cc22 commit 3627616

File tree

2 files changed

+100
-91
lines changed

2 files changed

+100
-91
lines changed
 

‎doc/api/webcrypto.md

+91-91
Original file line numberDiff line numberDiff line change
@@ -332,28 +332,28 @@ async function digest(data, algorithm = 'SHA-512') {
332332
The table details the algorithms supported by the Node.js Web Crypto API
333333
implementation and the APIs supported for each:
334334

335-
| Algorithm | `generateKey` | `exportKey` | `importKey` | `encrypt` | `decrypt` | `wrapKey` | `unwrapKey` | `deriveBits` | `deriveKey` | `sign` | `verify` | `digest` |
336-
| --------------------- | ------------- | ----------- | ----------- | --------- | --------- | --------- | ----------- | ------------ | ----------- | ------ | -------- | -------- |
337-
| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
338-
| `'RSA-PSS'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
339-
| `'RSA-OAEP'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | |
340-
| `'ECDSA'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
341-
| `'Ed25519'`[^1] | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
342-
| `'Ed448'`[^1] | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
343-
| `'ECDH'` | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | |
344-
| `'X25519'`[^1] | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | |
345-
| `'X448'`[^1] | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | |
346-
| `'AES-CTR'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | |
347-
| `'AES-CBC'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | |
348-
| `'AES-GCM'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | |
349-
| `'AES-KW'` | ✔ | ✔ | ✔ | | | ✔ | ✔ | | | | | |
350-
| `'HMAC'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
351-
| `'HKDF'` | | ✔ | ✔ | | | | | ✔ | ✔ | | | |
352-
| `'PBKDF2'` | | ✔ | ✔ | | | | | ✔ | ✔ | | | |
353-
| `'SHA-1'` | | | | | | | | | | | | ✔ |
354-
| `'SHA-256'` | | | | | | | | | | | | ✔ |
355-
| `'SHA-384'` | | | | | | | | | | | | ✔ |
356-
| `'SHA-512'` | | | | | | | | | | | | ✔ |
335+
| Algorithm | `generateKey` | `exportKey` | `importKey` | `encrypt` | `decrypt` | `wrapKey` | `unwrapKey` | `deriveBits` | `deriveKey` | `sign` | `verify` | `digest` |
336+
| --------------------------------------------------------- | ------------- | ----------- | ----------- | --------- | --------- | --------- | ----------- | ------------ | ----------- | ------ | -------- | -------- |
337+
| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
338+
| `'RSA-PSS'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
339+
| `'RSA-OAEP'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | |
340+
| `'ECDSA'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
341+
| `'Ed25519'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
342+
| `'Ed448'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
343+
| `'ECDH'` | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | |
344+
| `'X25519'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | |
345+
| `'X448'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | |
346+
| `'AES-CTR'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | |
347+
| `'AES-CBC'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | |
348+
| `'AES-GCM'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | |
349+
| `'AES-KW'` | ✔ | ✔ | ✔ | | | ✔ | ✔ | | | | | |
350+
| `'HMAC'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
351+
| `'HKDF'` | | ✔ | ✔ | | | | | ✔ | ✔ | | | |
352+
| `'PBKDF2'` | | ✔ | ✔ | | | | | ✔ | ✔ | | | |
353+
| `'SHA-1'` | | | | | | | | | | | | ✔ |
354+
| `'SHA-256'` | | | | | | | | | | | | ✔ |
355+
| `'SHA-384'` | | | | | | | | | | | | ✔ |
356+
| `'SHA-512'` | | | | | | | | | | | | ✔ |
357357

358358
## Class: `Crypto`
359359

@@ -475,24 +475,24 @@ The possible usages are:
475475
Valid key usages depend on the key algorithm (identified by
476476
`cryptokey.algorithm.name`).
477477

478-
| Key Type | `'encrypt'` | `'decrypt'` | `'sign'` | `'verify'` | `'deriveKey'` | `'deriveBits'` | `'wrapKey'` | `'unwrapKey'` |
479-
| --------------------- | ----------- | ----------- | -------- | ---------- | ------------- | -------------- | ----------- | ------------- |
480-
| `'AES-CBC'` | ✔ | ✔ | | | | | ✔ | ✔ |
481-
| `'AES-CTR'` | ✔ | ✔ | | | | | ✔ | ✔ |
482-
| `'AES-GCM'` | ✔ | ✔ | | | | | ✔ | ✔ |
483-
| `'AES-KW'` | | | | | | | ✔ | ✔ |
484-
| `'ECDH'` | | | | | ✔ | ✔ | | |
485-
| `'X25519'`[^1] | | | | | ✔ | ✔ | | |
486-
| `'X448'`[^1] | | | | | ✔ | ✔ | | |
487-
| `'ECDSA'` | | | ✔ | ✔ | | | | |
488-
| `'Ed25519'`[^1] | | | ✔ | ✔ | | | | |
489-
| `'Ed448'`[^1] | | | ✔ | ✔ | | | | |
490-
| `'HDKF'` | | | | | ✔ | ✔ | | |
491-
| `'HMAC'` | | | ✔ | ✔ | | | | |
492-
| `'PBKDF2'` | | | | | ✔ | ✔ | | |
493-
| `'RSA-OAEP'` | ✔ | ✔ | | | | | ✔ | ✔ |
494-
| `'RSA-PSS'` | | | ✔ | ✔ | | | | |
495-
| `'RSASSA-PKCS1-v1_5'` | | | ✔ | ✔ | | | | |
478+
| Key Type | `'encrypt'` | `'decrypt'` | `'sign'` | `'verify'` | `'deriveKey'` | `'deriveBits'` | `'wrapKey'` | `'unwrapKey'` |
479+
| --------------------------------------------------------- | ----------- | ----------- | -------- | ---------- | ------------- | -------------- | ----------- | ------------- |
480+
| `'AES-CBC'` | ✔ | ✔ | | | | | ✔ | ✔ |
481+
| `'AES-CTR'` | ✔ | ✔ | | | | | ✔ | ✔ |
482+
| `'AES-GCM'` | ✔ | ✔ | | | | | ✔ | ✔ |
483+
| `'AES-KW'` | | | | | | | ✔ | ✔ |
484+
| `'ECDH'` | | | | | ✔ | ✔ | | |
485+
| `'X25519'` <span class="experimental-inline"></span>[^1] | | | | | ✔ | ✔ | | |
486+
| `'X448'` <span class="experimental-inline"></span>[^1] | | | | | ✔ | ✔ | | |
487+
| `'ECDSA'` | | | ✔ | ✔ | | | | |
488+
| `'Ed25519'` <span class="experimental-inline"></span>[^1] | | | ✔ | ✔ | | | | |
489+
| `'Ed448'` <span class="experimental-inline"></span>[^1] | | | ✔ | ✔ | | | | |
490+
| `'HDKF'` | | | | | ✔ | ✔ | | |
491+
| `'HMAC'` | | | ✔ | ✔ | | | | |
492+
| `'PBKDF2'` | | | | | ✔ | ✔ | | |
493+
| `'RSA-OAEP'` | ✔ | ✔ | | | | | ✔ | ✔ |
494+
| `'RSA-PSS'` | | | ✔ | ✔ | | | | |
495+
| `'RSASSA-PKCS1-v1_5'` | | | ✔ | ✔ | | | | |
496496

497497
## Class: `CryptoKeyPair`
498498

@@ -575,7 +575,7 @@ The Node.js implementation requires that when `length` is a
575575
number it must be multiple of `8`.
576576

577577
When `length` is `null` the maximum number of bits for a given algorithm is
578-
generated. This is allowed for the `'ECDH'`, `'X25519'`[^1], and `'X448'`[^1]
578+
generated. This is allowed for the `'ECDH'`, `'X25519'`, and `'X448'`
579579
algorithms.
580580

581581
If successful, the returned promise will be resolved with an {ArrayBuffer}
@@ -584,8 +584,8 @@ containing the generated data.
584584
The algorithms currently supported include:
585585

586586
* `'ECDH'`
587-
* `'X25519'`[^1]
588-
* `'X448'`[^1]
587+
* `'X25519'` <span class="experimental-inline"></span>[^1]
588+
* `'X448'` <span class="experimental-inline"></span>[^1]
589589
* `'HKDF'`
590590
* `'PBKDF2'`
591591

@@ -622,8 +622,8 @@ generate raw keying material, then passing the result into the
622622
The algorithms currently supported include:
623623

624624
* `'ECDH'`
625-
* `'X25519'`[^1]
626-
* `'X448'`[^1]
625+
* `'X25519'` <span class="experimental-inline"></span>[^1]
626+
* `'X448'` <span class="experimental-inline"></span>[^1]
627627
* `'HKDF'`
628628
* `'PBKDF2'`
629629

@@ -703,22 +703,22 @@ When `format` is `'jwk'` and the export is successful, the returned promise
703703
will be resolved with a JavaScript object conforming to the [JSON Web Key][]
704704
specification.
705705

706-
| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
707-
| --------------------- | -------- | --------- | ------- | ------- |
708-
| `'AES-CBC'` | | | ✔ | ✔ |
709-
| `'AES-CTR'` | | | ✔ | ✔ |
710-
| `'AES-GCM'` | | | ✔ | ✔ |
711-
| `'AES-KW'` | | | ✔ | ✔ |
712-
| `'ECDH'` | ✔ | ✔ | ✔ | ✔ |
713-
| `'ECDSA'` | ✔ | ✔ | ✔ | ✔ |
714-
| `'Ed25519'`[^1] | ✔ | ✔ | ✔ | ✔ |
715-
| `'Ed448'`[^1] | ✔ | ✔ | ✔ | ✔ |
716-
| `'HDKF'` | | | | |
717-
| `'HMAC'` | | | ✔ | ✔ |
718-
| `'PBKDF2'` | | | | |
719-
| `'RSA-OAEP'` | ✔ | ✔ | ✔ | |
720-
| `'RSA-PSS'` | ✔ | ✔ | ✔ | |
721-
| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | |
706+
| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
707+
| --------------------------------------------------------- | -------- | --------- | ------- | ------- |
708+
| `'AES-CBC'` | | | ✔ | ✔ |
709+
| `'AES-CTR'` | | | ✔ | ✔ |
710+
| `'AES-GCM'` | | | ✔ | ✔ |
711+
| `'AES-KW'` | | | ✔ | ✔ |
712+
| `'ECDH'` | ✔ | ✔ | ✔ | ✔ |
713+
| `'ECDSA'` | ✔ | ✔ | ✔ | ✔ |
714+
| `'Ed25519'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | ✔ |
715+
| `'Ed448'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | ✔ |
716+
| `'HDKF'` | | | | |
717+
| `'HMAC'` | | | ✔ | ✔ |
718+
| `'PBKDF2'` | | | | |
719+
| `'RSA-OAEP'` | ✔ | ✔ | ✔ | |
720+
| `'RSA-PSS'` | ✔ | ✔ | ✔ | |
721+
| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | |
722722

723723
### `subtle.generateKey(algorithm, extractable, keyUsages)`
724724

@@ -747,11 +747,11 @@ include:
747747
* `'RSA-PSS'`
748748
* `'RSA-OAEP'`
749749
* `'ECDSA'`
750-
* `'Ed25519'`[^1]
751-
* `'Ed448'`[^1]
750+
* `'Ed25519'` <span class="experimental-inline"></span>[^1]
751+
* `'Ed448'` <span class="experimental-inline"></span>[^1]
752752
* `'ECDH'`
753-
* `'X25519'`[^1]
754-
* `'X448'`[^1]
753+
* `'X25519'` <span class="experimental-inline"></span>[^1]
754+
* `'X448'` <span class="experimental-inline"></span>[^1]
755755

756756
The {CryptoKey} (secret key) generating algorithms supported include:
757757

@@ -797,24 +797,24 @@ If importing a `'PBKDF2'` key, `extractable` must be `false`.
797797

798798
The algorithms currently supported include:
799799

800-
| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
801-
| --------------------- | -------- | --------- | ------- | ------- |
802-
| `'AES-CBC'` | | | ✔ | ✔ |
803-
| `'AES-CTR'` | | | ✔ | ✔ |
804-
| `'AES-GCM'` | | | ✔ | ✔ |
805-
| `'AES-KW'` | | | ✔ | ✔ |
806-
| `'ECDH'` | ✔ | ✔ | ✔ | ✔ |
807-
| `'X25519'`[^1] | ✔ | ✔ | ✔ | ✔ |
808-
| `'X448'`[^1] | ✔ | ✔ | ✔ | ✔ |
809-
| `'ECDSA'` | ✔ | ✔ | ✔ | ✔ |
810-
| `'Ed25519'`[^1] | ✔ | ✔ | ✔ | ✔ |
811-
| `'Ed448'`[^1] | ✔ | ✔ | ✔ | ✔ |
812-
| `'HDKF'` | | | | ✔ |
813-
| `'HMAC'` | | | ✔ | ✔ |
814-
| `'PBKDF2'` | | | | ✔ |
815-
| `'RSA-OAEP'` | ✔ | ✔ | ✔ | |
816-
| `'RSA-PSS'` | ✔ | ✔ | ✔ | |
817-
| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | |
800+
| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
801+
| --------------------------------------------------------- | -------- | --------- | ------- | ------- |
802+
| `'AES-CBC'` | | | ✔ | ✔ |
803+
| `'AES-CTR'` | | | ✔ | ✔ |
804+
| `'AES-GCM'` | | | ✔ | ✔ |
805+
| `'AES-KW'` | | | ✔ | ✔ |
806+
| `'ECDH'` | ✔ | ✔ | ✔ | ✔ |
807+
| `'X25519'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | ✔ |
808+
| `'X448'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | ✔ |
809+
| `'ECDSA'` | ✔ | ✔ | ✔ | ✔ |
810+
| `'Ed25519'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | ✔ |
811+
| `'Ed448'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | ✔ |
812+
| `'HDKF'` | | | | ✔ |
813+
| `'HMAC'` | | | ✔ | ✔ |
814+
| `'PBKDF2'` | | | | ✔ |
815+
| `'RSA-OAEP'` | ✔ | ✔ | ✔ | |
816+
| `'RSA-PSS'` | ✔ | ✔ | ✔ | |
817+
| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | |
818818

819819
### `subtle.sign(algorithm, key, data)`
820820

@@ -845,8 +845,8 @@ The algorithms currently supported include:
845845
* `'RSASSA-PKCS1-v1_5'`
846846
* `'RSA-PSS'`
847847
* `'ECDSA'`
848-
* `'Ed25519'`[^1]
849-
* `'Ed448'`[^1]
848+
* `'Ed25519'` <span class="experimental-inline"></span>[^1]
849+
* `'Ed448'` <span class="experimental-inline"></span>[^1]
850850
* `'HMAC'`
851851

852852
### `subtle.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgo, unwrappedKeyAlgo, extractable, keyUsages)`
@@ -893,11 +893,11 @@ The unwrapped key algorithms supported include:
893893
* `'RSA-PSS'`
894894
* `'RSA-OAEP'`
895895
* `'ECDSA'`
896-
* `'Ed25519'`[^1]
897-
* `'Ed448'`[^1]
896+
* `'Ed25519'` <span class="experimental-inline"></span>[^1]
897+
* `'Ed448'` <span class="experimental-inline"></span>[^1]
898898
* `'ECDH'`
899-
* `'X25519'`[^1]
900-
* `'X448'`[^1]
899+
* `'X25519'` <span class="experimental-inline"></span>[^1]
900+
* `'X448'` <span class="experimental-inline"></span>[^1]
901901
* `'HMAC'`
902902
* `'AES-CTR'`
903903
* `'AES-CBC'`
@@ -934,8 +934,8 @@ The algorithms currently supported include:
934934
* `'RSASSA-PKCS1-v1_5'`
935935
* `'RSA-PSS'`
936936
* `'ECDSA'`
937-
* `'Ed25519'`[^1]
938-
* `'Ed448'`[^1]
937+
* `'Ed25519'` <span class="experimental-inline"></span>[^1]
938+
* `'Ed448'` <span class="experimental-inline"></span>[^1]
939939
* `'HMAC'`
940940

941941
### `subtle.wrapKey(format, key, wrappingKey, wrapAlgo)`

‎doc/api_assets/style.css

+9
Original file line numberDiff line numberDiff line change
@@ -616,6 +616,15 @@ hr {
616616
border-radius: 3px;
617617
}
618618

619+
.experimental-inline::after {
620+
background-color: var(--red3);
621+
color: var(--white);
622+
content: "experimental";
623+
margin-left: .25rem;
624+
padding: 1px 3px;
625+
border-radius: 3px;
626+
}
627+
619628
#apicontent li {
620629
margin-bottom: .5rem;
621630
}

0 commit comments

Comments
 (0)
Please sign in to comment.