From c2fb38cfdf847a0e8c4dc44ee3f5b94c5f1ca4ec Mon Sep 17 00:00:00 2001
From: Filip Skokan <panva.ip@gmail.com>
Date: Thu, 5 Dec 2024 12:01:58 +0100
Subject: [PATCH] crypto: graduate WebCryptoAPI Ed25519 and X25519 algorithms
 as stable
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PR-URL: https://github.com/nodejs/node/pull/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>
---
 doc/api/webcrypto.md        | 175 ++++++++++++++++++------------------
 lib/internal/crypto/util.js |  18 ++--
 2 files changed, 95 insertions(+), 98 deletions(-)

diff --git a/doc/api/webcrypto.md b/doc/api/webcrypto.md
index 349fb116b1c0d6..b0e3257a8a7100 100644
--- a/doc/api/webcrypto.md
+++ b/doc/api/webcrypto.md
@@ -2,6 +2,9 @@
 
 <!-- YAML
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/56142
+    description: Algorithms `Ed25519` and `X25519` are now stable.
   - version:
     - v20.0.0
     - v18.17.0
@@ -113,9 +116,7 @@ async function generateEcKey(namedCurve = 'P-521') {
 }
 ```
 
-#### Ed25519/Ed448/X25519/X448 key pairs
-
-> Stability: 1 - Experimental
+#### Ed25519/X25519 key pairs
 
 ```js
 const { subtle } = globalThis.crypto;
