From 12c25a14156d92c2b8e619e7808781b873644822 Mon Sep 17 00:00:00 2001
From: Syed Moiz Ali <dev.syedmoizali@gmail.com>
Date: Tue, 16 Jun 2026 14:25:16 +0530
Subject: [PATCH] Document maximum deriveBits length for ECDH curves
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Updates documentation on EcdhPrivateKey.deriveBits to include
the maximum number of bits that can be derived for each curve:

  * EllipticCurve.p256 — up to 256 bits
  * EllipticCurve.p384 — up to 384 bits
  * EllipticCurve.p521 — up to 528 bits

Also adds test coverage for all three curves at their maximum
derive lengths in the ECDH test runner.

Fixes #130
---
 lib/src/testing/webcrypto/ecdh.dart   | 21 ++++++++++++++++++++-
 lib/src/webcrypto/webcrypto.ecdh.dart |  9 +++++----
 2 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/lib/src/testing/webcrypto/ecdh.dart b/lib/src/testing/webcrypto/ecdh.dart
index d7c99cb3..d8202aa0 100644
--- a/lib/src/testing/webcrypto/ecdh.dart
+++ b/lib/src/testing/webcrypto/ecdh.dart
@@ -59,13 +59,32 @@ final runner = TestRunner.asymmetric<EcdhPrivateKey, EcdhPublicKey>(
 );
 
 void main() async {
-  log('generate ECDH test case');
+  log('generate ECDH test cases');
+
+  // P-256: up to 256 bits (32 bytes)
   await runner.generate(
     generateKeyParams: {'curve': curveToJson(EllipticCurve.p256)},
     importKeyParams: {'curve': curveToJson(EllipticCurve.p256)},
     deriveParams: {},
     maxDeriveLength: 32,
   );
+
+  // P-384: up to 384 bits (48 bytes)
+  await runner.generate(
+    generateKeyParams: {'curve': curveToJson(EllipticCurve.p384)},
+    importKeyParams: {'curve': curveToJson(EllipticCurve.p384)},
+    deriveParams: {},
+    maxDeriveLength: 48,
+  );
+
+  // P-521: up to 528 bits (66 bytes)
+  await runner.generate(
+    generateKeyParams: {'curve': curveToJson(EllipticCurve.p521)},
+    importKeyParams: {'curve': curveToJson(EllipticCurve.p521)},
+    deriveParams: {},
+    maxDeriveLength: 66,
+  );
+
   log('--------------------');
 
   await runner.tests().runTests();
diff --git a/lib/src/webcrypto/webcrypto.ecdh.dart b/lib/src/webcrypto/webcrypto.ecdh.dart
index 064dbb17..ebb91020 100644
--- a/lib/src/webcrypto/webcrypto.ecdh.dart
+++ b/lib/src/webcrypto/webcrypto.ecdh.dart
@@ -206,15 +206,16 @@ final class EcdhPrivateKey {
   /// two parties.
   ///
   /// [length] specifies the length of the derived secret in bits.
+  /// The maximum length depends on the [EllipticCurve] used:
+  ///   * [EllipticCurve.p256] — up to 256 bits.
+  ///   * [EllipticCurve.p384] — up to 384 bits.
+  ///   * [EllipticCurve.p521] — up to 528 bits.
+  ///
   /// [publicKey] is [EcdhPublicKey] from the other party's ECDH key pair.
   ///
   /// Returns a [Uint8List] containing the derived shared secret.
   ///
   /// {@macro EcdhPrivateKey:example}
-  // Note some webcrypto implementations (chrome, not firefox) supports passing
-  // null for length (in this primitive). However, you can always know the right
-  // length from the curve. Note p512 can provide up to: 528 bits!!!
-  //
   // See: https://www.rfc-editor.org/rfc/rfc6090#section-4
   // Notice that this is not uniformly distributed, see also:
   // https://www.rfc-editor.org/rfc/rfc6090#appendix-B