From b85cd5d056e4a78761b5ebe7d9c54e4e4f852310 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Tue, 23 Jul 2024 16:58:38 +1000 Subject: [PATCH 01/33] FF129 SubtlCrypto - support for Ed25519 - update table of supported algos - Tidy up the algorithms to be a bit more monolithic and cross link --- .../web/api/subtlecrypto/derivekey/index.md | 32 ++- .../web/api/subtlecrypto/generatekey/index.md | 129 +++++++--- files/en-us/web/api/subtlecrypto/index.md | 94 ++++--- .../en-us/web/api/subtlecrypto/sign/index.md | 234 +++++++++++++----- .../web/api/subtlecrypto/verify/index.md | 15 +- 5 files changed, 352 insertions(+), 152 deletions(-) diff --git a/files/en-us/web/api/subtlecrypto/derivekey/index.md b/files/en-us/web/api/subtlecrypto/derivekey/index.md index 653a1acd5014a73..96b15ee41c8031a 100644 --- a/files/en-us/web/api/subtlecrypto/derivekey/index.md +++ b/files/en-us/web/api/subtlecrypto/derivekey/index.md @@ -86,40 +86,38 @@ The promise is rejected when one of the following exceptions are encountered: ## Supported algorithms -The three algorithms supported by `deriveKey()` have quite different -characteristics and are appropriate in different situations. +The three 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). +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). ### 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 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). +#### X25519 + +X25519 is a high-performance key agreement algorithm 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] diff --git a/files/en-us/web/api/subtlecrypto/generatekey/index.md b/files/en-us/web/api/subtlecrypto/generatekey/index.md index bc33496c76b130c..a19633263cd487f 100644 --- a/files/en-us/web/api/subtlecrypto/generatekey/index.md +++ b/files/en-us/web/api/subtlecrypto/generatekey/index.md @@ -8,9 +8,7 @@ browser-compat: api.SubtleCrypto.generateKey {{APIRef("Web Crypto API")}}{{SecureContext_header}} -Use the **`generateKey()`** method of the -{{domxref("SubtleCrypto")}} interface to generate a new key (for symmetric algorithms) -or key pair (for public-key algorithms). +The **`generateKey()`** method of the {{domxref("SubtleCrypto")}} interface is used to generate a new key (for symmetric algorithms) or key pair (for public-key algorithms). ## Syntax @@ -25,48 +23,55 @@ generateKey(algorithm, extractable, keyUsages) - : An object defining the type of key to generate and providing extra algorithm-specific parameters. - For [RSASSA-PKCS1-v1_5](/en-US/docs/Web/API/SubtleCrypto/sign#rsassa-pkcs1-v1_5), [RSA-PSS](/en-US/docs/Web/API/SubtleCrypto/sign#rsa-pss), - or [RSA-OAEP](/en-US/docs/Web/API/SubtleCrypto/encrypt#rsa-oaep): + or [RSA-OAEP](/en-US/docs/Web/API/SubtleCrypto/encrypt#rsa-oaep) — pass an [`RsaHashedKeyGenParams`](/en-US/docs/Web/API/RsaHashedKeyGenParams) object. - - For [ECDSA](/en-US/docs/Web/API/SubtleCrypto/sign#ecdsa) or [ECDH](/en-US/docs/Web/API/SubtleCrypto/deriveKey#ecdh): + - For [ECDSA](/en-US/docs/Web/API/SubtleCrypto/sign#ecdsa) or [ECDH](/en-US/docs/Web/API/SubtleCrypto/deriveKey#ecdh) — pass an [`EcKeyGenParams`](/en-US/docs/Web/API/EcKeyGenParams) object. - - For [HMAC](/en-US/docs/Web/API/SubtleCrypto/sign#hmac): - pass an [`HmacKeyGenParams`](/en-US/docs/Web/API/HmacKeyGenParams) object. + - 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): + [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 the Ed25519 signature algorithm — pass an object of the form: `{ name: "Ed25519"}`. - `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 newly generated key. Possible values for array elements 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. - - `verify`: The key may be used to [verify](/en-US/docs/Web/API/SubtleCrypto/verify) signatures. - - `deriveKey`: The key may be used in [deriving a new key](/en-US/docs/Web/API/SubtleCrypto/deriveKey). - - `deriveBits`: The key may be used in [deriving bits](/en-US/docs/Web/API/SubtleCrypto/deriveBits). - - `wrapKey`: The key may be used to [wrap a key](/en-US/docs/Web/API/SubtleCrypto/wrapKey). - - `unwrapKey`: The key may be used to [unwrap a key](/en-US/docs/Web/API/SubtleCrypto/unwrapKey). + + - : An {{jsxref("Array")}} of strings indicating what can be done with the newly generated key. + Possible values for array elements are: + + - `encrypt` + - : The key may be used to {{domxref("SubtleCrypto.encrypt()", "encrypt")}} messages. + - `decrypt` + - : The key may be used to {{domxref("SubtleCrypto.decrypt()", "decrypt")}} messages. + - `sign` + - : The key may be used to {{domxref("SubtleCrypto.sign()", "sign")}} messages. + - `verify` + - : The key may be used to {{domxref("SubtleCrypto.verify()", "verify")}} signatures. + - `deriveKey` + - : The key may be used in {{domxref("SubtleCrypto.deriveKey()", "deriving a new key")}}. + - `deriveBits` + - : The key may be used in {{domxref("SubtleCrypto.deriveBits()", "deriving bits")}}. + - `wrapKey` + - : The key may be used to {{domxref("SubtleCrypto.wrapKey()", "wrap a key")}}. + - `unwrapKey` + - : The key may be used to {{domxref("SubtleCrypto.unwrapKey()", "unwrap a key")}}. ### Return value -A {{jsxref("Promise")}} that fulfills with a -{{domxref("CryptoKey")}} (for symmetric algorithms) or a {{domxref("CryptoKeyPair")}} -(for public-key algorithms). +A {{jsxref("Promise")}} that fulfills with a {{domxref("CryptoKey")}} (for symmetric algorithms) or a {{domxref("CryptoKeyPair")}} (for public-key algorithms). ### Exceptions The promise is rejected when the following exception is encountered: - `SyntaxError` {{domxref("DOMException")}} - - : Raised when the result is a {{domxref("CryptoKey")}} of type `secret` or - `private` but `keyUsages` is empty. + - : Raised when the result is a {{domxref("CryptoKey")}} of type `secret` or `private` but `keyUsages` is empty. - `SyntaxError` {{domxref("DOMException")}} - - : Raised when the result is a {{domxref("CryptoKeyPair")}} and its - `privateKey.usages` attribute is empty. + - : Raised when the result is a {{domxref("CryptoKeyPair")}} and its `privateKey.usages` attribute is empty. ## Examples @@ -139,6 +144,74 @@ let key = await window.crypto.subtle.generateKey( ); ``` +### Ed25519 key generation + +This code generates an Ed25519 signing key pair. +It is derived from [this source code on GitHub.](https://github.com/mdn/dom-examples/blob/main/web-crypto/sign-verify/ed25519.js), which you can [run live here](https://mdn.github.io/dom-examples/web-crypto/sign-verify/). + +```html hidden +