@@ -353,28 +354,28 @@ async function digest(data, algorithm = 'SHA-512') {
 The table details the algorithms supported by the Node.js Web Crypto API
 implementation and the APIs supported for each:
 
-| Algorithm                                                 | `generateKey` | `exportKey` | `importKey` | `encrypt` | `decrypt` | `wrapKey` | `unwrapKey` | `deriveBits` | `deriveKey` | `sign` | `verify` | `digest` |
-| --------------------------------------------------------- | ------------- | ----------- | ----------- | --------- | --------- | --------- | ----------- | ------------ | ----------- | ------ | -------- | -------- |
-| `'RSASSA-PKCS1-v1_5'`                                     | ✔             | ✔           | ✔           |           |           |           |             |              |             | ✔      | ✔        |          |
-| `'RSA-PSS'`                                               | ✔             | ✔           | ✔           |           |           |           |             |              |             | ✔      | ✔        |          |
-| `'RSA-OAEP'`                                              | ✔             | ✔           | ✔           | ✔         | ✔         | ✔         | ✔           |              |             |        |          |          |
-| `'ECDSA'`                                                 | ✔             | ✔           | ✔           |           |           |           |             |              |             | ✔      | ✔        |          |
-| `'Ed25519'` <span class="experimental-inline"></span>[^1] | ✔             | ✔           | ✔           |           |           |           |             |              |             | ✔      | ✔        |          |
-| `'Ed448'` <span class="experimental-inline"></span>[^1]   | ✔             | ✔           | ✔           |           |           |           |             |              |             | ✔      | ✔        |          |
-| `'ECDH'`                                                  | ✔             | ✔           | ✔           |           |           |           |             | ✔            | ✔           |        |          |          |
-| `'X25519'` <span class="experimental-inline"></span>[^1]  | ✔             | ✔           | ✔           |           |           |           |             | ✔            | ✔           |        |          |          |
-| `'X448'` <span class="experimental-inline"></span>[^1]    | ✔             | ✔           | ✔           |           |           |           |             | ✔            | ✔           |        |          |          |
-| `'AES-CTR'`                                               | ✔             | ✔           | ✔           | ✔         | ✔         | ✔         | ✔           |              |             |        |          |          |
-| `'AES-CBC'`                                               | ✔             | ✔           | ✔           | ✔         | ✔         | ✔         | ✔           |              |             |        |          |          |
-| `'AES-GCM'`                                               | ✔             | ✔           | ✔           | ✔         | ✔         | ✔         | ✔           |              |             |        |          |          |
-| `'AES-KW'`                                                | ✔             | ✔           | ✔           |           |           | ✔         | ✔           |              |             |        |          |          |
-| `'HMAC'`                                                  | ✔             | ✔           | ✔           |           |           |           |             |              |             | ✔      | ✔        |          |
-| `'HKDF'`                                                  |               | ✔           | ✔           |           |           |           |             | ✔            | ✔           |        |          |          |
-| `'PBKDF2'`                                                |               | ✔           | ✔           |           |           |           |             | ✔            | ✔           |        |          |          |
-| `'SHA-1'`                                                 |               |             |             |           |           |           |             |              |             |        |          | ✔        |
-| `'SHA-256'`                                               |               |             |             |           |           |           |             |              |             |        |          | ✔        |
-| `'SHA-384'`                                               |               |             |             |           |           |           |             |              |             |        |          | ✔        |
-| `'SHA-512'`                                               |               |             |             |           |           |           |             |              |             |        |          | ✔        |
+| Algorithm                                               | `generateKey` | `exportKey` | `importKey` | `encrypt` | `decrypt` | `wrapKey` | `unwrapKey` | `deriveBits` | `deriveKey` | `sign` | `verify` | `digest` |
+| ------------------------------------------------------- | ------------- | ----------- | ----------- | --------- | --------- | --------- | ----------- | ------------ | ----------- | ------ | -------- | -------- |
+| `'RSASSA-PKCS1-v1_5'`                                   | ✔             | ✔           | ✔           |           |           |           |             |              |             | ✔      | ✔        |          |
+| `'RSA-PSS'`                                             | ✔             | ✔           | ✔           |           |           |           |             |              |             | ✔      | ✔        |          |
+| `'RSA-OAEP'`                                            | ✔             | ✔           | ✔           | ✔         | ✔         | ✔         | ✔           |              |             |        |          |          |
+| `'ECDSA'`                                               | ✔             | ✔           | ✔           |           |           |           |             |              |             | ✔      | ✔        |          |
+| `'Ed25519'`                                             | ✔             | ✔           | ✔           |           |           |           |             |              |             | ✔      | ✔        |          |
+| `'Ed448'` <span class="experimental-inline"></span>[^1] | ✔             | ✔           | ✔           |           |           |           |             |              |             | ✔      | ✔        |          |
+| `'ECDH'`                                                | ✔             | ✔           | ✔           |           |           |           |             | ✔            | ✔           |        |          |          |
+| `'X25519'`                                              | ✔             | ✔           | ✔           |           |           |           |             | ✔            | ✔           |        |          |          |
+| `'X448'` <span class="experimental-inline"></span>[^1]  | ✔             | ✔           | ✔           |           |           |           |             | ✔            | ✔           |        |          |          |
+| `'AES-CTR'`                                             | ✔             | ✔           | ✔           | ✔         | ✔         | ✔         | ✔           |              |             |        |          |          |
+| `'AES-CBC'`                                             | ✔             | ✔           | ✔           | ✔         | ✔         | ✔         | ✔           |              |             |        |          |          |
+| `'AES-GCM'`                                             | ✔             | ✔           | ✔           | ✔         | ✔         | ✔         | ✔           |              |             |        |          |          |
+| `'AES-KW'`                                              | ✔             | ✔           | ✔           |           |           | ✔         | ✔           |              |             |        |          |          |
+| `'HMAC'`                                                | ✔             | ✔           | ✔           |           |           |           |             |              |             | ✔      | ✔        |          |
+| `'HKDF'`                                                |               | ✔           | ✔           |           |           |           |             | ✔            | ✔           |        |          |          |
+| `'PBKDF2'`                                              |               | ✔           | ✔           |           |           |           |             | ✔            | ✔           |        |          |          |
+| `'SHA-1'`                                               |               |             |             |           |           |           |             |              |             |        |          | ✔        |
+| `'SHA-256'`                                             |               |             |             |           |           |           |             |              |             |        |          | ✔        |
+| `'SHA-384'`                                             |               |             |             |           |           |           |             |              |             |        |          | ✔        |
+| `'SHA-512'`                                             |               |             |             |           |           |           |             |              |             |        |          | ✔        |
 
 ## Class: `Crypto`
 
@@ -496,24 +497,24 @@ The possible usages are:
 Valid key usages depend on the key algorithm (identified by
 `cryptokey.algorithm.name`).
 
-| Key Type                                                  | `'encrypt'` | `'decrypt'` | `'sign'` | `'verify'` | `'deriveKey'` | `'deriveBits'` | `'wrapKey'` | `'unwrapKey'` |
-| --------------------------------------------------------- | ----------- | ----------- | -------- | ---------- | ------------- | -------------- | ----------- | ------------- |
-| `'AES-CBC'`                                               | ✔           | ✔           |          |            |               |                | ✔           | ✔             |
-| `'AES-CTR'`                                               | ✔           | ✔           |          |            |               |                | ✔           | ✔             |
-| `'AES-GCM'`                                               | ✔           | ✔           |          |            |               |                | ✔           | ✔             |
-| `'AES-KW'`                                                |             |             |          |            |               |                | ✔           | ✔             |
-| `'ECDH'`                                                  |             |             |          |            | ✔             | ✔              |             |               |
-| `'X25519'` <span class="experimental-inline"></span>[^1]  |             |             |          |            | ✔             | ✔              |             |               |
-| `'X448'` <span class="experimental-inline"></span>[^1]    |             |             |          |            | ✔             | ✔              |             |               |
-| `'ECDSA'`                                                 |             |             | ✔        | ✔          |               |                |             |               |
-| `'Ed25519'` <span class="experimental-inline"></span>[^1] |             |             | ✔        | ✔          |               |                |             |               |
-| `'Ed448'` <span class="experimental-inline"></span>[^1]   |             |             | ✔        | ✔          |               |                |             |               |
-| `'HDKF'`                                                  |             |             |          |            | ✔             | ✔              |             |               |
-| `'HMAC'`                                                  |             |             | ✔        | ✔          |               |                |             |               |
-| `'PBKDF2'`                                                |             |             |          |            | ✔             | ✔              |             |               |
-| `'RSA-OAEP'`                                              | ✔           | ✔           |          |            |               |                | ✔           | ✔             |
-| `'RSA-PSS'`                                               |             |             | ✔        | ✔          |               |                |             |               |
-| `'RSASSA-PKCS1-v1_5'`                                     |             |             | ✔        | ✔          |               |                |             |               |
+| Key Type                                                | `'encrypt'` | `'decrypt'` | `'sign'` | `'verify'` | `'deriveKey'` | `'deriveBits'` | `'wrapKey'` | `'unwrapKey'` |
+| ------------------------------------------------------- | ----------- | ----------- | -------- | ---------- | ------------- | -------------- | ----------- | ------------- |
+| `'AES-CBC'`                                             | ✔           | ✔           |          |            |               |                | ✔           | ✔             |
+| `'AES-CTR'`                                             | ✔           | ✔           |          |            |               |                | ✔           | ✔             |
+| `'AES-GCM'`                                             | ✔           | ✔           |          |            |               |                | ✔           | ✔             |
+| `'AES-KW'`                                              |             |             |          |            |               |                | ✔           | ✔             |
+| `'ECDH'`                                                |             |             |          |            | ✔             | ✔              |             |               |
+| `'X25519'`                                              |             |             |          |            | ✔             | ✔              |             |               |
+| `'X448'` <span class="experimental-inline"></span>[^1]  |             |             |          |            | ✔             | ✔              |             |               |
+| `'ECDSA'`                                               |             |             | ✔        | ✔          |               |                |             |               |
+| `'Ed25519'`                                             |             |             | ✔        | ✔          |               |                |             |               |
+| `'Ed448'` <span class="experimental-inline"></span>[^1] |             |             | ✔        | ✔          |               |                |             |               |
+| `'HDKF'`                                                |             |             |          |            | ✔             | ✔              |             |               |
+| `'HMAC'`                                                |             |             | ✔        | ✔          |               |                |             |               |
+| `'PBKDF2'`                                              |             |             |          |            | ✔             | ✔              |             |               |
+| `'RSA-OAEP'`                                            | ✔           | ✔           |          |            |               |                | ✔           | ✔             |
+| `'RSA-PSS'`                                             |             |             | ✔        | ✔          |               |                |             |               |
+| `'RSASSA-PKCS1-v1_5'`                                   |             |             | ✔        | ✔          |               |                |             |               |
 
 ## Class: `CryptoKeyPair`
 
@@ -610,7 +611,7 @@ containing the generated data.
 The algorithms currently supported include:
 
 * `'ECDH'`
-* `'X25519'` <span class="experimental-inline"></span>[^1]
+* `'X25519'`
 * `'X448'` <span class="experimental-inline"></span>[^1]
 * `'HKDF'`
 * `'PBKDF2'`
@@ -650,7 +651,7 @@ generate raw keying material, then passing the result into the
 The algorithms currently supported include:
 
 * `'ECDH'`
-* `'X25519'` <span class="experimental-inline"></span>[^1]
+* `'X25519'`
 * `'X448'` <span class="experimental-inline"></span>[^1]
 * `'HKDF'`
 * `'PBKDF2'`
@@ -734,22 +735,22 @@ When `format` is `'jwk'` and the export is successful, the returned promise
 will be resolved with a JavaScript object conforming to the [JSON Web Key][]
 specification.
 
-| Key Type                                                  | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
-| --------------------------------------------------------- | -------- | --------- | ------- | ------- |
-| `'AES-CBC'`                                               |          |           | ✔       | ✔       |
-| `'AES-CTR'`                                               |          |           | ✔       | ✔       |
-| `'AES-GCM'`                                               |          |           | ✔       | ✔       |
-| `'AES-KW'`                                                |          |           | ✔       | ✔       |
-| `'ECDH'`                                                  | ✔        | ✔         | ✔       | ✔       |
-| `'ECDSA'`                                                 | ✔        | ✔         | ✔       | ✔       |
-| `'Ed25519'` <span class="experimental-inline"></span>[^1] | ✔        | ✔         | ✔       | ✔       |
-| `'Ed448'` <span class="experimental-inline"></span>[^1]   | ✔        | ✔         | ✔       | ✔       |
-| `'HDKF'`                                                  |          |           |         |         |
-| `'HMAC'`                                                  |          |           | ✔       | ✔       |
-| `'PBKDF2'`                                                |          |           |         |         |
-| `'RSA-OAEP'`                                              | ✔        | ✔         | ✔       |         |
-| `'RSA-PSS'`                                               | ✔        | ✔         | ✔       |         |
-| `'RSASSA-PKCS1-v1_5'`                                     | ✔        | ✔         | ✔       |         |
+| Key Type                                                | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
+| ------------------------------------------------------- | -------- | --------- | ------- | ------- |
+| `'AES-CBC'`                                             |          |           | ✔       | ✔       |
+| `'AES-CTR'`                                             |          |           | ✔       | ✔       |
+| `'AES-GCM'`                                             |          |           | ✔       | ✔       |
+| `'AES-KW'`                                              |          |           | ✔       | ✔       |
+| `'ECDH'`                                                | ✔        | ✔         | ✔       | ✔       |
+| `'ECDSA'`                                               | ✔        | ✔         | ✔       | ✔       |
+| `'Ed25519'`                                             | ✔        | ✔         | ✔       | ✔       |
+| `'Ed448'` <span class="experimental-inline"></span>[^1] | ✔        | ✔         | ✔       | ✔       |
+| `'HDKF'`                                                |          |           |         |         |
+| `'HMAC'`                                                |          |           | ✔       | ✔       |
+| `'PBKDF2'`                                              |          |           |         |         |
+| `'RSA-OAEP'`                                            | ✔        | ✔         | ✔       |         |
+| `'RSA-PSS'`                                             | ✔        | ✔         | ✔       |         |
+| `'RSASSA-PKCS1-v1_5'`                                   | ✔        | ✔         | ✔       |         |
 
 ### `subtle.generateKey(algorithm, extractable, keyUsages)`
 
@@ -778,10 +779,10 @@ include:
 * `'RSA-PSS'`
 * `'RSA-OAEP'`
 * `'ECDSA'`
-* `'Ed25519'` <span class="experimental-inline"></span>[^1]
+* `'Ed25519'`
 * `'Ed448'` <span class="experimental-inline"></span>[^1]
 * `'ECDH'`
-* `'X25519'` <span class="experimental-inline"></span>[^1]
+* `'X25519'`
 * `'X448'` <span class="experimental-inline"></span>[^1]
 
 The {CryptoKey} (secret key) generating algorithms supported include:
@@ -830,24 +831,24 @@ If importing a `'PBKDF2'` key, `extractable` must be `false`.
 
 The algorithms currently supported include:
 
-| Key Type                                                  | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
-| --------------------------------------------------------- | -------- | --------- | ------- | ------- |
-| `'AES-CBC'`                                               |          |           | ✔       | ✔       |
-| `'AES-CTR'`                                               |          |           | ✔       | ✔       |
-| `'AES-GCM'`                                               |          |           | ✔       | ✔       |
-| `'AES-KW'`                                                |          |           | ✔       | ✔       |
-| `'ECDH'`                                                  | ✔        | ✔         | ✔       | ✔       |
-| `'X25519'` <span class="experimental-inline"></span>[^1]  | ✔        | ✔         | ✔       | ✔       |
-| `'X448'` <span class="experimental-inline"></span>[^1]    | ✔        | ✔         | ✔       | ✔       |
-| `'ECDSA'`                                                 | ✔        | ✔         | ✔       | ✔       |
-| `'Ed25519'` <span class="experimental-inline"></span>[^1] | ✔        | ✔         | ✔       | ✔       |
-| `'Ed448'` <span class="experimental-inline"></span>[^1]   | ✔        | ✔         | ✔       | ✔       |
-| `'HDKF'`                                                  |          |           |         | ✔       |
-| `'HMAC'`                                                  |          |           | ✔       | ✔       |
-| `'PBKDF2'`                                                |          |           |         | ✔       |
-| `'RSA-OAEP'`                                              | ✔        | ✔         | ✔       |         |
-| `'RSA-PSS'`                                               | ✔        | ✔         | ✔       |         |
-| `'RSASSA-PKCS1-v1_5'`                                     | ✔        | ✔         | ✔       |         |
+| Key Type                                                | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
+| ------------------------------------------------------- | -------- | --------- | ------- | ------- |
+| `'AES-CBC'`                                             |          |           | ✔       | ✔       |
+| `'AES-CTR'`                                             |          |           | ✔       | ✔       |
+| `'AES-GCM'`                                             |          |           | ✔       | ✔       |
+| `'AES-KW'`                                              |          |           | ✔       | ✔       |
+| `'ECDH'`                                                | ✔        | ✔         | ✔       | ✔       |
+| `'X25519'`                                              | ✔        | ✔         | ✔       | ✔       |
+| `'X448'` <span class="experimental-inline"></span>[^1]  | ✔        | ✔         | ✔       | ✔       |
+| `'ECDSA'`                                               | ✔        | ✔         | ✔       | ✔       |
+| `'Ed25519'`                                             | ✔        | ✔         | ✔       | ✔       |
+| `'Ed448'` <span class="experimental-inline"></span>[^1] | ✔        | ✔         | ✔       | ✔       |
+| `'HDKF'`                                                |          |           |         | ✔       |
+| `'HMAC'`                                                |          |           | ✔       | ✔       |
+| `'PBKDF2'`                                              |          |           |         | ✔       |
+| `'RSA-OAEP'`                                            | ✔        | ✔         | ✔       |         |
+| `'RSA-PSS'`                                             | ✔        | ✔         | ✔       |         |
+| `'RSASSA-PKCS1-v1_5'`                                   | ✔        | ✔         | ✔       |         |
 
 ### `subtle.sign(algorithm, key, data)`
 
@@ -880,7 +881,7 @@ The algorithms currently supported include:
 * `'RSASSA-PKCS1-v1_5'`
 * `'RSA-PSS'`
 * `'ECDSA'`
-* `'Ed25519'` <span class="experimental-inline"></span>[^1]
+* `'Ed25519'`
 * `'Ed448'` <span class="experimental-inline"></span>[^1]
 * `'HMAC'`
 
@@ -928,10 +929,10 @@ The unwrapped key algorithms supported include:
 * `'RSA-PSS'`
 * `'RSA-OAEP'`
 * `'ECDSA'`
-* `'Ed25519'` <span class="experimental-inline"></span>[^1]
+* `'Ed25519'`
 * `'Ed448'` <span class="experimental-inline"></span>[^1]
 * `'ECDH'`
-* `'X25519'` <span class="experimental-inline"></span>[^1]
+* `'X25519'`
 * `'X448'` <span class="experimental-inline"></span>[^1]
 * `'HMAC'`
 * `'AES-CTR'`
@@ -971,7 +972,7 @@ The algorithms currently supported include:
 * `'RSASSA-PKCS1-v1_5'`
 * `'RSA-PSS'`
 * `'ECDSA'`
-* `'Ed25519'` <span class="experimental-inline"></span>[^1]
+* `'Ed25519'`
 * `'Ed448'` <span class="experimental-inline"></span>[^1]
 * `'HMAC'`
 
@@ -1644,8 +1645,8 @@ added: v15.0.0
 
 The length (in bytes) of the random salt to use.
 
-[^1]: An experimental implementation of
-    [Secure Curves in the Web Cryptography API][] as of 30 August 2023
+[^1]: An experimental implementation of Ed448 and X448 algorithms from
+    [Secure Curves in the Web Cryptography API][] as of 21 October 2024
 
 [JSON Web Key]: https://tools.ietf.org/html/rfc7517
 [Key usages]: #cryptokeyusages
diff --git a/lib/internal/crypto/util.js b/lib/internal/crypto/util.js
index a1d7e84dae36bc..3cf6599a186c3f 100644
--- a/lib/internal/crypto/util.js
+++ b/lib/internal/crypto/util.js
@@ -189,18 +189,22 @@ const kSupportedAlgorithms = {
     'AES-GCM': 'AesKeyGenParams',
     'AES-KW': 'AesKeyGenParams',
     'HMAC': 'HmacKeyGenParams',
+    'Ed25519': null,
+    'X25519': null,
   },
   'sign': {
     'RSASSA-PKCS1-v1_5': null,
     'RSA-PSS': 'RsaPssParams',
     'ECDSA': 'EcdsaParams',
     'HMAC': null,
+    'Ed25519': null,
   },
   'verify': {
     'RSASSA-PKCS1-v1_5': null,
     'RSA-PSS': 'RsaPssParams',
     'ECDSA': 'EcdsaParams',
     'HMAC': null,
+    'Ed25519': null,
   },
   'importKey': {
     'RSASSA-PKCS1-v1_5': 'RsaHashedImportParams',
@@ -215,11 +219,14 @@ const kSupportedAlgorithms = {
     'AES-CBC': null,
     'AES-GCM': null,
     'AES-KW': null,
+    'Ed25519': null,
+    'X25519': null,
   },
   'deriveBits': {
     'HKDF': 'HkdfParams',
     'PBKDF2': 'Pbkdf2Params',
     'ECDH': 'EcdhKeyDeriveParams',
+    'X25519': 'EcdhKeyDeriveParams',
   },
   'encrypt': {
     'RSA-OAEP': 'RsaOaepParams',
@@ -251,17 +258,6 @@ const kSupportedAlgorithms = {
 };
 
 const experimentalAlgorithms = ObjectEntries({
-  'X25519': {
-    generateKey: null,
-    importKey: null,
-    deriveBits: 'EcdhKeyDeriveParams',
-  },
-  'Ed25519': {
-    generateKey: null,
-    sign: null,
-    verify: null,
-    importKey: null,
-  },
   'X448': {
     generateKey: null,
     importKey: null,