FF129 SubtleCrypto - support for Ed25519

files/en-us/web/api/ecdhkeyderiveparams/index.md

@@ -7,7 +7,7 @@ spec-urls: https://w3c.github.io/webcrypto/#dfn-EcdhKeyDeriveParams
 
 {{ APIRef("Web Crypto API") }}
 
-The **`EcdhKeyDeriveParams`** dictionary of the [Web Crypto API](/en-US/docs/Web/API/Web_Crypto_API) represents the object that should be passed as the `algorithm` parameter into {{domxref("SubtleCrypto.deriveKey()")}}, when using the [ECDH](/en-US/docs/Web/API/SubtleCrypto/deriveKey#ecdh) algorithm.
+The **`EcdhKeyDeriveParams`** dictionary of the [Web Crypto API](/en-US/docs/Web/API/Web_Crypto_API) represents the object that should be passed as the `algorithm` parameter into {{domxref("SubtleCrypto.deriveKey()")}} and {{domxref("SubtleCrypto.deriveBits()")}}, when using the [ECDH](/en-US/docs/Web/API/SubtleCrypto/deriveKey#ecdh) or [X25519](/en-US/docs/Web/API/SubtleCrypto/deriveKey#x25519) algorithms.
 
 ECDH enables two people who each have a key pair consisting of a public and a private key to derive a shared secret. They exchange public keys and use the combination of their private key and the other entity's public key to derive a secret key that they — and no one else — share.
 
@@ -16,22 +16,24 @@ The parameters for ECDH `deriveKey()` therefore include the other entity's publi
 ## Instance properties
 
 - `name`
-  - : A string. This should be set to `ECDH`.
+  - : A string.
+    This should be set to `ECDH` or `X25519`, depending on the algorithm used.
 - `public`
   - : A {{domxref("CryptoKey")}} object representing the public key of the other entity.
 
 ## Examples
 
-See the examples for {{domxref("SubtleCrypto.deriveKey()")}}.
+See the examples for {{domxref("SubtleCrypto.deriveKey()")}} and {{domxref("SubtleCrypto.deriveBits()")}}.
 
 ## Specifications
 
 {{Specifications}}
 
 ## Browser compatibility
 
-Browsers that support the "ECDH" algorithm for the {{domxref("SubtleCrypto.deriveKey()")}} method will support this type.
+Browsers that support the "ECDH" or "X25519" algorithm for the {{domxref("SubtleCrypto.deriveKey()")}} method will support this type.
 
 ## See also
 
 - {{domxref("SubtleCrypto.deriveKey()")}}.
+- {{domxref("SubtleCrypto.deriveBits()")}}

files/en-us/web/api/subtlecrypto/derivebits/index.md

@@ -26,9 +26,8 @@ except that `deriveKey()` returns a
 `deriveBits()` followed by
 [`importKey()`](/en-US/docs/Web/API/SubtleCrypto/importKey).
 
-This function supports the same derivation algorithms as `deriveKey()`:
-ECDH, HKDF, and PBKDF2. See [Supported algorithms](/en-US/docs/Web/API/SubtleCrypto/deriveKey#supported_algorithms)
-for some more detail on these algorithms.
+This function supports the same derivation algorithms as `deriveKey()`: ECDH, HKDF, PBKDF2, and X25519.
+See [Supported algorithms](/en-US/docs/Web/API/SubtleCrypto/deriveKey#supported_algorithms) for some more detail on these algorithms.
 
 ## Syntax
 
@@ -40,12 +39,10 @@ deriveBits(algorithm, baseKey, length)
 
 - `algorithm`
   - : An object defining the [derivation algorithm](/en-US/docs/Web/API/SubtleCrypto/deriveKey#supported_algorithms) to use.
-    - To use [ECDH](/en-US/docs/Web/API/SubtleCrypto/deriveKey#ecdh), pass an
-      [`EcdhKeyDeriveParams`](/en-US/docs/Web/API/EcdhKeyDeriveParams) object.
-    - To use [HKDF](/en-US/docs/Web/API/SubtleCrypto/deriveKey#hkdf), pass
-      an [`HkdfParams`](/en-US/docs/Web/API/HkdfParams) object.
-    - To use [PBKDF2](/en-US/docs/Web/API/SubtleCrypto/deriveKey#pbkdf2),
-      pass a [`Pbkdf2Params`](/en-US/docs/Web/API/Pbkdf2Params) object.
+    - To use [ECDH](/en-US/docs/Web/API/SubtleCrypto/deriveKey#ecdh), pass an [`EcdhKeyDeriveParams`](/en-US/docs/Web/API/EcdhKeyDeriveParams) object, specifying the string `ECDH` as the `name` property.
+    - To use [HKDF](/en-US/docs/Web/API/SubtleCrypto/deriveKey#hkdf), pass an [`HkdfParams`](/en-US/docs/Web/API/HkdfParams) object.
+    - To use [PBKDF2](/en-US/docs/Web/API/SubtleCrypto/deriveKey#pbkdf2), pass a [`Pbkdf2Params`](/en-US/docs/Web/API/Pbkdf2Params) object.
+    - To use [X25519](/en-US/docs/Web/API/SubtleCrypto/deriveKey#x25519), pass an [`EcdhKeyDeriveParams`](/en-US/docs/Web/API/EcdhKeyDeriveParams) object, specifying the string `X25519` as the `name` property.
 - `baseKey`
   - : A {{domxref("CryptoKey")}} representing the input
     to the derivation algorithm. If `algorithm` is ECDH, this will be the ECDH

files/en-us/web/api/subtlecrypto/derivekey/index.md

@@ -8,15 +8,13 @@ browser-compat: api.SubtleCrypto.deriveKey
 
 {{APIRef("Web Crypto API")}}{{SecureContext_header}}
 
-The **`deriveKey()`** method of the {{domxref("SubtleCrypto")}}
-interface can be used to derive a secret key from a master key.
+The **`deriveKey()`** method of the {{domxref("SubtleCrypto")}} interface can be used to derive a secret key from a master key.
 
-It takes as arguments some initial key material, the derivation algorithm to use, and
-the desired properties for the key to derive. It returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
-which will be fulfilled with a {{domxref("CryptoKey")}} object representing the new key.
+It takes as arguments some initial key material, the derivation algorithm to use, and the desired properties for the key to derive.
+It returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) which will be fulfilled with a {{domxref("CryptoKey")}} object representing the new key.
 
-It's worth noting that the three key derivation algorithms you can use have quite
-different characteristics and are appropriate in quite different situations. See [Supported algorithms](#supported_algorithms) for some more detail on this.
+It's worth noting that the supported key derivation algorithms have quite different characteristics and are appropriate in quite different situations.
+See [Supported algorithms](#supported_algorithms) for some more detail on this.
 
 ## Syntax
 
@@ -28,34 +26,24 @@ deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)
 
 - `algorithm`
   - : An object defining the [derivation algorithm](#supported_algorithms) to use.
-    - To use [ECDH](#ecdh), pass an
-      [`EcdhKeyDeriveParams`](/en-US/docs/Web/API/EcdhKeyDeriveParams) object.
+    - To use [ECDH](#ecdh), pass an [`EcdhKeyDeriveParams`](/en-US/docs/Web/API/EcdhKeyDeriveParams) object, specifying the string `ECDH` as the `name` property.
     - To use [HKDF](#hkdf), pass an [`HkdfParams`](/en-US/docs/Web/API/HkdfParams) object.
-    - To use [PBKDF2](#pbkdf2), pass
-      a [`Pbkdf2Params`](/en-US/docs/Web/API/Pbkdf2Params) object.
+    - To use [X25519](#x25519), pass an [`EcdhKeyDeriveParams`](/en-US/docs/Web/API/EcdhKeyDeriveParams) object, specifying the string `X25519` as the `name` property.
 - `baseKey`
-  - : A {{domxref("CryptoKey")}} representing the input
-    to the derivation algorithm. If `algorithm` is ECDH, then this will be the
-    ECDH private key. Otherwise it will be the initial key material for the derivation
-    function: for example, for PBKDF2 it might be a password, imported as a
-    `CryptoKey` using
-    [`SubtleCrypto.importKey()`](/en-US/docs/Web/API/SubtleCrypto/importKey).
+  - : A {{domxref("CryptoKey")}} representing the input to the derivation algorithm.
+    If `algorithm` is ECDH or X25519, then this will be the ECDH or X25519 private key.
+    Otherwise it will be the initial key material for the derivation function: for example, for PBKDF2 it might be a password, imported as a `CryptoKey` using [`SubtleCrypto.importKey()`](/en-US/docs/Web/API/SubtleCrypto/importKey).
 - `derivedKeyAlgorithm`
   - : An object defining the algorithm the derived key will be used for:
     - For [HMAC](/en-US/docs/Web/API/SubtleCrypto/sign#hmac) pass an [`HmacKeyGenParams`](/en-US/docs/Web/API/HmacKeyGenParams) object.
-    - For [AES-CTR](/en-US/docs/Web/API/SubtleCrypto/encrypt#aes-ctr), [AES-CBC](/en-US/docs/Web/API/SubtleCrypto/encrypt#aes-cbc),
-      [AES-GCM](/en-US/docs/Web/API/SubtleCrypto/encrypt#aes-gcm), or [AES-KW](/en-US/docs/Web/API/SubtleCrypto/wrapKey#aes-kw), pass an
-      [`AesKeyGenParams`](/en-US/docs/Web/API/AesKeyGenParams) object.
+    - For [AES-CTR](/en-US/docs/Web/API/SubtleCrypto/encrypt#aes-ctr), [AES-CBC](/en-US/docs/Web/API/SubtleCrypto/encrypt#aes-cbc), [AES-GCM](/en-US/docs/Web/API/SubtleCrypto/encrypt#aes-gcm), or [AES-KW](/en-US/docs/Web/API/SubtleCrypto/wrapKey#aes-kw), pass an [`AesKeyGenParams`](/en-US/docs/Web/API/AesKeyGenParams) object.
     - For [HKDF](#hkdf), pass an [`HkdfParams`](/en-US/docs/Web/API/HkdfParams) object.
     - For [PBKDF2](#pbkdf2), pass a [`Pbkdf2Params`](/en-US/docs/Web/API/Pbkdf2Params) object.
 - `extractable`
-  - : A boolean value indicating whether it
-    will be possible to export the key using {{domxref("SubtleCrypto.exportKey()")}} or
-    {{domxref("SubtleCrypto.wrapKey()")}}.
+  - : A boolean value indicating whether it will be possible to export the key using {{domxref("SubtleCrypto.exportKey()")}} or {{domxref("SubtleCrypto.wrapKey()")}}.
 - `keyUsages`
-  - : An {{jsxref("Array")}} indicating what can be
-    done with the derived key. Note that the key usages must be allowed by the algorithm
-    set in `derivedKeyAlgorithm`. Possible values of the array are:
+  - : An {{jsxref("Array")}} indicating what can be done with the derived key. Note that the key usages must be allowed by the algorithm set in `derivedKeyAlgorithm`.
+    Possible values of the array are:
     - `encrypt`: The key may be used to [encrypt](/en-US/docs/Web/API/SubtleCrypto/encrypt) messages.
     - `decrypt`: The key may be used to [decrypt](/en-US/docs/Web/API/SubtleCrypto/decrypt) messages.
     - `sign`: The key may be used to [sign](/en-US/docs/Web/API/SubtleCrypto/sign) messages.
@@ -74,62 +62,60 @@ A {{jsxref("Promise")}} that fulfills with a {{domxref("CryptoKey")}}.
 The promise is rejected when one of the following exceptions are encountered:
 
 - `InvalidAccessError` {{domxref("DOMException")}}
-  - : Raised when the master key is not a key for the requested derivation algorithm
-    or if the `keyUsages` value of that key doesn't contain `deriveKey`.
+  - : Raised when the master key is not a key for the requested derivation algorithm or if the `keyUsages` value of that key doesn't contain `deriveKey`.
 - `NotSupported` {{domxref("DOMException")}}
-  - : Raised when trying to use an algorithm that is either unknown or isn't suitable for
-    derivation, or if the algorithm requested for the derived key doesn't define a key
-    length.
+  - : Raised when trying to use an algorithm that is either unknown or isn't suitable for derivation, or if the algorithm requested for the derived key doesn't define a key length.
 - `SyntaxError` {{domxref("DOMException")}}
-  - : Raised when `keyUsages` is empty but the unwrapped key is of
-    type `secret` or `private`.
+  - : Raised when `keyUsages` is empty but the unwrapped key is of type `secret` or `private`.
 
 ## Supported algorithms
 
-The three algorithms supported by `deriveKey()` have quite different
-characteristics and are appropriate in different situations.
+The algorithms supported by `deriveKey()` have quite different characteristics and are appropriate in different situations.
 
-### ECDH
-
-ECDH (Elliptic Curve Diffie-Hellman) is a _key-agreement algorithm_. It enables
-two people who each have an ECDH public/private key pair to generate a shared secret:
-that is, a secret that they — and no one else — share. They can then use this shared
-secret as a symmetric key to secure their communication, or can use the secret as an
-input to derive such a key (for example, using the HKDF algorithm).
+### Key derivation algorithms
 
-ECDH is specified in [RFC 6090](https://datatracker.ietf.org/doc/html/rfc6090).
+#### HKDF
 
-### HKDF
+HKDF is a _key derivation function_.
+It's designed to derive key material from some high-entropy input, such as the output of an ECDH key agreement operation.
 
-HKDF is a _key derivation function_. It's designed to derive key material from
-some high-entropy input, such as the output of an ECDH key agreement operation.
-
-It's _not_ designed to derive keys from relatively low-entropy inputs such as
-passwords. For that, use PBKDF2.
+It's _not_ designed to derive keys from relatively low-entropy inputs such as passwords.
+For that, use PBKDF2.
 
 HKDF is specified in [RFC 5869](https://datatracker.ietf.org/doc/html/rfc5869).
 
-### PBKDF2
+#### PBKDF2
 
-PBKDF2 is also a _key derivation function_. It's designed to derive key material
-from some relatively low-entropy input, such as a password. It derives key material by
-applying a function such as HMAC to the input password along with some salt, and
-repeating this process many times. The more times the process is repeated, the more
-computationally expensive key derivation is: this makes it harder for an attacker to use
-brute-force to discover the key using a dictionary attack.
+PBKDF2 is also a _key derivation function_. It's designed to derive key material from some relatively low-entropy input, such as a password.
+It derives key material by applying a function such as HMAC to the input password along with some salt, and repeating this process many times.
+The more times the process is repeated, the more computationally expensive key derivation is: this makes it harder for an attacker to use brute-force to discover the key using a dictionary attack.
 
 PBKDF2 is specified in [RFC 2898](https://datatracker.ietf.org/doc/html/rfc2898).
 
+### Key agreement algorithms
+
+#### ECDH
+
+ECDH (Elliptic Curve Diffie-Hellman) is a _key-agreement algorithm_. It enables two people who each have an ECDH public/private key pair to generate a shared secret: that is, a secret that they — and no one else — share.
+They can then use this shared secret as a symmetric key to secure their communication, or can use the secret as an input to derive such a key (for example, using the HKDF algorithm).
+
+ECDH is specified in [RFC 6090](https://datatracker.ietf.org/doc/html/rfc6090).
+
+#### X25519
+
+X25519 is a key agreement algorithm like ECDH, but built on the [Curve25519](https://en.wikipedia.org/wiki/Curve25519) elliptic curve, which is part of the Edwards-Curve Digital Signature Algorithm (EdDSA) family of algorithms defined in {{rfc("8032")}}.
+The algorithm is specified in {{rfc("7748")}}.
+
 ## Examples
 
 > [!NOTE]
 > You can [try the working examples](https://mdn.github.io/dom-examples/web-crypto/derive-key/index.html) on GitHub.
 
 ### ECDH
 
-In this example Alice and Bob each generate an ECDH key pair, then exchange public
-keys. They then use `deriveKey()` to derive a shared AES key, that they could
-use to encrypt messages. [See the complete code on GitHub.](https://github.com/mdn/dom-examples/blob/main/web-crypto/derive-key/ecdh.js)
+In this example Alice and Bob each generate an ECDH key pair, then exchange public keys.
+They then use `deriveKey()` to derive a shared AES key, that they could use to encrypt messages.
+[See the complete code on GitHub.](https://github.com/mdn/dom-examples/blob/main/web-crypto/derive-key/ecdh.js)
 
 ```js
 /*