ITADN
systemslibrarian/crypto-lab-curve-lens
代码 动态 Issues 合并请求 版本
systemslibrarian/crypto-lab-curve-lens · 文件
文件最后提交记录最后更新时间
README.md

crypto-lab-curve-lens

What It Is

Elliptic-curve Diffie-Hellman (ECDH) is an asymmetric key-agreement protocol built on the elliptic-curve discrete logarithm problem (ECDLP): given a public point Q = k·G on a curve, recovering the private scalar k is computationally infeasible at production field sizes. This demo implements exact finite-field point addition and scalar multiplication for a small teaching curve (y² = x³ + 2x + 2 mod 17 and analogs), plus real arithmetic for P-256, Curve25519/X25519, and secp256k1 via @noble/curves. The security model is asymmetric: two parties exchange public points derived from private scalars and independently compute the same shared point without ever transmitting the secret. None of the three production curves shown are post-quantum secure; Shor's algorithm on a sufficiently large fault-tolerant quantum computer solves ECDLP in polynomial time.

The lab is built to be read top to bottom by a first-time visitor: it opens with the group law drawn over the ordinary real numbers (a smooth chord-and-tangent picture), then drops the identical algebra onto a finite field, where the same straight line is shown wrapping around the grid so it still passes through P, Q, and the third intersection. A plain-language glossary defines the vocabulary (generator, subgroup order, cofactor, Weierstrass vs Montgomery, u-coordinate) inline, and the ECDH payoff is first shown on the toy curve — Alice's a·B and Bob's b·A landing on one literal shared dot — before the real hex.

When to Use It

  • Ephemeral key agreement in TLS 1.3. X25519 (Curve25519 ECDH) is the preferred key-exchange group; P-256 is the fallback for FIPS-constrained environments. Both prove forward secrecy because the ephemeral scalar is discarded after each handshake.
  • End-to-end encrypted messaging. Signal's X3DH and Double Ratchet protocols chain multiple ECDH operations on Curve25519 to establish and continuously refresh session keys.
  • Hardware authenticator key generation. FIDO2/WebAuthn uses P-256 (ES256) for credential key pairs because P-256 is supported in secure-element hardware and is FIPS-approved.
  • Blockchain transaction signing. secp256k1 is used in Bitcoin and Ethereum for ECDSA signatures; choose it only when compatibility with those ecosystems is required — not for general-purpose key agreement.
  • Do not use ECDH when post-quantum security is a requirement (NIST PQC standards such as ML-KEM / FIPS 203 should be preferred), or when the runtime cannot guarantee a cryptographically secure random number generator for private scalar generation.
  • Do NOT treat this as production code — it is a browser teaching demo, not a hardened key-agreement library.

Live Demo

systemslibrarian.github.io/crypto-lab-curve-lens

The demo has five interactive panels. Panel 1 (Curve Explorer) starts with a Reals first (ℝ) sub-view: slide P and Q along a smooth curve over the real numbers and watch the straight chord hit a third point that reflects down to P+Q — the origin of the group law. Switch to the Finite field 𝔽₁₇ sub-view to plot every point on the small teaching curve, click any two to compute their exact finite-field sum, and see the same line y ≡ λx + c drawn wrapped modulo p — re-entering the opposite grid edge so it genuinely passes through P, Q, and the third intersection −(P+Q) before the reflection. Panel 2 runs scalar multiplication in both toy and production modes, with a full double-and-add trace for the small field, real generator multiplication for P-256, Curve25519, and secp256k1, an (x, y)-segmented view of the public point, and a "what changed from the toy curve" note mapping the toy trace to the real one. Panel 3 lets you brute-force the elliptic-curve discrete logarithm on the toy curve — watch G, 2·G, 3·G, … walk the subgroup until the public point appears — then contrasts that with the ~2²⁵⁶ work the same sequential walk would take on P-256, and notes that the best known generic attack, Pollard's rho, needs only ~2¹²⁸ group operations — which is why P-256 is rated at 128-bit security, not 256. Panel 4 shows side-by-side comparison cards for the three production curves (field size, subgroup order, cofactor, SafeCurves rating, post-quantum status) with an inline plain-language glossary for the jargon. Panel 5 first shows ECDH on the toy curve as a two-lane diagram — Alice's a·B and Bob's b·A landing on the same highlighted dot, with the colour-coded identity a·(bG) = b·(aG) = (ab)·G — then runs a live real exchange: click "Generate fresh keypairs" to produce new random Alice and Bob key pairs on your chosen curve and verify that both arrive at the same shared value, with one-click copy on every key.