+```
+
+```css hidden
+#log {
+  height: 170px;
+  overflow: scroll;
+  padding: 0.5rem;
+  border: 1px solid black;
+}
+```
+
+```js hidden
+const logElement = document.querySelector("#log");
+function log(text) {
+  logElement.innerText = `${logElement.innerText}${text}\n`;
+  logElement.scrollTop = logElement.scrollHeight;
+}
+```
+
+#### JavaScript
+
+Code for generating a key pair using the `Ed25519` algorithm and logging the information in each key is shown below.
+Note that the code is run in a `try..catch` block because not all browsers support this algorithm.
+
+```js
+async function test() {
+  try {
+    // Create a key pair and use destructuring assignment to assign to variables
+    const { publicKey, privateKey } = await crypto.subtle.generateKey(
+      {
+        name: "Ed25519",
+      },
+      true,
+      ["sign", "verify"],
+    );
+
+    // Log the properties of the keys
+    log(`publicKey: ${publicKey}`);
+    log(` type: ${publicKey.type}`);
+    log(` extractable: ${publicKey.extractable}`);
+    log(` algorithm: ${JSON.stringify(publicKey.algorithm)}`);
+    log(` usages: ${publicKey.usages}`);
+    log(`privateKey: ${privateKey}`);
+    log(` type: ${privateKey.type}`);
+    log(` extractable: ${privateKey.extractable}`);
+    log(` algorithm: ${JSON.stringify(privateKey.algorithm)}`);
+    log(` usages: ${privateKey.usages}`);
+  } catch (error) {
+    log(error);
+  }
+}
+
+test();
+```
+
+#### Result
+
+The information about the created keys is logged below (or an error string if the browser does not allow the key to be created).
+
+{{EmbedLiveSample("Ed25519", "100%", "230px")}}
+
 ## Specifications
 
 {{Specifications}}
diff --git a/files/en-us/web/api/subtlecrypto/index.md b/files/en-us/web/api/subtlecrypto/index.md
index 478a2b3a5beb41b..2b40ba9890b45a8 100644
--- a/files/en-us/web/api/subtlecrypto/index.md
+++ b/files/en-us/web/api/subtlecrypto/index.md
@@ -87,7 +87,8 @@ The inverse of `wrapKey()` is {{DOMxRef("SubtleCrypto.unwrapKey","unwrapKey()")}
 
 #### Storing keys
 
-`CryptoKey` objects can be stored using the [structured clone algorithm](/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), meaning that you can store and retrieve them using standard web storage APIs. The specification expects that most developers will use the [IndexedDB API](/en-US/docs/Web/API/IndexedDB_API) to store `CryptoKey` objects.
+`CryptoKey` is a {{glossary("serializable object")}}, which allows keys to be stored and retrieved using standard web storage APIs.
+The specification expects that most developers will use the [IndexedDB API](/en-US/docs/Web/API/IndexedDB_API), sotring `CryptoKey` objects against some key string identifier that is meaningful to the application, along with any other metadata it finds useful.
 
 ### Supported algorithms
 
@@ -100,162 +101,187 @@ The table below summarizes which algorithms are suitable for which cryptographic
     
       
       
-        sign()
verify()
+        sign()
verify()
       
       
-        encrypt()
decrypt()
+        encrypt()
decrypt()
       
       
         digest()
       
       
-        deriveBits()
deriveKey()
+        deriveBits()
deriveKey()
       
       
-        wrapKey()
unwrapKey()
+        wrapKey()
unwrapKey()
+      
+      
+        generateKey()
importKey()
exportKey()
       
     
   
   
     
-      RSASSA-PKCS1-v1_5
+      RSASSA-PKCS1-v1_5>
       ✓
       
       
       
       
+      ✓
     
     
-      RSA-PSS
+      RSA-PSS
       ✓
       
       
       
       
+      ✓
     
     
-      ECDSA
+      ECDSA
       ✓
       
       
       
       
+      ✓
+    
+    
+      Ed25519
+      ✓
+      
+      
+      
+      ✓
+      ✓
     
     
-      HMAC
+      HMAC
       ✓
       
       
       
       
+      ✓
     
     
-      RSA-OAEP
+      RSA-OAEP
       
       ✓
       
       
       ✓
+      ✓
     
     
-      AES-CTR
+      AES-CTR
       
       ✓
       
       
       ✓
+      ✓
     
     
-      AES-CBC
+      AES-CBC
       
       ✓
       
       
       ✓
+      ✓
     
     
-      AES-GCM
+      AES-GCM
+      
+      ✓
+      
       
       ✓
+      ✓
+    
+    
+      AES-KW
+      
+      
       
       
       ✓
+      ✓
     
     
-      SHA-1
+      SHA-1
       
       
       ✓
       
       
+      
     
     
-      SHA-256
+      SHA-256
       
       
       ✓
       
       
+      
     
     
-      SHA-384
+      SHA-384
       
       
       ✓
       
       
+      
     
     
-      SHA-512
+      SHA-512
       
       
       ✓
       
       
+      
     
     
-      ECDH
+      ECDH
       
       
       
       ✓
       
+      
     
     
-      HKDF
+      HKDF
       
       
       
       ✓
       
+      
     
     
-      PBKDF2
+      PBKDF2
       
       
       
       ✓
       
+      
     
     
-      AES-KW
-      
+      X25519
       
       
       
       ✓
+      ✓
+      ✓
     
   
 
diff --git a/files/en-us/web/api/subtlecrypto/sign/index.md b/files/en-us/web/api/subtlecrypto/sign/index.md
index 88186b343dd6abe..578fb8115762e31 100644
--- a/files/en-us/web/api/subtlecrypto/sign/index.md
+++ b/files/en-us/web/api/subtlecrypto/sign/index.md
@@ -8,15 +8,11 @@ browser-compat: api.SubtleCrypto.sign
 
 {{APIRef("Web Crypto API")}}{{SecureContext_header}}
 
-The **`sign()`** method of the {{domxref("SubtleCrypto")}}
-interface generates a digital {{glossary("signature")}}.
+The **`sign()`** method of the {{domxref("SubtleCrypto")}} interface generates a digital {{glossary("signature")}}.
 
-It takes as its arguments a {{glossary("key")}} to sign with, some algorithm-specific
-parameters, and the data to sign. It returns a {{jsxref("Promise")}} which will be
-fulfilled with the signature.
+It takes as its arguments a {{glossary("key")}} to sign with, some algorithm-specific parameters, and the data to sign. It returns a {{jsxref("Promise")}} which will be fulfilled with the signature.
 
-You can use the corresponding {{domxref("SubtleCrypto.verify()")}} method to verify the
-signature.
+You can use the corresponding {{domxref("SubtleCrypto.verify()")}} method to verify the signature.
 
 ## Syntax
 
@@ -28,12 +24,11 @@ sign(algorithm, key, data)
 
 - `algorithm`
   - : A string or object that specifies the signature algorithm to use and its parameters:
-    - To use [RSASSA-PKCS1-v1_5](#rsassa-pkcs1-v1_5), pass the string `"RSASSA-PKCS1-v1_5"`
-      or an object of the form `{ "name": "RSASSA-PKCS1-v1_5" }`.
+    - To use [RSASSA-PKCS1-v1_5](#rsassa-pkcs1-v1_5), pass the string `"RSASSA-PKCS1-v1_5"` or an object of the form `{ "name": "RSASSA-PKCS1-v1_5" }`.
     - To use [RSA-PSS](#rsa-pss), pass an {{domxref("RsaPssParams")}} object.
     - To use [ECDSA](#ecdsa), pass an {{domxref("EcdsaParams")}} object.
-    - To use [HMAC](#hmac), pass the string `"HMAC"`
-      or an object of the form `{ "name": "HMAC" }`.
+    - To use [HMAC](#hmac), pass the string `"HMAC"` or an object of the form `{ "name": "HMAC" }`.
+    - To use [Ed25519](#ed25519), pass an object of the form `{ "name": "Ed25519" }`.
 - `key`
   - : A {{domxref("CryptoKey")}} object containing the key to be used for signing.
     If `algorithm` identifies a public-key cryptosystem, this is the private key.
@@ -42,74 +37,67 @@ sign(algorithm, key, data)
 
 ### Return value
 
-A {{jsxref("Promise")}} that fulfills with an
-{{jsxref("ArrayBuffer")}} containing the signature.
+A {{jsxref("Promise")}} that fulfills with an {{jsxref("ArrayBuffer")}} containing the signature.
 
 ### Exceptions
 
 The promise is rejected when the following exception is encountered:
 
 - `InvalidAccessError` {{domxref("DOMException")}}
-  - : Raised when the signing key is not a key for the request signing algorithm or when
-    trying to use an algorithm that is either unknown or isn't suitable for signing.
+  - : Raised when the signing key is not a key for the request signing algorithm or when trying to use an algorithm that is either unknown or isn't suitable for signing.
 
 ## Supported algorithms
 
-The Web Crypto API provides four algorithms that can be used for signing and signature
-verification.
+The Web Crypto API provides the following algorithms that can be used for signing (and signature verification):
 
-Three of these algorithms — RSASSA-PKCS1-v1_5, RSA-PSS, and ECDSA — are
-{{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private
-key for signing and the public key for verification.
-These systems all use a [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms)
-to hash the message to a short fixed size before signing.
-Except for ECDSA (for which it is passed in the `algorithm` object), the choice of digest algorithm is passed into the
-{{domxref("SubtleCrypto.generateKey()", "generateKey()")}} or {{domxref("SubtleCrypto.importKey()", "importKey()")}} functions.
-
-The fourth algorithm — HMAC — uses the same algorithm and key for signing and for
-verification: this means that the verification key must be kept secret, which in turn
-means that this algorithm is not suitable for many signature use cases. It can be a good
-choice however when the signer and verifier are the same entity.
-
-### RSASSA-PKCS1-v1_5
+#### RSASSA-PKCS1-v1_5
 
 The RSASSA-PKCS1-v1_5 algorithm is specified in [RFC 3447](https://datatracker.ietf.org/doc/html/rfc3447).
 
-### RSA-PSS
+This algorithm is used in {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
+Systems that use this algorithm use a [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) to hash the message to a short fixed size before signing.
+The choice of digest algorithm is passed into the {{domxref("SubtleCrypto.generateKey()", "generateKey()")}} or {{domxref("SubtleCrypto.importKey()", "importKey()")}} functions.
+
+#### RSA-PSS
 
 The RSA-PSS algorithm is specified in [RFC 3447](https://datatracker.ietf.org/doc/html/rfc3447).
 
-It's different from RSASSA-PKCS1-v1_5 in that it incorporates a random salt in the
-signature operation, so the same message signed with the same key will not result in the
-same signature each time. An extra property, defining the salt length, is passed into
-the `sign()` and {{domxref("SubtleCrypto.verify()", "verify()")}} functions when they are invoked.
+It's different from RSASSA-PKCS1-v1_5 in that it incorporates a random salt in the signature operation, so the same message signed with the same key will not result in the same signature each time. An extra property, defining the salt length, is passed into the {{domxref("SubtleCrypto.sign()", "sign()")}} and {{domxref("SubtleCrypto.verify()", "verify()")}} functions when they are invoked.
 
-### ECDSA
+This algorithm is used in {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
+Systems that use this algorithm use a [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) to hash the message to a short fixed size before signing.
+The choice of digest algorithm is passed into the {{domxref("SubtleCrypto.generateKey()", "generateKey()")}} or {{domxref("SubtleCrypto.importKey()", "importKey()")}} functions.
 
-ECDSA (Elliptic Curve Digital Signature Algorithm) is a variant of the Digital
-Signature Algorithm, specified in [FIPS-186](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf),
-that uses Elliptic Curve Cryptography ([RFC 6090](https://datatracker.ietf.org/doc/html/rfc6090)).
+#### ECDSA
 
-Signatures are encoded as the `s1` and `s2` values specified in RFC 6090 (known respectively as `r`
-and `s` in [RFC 4754](https://datatracker.ietf.org/doc/html/rfc4754#section-3)), each in big-endian
-byte arrays, with their length the bit size of the curve rounded up to a whole number of bytes.
+ECDSA (Elliptic Curve Digital Signature Algorithm) is a variant of the Digital Signature Algorithm, specified in [FIPS-186](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf), that uses Elliptic Curve Cryptography ([RFC 6090](https://datatracker.ietf.org/doc/html/rfc6090)).
+
+Signatures are encoded as the `s1` and `s2` values specified in RFC 6090 (known respectively as `r` and `s` in [RFC 4754](https://datatracker.ietf.org/doc/html/rfc4754#section-3)), each in big-endian byte arrays, with their length the bit size of the curve rounded up to a whole number of bytes.
 These values are concatenated together in this order.
 
-This encoding was also proposed by the [IEEE 1363-2000](https://standards.ieee.org/ieee/1363/2049/)
-standard, and is sometimes referred to as the IEEE P1363 format. It differs from the
-[X.509](https://www.itu.int/rec/T-REC-X.509) signature structure, which is the default format
-produced by some tools and libraries such as [OpenSSL](https://www.openssl.org).
+This encoding was also proposed by the [IEEE 1363-2000](https://standards.ieee.org/ieee/1363/2049/) standard, and is sometimes referred to as the IEEE P1363 format. It differs from the [X.509](https://www.itu.int/rec/T-REC-X.509) signature structure, which is the default format produced by some tools and libraries such as [OpenSSL](https://www.openssl.org).
 
-### HMAC
+This algorithm is used in {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
+Systems that use this algorithm use a [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) to hash the message to a short fixed size before signing.
+This
+For ECDSA the choice of digest algorithm is passed as part of the `algorithm` object, a {{domxref("EcdsaParams")}}, when calling {{domxref("SubtleCrypto.sign()")}}.
+
+#### HMAC
+
+The HMAC algorithm calculates and verifies hash-based message authentication codes according to the [FIPS 198-1 standard](https://csrc.nist.gov/csrc/media/publications/fips/198/1/final/documents/fips-198-1_final.pdf).
+
+The digest algorithm to use is specified in the [`HmacKeyGenParams`](/en-US/docs/Web/API/HmacKeyGenParams) object that you pass into {{domxref("SubtleCrypto.generateKey()", "generateKey()")}}, or the
+[`HmacImportParams`](/en-US/docs/Web/API/HmacImportParams) object that you pass into {{domxref("SubtleCrypto.importKey()", "importKey()")}}.
 
-The HMAC algorithm calculates and verifies hash-based message authentication codes according to the
-[FIPS 198-1 standard](https://csrc.nist.gov/csrc/media/publications/fips/198/1/final/documents/fips-198-1_final.pdf).
+The HMAC algorithm uses the same algorithm and key for signing and for verification: this means that the verification key must be kept secret, which in turn means that this algorithm is not suitable for many signature use cases.
+It can be a good choice however when the signer and verifier are the same entity.
 
-The digest algorithm to use is specified in the
-[`HmacKeyGenParams`](/en-US/docs/Web/API/HmacKeyGenParams) object
-that you pass into {{domxref("SubtleCrypto.generateKey()", "generateKey()")}}, or the
-[`HmacImportParams`](/en-US/docs/Web/API/HmacImportParams) object
-that you pass into {{domxref("SubtleCrypto.importKey()", "importKey()")}}.
+#### Ed25519
+
+Ed25519 is a high-performance digital signature algorithm 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")}}.
+
+This algorithm is used in {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
+Unlike some other such systems (RSASSA-PKCS1-v1_5, RSA-PSS, and ECDSA), it does not pass in a [digest](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) of the message for signing.
 
 ## Examples
 
@@ -118,8 +106,7 @@ that you pass into {{domxref("SubtleCrypto.importKey()", "importKey()")}}.
 
 ### RSASSA-PKCS1-v1_5
 
-This code fetches the contents of a text box, encodes it for signing, and signs it with
-a private key.
+This code fetches the contents of a text box, encodes it for signing, and signs it with a private key.
 [See the complete source code on GitHub.](https://github.com/mdn/dom-examples/blob/main/web-crypto/sign-verify/rsassa-pkcs1.js)
 
 ```js
