Skip to content

Commit 72e8e06

Browse files
panvaruyadorno
panva
authored and
ruyadorno
committedJan 5, 2025
crypto: graduate WebCryptoAPI Ed25519 and X25519 algorithms as stable
PR-URL: #56142 Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Tobias Nießen <tniessen@tnie.de>
·
v22.14.0v22.13.0
1 parent 81c94a3 commit 72e8e06

File tree

2 files changed

+95
-98
lines changed

2 files changed

+95
-98
lines changed
 

‎doc/api/webcrypto.md

+88-87
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22

33
<!-- YAML
44
changes:
5+
- version: REPLACEME
6+
pr-url: https://github.com/nodejs/node/pull/56142
7+
description: Algorithms `Ed25519` and `X25519` are now stable.
58
- version:
69
- v20.0.0
710
- v18.17.0
@@ -113,9 +116,7 @@ async function generateEcKey(namedCurve = 'P-521') {
113116
}
114117
```
115118

116-
#### Ed25519/Ed448/X25519/X448 key pairs
117-
118-
> Stability: 1 - Experimental
119+
#### Ed25519/X25519 key pairs
119120

120121
```js
121122
const { subtle } = globalThis.crypto;
@@ -353,28 +354,28 @@ async function digest(data, algorithm = 'SHA-512') {
353354
The table details the algorithms supported by the Node.js Web Crypto API
354355
implementation and the APIs supported for each:
355356

356-
| Algorithm | `generateKey` | `exportKey` | `importKey` | `encrypt` | `decrypt` | `wrapKey` | `unwrapKey` | `deriveBits` | `deriveKey` | `sign` | `verify` | `digest` |
357-
| --------------------------------------------------------- | ------------- | ----------- | ----------- | --------- | --------- | --------- | ----------- | ------------ | ----------- | ------ | -------- | -------- |
358-
| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
359-
| `'RSA-PSS'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
360-
| `'RSA-OAEP'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | |
361-
| `'ECDSA'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
362-
| `'Ed25519'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
363-
| `'Ed448'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
364-
| `'ECDH'` | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | |
365-
| `'X25519'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | |
366-
| `'X448'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | |
367-
| `'AES-CTR'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | |
368-
| `'AES-CBC'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | |
369-
| `'AES-GCM'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | |
370-
| `'AES-KW'` | ✔ | ✔ | ✔ | | | ✔ | ✔ | | | | | |
371-
| `'HMAC'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
372-
| `'HKDF'` | | ✔ | ✔ | | | | | ✔ | ✔ | | | |
373-
| `'PBKDF2'` | | ✔ | ✔ | | | | | ✔ | ✔ | | | |
374-
| `'SHA-1'` | | | | | | | | | | | | ✔ |
375-
| `'SHA-256'` | | | | | | | | | | | | ✔ |
376-
| `'SHA-384'` | | | | | | | | | | | | ✔ |
377-
| `'SHA-512'` | | | | | | | | | | | | ✔ |
357+
| Algorithm | `generateKey` | `exportKey` | `importKey` | `encrypt` | `decrypt` | `wrapKey` | `unwrapKey` | `deriveBits` | `deriveKey` | `sign` | `verify` | `digest` |
358+
| ------------------------------------------------------- | ------------- | ----------- | ----------- | --------- | --------- | --------- | ----------- | ------------ | ----------- | ------ | -------- | -------- |
359+
| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
360+
| `'RSA-PSS'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
361+
| `'RSA-OAEP'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | |
362+
| `'ECDSA'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
363+
| `'Ed25519'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
364+
| `'Ed448'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
365+
| `'ECDH'` | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | |
366+
| `'X25519'` | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | |
367+
| `'X448'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | |
368+
| `'AES-CTR'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | |
369+
| `'AES-CBC'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | |
370+
| `'AES-GCM'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | |
371+
| `'AES-KW'` | ✔ | ✔ | ✔ | | | ✔ | ✔ | | | | | |
372+
| `'HMAC'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
373+
| `'HKDF'` | | ✔ | ✔ | | | | | ✔ | ✔ | | | |
374+
| `'PBKDF2'` | | ✔ | ✔ | | | | | ✔ | ✔ | | | |
375+
| `'SHA-1'` | | | | | | | | | | | | ✔ |
376+
| `'SHA-256'` | | | | | | | | | | | | ✔ |
377+
| `'SHA-384'` | | | | | | | | | | | | ✔ |
378+
| `'SHA-512'` | | | | | | | | | | | | ✔ |
378379

379380
## Class: `Crypto`
380381

@@ -496,24 +497,24 @@ The possible usages are:
496497
Valid key usages depend on the key algorithm (identified by
497498
`cryptokey.algorithm.name`).
498499

499-
| Key Type | `'encrypt'` | `'decrypt'` | `'sign'` | `'verify'` | `'deriveKey'` | `'deriveBits'` | `'wrapKey'` | `'unwrapKey'` |
500-
| --------------------------------------------------------- | ----------- | ----------- | -------- | ---------- | ------------- | -------------- | ----------- | ------------- |
501-
| `'AES-CBC'` | ✔ | ✔ | | | | | ✔ | ✔ |
502-
| `'AES-CTR'` | ✔ | ✔ | | | | | ✔ | ✔ |
503-
| `'AES-GCM'` | ✔ | ✔ | | | | | ✔ | ✔ |
504-
| `'AES-KW'` | | | | | | | ✔ | ✔ |
505-
| `'ECDH'` | | | | | ✔ | ✔ | | |
506-
| `'X25519'` <span class="experimental-inline"></span>[^1] | | | | | ✔ | ✔ | | |
507-
| `'X448'` <span class="experimental-inline"></span>[^1] | | | | | ✔ | ✔ | | |
508-
| `'ECDSA'` | | | ✔ | ✔ | | | | |
509-
| `'Ed25519'` <span class="experimental-inline"></span>[^1] | | | ✔ | ✔ | | | | |
510-
| `'Ed448'` <span class="experimental-inline"></span>[^1] | | | ✔ | ✔ | | | | |
511-
| `'HDKF'` | | | | | ✔ | ✔ | | |
512-
| `'HMAC'` | | | ✔ | ✔ | | | | |
513-
| `'PBKDF2'` | | | | | ✔ | ✔ | | |
514-
| `'RSA-OAEP'` | ✔ | ✔ | | | | | ✔ | ✔ |
515-
| `'RSA-PSS'` | | | ✔ | ✔ | | | | |
516-
| `'RSASSA-PKCS1-v1_5'` | | | ✔ | ✔ | | | | |
500+
| Key Type | `'encrypt'` | `'decrypt'` | `'sign'` | `'verify'` | `'deriveKey'` | `'deriveBits'` | `'wrapKey'` | `'unwrapKey'` |
501+
| ------------------------------------------------------- | ----------- | ----------- | -------- | ---------- | ------------- | -------------- | ----------- | ------------- |
502+
| `'AES-CBC'` | ✔ | ✔ | | | | | ✔ | ✔ |
503+
| `'AES-CTR'` | ✔ | ✔ | | | | | ✔ | ✔ |
504+
| `'AES-GCM'` | ✔ | ✔ | | | | | ✔ | ✔ |
505+
| `'AES-KW'` | | | | | | | ✔ | ✔ |
506+
| `'ECDH'` | | | | | ✔ | ✔ | | |
507+
| `'X25519'` | | | | | ✔ | ✔ | | |
508+
| `'X448'` <span class="experimental-inline"></span>[^1] | | | | | ✔ | ✔ | | |
509+
| `'ECDSA'` | | | ✔ | ✔ | | | | |
510+
| `'Ed25519'` | | | ✔ | ✔ | | | | |
511+
| `'Ed448'` <span class="experimental-inline"></span>[^1] | | | ✔ | ✔ | | | | |
512+
| `'HDKF'` | | | | | ✔ | ✔ | | |
513+
| `'HMAC'` | | | ✔ | ✔ | | | | |
514+
| `'PBKDF2'` | | | | | ✔ | ✔ | | |
515+
| `'RSA-OAEP'` | ✔ | ✔ | | | | | ✔ | ✔ |
516+
| `'RSA-PSS'` | | | ✔ | ✔ | | | | |
517+
| `'RSASSA-PKCS1-v1_5'` | | | ✔ | ✔ | | | | |
517518

518519
## Class: `CryptoKeyPair`
519520

@@ -608,7 +609,7 @@ containing the generated data.
608609
The algorithms currently supported include:
609610

610611
* `'ECDH'`
611-
* `'X25519'` <span class="experimental-inline"></span>[^1]
612+
* `'X25519'`
612613
* `'X448'` <span class="experimental-inline"></span>[^1]
613614
* `'HKDF'`
614615
* `'PBKDF2'`
@@ -648,7 +649,7 @@ generate raw keying material, then passing the result into the
648649
The algorithms currently supported include:
649650

650651
* `'ECDH'`
651-
* `'X25519'` <span class="experimental-inline"></span>[^1]
652+
* `'X25519'`
652653
* `'X448'` <span class="experimental-inline"></span>[^1]
653654
* `'HKDF'`
654655
* `'PBKDF2'`
@@ -732,22 +733,22 @@ When `format` is `'jwk'` and the export is successful, the returned promise
732733
will be resolved with a JavaScript object conforming to the [JSON Web Key][]
733734
specification.
734735

735-
| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
736-
| --------------------------------------------------------- | -------- | --------- | ------- | ------- |
737-
| `'AES-CBC'` | | | ✔ | ✔ |
738-
| `'AES-CTR'` | | | ✔ | ✔ |
739-
| `'AES-GCM'` | | | ✔ | ✔ |
740-
| `'AES-KW'` | | | ✔ | ✔ |
741-
| `'ECDH'` | ✔ | ✔ | ✔ | ✔ |
742-
| `'ECDSA'` | ✔ | ✔ | ✔ | ✔ |
743-
| `'Ed25519'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | ✔ |
744-
| `'Ed448'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | ✔ |
745-
| `'HDKF'` | | | | |
746-
| `'HMAC'` | | | ✔ | ✔ |
747-
| `'PBKDF2'` | | | | |
748-
| `'RSA-OAEP'` | ✔ | ✔ | ✔ | |
749-
| `'RSA-PSS'` | ✔ | ✔ | ✔ | |
750-
| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | |
736+
| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
737+
| ------------------------------------------------------- | -------- | --------- | ------- | ------- |
738+
| `'AES-CBC'` | | | ✔ | ✔ |
739+
| `'AES-CTR'` | | | ✔ | ✔ |
740+
| `'AES-GCM'` | | | ✔ | ✔ |
741+
| `'AES-KW'` | | | ✔ | ✔ |
742+
| `'ECDH'` | ✔ | ✔ | ✔ | ✔ |
743+
| `'ECDSA'` | ✔ | ✔ | ✔ | ✔ |
744+
| `'Ed25519'` | ✔ | ✔ | ✔ | ✔ |
745+
| `'Ed448'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | ✔ |
746+
| `'HDKF'` | | | | |
747+
| `'HMAC'` | | | ✔ | ✔ |
748+
| `'PBKDF2'` | | | | |
749+
| `'RSA-OAEP'` | ✔ | ✔ | ✔ | |
750+
| `'RSA-PSS'` | ✔ | ✔ | ✔ | |
751+
| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | |
751752

752753
### `subtle.generateKey(algorithm, extractable, keyUsages)`
753754

@@ -776,10 +777,10 @@ include:
776777
* `'RSA-PSS'`
777778
* `'RSA-OAEP'`
778779
* `'ECDSA'`
779-
* `'Ed25519'` <span class="experimental-inline"></span>[^1]
780+
* `'Ed25519'`
780781
* `'Ed448'` <span class="experimental-inline"></span>[^1]
781782
* `'ECDH'`
782-
* `'X25519'` <span class="experimental-inline"></span>[^1]
783+
* `'X25519'`
783784
* `'X448'` <span class="experimental-inline"></span>[^1]
784785

785786
The {CryptoKey} (secret key) generating algorithms supported include:
@@ -828,24 +829,24 @@ If importing a `'PBKDF2'` key, `extractable` must be `false`.
828829

829830
The algorithms currently supported include:
830831

831-
| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
832-
| --------------------------------------------------------- | -------- | --------- | ------- | ------- |
833-
| `'AES-CBC'` | | | ✔ | ✔ |
834-
| `'AES-CTR'` | | | ✔ | ✔ |
835-
| `'AES-GCM'` | | | ✔ | ✔ |
836-
| `'AES-KW'` | | | ✔ | ✔ |
837-
| `'ECDH'` | ✔ | ✔ | ✔ | ✔ |
838-
| `'X25519'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | ✔ |
839-
| `'X448'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | ✔ |
840-
| `'ECDSA'` | ✔ | ✔ | ✔ | ✔ |
841-
| `'Ed25519'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | ✔ |
842-
| `'Ed448'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | ✔ |
843-
| `'HDKF'` | | | | ✔ |
844-
| `'HMAC'` | | | ✔ | ✔ |
845-
| `'PBKDF2'` | | | | ✔ |
846-
| `'RSA-OAEP'` | ✔ | ✔ | ✔ | |
847-
| `'RSA-PSS'` | ✔ | ✔ | ✔ | |
848-
| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | |
832+
| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
833+
| ------------------------------------------------------- | -------- | --------- | ------- | ------- |
834+
| `'AES-CBC'` | | | ✔ | ✔ |
835+
| `'AES-CTR'` | | | ✔ | ✔ |
836+
| `'AES-GCM'` | | | ✔ | ✔ |
837+
| `'AES-KW'` | | | ✔ | ✔ |
838+
| `'ECDH'` | ✔ | ✔ | ✔ | ✔ |
839+
| `'X25519'` | ✔ | ✔ | ✔ | ✔ |
840+
| `'X448'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | ✔ |
841+
| `'ECDSA'` | ✔ | ✔ | ✔ | ✔ |
842+
| `'Ed25519'` | ✔ | ✔ | ✔ | ✔ |
843+
| `'Ed448'` <span class="experimental-inline"></span>[^1] | ✔ | ✔ | ✔ | ✔ |
844+
| `'HDKF'` | | | | ✔ |
845+
| `'HMAC'` | | | ✔ | ✔ |
846+
| `'PBKDF2'` | | | | ✔ |
847+
| `'RSA-OAEP'` | ✔ | ✔ | ✔ | |
848+
| `'RSA-PSS'` | ✔ | ✔ | ✔ | |
849+
| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | |
849850

850851
### `subtle.sign(algorithm, key, data)`
851852

@@ -878,7 +879,7 @@ The algorithms currently supported include:
878879
* `'RSASSA-PKCS1-v1_5'`
879880
* `'RSA-PSS'`
880881
* `'ECDSA'`
881-
* `'Ed25519'` <span class="experimental-inline"></span>[^1]
882+
* `'Ed25519'`
882883
* `'Ed448'` <span class="experimental-inline"></span>[^1]
883884
* `'HMAC'`
884885

@@ -926,10 +927,10 @@ The unwrapped key algorithms supported include:
926927
* `'RSA-PSS'`
927928
* `'RSA-OAEP'`
928929
* `'ECDSA'`
929-
* `'Ed25519'` <span class="experimental-inline"></span>[^1]
930+
* `'Ed25519'`
930931
* `'Ed448'` <span class="experimental-inline"></span>[^1]
931932
* `'ECDH'`
932-
* `'X25519'` <span class="experimental-inline"></span>[^1]
933+
* `'X25519'`
933934
* `'X448'` <span class="experimental-inline"></span>[^1]
934935
* `'HMAC'`
935936
* `'AES-CTR'`
@@ -969,7 +970,7 @@ The algorithms currently supported include:
969970
* `'RSASSA-PKCS1-v1_5'`
970971
* `'RSA-PSS'`
971972
* `'ECDSA'`
972-
* `'Ed25519'` <span class="experimental-inline"></span>[^1]
973+
* `'Ed25519'`
973974
* `'Ed448'` <span class="experimental-inline"></span>[^1]
974975
* `'HMAC'`
975976

@@ -1642,8 +1643,8 @@ added: v15.0.0
16421643

16431644
The length (in bytes) of the random salt to use.
16441645

1645-
[^1]: An experimental implementation of
1646-
[Secure Curves in the Web Cryptography API][] as of 30 August 2023
1646+
[^1]: An experimental implementation of Ed448 and X448 algorithms from
1647+
[Secure Curves in the Web Cryptography API][] as of 21 October 2024
16471648

16481649
[JSON Web Key]: https://tools.ietf.org/html/rfc7517
16491650
[Key usages]: #cryptokeyusages

‎lib/internal/crypto/util.js

+7-11
Original file line numberDiff line numberDiff line change
@@ -189,18 +189,22 @@ const kSupportedAlgorithms = {
189189
'AES-GCM': 'AesKeyGenParams',
190190
'AES-KW': 'AesKeyGenParams',
191191
'HMAC': 'HmacKeyGenParams',
192+
'Ed25519': null,
193+
'X25519': null,
192194
},
193195
'sign': {
194196
'RSASSA-PKCS1-v1_5': null,
195197
'RSA-PSS': 'RsaPssParams',
196198
'ECDSA': 'EcdsaParams',
197199
'HMAC': null,
200+
'Ed25519': null,
198201
},
199202
'verify': {
200203
'RSASSA-PKCS1-v1_5': null,
201204
'RSA-PSS': 'RsaPssParams',
202205
'ECDSA': 'EcdsaParams',
203206
'HMAC': null,
207+
'Ed25519': null,
204208
},
205209
'importKey': {
206210
'RSASSA-PKCS1-v1_5': 'RsaHashedImportParams',
@@ -215,11 +219,14 @@ const kSupportedAlgorithms = {
215219
'AES-CBC': null,
216220
'AES-GCM': null,
217221
'AES-KW': null,
222+
'Ed25519': null,
223+
'X25519': null,
218224
},
219225
'deriveBits': {
220226
'HKDF': 'HkdfParams',
221227
'PBKDF2': 'Pbkdf2Params',
222228
'ECDH': 'EcdhKeyDeriveParams',
229+
'X25519': 'EcdhKeyDeriveParams',
223230
},
224231
'encrypt': {
225232
'RSA-OAEP': 'RsaOaepParams',
@@ -251,17 +258,6 @@ const kSupportedAlgorithms = {
251258
};
252259

253260
const experimentalAlgorithms = ObjectEntries({
254-
'X25519': {
255-
generateKey: null,
256-
importKey: null,
257-
deriveBits: 'EcdhKeyDeriveParams',
258-
},
259-
'Ed25519': {
260-
generateKey: null,
261-
sign: null,
262-
verify: null,
263-
importKey: null,
264-
},
265261
'X448': {
266262
generateKey: null,
267263
importKey: null,

0 commit comments

Comments
 (0)
Please sign in to comment.