The explorer grid is fully keyboard-navigable (Tab to focus the grid, arrow keys to move between points, Enter to select), and the current view — selected points, scalar, and chosen curves — is encoded in the URL, so "Copy shareable link" reproduces exactly what you're looking at.

What Can Go Wrong

  • Small-subgroup / invalid-point attack. If the curve cofactor h > 1 (Curve25519 has h = 8) and the implementation does not validate that the received public point lies in the prime-order subgroup, an attacker can send a low-order point that leaks bits of the private scalar through the shared secret.
  • Reuse of ephemeral scalars. ECDH is designed for one-time use per session. Reusing the same ephemeral private scalar across multiple exchanges eliminates forward secrecy and, if combined with additional oracle access, can expose the scalar entirely.
  • Scalar generation from a weak RNG. The security of the entire scheme depends on the private scalar being drawn from a cryptographically uniform distribution. A biased or predictable RNG (e.g., a seeded PRNG, Math.random()) reduces the effective key space and makes the scalar recoverable.
  • Timing side-channel in scalar multiplication. A variable-time double-and-add loop leaks secret scalar bits through execution timing. Production libraries such as @noble/curves use constant-time implementations; hand-rolled implementations often do not.
  • Conflating the shared point with a symmetric key. The x-coordinate of the ECDH shared point is not uniformly distributed and must be passed through a KDF (e.g., HKDF) before use as an AES or ChaCha20 key. Using the raw coordinate directly is a protocol error present in numerous real-world implementations.

Real-World Usage

  • TLS 1.3 (RFC 8446). X25519 and P-256 are the two most widely negotiated key-share groups; the ephemeral ECDH step in the handshake provides forward secrecy for every HTTPS connection.
  • Signal Protocol. X3DH (Extended Triple Diffie-Hellman) and the Double Ratchet both rely on X25519 ECDH for initial key agreement and continuous ratcheting in Signal, WhatsApp, and other adopters.
  • WireGuard. Uses Curve25519 (X25519) as its sole key-exchange mechanism; the simplicity and speed of the curve are central to the protocol's design goals.
  • FIDO2 / WebAuthn (W3C + CTAP2). P-256 (ES256) is the mandatory-to-implement credential algorithm for hardware security keys and platform authenticators, used in passkey authentication and hardware 2FA.
  • Bitcoin and Ethereum. secp256k1 is used for ECDSA transaction signing in both networks; every Bitcoin address and Ethereum account is derived from a secp256k1 public key.

How to Run Locally

git clone https://github.com/systemslibrarian/crypto-lab-curve-lens
cd crypto-lab-curve-lens
npm install
npm run dev

Development

npm install      # install dependencies
npm run dev      # start the Vite dev server
npm test         # run the Vitest suite (arithmetic, real-curve vectors, DOM smoke tests)
npm run lint     # ESLint + Prettier check
npm run format   # apply Prettier
npm run build    # typecheck (tsc --noEmit) + production build

The finite-field arithmetic, the @noble/curves integration, and the rendered UI are all covered by tests. runVerificationSuite() additionally re-checks the P-256 and secp256k1 base points and subgroup orders and the RFC 7748 X25519 vectors at runtime, surfacing the results in Panel 2. CI (.github/workflows/ci.yml) runs lint, tests, and build on every push and pull request; deployment to GitHub Pages runs only after the same checks pass.

Part of the Crypto Lab suite.

"So whether you eat or drink or whatever you do, do it all for the glory of God." — 1 Corinthians 10:31