@@ -144,8 +131,7 @@ let signature = await window.crypto.subtle.sign(
 
 ### RSA-PSS
 
-This code fetches the contents of a text box, encodes it for signing, and signs it with
-a private key.
+This code fetches the contents of a text box, encodes it for signing, and signs it with a private key.
 [See the complete source code on GitHub.](https://github.com/mdn/dom-examples/blob/main/web-crypto/sign-verify/rsa-pss.js)
 
 ```js
@@ -173,8 +159,7 @@ let signature = await window.crypto.subtle.sign(
 
 ### ECDSA
 
-This code fetches the contents of a text box, encodes it for signing, and signs it with
-a private key.
+This code fetches the contents of a text box, encodes it for signing, and signs it with a private key.
 [See the complete source code on GitHub.](https://github.com/mdn/dom-examples/blob/main/web-crypto/sign-verify/ecdsa.js)
 
 ```js
@@ -202,8 +187,7 @@ let signature = await window.crypto.subtle.sign(
 
 ### HMAC
 
-This code fetches the contents of a text box, encodes it for signing, and signs it with
-a secret key.
+This code fetches the contents of a text box, encodes it for signing, and signs it with a secret key.
 [See the complete source code on GitHub.](https://github.com/mdn/dom-examples/blob/main/web-crypto/sign-verify/hmac.js)
 
 ```js
@@ -222,6 +206,130 @@ let encoded = getMessageEncoding();
 let signature = await window.crypto.subtle.sign("HMAC", key, encoded);
 ```
 
+### Ed25519 (key generation, signing, and verification)
+
+This code generates an Ed25519 signing key pair, uses the private key to sign the (encoded) contents of a text ``, and then verifies the signature using the public key.
+It is derived from [this source code on GitHub.](https://github.com/mdn/dom-examples/blob/main/web-crypto/sign-verify/ed25519.js), which you can [run live here](https://mdn.github.io/dom-examples/web-crypto/sign-verify/).
+
+#### HTML
+
+The HTML defines an ``, containing the text to be signed, and a button that starts the operation to create keys, sign the text and then verify the signature.
+
+```html
+
+
+
+
+```
+
+```html hidden
+
Click "Run" button

+```
+
+```css hidden
+#log {
+  height: 110px;
+  overflow: scroll;
+  padding: 0.5rem;
+  border: 1px solid black;
+}
+```
+
+```js hidden
+const logElement = document.querySelector("#log");
+function log(text) {
+  logElement.innerText = `${logElement.innerText}${text}\n`;
+  logElement.scrollTop = logElement.scrollHeight;
+}
+```
+
+#### JavaScript
+
+The JavaScript first gets the `button` and message `input` elements, and then adds a listener for the `click` event on the button.
+The event handler that clears the log and runs the other operations passing the content of the `input` element.
+
+```js
+const button = document.querySelector("#sign-button");
+const input = document.querySelector("#message");
+
+button.addEventListener("click", () => {
+  // Clear log
+  logElement.innerText = "";
+  logElement.scrollTop = logElement.scrollHeight;
+  // Run test
+  test(input.value);
+});
+```
+
+The code below has several parts.
+First it generates keys using the Ed25519 algorithm, then it encodes text and signs that text using the private key.
+Then if calls {{domxref("SubtleCrypto.verify()")}} with the public key to verify the signature.
+
+```js
+async function test(data) {
+  log(`Message: ${data}`);
+  try {
+    // Generate keys
+    const { publicKey, privateKey } = await crypto.subtle.generateKey(
+      {
+        name: "Ed25519",
+      },
+      true,
+      ["sign", "verify"],
+    );
+
+    log(`publicKey: ${publicKey}, type: ${publicKey.type}`);
+    log(`privateKey: ${privateKey},  type: ${privateKey.type}`);
+
+    // Encode data prior to signing
+    const encoder = new TextEncoder();
+    encodedData = encoder.encode(data);
+    log(`encodedData: ${encodedData}`);
+
+    // Sign the data using the private key.
+    const signature = await crypto.subtle.sign(
+      {
+        name: "Ed25519",
+      },
+      privateKey,
+      encodedData,
+    );
+
+    // Log the first part of the signature data
+    const signatureBuffer = new Uint8Array(signature, 0, 8);
+    log(
+      `signature: ${signatureBuffer}...[${signature.byteLength} bytes total]`,
+    );
+
+    // Verify the signature using the public key
+    const verifyResult = await crypto.subtle.verify(
+      {
+        name: "Ed25519",
+      },
+      publicKey,
+      signature,
+      encodedData,
+    );
+
+    // Log result - true if the text was signed with the corresponding public key.
+    log(`signature verified?: ${verifyResult}`);
+  } catch (error) {
+    log(error);
+  }
+}
+```
+
+#### Result
+
+The information about the created keys is logged below (or an error string if the browser does not allow the key to be created).
+
+{{EmbedLiveSample("Ed25519 (key generation, signing, and verification)", "100%", "170px")}}
+
 ## Specifications
 
 {{Specifications}}
diff --git a/files/en-us/web/api/subtlecrypto/verify/index.md b/files/en-us/web/api/subtlecrypto/verify/index.md
index 3ca8a7ba118d48b..e6ffb6d615ce606 100644
--- a/files/en-us/web/api/subtlecrypto/verify/index.md
+++ b/files/en-us/web/api/subtlecrypto/verify/index.md
@@ -11,10 +11,8 @@ browser-compat: api.SubtleCrypto.verify
 The **`verify()`** method of the {{domxref("SubtleCrypto")}}
 interface verifies a digital {{glossary("signature")}}.
 
-It takes as its arguments a {{glossary("key")}} to verify the signature with, some
-algorithm-specific parameters, the signature, and the original signed data. It returns a
-{{jsxref("Promise")}} which will be fulfilled with a boolean value
-indicating whether the signature is valid.
+It takes as its arguments a {{glossary("key")}} to verify the signature with, some algorithm-specific parameters, the signature, and the original signed data.
+It returns a {{jsxref("Promise")}} which will be fulfilled with a boolean value indicating whether the signature is valid.
 
 ## Syntax
 
@@ -32,6 +30,7 @@ verify(algorithm, key, signature, data)
     - To use [RSA-PSS](/en-US/docs/Web/API/SubtleCrypto/sign#rsa-pss), pass an {{domxref("RsaPssParams")}} object.
     - To use [ECDSA](/en-US/docs/Web/API/SubtleCrypto/sign#ecdsa), pass an {{domxref("EcdsaParams")}} object.
     - To use [HMAC](/en-US/docs/Web/API/SubtleCrypto/sign#hmac), pass the string `"HMAC"` or an object of the form `{ "name": "HMAC" }`.
+    - To use [Ed25519](/en-US/docs/Web/API/SubtleCrypto/sign##ed25519), pass an object of the form `{ "name": "Ed25519" }`.
 - `key`
   - : A {{domxref("CryptoKey")}} containing the key that will be used to verify the signature.
     It is the secret key for a symmetric algorithm and the public key for a public-key system.
@@ -51,15 +50,11 @@ otherwise.
 The promise is rejected when the following exception is encountered:
 
 - `InvalidAccessError` {{domxref("DOMException")}}
-  - : Raised when the encryption key is not a key for the requested verifying algorithm or
-    when trying to use an algorithm that is either unknown or isn't suitable for a verify
-    operation.
+  - : Raised when the encryption key is not a key for the requested verifying algorithm or when trying to use an algorithm that is either unknown or isn't suitable for a verify operation.
 
 ## Supported algorithms
 
-The `verify()` method supports the same algorithms as the
-[`sign()`](/en-US/docs/Web/API/SubtleCrypto/sign#supported_algorithms)
-method.
+The `verify()` method supports the same algorithms as the [`sign()`](/en-US/docs/Web/API/SubtleCrypto/sign#supported_algorithms) method.
 
 ## Examples
 

From 18e3861fad6b1d073ff5a89b26a98aec7ec6ab70 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Mon, 29 Jul 2024 14:47:09 +1000
Subject: [PATCH 02/33] Web Crypto API overview - list interfaces

---
 files/en-us/web/api/web_crypto_api/index.md | 56 ++++++++++++++++++++-
 1 file changed, 55 insertions(+), 1 deletion(-)

diff --git a/files/en-us/web/api/web_crypto_api/index.md b/files/en-us/web/api/web_crypto_api/index.md
index 04f335e404142cc..0516c97c9a49850 100644
--- a/files/en-us/web/api/web_crypto_api/index.md
+++ b/files/en-us/web/api/web_crypto_api/index.md
@@ -9,6 +9,10 @@ browser-compat: api.Crypto
 
 The **Web Crypto API** is an interface allowing a script to use cryptographic primitives in order to build systems using cryptography.
 
+Some browsers implemented an interface called {{domxref("Crypto")}} without having it well defined or being cryptographically sound.
+In order to avoid confusion, methods and properties of this interface have been removed from browsers implementing the Web Crypto API, and all Web Crypto API methods are available on a new interface: {{domxref("SubtleCrypto")}}.
+The {{domxref("Crypto.subtle")}} property gives access to an object implementing it.
+
 > [!WARNING]
 > The Web Crypto API provides a number of low-level cryptographic primitives. It's very easy to misuse them, and the pitfalls involved can be very subtle.
 >
@@ -20,7 +24,57 @@ The **Web Crypto API** is an interface allowing a script to use cryptographic pr
 
 ## Interfaces
 
-Some browsers implemented an interface called {{domxref("Crypto")}} without having it well defined or being cryptographically sound. In order to avoid confusion, methods and properties of this interface have been removed from browsers implementing the Web Crypto API, and all Web Crypto API methods are available on a new interface: {{domxref("SubtleCrypto")}}. The {{domxref("Crypto.subtle")}} property gives access to an object implementing it.
+- {{domxref("Crypto")}}
+  - : Provides basic cryptography features, such as a cryptographically strong random number generator, and access to cryptographic primitives via a [`SubtleCrypto`](#subtlecryto) object.
+    An object of this type can be accessed in the global scope using {{domxref("Window.crypto")}} or {{domxref("WorkerGlobalScope.crypto")}}.
+- {{domxref("SubtleCrypto")}}
+  - : Represents an object that provides low-level cryptographic functions for key generation, encryption, decryption, key wrapping and unwrapping, and so on.
+- {{domxref("CryptoKey")}}
+  - : Represents a cryptographic {{glossary("key")}} obtained from one of the {{domxref("SubtleCrypto")}} methods {{domxref("SubtleCrypto.generateKey", "generateKey()")}}, {{domxref("SubtleCrypto.deriveKey", "deriveKey()")}}, {{domxref("SubtleCrypto.importKey", "importKey()")}}, or {{domxref("SubtleCrypto.unwrapKey", "unwrapKey()")}}.
+
+### Dictionaries
+
+- {{domxref("AesCbcParams")}}
+  - : Represents the object that should be passed as the `algorithm` parameter into {{domxref("SubtleCrypto.encrypt()")}}, {{domxref("SubtleCrypto.decrypt()")}}, {{domxref("SubtleCrypto.wrapKey()")}}, or {{domxref("SubtleCrypto.unwrapKey()")}}, when using the [AES-CBC](/en-US/docs/Web/API/SubtleCrypto/encrypt#aes-cbc) algorithm.
+- {{domxref("AesCtrParams")}}
+  - : Represents the object that should be passed as the `algorithm` parameter into {{domxref("SubtleCrypto.encrypt()")}}, {{domxref("SubtleCrypto.decrypt()")}}, {{domxref("SubtleCrypto.wrapKey()")}}, or {{domxref("SubtleCrypto.unwrapKey()")}}, when using the [AES-CTR](/en-US/docs/Web/API/SubtleCrypto/encrypt#aes-ctr) algorithm.
+- {{domxref("AesGcmParams")}}
+  - : Represents the object that should be passed as the `algorithm` parameter into {{domxref("SubtleCrypto.encrypt()")}}, {{domxref("SubtleCrypto.decrypt()")}}, {{domxref("SubtleCrypto.wrapKey()")}}, or {{domxref("SubtleCrypto.unwrapKey()")}}, when using the [AES-GCM](/en-US/docs/Web/API/SubtleCrypto/encrypt#aes-gcm) algorithm.
+- {{domxref("AesKeyGenParams")}}
+  - : Represents the object that should be passed as the `algorithm` parameter into {{domxref("SubtleCrypto.generateKey()")}}, when generating an AES key: that is, when the algorithm is identified as any of [AES-CBC](/en-US/docs/Web/API/SubtleCrypto/encrypt#aes-cbc), [AES-CTR](/en-US/docs/Web/API/SubtleCrypto/encrypt#aes-ctr), [AES-GCM](/en-US/docs/Web/API/SubtleCrypto/encrypt#aes-gcm), or [AES-KW](/en-US/docs/Web/API/SubtleCrypto/wrapKey#aes-kw).
+- {{domxref("CryptoKeyPair")}}
+  - : Represents a public and private key pair used for an asymmetric cryptography algorithm.
+- {{domxref("EcKeyGenParams")}}
+  - : Represents the object that should be passed as the `algorithm` parameter into {{domxref("SubtleCrypto.generateKey()")}}, when generating any elliptic-curve-based key pair: that is, when the algorithm is identified as either of [ECDSA](/en-US/docs/Web/API/SubtleCrypto/sign#ecdsa) or [ECDH](/en-US/docs/Web/API/SubtleCrypto/deriveKey#ecdh).
+- {{domxref("EcKeyImportParams")}}
+  - : Represents the object that should be passed as the `algorithm` parameter into {{domxref("SubtleCrypto.importKey()")}} or {{domxref("SubtleCrypto.unwrapKey()")}}, when generating any elliptic-curve-based key pair: that is, when the algorithm is identified as either of [ECDSA](/en-US/docs/Web/API/SubtleCrypto/sign#ecdsa) or [ECDH](/en-US/docs/Web/API/SubtleCrypto/deriveKey#ecdh).
+- {{domxref("EcdhKeyDeriveParams")}}
+  - : 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.
+- {{domxref("EcdsaParams")}}
+  - : Represents the object that should be passed as the `algorithm` parameter into {{domxref("SubtleCrypto.sign()")}} or {{domxref("SubtleCrypto.verify()")}} when using the [ECDSA](/en-US/docs/Web/API/SubtleCrypto/sign#ecdsa) algorithm.
+- {{domxref("HkdfParams")}}
+  - : Represents the object that should be passed as the `algorithm` parameter into {{domxref("SubtleCrypto.deriveKey()")}}, when using the [HKDF](/en-US/docs/Web/API/SubtleCrypto/deriveKey#hkdf) algorithm.
+- {{domxref("HmacImportParams")}}
+  - : Represents the object that should be passed as the `algorithm` parameter into {{domxref("SubtleCrypto.importKey()")}} or {{domxref("SubtleCrypto.unwrapKey()")}}, when generating a key for the [HMAC](/en-US/docs/Web/API/SubtleCrypto/sign#hmac) algorithm.
+- {{domxref("HmacKeyGenParams")}}
+  - : Represents the object that should be passed as the `algorithm` parameter into {{domxref("SubtleCrypto.generateKey()")}}, when generating a key for the [HMAC](/en-US/docs/Web/API/SubtleCrypto/sign#hmac) algorithm.
+- {{domxref("Pbkdf2Params")}}
+  - : Represents the object that should be passed as the `algorithm` parameter into {{domxref("SubtleCrypto.deriveKey()")}}, when using the [PBKDF2](/en-US/docs/Web/API/SubtleCrypto/deriveKey#pbkdf2) algorithm.
+- {{domxref("RsaHashedImportParams")}}
+  - : Represents the object that should be passed as the `algorithm` parameter into {{domxref("SubtleCrypto.importKey()")}} or {{domxref("SubtleCrypto.unwrapKey()")}}, when importing any RSA-based key pair: that is, when the algorithm is identified as any of [RSASSA-PKCS1-v1_5](/en-US/docs/Web/API/SubtleCrypto/sign#rsassa-pkcs1-v1_5), [RSA-PSS](/en-US/docs/Web/API/SubtleCrypto/sign#rsa-pss), or [RSA-OAEP](/en-US/docs/Web/API/SubtleCrypto/encrypt#rsa-oaep).
+- {{domxref("RsaHashedKeyGenParams")}}
+  - : Represents the object that should be passed as the `algorithm` parameter into {{domxref("SubtleCrypto.generateKey()")}}, when generating any RSA-based key pair: that is, when the algorithm is identified as any of [RSASSA-PKCS1-v1_5](/en-US/docs/Web/API/SubtleCrypto/sign#rsassa-pkcs1-v1_5), [RSA-PSS](/en-US/docs/Web/API/SubtleCrypto/sign#rsa-pss), or [RSA-OAEP](/en-US/docs/Web/API/SubtleCrypto/encrypt#rsa-oaep).
+- {{domxref("RsaOaepParams")}}
+  - : Represents the object that should be passed as the `algorithm` parameter into {{domxref("SubtleCrypto.encrypt()")}}, {{domxref("SubtleCrypto.decrypt()")}}, {{domxref("SubtleCrypto.wrapKey()")}}, or {{domxref("SubtleCrypto.unwrapKey()")}}, when using the [RSA_OAEP](/en-US/docs/Web/API/SubtleCrypto/encrypt#rsa-oaep) algorithm.
+- {{domxref("RsaPssParams")}}
+  - : Represents the object that should be passed as the `algorithm` parameter into {{domxref("SubtleCrypto.sign()")}} or {{domxref("SubtleCrypto.verify()")}}, when using the [RSA-PSS](/en-US/docs/Web/API/SubtleCrypto/sign#rsa-pss) algorithm.
+
+### Extensions to other interfaces
+
+- {{domxref("Window.crypto")}}
+  - : Represents the {{domxref("Crypto")}} object associated with the global object in the main thread scope.
+- {{domxref("WorkerGlobalScope.crypto")}}
+  - : Represents {{domxref("Crypto")}} object associated with the global object in worker scope.
 
 ## Specifications
 

From bb16d24fff1fe542c9b7ac79949f5fadd67b37aa Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Mon, 29 Jul 2024 15:29:37 +1000
Subject: [PATCH 03/33] Add params for ED25519 and X25519 on the methods that
 use it

---
 .../web/api/subtlecrypto/generatekey/index.md |  3 ++-
 .../web/api/subtlecrypto/importkey/index.md   |  5 ++--
 .../en-us/web/api/subtlecrypto/sign/index.md  | 24 +++++++++----------
 .../web/api/subtlecrypto/unwrapkey/index.md   |  2 ++
 .../web/api/subtlecrypto/verify/index.md      | 19 +++++++++++++++
 5 files changed, 38 insertions(+), 15 deletions(-)

diff --git a/files/en-us/web/api/subtlecrypto/generatekey/index.md b/files/en-us/web/api/subtlecrypto/generatekey/index.md
index a19633263cd487f..0e88f08ebc901f4 100644
--- a/files/en-us/web/api/subtlecrypto/generatekey/index.md
+++ b/files/en-us/web/api/subtlecrypto/generatekey/index.md
@@ -34,7 +34,8 @@ generateKey(algorithm, extractable, keyUsages)
     - 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 the Ed25519 signature algorithm — pass an object of the form: `{ name: "Ed25519"}`.
+    - For the [ED25519](/en-US/docs/Web/API/SubtleCrypto/sign#ed25519) signature algorithm — pass an object of the form: `{ name: "Ed25519"}`.
+    - For the [X25519](/en-US/docs/Web/API/SubtleCrypto/sign#ed25519) ey agreement algorithm algorithm — pass an object of the form: `{name: 'X25519'}`.
 
 - `extractable`
   - : A boolean value indicating whether it will be possible to export the key using {{domxref("SubtleCrypto.exportKey()")}} or {{domxref("SubtleCrypto.wrapKey()")}}.
diff --git a/files/en-us/web/api/subtlecrypto/importkey/index.md b/files/en-us/web/api/subtlecrypto/importkey/index.md
index ffccf930e7360aa..1fa50bea04a12ad 100644
--- a/files/en-us/web/api/subtlecrypto/importkey/index.md
+++ b/files/en-us/web/api/subtlecrypto/importkey/index.md
@@ -46,9 +46,10 @@ importKey(format, keyData, algorithm, extractable, keyUsages)
       Pass the string identifying the algorithm or an object of the form `{ "name": ALGORITHM }`, where `ALGORITHM` is the name of the algorithm.
     - For [PBKDF2](/en-US/docs/Web/API/SubtleCrypto/deriveKey#pbkdf2): Pass the string `PBKDF2`.
     - For [HKDF](/en-US/docs/Web/API/SubtleCrypto/deriveKey#hkdf): Pass the string `HKDF`.
+    - For [Ed25519](#ed25519): Pass an object of the form `{ "name": "Ed25519" }`.
+    - For [X25519](/en-US/docs/Web/API/SubtleCrypto/sign#ed25519): Pass an object of the form: `{name: 'X25519'}`.
 - `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 key. Possible array values are:
     - `encrypt`: The key may be used to [encrypt](/en-US/docs/Web/API/SubtleCrypto/encrypt) messages.
diff --git a/files/en-us/web/api/subtlecrypto/sign/index.md b/files/en-us/web/api/subtlecrypto/sign/index.md
index 578fb8115762e31..5f17e575169ee8c 100644
--- a/files/en-us/web/api/subtlecrypto/sign/index.md
+++ b/files/en-us/web/api/subtlecrypto/sign/index.md
@@ -52,23 +52,28 @@ The Web Crypto API provides the following algorithms that can be used for signin
 
 #### RSASSA-PKCS1-v1_5
 
-The RSASSA-PKCS1-v1_5 algorithm is specified in [RFC 3447](https://datatracker.ietf.org/doc/html/rfc3447).
-
-This algorithm is used in {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
+The SASSA-PKCS1-v1_5 algorithm is used in {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
 Systems that use this algorithm use a [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) to hash the message to a short fixed size before signing.
 The choice of digest algorithm is passed into the {{domxref("SubtleCrypto.generateKey()", "generateKey()")}} or {{domxref("SubtleCrypto.importKey()", "importKey()")}} functions.
 
+The RSASSA-PKCS1-v1_5 algorithm is specified in [RFC 3447](https://datatracker.ietf.org/doc/html/rfc3447).
+
 #### RSA-PSS
 
-The RSA-PSS algorithm is specified in [RFC 3447](https://datatracker.ietf.org/doc/html/rfc3447).
+The RSA-PSS algorithm is used in {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
+Systems that use this algorithm use a [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) to hash the message to a short fixed size before signing.
+The choice of digest algorithm is passed into the {{domxref("SubtleCrypto.generateKey()", "generateKey()")}} or {{domxref("SubtleCrypto.importKey()", "importKey()")}} functions.
+
+The algorithm is specified in [RFC 3447](https://datatracker.ietf.org/doc/html/rfc3447).
 
 It's different from RSASSA-PKCS1-v1_5 in that it incorporates a random salt in the signature operation, so the same message signed with the same key will not result in the same signature each time. An extra property, defining the salt length, is passed into the {{domxref("SubtleCrypto.sign()", "sign()")}} and {{domxref("SubtleCrypto.verify()", "verify()")}} functions when they are invoked.
 
+#### ECDSA
+
 This algorithm is used in {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
 Systems that use this algorithm use a [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) to hash the message to a short fixed size before signing.
-The choice of digest algorithm is passed into the {{domxref("SubtleCrypto.generateKey()", "generateKey()")}} or {{domxref("SubtleCrypto.importKey()", "importKey()")}} functions.
-
-#### ECDSA
+This
+For ECDSA the choice of digest algorithm is passed as part of the `algorithm` object, a {{domxref("EcdsaParams")}}, when calling {{domxref("SubtleCrypto.sign()")}}.
 
 ECDSA (Elliptic Curve Digital Signature Algorithm) is a variant of the Digital Signature Algorithm, specified in [FIPS-186](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf), that uses Elliptic Curve Cryptography ([RFC 6090](https://datatracker.ietf.org/doc/html/rfc6090)).
 
@@ -77,11 +82,6 @@ These values are concatenated together in this order.
 
 This encoding was also proposed by the [IEEE 1363-2000](https://standards.ieee.org/ieee/1363/2049/) standard, and is sometimes referred to as the IEEE P1363 format. It differs from the [X.509](https://www.itu.int/rec/T-REC-X.509) signature structure, which is the default format produced by some tools and libraries such as [OpenSSL](https://www.openssl.org).
 
-This algorithm is used in {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
-Systems that use this algorithm use a [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) to hash the message to a short fixed size before signing.
-This
-For ECDSA the choice of digest algorithm is passed as part of the `algorithm` object, a {{domxref("EcdsaParams")}}, when calling {{domxref("SubtleCrypto.sign()")}}.
-
 #### HMAC
 
 The HMAC algorithm calculates and verifies hash-based message authentication codes according to the [FIPS 198-1 standard](https://csrc.nist.gov/csrc/media/publications/fips/198/1/final/documents/fips-198-1_final.pdf).
diff --git a/files/en-us/web/api/subtlecrypto/unwrapkey/index.md b/files/en-us/web/api/subtlecrypto/unwrapkey/index.md
index 4ba7aba684dce18..ea0876a2cd27481 100644
--- a/files/en-us/web/api/subtlecrypto/unwrapkey/index.md
+++ b/files/en-us/web/api/subtlecrypto/unwrapkey/index.md
@@ -62,6 +62,8 @@ unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgo, unwrappedKeyAlgo, extra
     - 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 the string identifying the algorithm or an object of the form `{ "name": ALGORITHM }`, where `ALGORITHM` is the name of the algorithm.
+    - For [ED25519](#ed25519): Pass an object of the form `{ "name": "Ed25519" }`.
+    - For [X25519](/en-US/docs/Web/API/SubtleCrypto/sign#ed25519): Pass an object of the form: `{name: 'X25519'}`.
 - `extractable`
   - : A boolean indicating whether it will be possible to export the key
     using [`SubtleCrypto.exportKey()`](/en-US/docs/Web/API/SubtleCrypto/exportKey) or [`SubtleCrypto.wrapKey()`](/en-US/docs/Web/API/SubtleCrypto/wrapKey).
diff --git a/files/en-us/web/api/subtlecrypto/verify/index.md b/files/en-us/web/api/subtlecrypto/verify/index.md
index e6ffb6d615ce606..137e11674c60226 100644
--- a/files/en-us/web/api/subtlecrypto/verify/index.md
+++ b/files/en-us/web/api/subtlecrypto/verify/index.md
@@ -221,6 +221,25 @@ async function verifyMessage(key) {
 }
 ```
 
+### Ed25519
+
+The [Ed25519 live example](/en-US/docs/Web/API/SubtleCrypto/sign#ed25519_key_generation_signing_and_verification) in `SubtleCrypto.sign()` shows how to generate public and private keys, use the private key to sign some data, and then use the public key to verify the signature.
+
+The code below shows the part that is relevant to verifying the signature using the public key and encoded data:
+
+```js
+// Verify the signature using the public key
+const verifyResult = await crypto.subtle.verify(
+  {
+    name: "Ed25519",
+  },
+  publicKey,
+  signature,
+  encodedData,
+);
+// True if the signature is valid.
+```
+
 ## Specifications
 
 {{Specifications}}

From dcd010508bb0a647b4bc5f2b829eadcad41d581e Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Mon, 29 Jul 2024 15:37:04 +1000
Subject: [PATCH 04/33] Update files/en-us/web/api/subtlecrypto/sign/index.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
---
 files/en-us/web/api/subtlecrypto/sign/index.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/files/en-us/web/api/subtlecrypto/sign/index.md b/files/en-us/web/api/subtlecrypto/sign/index.md
index 5f17e575169ee8c..2b31f924ef14201 100644
--- a/files/en-us/web/api/subtlecrypto/sign/index.md
+++ b/files/en-us/web/api/subtlecrypto/sign/index.md
@@ -66,6 +66,7 @@ The choice of digest algorithm is passed into the {{domxref("SubtleCrypto.genera
 
 The algorithm is specified in [RFC 3447](https://datatracker.ietf.org/doc/html/rfc3447).
 
+
 It's different from RSASSA-PKCS1-v1_5 in that it incorporates a random salt in the signature operation, so the same message signed with the same key will not result in the same signature each time. An extra property, defining the salt length, is passed into the {{domxref("SubtleCrypto.sign()", "sign()")}} and {{domxref("SubtleCrypto.verify()", "verify()")}} functions when they are invoked.
 
 #### ECDSA

From 1ab14387ae906fb489d16864fe16470ccea0c531 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Mon, 29 Jul 2024 15:43:28 +1000
Subject: [PATCH 05/33] Prettier sign()

---
 files/en-us/web/api/subtlecrypto/sign/index.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/files/en-us/web/api/subtlecrypto/sign/index.md b/files/en-us/web/api/subtlecrypto/sign/index.md
index 2b31f924ef14201..5f17e575169ee8c 100644
--- a/files/en-us/web/api/subtlecrypto/sign/index.md
+++ b/files/en-us/web/api/subtlecrypto/sign/index.md
@@ -66,7 +66,6 @@ The choice of digest algorithm is passed into the {{domxref("SubtleCrypto.genera
 
 The algorithm is specified in [RFC 3447](https://datatracker.ietf.org/doc/html/rfc3447).
 
-
 It's different from RSASSA-PKCS1-v1_5 in that it incorporates a random salt in the signature operation, so the same message signed with the same key will not result in the same signature each time. An extra property, defining the salt length, is passed into the {{domxref("SubtleCrypto.sign()", "sign()")}} and {{domxref("SubtleCrypto.verify()", "verify()")}} functions when they are invoked.
 
 #### ECDSA

From 16f10d258ab3525adfc59bc9d57c83da5d632d98 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Fri, 2 Aug 2024 13:13:18 +1000
Subject: [PATCH 06/33] Update files/en-us/web/api/subtlecrypto/index.md

---
 files/en-us/web/api/subtlecrypto/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/api/subtlecrypto/index.md b/files/en-us/web/api/subtlecrypto/index.md
index 2b40ba9890b45a8..9403af9ee75d2e7 100644
--- a/files/en-us/web/api/subtlecrypto/index.md
+++ b/files/en-us/web/api/subtlecrypto/index.md
@@ -88,7 +88,7 @@ The inverse of `wrapKey()` is {{DOMxRef("SubtleCrypto.unwrapKey","unwrapKey()")}
 #### Storing keys
 
 `CryptoKey` is a {{glossary("serializable object")}}, which allows keys to be stored and retrieved using standard web storage APIs.
-The specification expects that most developers will use the [IndexedDB API](/en-US/docs/Web/API/IndexedDB_API), sotring `CryptoKey` objects against some key string identifier that is meaningful to the application, along with any other metadata it finds useful.
+The specification expects that most developers will use the [IndexedDB API](/en-US/docs/Web/API/IndexedDB_API), storing `CryptoKey` objects against some key string identifier that is meaningful to the application, along with any other metadata it finds useful.
 
 ### Supported algorithms
 

From cc9e3daf72dc95f6a08b570582a5291ab2004233 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Fri, 2 Aug 2024 13:38:52 +1000
Subject: [PATCH 07/33] Update files/en-us/web/api/subtlecrypto/index.md

---
 files/en-us/web/api/subtlecrypto/index.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/files/en-us/web/api/subtlecrypto/index.md b/files/en-us/web/api/subtlecrypto/index.md
index 9403af9ee75d2e7..f3518350db807d9 100644
--- a/files/en-us/web/api/subtlecrypto/index.md
+++ b/files/en-us/web/api/subtlecrypto/index.md
@@ -88,7 +88,9 @@ The inverse of `wrapKey()` is {{DOMxRef("SubtleCrypto.unwrapKey","unwrapKey()")}
 #### Storing keys
 
 `CryptoKey` is a {{glossary("serializable object")}}, which allows keys to be stored and retrieved using standard web storage APIs.
+
 The specification expects that most developers will use the [IndexedDB API](/en-US/docs/Web/API/IndexedDB_API), storing `CryptoKey` objects against some key string identifier that is meaningful to the application, along with any other metadata it finds useful.
+This allows the storage and retrieval of the `CryptoKey` without having to expose its underlying key material to the application or the JavaScript environment.
 
 ### Supported algorithms
 

From 27fa5b4a19a31f169ac1ae2bddb4d1768865d59a Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Fri, 2 Aug 2024 13:42:49 +1000
Subject: [PATCH 08/33] Update
 files/en-us/web/api/subtlecrypto/derivekey/index.md

Co-authored-by: wbamberg 
---
 files/en-us/web/api/subtlecrypto/derivekey/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/api/subtlecrypto/derivekey/index.md b/files/en-us/web/api/subtlecrypto/derivekey/index.md
index 96b15ee41c8031a..03f3248af976e0d 100644
--- a/files/en-us/web/api/subtlecrypto/derivekey/index.md
+++ b/files/en-us/web/api/subtlecrypto/derivekey/index.md
@@ -113,7 +113,7 @@ The more times the process is repeated, the more computationally expensive key d
 
 PBKDF2 is specified in [RFC 2898](https://datatracker.ietf.org/doc/html/rfc2898).
 
-#### X25519
+### X25519
 
 X25519 is a high-performance key agreement algorithm 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")}}.

From 7c6911e414ce2d9bdbe48e57d874ee43d5f67e86 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Fri, 2 Aug 2024 14:50:06 +1000
Subject: [PATCH 09/33] Update
 files/en-us/web/api/subtlecrypto/generatekey/index.md

Co-authored-by: Brian Thomas Smith 
---
 files/en-us/web/api/subtlecrypto/generatekey/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/api/subtlecrypto/generatekey/index.md b/files/en-us/web/api/subtlecrypto/generatekey/index.md
index 0e88f08ebc901f4..4f37b828e547f87 100644
--- a/files/en-us/web/api/subtlecrypto/generatekey/index.md
+++ b/files/en-us/web/api/subtlecrypto/generatekey/index.md
@@ -35,7 +35,7 @@ generateKey(algorithm, extractable, keyUsages)
       [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 the [ED25519](/en-US/docs/Web/API/SubtleCrypto/sign#ed25519) signature algorithm — pass an object of the form: `{ name: "Ed25519"}`.
-    - For the [X25519](/en-US/docs/Web/API/SubtleCrypto/sign#ed25519) ey agreement algorithm algorithm — pass an object of the form: `{name: 'X25519'}`.
+    - For the [X25519](/en-US/docs/Web/API/SubtleCrypto/sign#ed25519) key agreement algorithm — pass an object of the form: `{name: "X25519"}`.
 
 - `extractable`
   - : A boolean value indicating whether it will be possible to export the key using {{domxref("SubtleCrypto.exportKey()")}} or {{domxref("SubtleCrypto.wrapKey()")}}.

From 102fa600b05a42529f61b058adcade91e6c392a1 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Fri, 2 Aug 2024 14:50:25 +1000
Subject: [PATCH 10/33] Update
 files/en-us/web/api/subtlecrypto/importkey/index.md

Co-authored-by: Brian Thomas Smith 
---
 files/en-us/web/api/subtlecrypto/importkey/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/api/subtlecrypto/importkey/index.md b/files/en-us/web/api/subtlecrypto/importkey/index.md
index 1fa50bea04a12ad..81ef0c77336bb98 100644
--- a/files/en-us/web/api/subtlecrypto/importkey/index.md
+++ b/files/en-us/web/api/subtlecrypto/importkey/index.md
@@ -47,7 +47,7 @@ importKey(format, keyData, algorithm, extractable, keyUsages)
     - For [PBKDF2](/en-US/docs/Web/API/SubtleCrypto/deriveKey#pbkdf2): Pass the string `PBKDF2`.
     - For [HKDF](/en-US/docs/Web/API/SubtleCrypto/deriveKey#hkdf): Pass the string `HKDF`.
     - For [Ed25519](#ed25519): Pass an object of the form `{ "name": "Ed25519" }`.
-    - For [X25519](/en-US/docs/Web/API/SubtleCrypto/sign#ed25519): Pass an object of the form: `{name: 'X25519'}`.
+    - For [X25519](/en-US/docs/Web/API/SubtleCrypto/sign#ed25519): Pass an object of the form: `{name: "X25519"}`.
 - `extractable`
   - : A boolean value indicating whether it will be possible to export the key using {{domxref("SubtleCrypto.exportKey()")}} or {{domxref("SubtleCrypto.wrapKey()")}}.
 - `keyUsages`

From 75a4027125be1c23a488f5bf6697b244618b39b1 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Fri, 2 Aug 2024 16:11:08 +1000
Subject: [PATCH 11/33] Make algorithm consistent

---
 .../web/api/subtlecrypto/generatekey/index.md  | 14 +++++++-------
 .../web/api/subtlecrypto/importkey/index.md    | 18 +++++++++---------
 files/en-us/web/api/subtlecrypto/sign/index.md |  6 +++---
 3 files changed, 19 insertions(+), 19 deletions(-)

diff --git a/files/en-us/web/api/subtlecrypto/generatekey/index.md b/files/en-us/web/api/subtlecrypto/generatekey/index.md
index 4f37b828e547f87..a519bbbed68d86d 100644
--- a/files/en-us/web/api/subtlecrypto/generatekey/index.md
+++ b/files/en-us/web/api/subtlecrypto/generatekey/index.md
@@ -23,19 +23,19 @@ generateKey(algorithm, extractable, keyUsages)
   - : An object defining the type of key to generate and providing extra algorithm-specific parameters.
 
     - For [RSASSA-PKCS1-v1_5](/en-US/docs/Web/API/SubtleCrypto/sign#rsassa-pkcs1-v1_5), [RSA-PSS](/en-US/docs/Web/API/SubtleCrypto/sign#rsa-pss),
-      or [RSA-OAEP](/en-US/docs/Web/API/SubtleCrypto/encrypt#rsa-oaep) —
+      or [RSA-OAEP](/en-US/docs/Web/API/SubtleCrypto/encrypt#rsa-oaep):
       pass an [`RsaHashedKeyGenParams`](/en-US/docs/Web/API/RsaHashedKeyGenParams) object.
-    - For [ECDSA](/en-US/docs/Web/API/SubtleCrypto/sign#ecdsa) or [ECDH](/en-US/docs/Web/API/SubtleCrypto/deriveKey#ecdh) —
+    - For [ECDSA](/en-US/docs/Web/API/SubtleCrypto/sign#ecdsa) or [ECDH](/en-US/docs/Web/API/SubtleCrypto/deriveKey#ecdh):
       pass an [`EcKeyGenParams`](/en-US/docs/Web/API/EcKeyGenParams) object.
-    - For [HMAC](/en-US/docs/Web/API/SubtleCrypto/sign#hmac) — pass an [`HmacKeyGenParams`](/en-US/docs/Web/API/HmacKeyGenParams) object.
+    - 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) —
+      [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) —
+      [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 the [ED25519](/en-US/docs/Web/API/SubtleCrypto/sign#ed25519) signature algorithm — pass an object of the form: `{ name: "Ed25519"}`.
-    - For the [X25519](/en-US/docs/Web/API/SubtleCrypto/sign#ed25519) key agreement algorithm — pass an object of the form: `{name: "X25519"}`.
+    - For [Ed25519](/en-US/docs/Web/API/SubtleCrypto/sign#ed25519): pass the string `Ed25519` or an object of the form `{ name: "Ed25519" }`.
+    - For [X25519](/en-US/docs/Web/API/SubtleCrypto/deriveKey#x25519): pass the string `X25519` or an object of the form `{ name: "X25519" }`.
 
 - `extractable`
   - : A boolean value indicating whether it will be possible to export the key using {{domxref("SubtleCrypto.exportKey()")}} or {{domxref("SubtleCrypto.wrapKey()")}}.
diff --git a/files/en-us/web/api/subtlecrypto/importkey/index.md b/files/en-us/web/api/subtlecrypto/importkey/index.md
index 81ef0c77336bb98..a09f05f560ae36b 100644
--- a/files/en-us/web/api/subtlecrypto/importkey/index.md
+++ b/files/en-us/web/api/subtlecrypto/importkey/index.md
@@ -36,18 +36,18 @@ importKey(format, keyData, algorithm, extractable, keyUsages)
   - : An object defining the type of key to import and providing extra algorithm-specific parameters.
     - For [RSASSA-PKCS1-v1_5](/en-US/docs/Web/API/SubtleCrypto/sign#rsassa-pkcs1-v1_5), [RSA-PSS](/en-US/docs/Web/API/SubtleCrypto/sign#rsa-pss),
       or [RSA-OAEP](/en-US/docs/Web/API/SubtleCrypto/encrypt#rsa-oaep):
-      Pass an [`RsaHashedImportParams`](/en-US/docs/Web/API/RsaHashedImportParams) object.
+      pass an [`RsaHashedImportParams`](/en-US/docs/Web/API/RsaHashedImportParams) object.
     - For [ECDSA](/en-US/docs/Web/API/SubtleCrypto/sign#ecdsa) or [ECDH](/en-US/docs/Web/API/SubtleCrypto/deriveKey#ecdh):
-      Pass an [`EcKeyImportParams`](/en-US/docs/Web/API/EcKeyImportParams) object.
+      pass an [`EcKeyImportParams`](/en-US/docs/Web/API/EcKeyImportParams) object.
     - For [HMAC](/en-US/docs/Web/API/SubtleCrypto/sign#hmac):
-      Pass an [`HmacImportParams`](/en-US/docs/Web/API/HmacImportParams) object.
+      pass an [`HmacImportParams`](/en-US/docs/Web/API/HmacImportParams) 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 the string identifying the algorithm or an object of the form `{ "name": ALGORITHM }`, where `ALGORITHM` is the name of the algorithm.
-    - For [PBKDF2](/en-US/docs/Web/API/SubtleCrypto/deriveKey#pbkdf2): Pass the string `PBKDF2`.
-    - For [HKDF](/en-US/docs/Web/API/SubtleCrypto/deriveKey#hkdf): Pass the string `HKDF`.
-    - For [Ed25519](#ed25519): Pass an object of the form `{ "name": "Ed25519" }`.
-    - For [X25519](/en-US/docs/Web/API/SubtleCrypto/sign#ed25519): Pass an object of the form: `{name: "X25519"}`.
+      [AES-GCM](/en-US/docs/Web/API/SubtleCrypto/encrypt#aes-gcm), and [AES-KW](/en-US/docs/Web/API/SubtleCrypto/wrapKey#aes-kw):
+      pass the string identifying the algorithm or an object of the form `{ name: ALGORITHM }`, where `ALGORITHM` is the name of the algorithm.
+    - For [PBKDF2](/en-US/docs/Web/API/SubtleCrypto/deriveKey#pbkdf2): pass the string `PBKDF2`.
+    - For [HKDF](/en-US/docs/Web/API/SubtleCrypto/deriveKey#hkdf): pass the string `HKDF`.
+    - For [Ed25519](/en-US/docs/Web/API/SubtleCrypto/sign#ed25519): pass the string `Ed25519` or an object of the form `{ name: "Ed25519" }`.
+    - For [X25519](/en-US/docs/Web/API/SubtleCrypto/deriveKey#x25519): pass the string `X25519` or an object of the form `{ name: "X25519" }`.
 - `extractable`
   - : A boolean value indicating whether it will be possible to export the key using {{domxref("SubtleCrypto.exportKey()")}} or {{domxref("SubtleCrypto.wrapKey()")}}.
 - `keyUsages`
diff --git a/files/en-us/web/api/subtlecrypto/sign/index.md b/files/en-us/web/api/subtlecrypto/sign/index.md
index 5f17e575169ee8c..2b77c6162848cfc 100644
--- a/files/en-us/web/api/subtlecrypto/sign/index.md
+++ b/files/en-us/web/api/subtlecrypto/sign/index.md
@@ -24,11 +24,11 @@ sign(algorithm, key, data)
 
 - `algorithm`
   - : A string or object that specifies the signature algorithm to use and its parameters:
-    - To use [RSASSA-PKCS1-v1_5](#rsassa-pkcs1-v1_5), pass the string `"RSASSA-PKCS1-v1_5"` or an object of the form `{ "name": "RSASSA-PKCS1-v1_5" }`.
+    - To use [RSASSA-PKCS1-v1_5](#rsassa-pkcs1-v1_5), pass the string `RSASSA-PKCS1-v1_5` or an object of the form `{ name: "RSASSA-PKCS1-v1_5" }`.
     - To use [RSA-PSS](#rsa-pss), pass an {{domxref("RsaPssParams")}} object.
     - To use [ECDSA](#ecdsa), pass an {{domxref("EcdsaParams")}} object.
-    - To use [HMAC](#hmac), pass the string `"HMAC"` or an object of the form `{ "name": "HMAC" }`.
-    - To use [Ed25519](#ed25519), pass an object of the form `{ "name": "Ed25519" }`.
+    - To use [HMAC](#hmac), pass the string `HMAC` or an object of the form `{ name: "HMAC" }`.
+    - To use [Ed25519](#ed25519), pass the string `Ed25519` or an object of the form `{ name: "Ed25519" }`.
 - `key`
   - : A {{domxref("CryptoKey")}} object containing the key to be used for signing.
     If `algorithm` identifies a public-key cryptosystem, this is the private key.

From 8f9628479b67d2fa1adc43635b1f3efa75e51163 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Fri, 2 Aug 2024 16:17:01 +1000
Subject: [PATCH 12/33] Consistent heading levels for sign() algorithm info

---
 files/en-us/web/api/subtlecrypto/sign/index.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/files/en-us/web/api/subtlecrypto/sign/index.md b/files/en-us/web/api/subtlecrypto/sign/index.md
index 2b77c6162848cfc..1c4c58acd4a76cb 100644
--- a/files/en-us/web/api/subtlecrypto/sign/index.md
+++ b/files/en-us/web/api/subtlecrypto/sign/index.md
@@ -50,7 +50,7 @@ The promise is rejected when the following exception is encountered:
 
 The Web Crypto API provides the following algorithms that can be used for signing (and signature verification):
 
-#### RSASSA-PKCS1-v1_5
+### RSASSA-PKCS1-v1_5
 
 The SASSA-PKCS1-v1_5 algorithm is used in {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
 Systems that use this algorithm use a [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) to hash the message to a short fixed size before signing.
@@ -58,7 +58,7 @@ The choice of digest algorithm is passed into the {{domxref("SubtleCrypto.genera
 
 The RSASSA-PKCS1-v1_5 algorithm is specified in [RFC 3447](https://datatracker.ietf.org/doc/html/rfc3447).
 
-#### RSA-PSS
+### RSA-PSS
 
 The RSA-PSS algorithm is used in {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
 Systems that use this algorithm use a [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) to hash the message to a short fixed size before signing.
@@ -68,7 +68,7 @@ The algorithm is specified in [RFC 3447](https://datatracker.ietf.org/doc/html/r
 
 It's different from RSASSA-PKCS1-v1_5 in that it incorporates a random salt in the signature operation, so the same message signed with the same key will not result in the same signature each time. An extra property, defining the salt length, is passed into the {{domxref("SubtleCrypto.sign()", "sign()")}} and {{domxref("SubtleCrypto.verify()", "verify()")}} functions when they are invoked.
 
-#### ECDSA
+### ECDSA
 
 This algorithm is used in {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
 Systems that use this algorithm use a [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) to hash the message to a short fixed size before signing.
@@ -82,7 +82,7 @@ These values are concatenated together in this order.
 
 This encoding was also proposed by the [IEEE 1363-2000](https://standards.ieee.org/ieee/1363/2049/) standard, and is sometimes referred to as the IEEE P1363 format. It differs from the [X.509](https://www.itu.int/rec/T-REC-X.509) signature structure, which is the default format produced by some tools and libraries such as [OpenSSL](https://www.openssl.org).
 
-#### HMAC
+### HMAC
 
 The HMAC algorithm calculates and verifies hash-based message authentication codes according to the [FIPS 198-1 standard](https://csrc.nist.gov/csrc/media/publications/fips/198/1/final/documents/fips-198-1_final.pdf).
 
@@ -92,7 +92,7 @@ The digest algorithm to use is specified in the [`HmacKeyGenParams`](/en-US/docs
 The HMAC algorithm uses the same algorithm and key for signing and for verification: this means that the verification key must be kept secret, which in turn means that this algorithm is not suitable for many signature use cases.
 It can be a good choice however when the signer and verifier are the same entity.
 
-#### Ed25519
+### Ed25519
 
 Ed25519 is a high-performance digital signature algorithm 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")}}.
 

From db3ae2cf9521febac1e3d7bbe1b53facf1e089ba Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Fri, 2 Aug 2024 17:05:42 +1000
Subject: [PATCH 13/33] Fix up the algorithm/method table

---
 files/en-us/web/api/subtlecrypto/index.md | 45 +++++++++++++++++------
 1 file changed, 33 insertions(+), 12 deletions(-)

diff --git a/files/en-us/web/api/subtlecrypto/index.md b/files/en-us/web/api/subtlecrypto/index.md
index f3518350db807d9..5501242fe21e164 100644
--- a/files/en-us/web/api/subtlecrypto/index.md
+++ b/files/en-us/web/api/subtlecrypto/index.md
@@ -103,22 +103,25 @@ The table below summarizes which algorithms are suitable for which cryptographic
     
       
       
-        sign()
verify()
+        sign
verify
       
       
-        encrypt()
decrypt()
+        encrypt
decrypt
       
       
-        digest()
+        digest
       
       
-        deriveBits()
deriveKey()
+        deriveBits
deriveKey
       
       
-        wrapKey()
unwrapKey()
+        wrapKey
unwrapKey
       
       
-        generateKey()
importKey()
exportKey()
+        generateKey
exportKey
+      
+      
+        importKey
       
     
   
@@ -131,6 +134,7 @@ The table below summarizes which algorithms are suitable for which cryptographic
       
       
       ✓
+      ✓
     
     
       RSA-PSS
@@ -140,6 +144,7 @@ The table below summarizes which algorithms are suitable for which cryptographic
       
       
       ✓
+      ✓
     
     
       ECDSA
@@ -149,6 +154,7 @@ The table below summarizes which algorithms are suitable for which cryptographic
       
       
       ✓
+      ✓
     
     
       Ed25519
@@ -156,6 +162,7 @@ The table below summarizes which algorithms are suitable for which cryptographic
       
       
       
+      
       ✓
       ✓
     
@@ -167,6 +174,7 @@ The table below summarizes which algorithms are suitable for which cryptographic
       
       
       ✓
+      ✓
     
     
       RSA-OAEP
@@ -176,6 +184,7 @@ The table below summarizes which algorithms are suitable for which cryptographic
       
       ✓
       ✓
+      ✓
     
     
       AES-CTR
@@ -185,6 +194,7 @@ The table below summarizes which algorithms are suitable for which cryptographic
       
       ✓
       ✓
+      ✓
     
     
       AES-CBC
@@ -194,6 +204,7 @@ The table below summarizes which algorithms are suitable for which cryptographic
       
       ✓
       ✓
+      ✓
     
     
       AES-GCM
@@ -203,6 +214,7 @@ The table below summarizes which algorithms are suitable for which cryptographic
       
       ✓
       ✓
+      ✓
     
     
       AES-KW
@@ -212,6 +224,7 @@ The table below summarizes which algorithms are suitable for which cryptographic
       
       ✓
       ✓
+      ✓
     
     
       SHA-1
@@ -221,6 +234,7 @@ The table below summarizes which algorithms are suitable for which cryptographic
       
       
       
+      
     
     
       SHA-256
@@ -230,6 +244,7 @@ The table below summarizes which algorithms are suitable for which cryptographic
       
       
       
+      
     
     
       SHA-384
@@ -239,6 +254,7 @@ The table below summarizes which algorithms are suitable for which cryptographic
       
       
       
+      
     
     
       SHA-512
@@ -248,6 +264,7 @@ The table below summarizes which algorithms are suitable for which cryptographic
       
       
       
+      
     
     
       ECDH
@@ -256,34 +273,38 @@ The table below summarizes which algorithms are suitable for which cryptographic
       
       ✓
       
-      
+      ✓
+      ✓
     
     
-      HKDF
+      X25519
       
       
       
       ✓
       
-      
+      ✓
+      ✓
     
     
-      PBKDF2
+      HKDF
       
       
       
       ✓
       
+      ✓
       
     
     
-      X25519
+      PBKDF2
       
       
       
       ✓
+      
       ✓
-      ✓
+      
     
   
 

From 7e44156531b13986f3614d53b6b3401002b64dc7 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Fri, 2 Aug 2024 17:36:38 +1000
Subject: [PATCH 14/33] Fix number algorithms

---
 .../web/api/subtlecrypto/derivebits/index.md  | 10 ++--
 .../web/api/subtlecrypto/derivekey/index.md   | 47 +++++++------------
 2 files changed, 20 insertions(+), 37 deletions(-)

diff --git a/files/en-us/web/api/subtlecrypto/derivebits/index.md b/files/en-us/web/api/subtlecrypto/derivebits/index.md
index d4cfe08ef7ec4ca..c594704241ee0e8 100644
--- a/files/en-us/web/api/subtlecrypto/derivebits/index.md
+++ b/files/en-us/web/api/subtlecrypto/derivebits/index.md
@@ -40,12 +40,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.
+    - 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 the string `X25519` or an object of the form `{ name: "X25519" }`.
 - `baseKey`
   - : A {{domxref("CryptoKey")}} representing the input
     to the derivation algorithm. If `algorithm` is ECDH, this will be the ECDH
diff --git a/files/en-us/web/api/subtlecrypto/derivekey/index.md b/files/en-us/web/api/subtlecrypto/derivekey/index.md
index 03f3248af976e0d..0c292f5703565ad 100644
--- a/files/en-us/web/api/subtlecrypto/derivekey/index.md
+++ b/files/en-us/web/api/subtlecrypto/derivekey/index.md
@@ -28,34 +28,23 @@ 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.
     - 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.
 - `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, 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).
 - `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,19 +63,15 @@ 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
 
@@ -115,7 +100,7 @@ PBKDF2 is specified in [RFC 2898](https://datatracker.ietf.org/doc/html/rfc2898)
 
 ### X25519
 
-X25519 is a high-performance key agreement algorithm 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")}}.
+X25519 is a key agreement algorithm 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
@@ -125,9 +110,9 @@ The algorithm is specified in {{rfc("7748")}}.
 
 ### 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
 /*

From 7ce4301a952bf5469eea385245bb09845f84b2e2 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Fri, 2 Aug 2024 17:46:59 +1000
Subject: [PATCH 15/33] X25519 - how to use with deriveKey and deriveBits

---
 files/en-us/web/api/ecdhkeyderiveparams/index.md     | 10 ++++++----
 files/en-us/web/api/subtlecrypto/derivebits/index.md |  9 ++++-----
 files/en-us/web/api/subtlecrypto/derivekey/index.md  |  3 ++-
 3 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/files/en-us/web/api/ecdhkeyderiveparams/index.md b/files/en-us/web/api/ecdhkeyderiveparams/index.md
index 7e80534bbbb2e83..f751b04905e4827 100644
--- a/files/en-us/web/api/ecdhkeyderiveparams/index.md
+++ b/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,13 +16,14 @@ 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
 
@@ -30,8 +31,9 @@ See the examples for {{domxref("SubtleCrypto.deriveKey()")}}.
 
 ## Browser compatibility
 
-Browsers that support the "ECDH" algorithm for the {{domxref("SubtleCrypto.deriveKey()")}} method will support this type.
+Browsers that support the "ECDH" and "X25519" algorithm for the {{domxref("SubtleCrypto.deriveKey()")}} method will support this type.
 
 ## See also
 
 - {{domxref("SubtleCrypto.deriveKey()")}}.
+- {{domxref("SubtleCrypto.deriveBits()")}}
diff --git a/files/en-us/web/api/subtlecrypto/derivebits/index.md b/files/en-us/web/api/subtlecrypto/derivebits/index.md
index c594704241ee0e8..29d4e59033d3192 100644
--- a/files/en-us/web/api/subtlecrypto/derivebits/index.md
+++ b/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,10 +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 [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 the string `X25519` or an object of the form `{ name: "X25519" }`.
+    - 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
diff --git a/files/en-us/web/api/subtlecrypto/derivekey/index.md b/files/en-us/web/api/subtlecrypto/derivekey/index.md
index 0c292f5703565ad..4b6703208ef3eb7 100644
--- a/files/en-us/web/api/subtlecrypto/derivekey/index.md
+++ b/files/en-us/web/api/subtlecrypto/derivekey/index.md
@@ -28,8 +28,9 @@ 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 [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.

From e4118747fbbf34c8df6ac51c31a087bb34be4a11 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Fri, 2 Aug 2024 17:55:18 +1000
Subject: [PATCH 16/33] Update
 files/en-us/web/api/subtlecrypto/derivekey/index.md

---
 files/en-us/web/api/subtlecrypto/derivekey/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/api/subtlecrypto/derivekey/index.md b/files/en-us/web/api/subtlecrypto/derivekey/index.md
index 4b6703208ef3eb7..a2962a8af46d746 100644
--- a/files/en-us/web/api/subtlecrypto/derivekey/index.md
+++ b/files/en-us/web/api/subtlecrypto/derivekey/index.md
@@ -101,7 +101,7 @@ PBKDF2 is specified in [RFC 2898](https://datatracker.ietf.org/doc/html/rfc2898)
 
 ### X25519
 
-X25519 is a key agreement algorithm 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")}}.
+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

From f596ae67dd563a16cefe61f94b88a30708131663 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Fri, 2 Aug 2024 17:58:11 +1000
Subject: [PATCH 17/33] Fix missing . in EcdhKeyDeriveParams

---
 files/en-us/web/api/ecdhkeyderiveparams/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/api/ecdhkeyderiveparams/index.md b/files/en-us/web/api/ecdhkeyderiveparams/index.md
index f751b04905e4827..5484b58dd70163f 100644
--- a/files/en-us/web/api/ecdhkeyderiveparams/index.md
+++ b/files/en-us/web/api/ecdhkeyderiveparams/index.md
@@ -17,7 +17,7 @@ The parameters for ECDH `deriveKey()` therefore include the other entity's publi
 
 - `name`
   - : A string.
-    This should be set to `ECDH` or `X25519`, depending on the algorithm used
+    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.
 

From e3f277452c78ae6be0937fb52b4568857f928899 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Fri, 2 Aug 2024 18:01:58 +1000
Subject: [PATCH 18/33] Add note to SubtleCrptyo index about the reason for the
 name

---
 files/en-us/web/api/subtlecrypto/index.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/files/en-us/web/api/subtlecrypto/index.md b/files/en-us/web/api/subtlecrypto/index.md
index 5501242fe21e164..e3fe2ae772a1821 100644
--- a/files/en-us/web/api/subtlecrypto/index.md
+++ b/files/en-us/web/api/subtlecrypto/index.md
@@ -9,6 +9,8 @@ browser-compat: api.SubtleCrypto
 
 The **`SubtleCrypto`** interface of the [Web Crypto API](/en-US/docs/Web/API/Web_Crypto_API) provides a number of low-level cryptographic functions.
 
+The interface name includes the term "subtle" to indicate that many of its algorithms have subtle usage requirements, and hence that it must be used carefully in order to provide suitable security guarantees.
+
 An instance of `SubtleCrypto` is available as the {{domxref("Crypto.subtle", "subtle")}} property of the {{domxref("Crypto")}} interface, which in turn is available in windows through the {{domxref("Window.crypto")}} property and in workers through the {{domxref("WorkerGlobalScope.crypto")}} property.
 
 > [!WARNING]

From 0c6d31d276a458b4a803185104863b8f43ec8f10 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Fri, 2 Aug 2024 18:05:02 +1000
Subject: [PATCH 19/33] Remove duplicate AES in generatekey

---
 files/en-us/web/api/subtlecrypto/generatekey/index.md | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/files/en-us/web/api/subtlecrypto/generatekey/index.md b/files/en-us/web/api/subtlecrypto/generatekey/index.md
index a519bbbed68d86d..75dbf3c67ca917e 100644
--- a/files/en-us/web/api/subtlecrypto/generatekey/index.md
+++ b/files/en-us/web/api/subtlecrypto/generatekey/index.md
@@ -28,9 +28,6 @@ generateKey(algorithm, extractable, keyUsages)
     - For [ECDSA](/en-US/docs/Web/API/SubtleCrypto/sign#ecdsa) or [ECDH](/en-US/docs/Web/API/SubtleCrypto/deriveKey#ecdh):
       pass an [`EcKeyGenParams`](/en-US/docs/Web/API/EcKeyGenParams) object.
     - 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.

From 38e21a861c4c62f7ab12ab2ed3bb22b73f2871ba Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Fri, 2 Aug 2024 18:07:04 +1000
Subject: [PATCH 20/33] Fix Ed25519 case typo

---
 files/en-us/web/api/subtlecrypto/unwrapkey/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/api/subtlecrypto/unwrapkey/index.md b/files/en-us/web/api/subtlecrypto/unwrapkey/index.md
index ea0876a2cd27481..de8fb7623fac0d4 100644
--- a/files/en-us/web/api/subtlecrypto/unwrapkey/index.md
+++ b/files/en-us/web/api/subtlecrypto/unwrapkey/index.md
@@ -62,7 +62,7 @@ unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgo, unwrappedKeyAlgo, extra
     - 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 the string identifying the algorithm or an object of the form `{ "name": ALGORITHM }`, where `ALGORITHM` is the name of the algorithm.
-    - For [ED25519](#ed25519): Pass an object of the form `{ "name": "Ed25519" }`.
+    - For [Ed25519](#ed25519): Pass an object of the form `{ "name": "Ed25519" }`.
     - For [X25519](/en-US/docs/Web/API/SubtleCrypto/sign#ed25519): Pass an object of the form: `{name: 'X25519'}`.
 - `extractable`
   - : A boolean indicating whether it will be possible to export the key

From 7b7f25c4259b50e1b2baa27ecd40cb949b2baab7 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Fri, 2 Aug 2024 18:09:17 +1000
Subject: [PATCH 21/33] Remove last instance of high performance when
 describing algorithms

---
 files/en-us/web/api/subtlecrypto/sign/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/api/subtlecrypto/sign/index.md b/files/en-us/web/api/subtlecrypto/sign/index.md
index 1c4c58acd4a76cb..14169d99192f6f5 100644
--- a/files/en-us/web/api/subtlecrypto/sign/index.md
+++ b/files/en-us/web/api/subtlecrypto/sign/index.md
@@ -94,7 +94,7 @@ It can be a good choice however when the signer and verifier are the same entity
 
 ### Ed25519
 
-Ed25519 is a high-performance digital signature algorithm 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")}}.
+Ed25519 is a digital signature algorithm 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")}}.
 
 This algorithm is used in {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
 Unlike some other such systems (RSASSA-PKCS1-v1_5, RSA-PSS, and ECDSA), it does not pass in a [digest](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) of the message for signing.

From 3eba474fc44ed485c00b45cea1674841c21f10c7 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Fri, 2 Aug 2024 18:17:22 +1000
Subject: [PATCH 22/33] Apply suggestions from code review

Co-authored-by: wbamberg 
Co-authored-by: Brian Thomas Smith 
---
 files/en-us/web/api/subtlecrypto/sign/index.md   | 12 +++++-------
 files/en-us/web/api/subtlecrypto/verify/index.md |  2 +-
 2 files changed, 6 insertions(+), 8 deletions(-)

diff --git a/files/en-us/web/api/subtlecrypto/sign/index.md b/files/en-us/web/api/subtlecrypto/sign/index.md
index 14169d99192f6f5..7ab1d20483cce8d 100644
--- a/files/en-us/web/api/subtlecrypto/sign/index.md
+++ b/files/en-us/web/api/subtlecrypto/sign/index.md
@@ -208,12 +208,12 @@ let signature = await window.crypto.subtle.sign("HMAC", key, encoded);
 
 ### Ed25519 (key generation, signing, and verification)
 
-This code generates an Ed25519 signing key pair, uses the private key to sign the (encoded) contents of a text ``, and then verifies the signature using the public key.
+This code generates an Ed25519 signing key pair, uses the private key to sign the (encoded) contents of a text [``](/en-US/docs/Web/HTML/Element/input/text), and then verifies the signature using the public key.
 It is derived from [this source code on GitHub.](https://github.com/mdn/dom-examples/blob/main/web-crypto/sign-verify/ed25519.js), which you can [run live here](https://mdn.github.io/dom-examples/web-crypto/sign-verify/).
 
 #### HTML
 
-The HTML defines an ``, containing the text to be signed, and a button that starts the operation to create keys, sign the text and then verify the signature.
+The HTML defines an `` element containing the text to be signed, and a button that starts the operation to create keys, sign the text and then verify the signature.
 
 ```html
 
@@ -250,8 +250,8 @@ function log(text) {
 
 #### JavaScript
 
-The JavaScript first gets the `button` and message `input` elements, and then adds a listener for the `click` event on the button.
-The event handler that clears the log and runs the other operations passing the content of the `input` element.
+The JavaScript first gets the `#sign-button` and `#message` {{HTMLElement("input")}} elements, then adds a listener for the `click` event on the button.
+The event handler clears the log and runs the other operations passing the content of the `` element.
 
 ```js
 const button = document.querySelector("#sign-button");
@@ -266,9 +266,8 @@ button.addEventListener("click", () => {
 });
 ```
 
-The code below has several parts.
 First it generates keys using the Ed25519 algorithm, then it encodes text and signs that text using the private key.
-Then if calls {{domxref("SubtleCrypto.verify()")}} with the public key to verify the signature.
+Finally it calls {{domxref("SubtleCrypto.verify()")}} with the public key to verify the signature.
 
 ```js
 async function test(data) {
@@ -326,7 +325,6 @@ async function test(data) {
 
 #### Result
 
-The information about the created keys is logged below (or an error string if the browser does not allow the key to be created).
 
 {{EmbedLiveSample("Ed25519 (key generation, signing, and verification)", "100%", "170px")}}
 
diff --git a/files/en-us/web/api/subtlecrypto/verify/index.md b/files/en-us/web/api/subtlecrypto/verify/index.md
index 137e11674c60226..1be71bfb4a38853 100644
--- a/files/en-us/web/api/subtlecrypto/verify/index.md
+++ b/files/en-us/web/api/subtlecrypto/verify/index.md
@@ -225,7 +225,7 @@ async function verifyMessage(key) {
 
 The [Ed25519 live example](/en-US/docs/Web/API/SubtleCrypto/sign#ed25519_key_generation_signing_and_verification) in `SubtleCrypto.sign()` shows how to generate public and private keys, use the private key to sign some data, and then use the public key to verify the signature.
 
-The code below shows the part that is relevant to verifying the signature using the public key and encoded data:
+The excerpt below shows the part that is relevant for verifying the signature using the public key and encoded data:
 
 ```js
 // Verify the signature using the public key

From d1529755c25b675691ff4ad404e57a96e56ee92b Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Fri, 2 Aug 2024 19:31:04 +1000
Subject: [PATCH 23/33] Fix sign example overflow

---
 files/en-us/web/api/subtlecrypto/sign/index.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/files/en-us/web/api/subtlecrypto/sign/index.md b/files/en-us/web/api/subtlecrypto/sign/index.md
index 7ab1d20483cce8d..9655afe2d11f23a 100644
--- a/files/en-us/web/api/subtlecrypto/sign/index.md
+++ b/files/en-us/web/api/subtlecrypto/sign/index.md
@@ -233,8 +233,8 @@ The HTML defines an `` element containing the text to be signed, and a bu
 
 ```css hidden
 #log {
-  height: 110px;
-  overflow: scroll;
+  height: 120px;
+  overflow: scroll-behavior: auto;
   padding: 0.5rem;
   border: 1px solid black;
 }
@@ -326,7 +326,7 @@ async function test(data) {
 #### Result
 
 
-{{EmbedLiveSample("Ed25519 (key generation, signing, and verification)", "100%", "170px")}}
+{{EmbedLiveSample("Ed25519 (key generation, signing, and verification)", "100", "200px")}}
 
 ## Specifications
 

From 612e1be7a9ff4794688e0813cb6d5b0caf82474f Mon Sep 17 00:00:00 2001
From: wbamberg 
Date: Fri, 2 Aug 2024 12:19:28 -0700
Subject: [PATCH 24/33] Update files/en-us/web/api/subtlecrypto/sign/index.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
---
 files/en-us/web/api/subtlecrypto/sign/index.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/files/en-us/web/api/subtlecrypto/sign/index.md b/files/en-us/web/api/subtlecrypto/sign/index.md
index 9655afe2d11f23a..9379b8d6806554b 100644
--- a/files/en-us/web/api/subtlecrypto/sign/index.md
+++ b/files/en-us/web/api/subtlecrypto/sign/index.md
@@ -325,7 +325,6 @@ async function test(data) {
 
 #### Result
 
-
 {{EmbedLiveSample("Ed25519 (key generation, signing, and verification)", "100", "200px")}}
 
 ## Specifications

From ce31bd21cdeab2023c00b41315e0165a48903c5f Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Mon, 5 Aug 2024 11:39:24 +1000
Subject: [PATCH 25/33] deriveKey - separate algos by key-derivation/agreement
 heading

---
 .../web/api/subtlecrypto/derivekey/index.md   | 22 +++++++++++--------
 1 file changed, 13 insertions(+), 9 deletions(-)

diff --git a/files/en-us/web/api/subtlecrypto/derivekey/index.md b/files/en-us/web/api/subtlecrypto/derivekey/index.md
index a2962a8af46d746..7b8ff8de0cf9f23 100644
--- a/files/en-us/web/api/subtlecrypto/derivekey/index.md
+++ b/files/en-us/web/api/subtlecrypto/derivekey/index.md
@@ -74,14 +74,9 @@ The promise is rejected when one of the following exceptions are encountered:
 
 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.
@@ -91,7 +86,7 @@ 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.
@@ -99,7 +94,16 @@ The more times the process is repeated, the more computationally expensive key d
 
 PBKDF2 is specified in [RFC 2898](https://datatracker.ietf.org/doc/html/rfc2898).
 
-### X25519
+### 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")}}.

From de527746fc85dbb7f5b36504404820a77520c8cf Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Mon, 5 Aug 2024 11:43:16 +1000
Subject: [PATCH 26/33] No one expects the spanish inquisition

---
 files/en-us/web/api/subtlecrypto/derivekey/index.md | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/files/en-us/web/api/subtlecrypto/derivekey/index.md b/files/en-us/web/api/subtlecrypto/derivekey/index.md
index 7b8ff8de0cf9f23..ebfbe62fdefc0b9 100644
--- a/files/en-us/web/api/subtlecrypto/derivekey/index.md
+++ b/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
 

From 02754740ab812954d92f509905a4f1c8349130e8 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Mon, 5 Aug 2024 12:04:08 +1000
Subject: [PATCH 27/33] Apply suggestions from code review

Co-authored-by: wbamberg 
---
 .../en-us/web/api/ecdhkeyderiveparams/index.md |  2 +-
 .../web/api/subtlecrypto/derivekey/index.md    |  2 +-
 .../web/api/subtlecrypto/generatekey/index.md  | 18 +++++++++---------
 .../web/api/subtlecrypto/importkey/index.md    |  4 ++--
 files/en-us/web/api/subtlecrypto/index.md      |  2 +-
 5 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/files/en-us/web/api/ecdhkeyderiveparams/index.md b/files/en-us/web/api/ecdhkeyderiveparams/index.md
index 5484b58dd70163f..ec499a7dcdbd662 100644
--- a/files/en-us/web/api/ecdhkeyderiveparams/index.md
+++ b/files/en-us/web/api/ecdhkeyderiveparams/index.md
@@ -31,7 +31,7 @@ See the examples for {{domxref("SubtleCrypto.deriveKey()")}} and {{domxref("Subt
 
 ## Browser compatibility
 
-Browsers that support the "ECDH" and "X25519" 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
 
diff --git a/files/en-us/web/api/subtlecrypto/derivekey/index.md b/files/en-us/web/api/subtlecrypto/derivekey/index.md
index ebfbe62fdefc0b9..074604186857e0b 100644
--- a/files/en-us/web/api/subtlecrypto/derivekey/index.md
+++ b/files/en-us/web/api/subtlecrypto/derivekey/index.md
@@ -31,7 +31,7 @@ deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)
     - 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.
+    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:
diff --git a/files/en-us/web/api/subtlecrypto/generatekey/index.md b/files/en-us/web/api/subtlecrypto/generatekey/index.md
index 75dbf3c67ca917e..6ae16354220600f 100644
--- a/files/en-us/web/api/subtlecrypto/generatekey/index.md
+++ b/files/en-us/web/api/subtlecrypto/generatekey/index.md
@@ -42,21 +42,21 @@ generateKey(algorithm, extractable, keyUsages)
     Possible values for array elements are:
 
     - `encrypt`
-      - : The key may be used to {{domxref("SubtleCrypto.encrypt()", "encrypt")}} messages.
+      - : The key may be used to {{domxref("SubtleCrypto.encrypt()", "encrypt", "", "nocode")}} messages.
     - `decrypt`
-      - : The key may be used to {{domxref("SubtleCrypto.decrypt()", "decrypt")}} messages.
+      - : The key may be used to {{domxref("SubtleCrypto.decrypt()", "decrypt", "", "nocode")}} messages.
     - `sign`
-      - : The key may be used to {{domxref("SubtleCrypto.sign()", "sign")}} messages.
+      - : The key may be used to {{domxref("SubtleCrypto.sign()", "sign", "", "nocode")}} messages.
     - `verify`
-      - : The key may be used to {{domxref("SubtleCrypto.verify()", "verify")}} signatures.
+      - : The key may be used to {{domxref("SubtleCrypto.verify()", "verify", "", "nocode")}} signatures.
     - `deriveKey`
-      - : The key may be used in {{domxref("SubtleCrypto.deriveKey()", "deriving a new key")}}.
+      - : The key may be used in {{domxref("SubtleCrypto.deriveKey()", "deriving a new key", "", "nocode")}}.
     - `deriveBits`
-      - : The key may be used in {{domxref("SubtleCrypto.deriveBits()", "deriving bits")}}.
+      - : The key may be used in {{domxref("SubtleCrypto.deriveBits()", "deriving bits", "", "nocode")}}.
     - `wrapKey`
-      - : The key may be used to {{domxref("SubtleCrypto.wrapKey()", "wrap a key")}}.
+      - : The key may be used to {{domxref("SubtleCrypto.wrapKey()", "wrap a key", "", "nocode")}}.
     - `unwrapKey`
-      - : The key may be used to {{domxref("SubtleCrypto.unwrapKey()", "unwrap a key")}}.
+      - : The key may be used to {{domxref("SubtleCrypto.unwrapKey()", "unwrap a key", "", "nocode")}}.
 
 ### Return value
 
@@ -145,7 +145,7 @@ let key = await window.crypto.subtle.generateKey(
 ### Ed25519 key generation
 
 This code generates an Ed25519 signing key pair.
-It is derived from [this source code on GitHub.](https://github.com/mdn/dom-examples/blob/main/web-crypto/sign-verify/ed25519.js), which you can [run live here](https://mdn.github.io/dom-examples/web-crypto/sign-verify/).
+It is derived from [this source code on GitHub](https://github.com/mdn/dom-examples/blob/main/web-crypto/sign-verify/ed25519.js), which you can [run live here](https://mdn.github.io/dom-examples/web-crypto/sign-verify/).
 
 ```html hidden
 

diff --git a/files/en-us/web/api/subtlecrypto/importkey/index.md b/files/en-us/web/api/subtlecrypto/importkey/index.md
index a09f05f560ae36b..82ea5f780d88bf3 100644
--- a/files/en-us/web/api/subtlecrypto/importkey/index.md
+++ b/files/en-us/web/api/subtlecrypto/importkey/index.md
@@ -44,8 +44,8 @@ importKey(format, keyData, algorithm, extractable, keyUsages)
     - 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), and [AES-KW](/en-US/docs/Web/API/SubtleCrypto/wrapKey#aes-kw):
       pass the string identifying the algorithm or an object of the form `{ name: ALGORITHM }`, where `ALGORITHM` is the name of the algorithm.
-    - For [PBKDF2](/en-US/docs/Web/API/SubtleCrypto/deriveKey#pbkdf2): pass the string `PBKDF2`.
-    - For [HKDF](/en-US/docs/Web/API/SubtleCrypto/deriveKey#hkdf): pass the string `HKDF`.
+    - For [PBKDF2](/en-US/docs/Web/API/SubtleCrypto/deriveKey#pbkdf2): pass the string `PBKDF2` or an object of the form `{ name: "PBKDF2" }`.
+    - For [HKDF](/en-US/docs/Web/API/SubtleCrypto/deriveKey#hkdf): pass the string `HKDF` or an object of the form `{ name: "HKDF" }`.
     - For [Ed25519](/en-US/docs/Web/API/SubtleCrypto/sign#ed25519): pass the string `Ed25519` or an object of the form `{ name: "Ed25519" }`.
     - For [X25519](/en-US/docs/Web/API/SubtleCrypto/deriveKey#x25519): pass the string `X25519` or an object of the form `{ name: "X25519" }`.
 - `extractable`
diff --git a/files/en-us/web/api/subtlecrypto/index.md b/files/en-us/web/api/subtlecrypto/index.md
index e3fe2ae772a1821..708d2a098b9fc19 100644
--- a/files/en-us/web/api/subtlecrypto/index.md
+++ b/files/en-us/web/api/subtlecrypto/index.md
@@ -129,7 +129,7 @@ The table below summarizes which algorithms are suitable for which cryptographic
   
   
     
-      RSASSA-PKCS1-v1_5>
+      RSASSA-PKCS1-v1_5
       ✓
       
       

From 9a03b1df166a711c5417b53ff7e965485f557e4a Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Mon, 5 Aug 2024 12:21:20 +1000
Subject: [PATCH 28/33] sign() - add back preamble for algos

---
 .../en-us/web/api/subtlecrypto/sign/index.md  | 25 +++++++++++++------
 1 file changed, 17 insertions(+), 8 deletions(-)

diff --git a/files/en-us/web/api/subtlecrypto/sign/index.md b/files/en-us/web/api/subtlecrypto/sign/index.md
index 9379b8d6806554b..5bc81d00b1b509d 100644
--- a/files/en-us/web/api/subtlecrypto/sign/index.md
+++ b/files/en-us/web/api/subtlecrypto/sign/index.md
@@ -48,7 +48,16 @@ The promise is rejected when the following exception is encountered:
 
 ## Supported algorithms
 
-The Web Crypto API provides the following algorithms that can be used for signing (and signature verification):
+The Web Crypto API provides the following algorithms that can be used for signing and signature verification.
+
+RSASSA-PKCS1-v1_5, RSA-PSS, and ECDSA, are {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
+These systems all use a [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) to hash the message to a short fixed size before signing.
+Except for ECDSA (for which it is passed in the `algorithm` object), the choice of digest algorithm is passed into the {{domxref("SubtleCrypto.generateKey()", "generateKey()")}} or {{domxref("SubtleCrypto.importKey()", "importKey()")}} functions.
+Ed25519 is also a public-key cryptosystem, but does not use a digest algorithm.
+
+The HMAC algorithm differs from the others in that it is not a public-key cryptosystem: it uses the same algorithm and key for signing and for verification.
+This means that the verification key must be kept secret, which in turn means that this algorithm is not suitable for many signature use cases.
+It can be a good choice however when the signer and verifier are the same entity.
 
 ### RSASSA-PKCS1-v1_5
 
@@ -82,6 +91,13 @@ These values are concatenated together in this order.
 
 This encoding was also proposed by the [IEEE 1363-2000](https://standards.ieee.org/ieee/1363/2049/) standard, and is sometimes referred to as the IEEE P1363 format. It differs from the [X.509](https://www.itu.int/rec/T-REC-X.509) signature structure, which is the default format produced by some tools and libraries such as [OpenSSL](https://www.openssl.org).
 
+### Ed25519
+
+Ed25519 is a digital signature algorithm 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")}}.
+
+This algorithm is used in {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
+Unlike some other such systems (RSASSA-PKCS1-v1_5, RSA-PSS, and ECDSA), it does not pass in a [digest](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) of the message for signing.
+
 ### HMAC
 
 The HMAC algorithm calculates and verifies hash-based message authentication codes according to the [FIPS 198-1 standard](https://csrc.nist.gov/csrc/media/publications/fips/198/1/final/documents/fips-198-1_final.pdf).
@@ -92,13 +108,6 @@ The digest algorithm to use is specified in the [`HmacKeyGenParams`](/en-US/docs
 The HMAC algorithm uses the same algorithm and key for signing and for verification: this means that the verification key must be kept secret, which in turn means that this algorithm is not suitable for many signature use cases.
 It can be a good choice however when the signer and verifier are the same entity.
 
-### Ed25519
-
-Ed25519 is a digital signature algorithm 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")}}.
-
-This algorithm is used in {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
-Unlike some other such systems (RSASSA-PKCS1-v1_5, RSA-PSS, and ECDSA), it does not pass in a [digest](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) of the message for signing.
-
 ## Examples
 
 > [!NOTE]

From f12a884daa47c5d101883ebc0800143e6b3161db Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Mon, 5 Aug 2024 13:57:49 +1000
Subject: [PATCH 29/33] Fix example scrolling + add run button to generate()

---
 .../web/api/subtlecrypto/generatekey/index.md | 25 +++++++++++++++----
 .../en-us/web/api/subtlecrypto/sign/index.md  |  5 +++-
 2 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/files/en-us/web/api/subtlecrypto/generatekey/index.md b/files/en-us/web/api/subtlecrypto/generatekey/index.md
index 6ae16354220600f..f1402e3b9ce4e12 100644
--- a/files/en-us/web/api/subtlecrypto/generatekey/index.md
+++ b/files/en-us/web/api/subtlecrypto/generatekey/index.md
@@ -148,13 +148,16 @@ This code generates an Ed25519 signing key pair.
 It is derived from [this source code on GitHub](https://github.com/mdn/dom-examples/blob/main/web-crypto/sign-verify/ed25519.js), which you can [run live here](https://mdn.github.io/dom-examples/web-crypto/sign-verify/).
 
 ```html hidden
-

+
+
Click "Run" button

 ```
 
 ```css hidden
 #log {
   height: 170px;
-  overflow: scroll;
+  white-space: pre-wrap; /* wrap pre blocks */
+  overflow-wrap: break-word; /* break on words */
+  overflow-y: auto;
   padding: 0.5rem;
   border: 1px solid black;
 }
@@ -173,7 +176,21 @@ function log(text) {
 Code for generating a key pair using the `Ed25519` algorithm and logging the information in each key is shown below.
 Note that the code is run in a `try..catch` block because not all browsers support this algorithm.
 
+The JavaScript first gets the `#sign-button` and `#message` {{HTMLElement("input")}} elements, then adds a listener for the `click` event on the button.
+The event handler clears the log and runs the other operations passing the content of the `` element.
+
 ```js
+const button = document.querySelector("#run-button");
+const input = document.querySelector("#log");
+
+button.addEventListener("click", () => {
+  // Clear log
+  logElement.innerText = "";
+  logElement.scrollTop = logElement.scrollHeight;
+  // Run test
+  test();
+});
+
 async function test() {
   try {
     // Create a key pair and use destructuring assignment to assign to variables
@@ -200,15 +217,13 @@ async function test() {
     log(error);
   }
 }
-
-test();
 ```
 
 #### Result
 
 The information about the created keys is logged below (or an error string if the browser does not allow the key to be created).
 
-{{EmbedLiveSample("Ed25519", "100%", "230px")}}
+{{EmbedLiveSample("Ed25519", "100%", "240px")}}
 
 ## Specifications
 
diff --git a/files/en-us/web/api/subtlecrypto/sign/index.md b/files/en-us/web/api/subtlecrypto/sign/index.md
index 5bc81d00b1b509d..ffb7c589b22a517 100644
--- a/files/en-us/web/api/subtlecrypto/sign/index.md
+++ b/files/en-us/web/api/subtlecrypto/sign/index.md
@@ -243,7 +243,9 @@ The HTML defines an `` element containing the text to be signed, and a bu
 ```css hidden
 #log {
   height: 120px;
-  overflow: scroll-behavior: auto;
+  white-space: pre-wrap; /* wrap pre blocks */
+  overflow-wrap: break-word; /* break on words */
+  overflow-y: auto;
   padding: 0.5rem;
   border: 1px solid black;
 }
@@ -297,6 +299,7 @@ async function test(data) {
     // Encode data prior to signing
     const encoder = new TextEncoder();
     encodedData = encoder.encode(data);
+
     log(`encodedData: ${encodedData}`);
 
     // Sign the data using the private key.

From 22daadc094403844fd117c87f7e7066cdc435321 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Mon, 5 Aug 2024 14:09:30 +1000
Subject: [PATCH 30/33] Truncate encoded data

---
 files/en-us/web/api/subtlecrypto/sign/index.md | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/files/en-us/web/api/subtlecrypto/sign/index.md b/files/en-us/web/api/subtlecrypto/sign/index.md
index ffb7c589b22a517..d4f4c98a11722c1 100644
--- a/files/en-us/web/api/subtlecrypto/sign/index.md
+++ b/files/en-us/web/api/subtlecrypto/sign/index.md
@@ -300,7 +300,12 @@ async function test(data) {
     const encoder = new TextEncoder();
     encodedData = encoder.encode(data);
 
-    log(`encodedData: ${encodedData}`);
+    // Log the first part of the encoded data
+    const shorterEncodedBuffer = new Uint8Array(encodedData.buffer, 0, 14);
+    log(
+      `encodedData: ${shorterEncodedBuffer}...[${encodedData.byteLength} bytes total]`,
+    );
+    //log(`encodedData: ${encodedData}`);
 
     // Sign the data using the private key.
     const signature = await crypto.subtle.sign(
@@ -312,7 +317,7 @@ async function test(data) {
     );
 
     // Log the first part of the signature data
-    const signatureBuffer = new Uint8Array(signature, 0, 8);
+    const signatureBuffer = new Uint8Array(signature, 0, 14);
     log(
       `signature: ${signatureBuffer}...[${signature.byteLength} bytes total]`,
     );

From 1e3139adb1f955bcc1e0fe0ba74df3c509b03c25 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Tue, 6 Aug 2024 11:22:13 +1000
Subject: [PATCH 31/33] Update files/en-us/web/api/subtlecrypto/sign/index.md

Co-authored-by: wbamberg 
---
 files/en-us/web/api/subtlecrypto/sign/index.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/files/en-us/web/api/subtlecrypto/sign/index.md b/files/en-us/web/api/subtlecrypto/sign/index.md
index 8b941a892f15da1..62e897f902350fe 100644
--- a/files/en-us/web/api/subtlecrypto/sign/index.md
+++ b/files/en-us/web/api/subtlecrypto/sign/index.md
@@ -50,10 +50,12 @@ The promise is rejected when the following exception is encountered:
 
 The Web Crypto API provides the following algorithms that can be used for signing and signature verification.
 
-RSASSA-PKCS1-v1_5, RSA-PSS, and ECDSA, are {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
+RSASSA-PKCS1-v1_5, RSA-PSS, ECDSA, and Ed25519 are {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
 These systems all use a [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) to hash the message to a short fixed size before signing.
-Except for ECDSA (for which it is passed in the `algorithm` object), the choice of digest algorithm is passed into the {{domxref("SubtleCrypto.generateKey()", "generateKey()")}} or {{domxref("SubtleCrypto.importKey()", "importKey()")}} functions.
-Ed25519 is also a public-key cryptosystem, but does not use a digest algorithm.
+
+- For RSASSA-PKCS1-v1_5 and RSA-PSS, the choice of digest algorithm is passed into the {{domxref("SubtleCrypto.generateKey()", "generateKey()")}} or {{domxref("SubtleCrypto.importKey()", "importKey()")}} functions.
+- For ECDSA the choice of digest algorithm is included in the `algorithm` parameter passed into the `sign()` function.
+- For Ed25519 the digest algorithm is always SHA-512.
 
 The HMAC algorithm differs from the others in that it is not a public-key cryptosystem: it uses the same algorithm and key for signing and for verification.
 This means that the verification key must be kept secret, which in turn means that this algorithm is not suitable for many signature use cases.

From b6f9f9ab85ca042c74e2628333025e0dffd874aa Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Tue, 6 Aug 2024 11:28:26 +1000
Subject: [PATCH 32/33] Apply suggestions from code review

---
 files/en-us/web/api/subtlecrypto/sign/index.md | 16 ----------------
 1 file changed, 16 deletions(-)

diff --git a/files/en-us/web/api/subtlecrypto/sign/index.md b/files/en-us/web/api/subtlecrypto/sign/index.md
index 62e897f902350fe..468c6c91c636278 100644
--- a/files/en-us/web/api/subtlecrypto/sign/index.md
+++ b/files/en-us/web/api/subtlecrypto/sign/index.md
@@ -63,29 +63,16 @@ It can be a good choice however when the signer and verifier are the same entity
 
 ### RSASSA-PKCS1-v1_5
 
-The SASSA-PKCS1-v1_5 algorithm is used in {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
-Systems that use this algorithm use a [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) to hash the message to a short fixed size before signing.
-The choice of digest algorithm is passed into the {{domxref("SubtleCrypto.generateKey()", "generateKey()")}} or {{domxref("SubtleCrypto.importKey()", "importKey()")}} functions.
-
 The RSASSA-PKCS1-v1_5 algorithm is specified in [RFC 3447](https://datatracker.ietf.org/doc/html/rfc3447).
 
 ### RSA-PSS
 
-The RSA-PSS algorithm is used in {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
-Systems that use this algorithm use a [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) to hash the message to a short fixed size before signing.
-The choice of digest algorithm is passed into the {{domxref("SubtleCrypto.generateKey()", "generateKey()")}} or {{domxref("SubtleCrypto.importKey()", "importKey()")}} functions.
-
 The algorithm is specified in [RFC 3447](https://datatracker.ietf.org/doc/html/rfc3447).
 
 It's different from RSASSA-PKCS1-v1_5 in that it incorporates a random salt in the signature operation, so the same message signed with the same key will not result in the same signature each time. An extra property, defining the salt length, is passed into the {{domxref("SubtleCrypto.sign()", "sign()")}} and {{domxref("SubtleCrypto.verify()", "verify()")}} functions when they are invoked.
 
 ### ECDSA
 
-This algorithm is used in {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
-Systems that use this algorithm use a [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) to hash the message to a short fixed size before signing.
-This
-For ECDSA the choice of digest algorithm is passed as part of the `algorithm` object, a {{domxref("EcdsaParams")}}, when calling {{domxref("SubtleCrypto.sign()")}}.
-
 ECDSA (Elliptic Curve Digital Signature Algorithm) is a variant of the Digital Signature Algorithm, specified in [FIPS-186](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf), that uses Elliptic Curve Cryptography ([RFC 6090](https://datatracker.ietf.org/doc/html/rfc6090)).
 
 Signatures are encoded as the `s1` and `s2` values specified in RFC 6090 (known respectively as `r` and `s` in [RFC 4754](https://datatracker.ietf.org/doc/html/rfc4754#section-3)), each in big-endian byte arrays, with their length the bit size of the curve rounded up to a whole number of bytes.
@@ -97,9 +84,6 @@ This encoding was also proposed by the [IEEE 1363-2000](https://standards.ieee.o
 
 Ed25519 is a digital signature algorithm 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")}}.
 
-This algorithm is used in {{Glossary("public-key cryptography", "public-key cryptosystems")}} that use the private key for signing and the public key for verification.
-Unlike some other such systems (RSASSA-PKCS1-v1_5, RSA-PSS, and ECDSA), it does not pass in a [digest](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) of the message for signing.
-
 ### HMAC
 
 The HMAC algorithm calculates and verifies hash-based message authentication codes according to the [FIPS 198-1 standard](https://csrc.nist.gov/csrc/media/publications/fips/198/1/final/documents/fips-198-1_final.pdf).

From 947664f09edb57f645f16b20a9c08cc1acb27284 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Tue, 6 Aug 2024 11:30:44 +1000
Subject: [PATCH 33/33] Apply suggestions from code review

---
 files/en-us/web/api/subtlecrypto/sign/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/api/subtlecrypto/sign/index.md b/files/en-us/web/api/subtlecrypto/sign/index.md
index 468c6c91c636278..0cd8f14501ed62f 100644
--- a/files/en-us/web/api/subtlecrypto/sign/index.md
+++ b/files/en-us/web/api/subtlecrypto/sign/index.md
@@ -67,7 +67,7 @@ The RSASSA-PKCS1-v1_5 algorithm is specified in [RFC 3447](https://datatracker.i
 
 ### RSA-PSS
 
-The algorithm is specified in [RFC 3447](https://datatracker.ietf.org/doc/html/rfc3447).
+The RSA-PSS algorithm is specified in [RFC 3447](https://datatracker.ietf.org/doc/html/rfc3447).
 
 It's different from RSASSA-PKCS1-v1_5 in that it incorporates a random salt in the signature operation, so the same message signed with the same key will not result in the same signature each time. An extra property, defining the salt length, is passed into the {{domxref("SubtleCrypto.sign()", "sign()")}} and {{domxref("SubtleCrypto.verify()", "verify()")}} functions when they are invoked.