Additional JavaDoc, relates to github issue #735

dghgit · dghgit · commit 4e3d735ced18 · 2026-05-11T23:15:34.000+10:00
diff --git a/core/src/main/java/org/bouncycastle/math/ec/rfc7748/X25519.java b/core/src/main/java/org/bouncycastle/math/ec/rfc7748/X25519.java
@@ -5,6 +5,47 @@
 import org.bouncycastle.math.ec.rfc8032.Ed25519;
 import org.bouncycastle.util.Arrays;
 
+/**
+ * A low-level implementation of X25519 (RFC 7748).
+ * <p>
+ * <b>Algorithm map.</b>
+ * <ul>
+ *   <li>{@link #generatePrivateKey} &mdash; 32 random bytes followed by
+ *       {@link #clampPrivateKey} (RFC 7748 sec. 5 clamping: clear bits
+ *       254..255 then 0..2, set bit 254).</li>
+ *   <li>{@link #generatePublicKey} / {@link #scalarMultBase} &mdash;
+ *       computed as {@code k * B} on the birationally-equivalent
+ *       {@code edwards25519} curve via
+ *       {@link Ed25519#scalarMultBaseYZ(Friend, byte[], int, int[], int[])}
+ *       (a signed multi-comb in extended Edwards coordinates), then
+ *       converted to the Curve25519 {@code u} coordinate using the RFC
+ *       7748 sec. 4.1 birational map {@code u = (1 + Y) / (1 - Y)}
+ *       where {@code Y = y / z}.</li>
+ *   <li>{@link #scalarMult} (key agreement) &mdash; Montgomery ladder on
+ *       XZ-only projective coordinates per RFC 7748 sec. 5, with
+ *       per-bit constant-time {@code cswap}; the
+ *       {@code A24 = (A + 2) / 4} curve constant is precomputed from
+ *       {@code A = 486662}. The trailing three doublings cancel the
+ *       cofactor introduced by the lowest cleared scalar bits.</li>
+ *   <li>{@link #calculateAgreement} &mdash; {@link #scalarMult} followed
+ *       by the RFC 7748 sec. 6.1 all-zero rejection.</li>
+ * </ul>
+ * <p>
+ * <b>Side-channel scope.</b> Secret-scalar operations are written to be
+ * constant-time at the Java level: the Montgomery ladder in
+ * {@link #scalarMult} performs identical field operations per bit with
+ * branchless {@code cswap}; {@link #scalarMultBase} routes through the
+ * Ed25519 signed-comb, which walks all precomputed entries with mask-based
+ * {@code cmov} rather than a secret-indexed array load and applies
+ * conditional negation by XOR-with-mask; the final modular inverse uses
+ * constant-time {@code Mod.modOddInverse}. The all-zero rejection in
+ * {@link #calculateAgreement} runs an OR-accumulator and only leaks the
+ * RFC-mandated public rejection criterion. This is sufficient against a
+ * remote network timing attacker but is not a substitute for a constant-time
+ * native implementation against a co-located cache-line-resolution
+ * adversary &mdash; JVM-level timing variance from JIT, GC and cache
+ * eviction is not addressable in pure Java.
+ */
 public abstract class X25519
 {
     public static class Friend
@@ -165,6 +206,9 @@ public static void scalarMultBase(byte[] k, int kOff, byte[] r, int rOff)
 
         Ed25519.scalarMultBaseYZ(Friend.INSTANCE, k, kOff, y, z);
 
+        // Birational map edwards25519 -> Curve25519 (RFC 7748 sec. 4.1):
+        //   u = (1 + Y) / (1 - Y),  where Y = y / z.
+        // Computed projectively: y' := z + y, z' := z - y, then u = y' / z'.
         F.apm(z, y, y, z);
 
         F.inv(z, z);
diff --git a/core/src/main/java/org/bouncycastle/math/ec/rfc7748/X448.java b/core/src/main/java/org/bouncycastle/math/ec/rfc7748/X448.java
@@ -5,6 +5,47 @@
 import org.bouncycastle.math.ec.rfc8032.Ed448;
 import org.bouncycastle.util.Arrays;
 
+/**
+ * A low-level implementation of X448 (RFC 7748).
+ * <p>
+ * <b>Algorithm map.</b>
+ * <ul>
+ *   <li>{@link #generatePrivateKey} &mdash; 56 random bytes followed by
+ *       {@link #clampPrivateKey} (RFC 7748 sec. 5 clamping: clear bits
+ *       0..1, set bit 447).</li>
+ *   <li>{@link #generatePublicKey} / {@link #scalarMultBase} &mdash;
+ *       computed as {@code k * B} on the birationally-equivalent
+ *       {@code edwards448} curve via
+ *       {@link Ed448#scalarMultBaseXY(Friend, byte[], int, int[], int[])}
+ *       (a signed multi-comb in projective Edwards coordinates), then
+ *       converted to the Curve448 {@code u} coordinate using the RFC
+ *       7748 sec. 4.2 / errata 5568 birational map
+ *       {@code u = (y / x)^2}.</li>
+ *   <li>{@link #scalarMult} (key agreement) &mdash; Montgomery ladder on
+ *       XZ-only projective coordinates per RFC 7748 sec. 5, with
+ *       per-bit constant-time {@code cswap}; the
+ *       {@code A24 = (A + 2) / 4} curve constant is precomputed from
+ *       {@code A = 156326}. The trailing two doublings cancel the
+ *       cofactor introduced by the lowest cleared scalar bits.</li>
+ *   <li>{@link #calculateAgreement} &mdash; {@link #scalarMult} followed
+ *       by the RFC 7748 sec. 6.2 all-zero rejection.</li>
+ * </ul>
+ * <p>
+ * <b>Side-channel scope.</b> Secret-scalar operations are written to be
+ * constant-time at the Java level: the Montgomery ladder in
+ * {@link #scalarMult} performs identical field operations per bit with
+ * branchless {@code cswap}; {@link #scalarMultBase} routes through the
+ * Ed448 signed-comb, which walks all precomputed entries with mask-based
+ * {@code cmov} rather than a secret-indexed array load and applies
+ * conditional negation by XOR-with-mask; the final modular inverse uses
+ * constant-time {@code Mod.modOddInverse}. The all-zero rejection in
+ * {@link #calculateAgreement} runs an OR-accumulator and only leaks the
+ * RFC-mandated public rejection criterion. This is sufficient against a
+ * remote network timing attacker but is not a substitute for a constant-time
+ * native implementation against a co-located cache-line-resolution
+ * adversary &mdash; JVM-level timing variance from JIT, GC and cache
+ * eviction is not addressable in pure Java.
+ */
 public abstract class X448
 {
     public static class Friend
@@ -173,6 +214,9 @@ public static void scalarMultBase(byte[] k, int kOff, byte[] r, int rOff)
 
         Ed448.scalarMultBaseXY(Friend.INSTANCE, k, kOff, x, y);
 
+        // Birational map edwards448 -> Curve448 (RFC 7748 sec. 4.2 /
+        // errata 5568):  u = (y / x)^2.  The Ed448 comb returns the
+        // affine Edwards (x, y); invert x and square the ratio.
         F.inv(x, x);
         F.mul(x, y, x);
         F.sqr(x, x);
diff --git a/core/src/main/java/org/bouncycastle/math/ec/rfc8032/Ed25519.java b/core/src/main/java/org/bouncycastle/math/ec/rfc8032/Ed25519.java
@@ -20,6 +20,38 @@
  * "extensible coordinates" (for accumulators). Standard
  * <a href="https://hyperelliptic.org/EFD/g1p/auto-twisted-extended.html">extended coordinates</a> are used
  * during precomputations, needing only a single extra point addition formula.
+ * <p>
+ * <b>Algorithm map.</b>
+ * <ul>
+ *   <li>Key generation &mdash; {@code generatePrivateKey} returns a 32-byte seed;
+ *       {@code generatePublicKey} (via {@code scalarMultBaseEncoded}) computes
+ *       {@code A = s * B} where {@code s} is the SHA-512-expanded clamped secret scalar (RFC 8032
+ *       sec. 5.1.5), using the constant-time signed multi-comb {@code scalarMultBase}.</li>
+ *   <li>Signing &mdash; {@code sign} computes {@code R = r * B} (signed multi-comb) where
+ *       {@code r = SHA-512(prefix || M) mod L}, then {@code S = (r + k * s) mod L} (RFC 8032
+ *       sec. 5.1.6). Reduction modulo {@code L} uses {@code Scalar25519.reduce512} (Barrett-style,
+ *       straight-line). No variable-base scalar multiplication is performed.</li>
+ *   <li>Verification &mdash; {@code verify} runs the small-multiple basis-reduction trick of
+ *       <a href="https://ia.cr/2003/116">Antipa-Brown-Menezes-Struik-Vanstone</a> via
+ *       {@code Scalar25519.reduceBasisVar} then evaluates the combined relation with Strauss-Shamir's
+ *       trick in {@code scalarMultStraus128Var}. Both routines are deliberately variable-time and
+ *       operate only on public material (signature, message, public key).</li>
+ *   <li>Coordinates &mdash; the precomputed base-point comb table lives in
+ *       <a href="https://ia.cr/2012/309">half-Niels</a> form; signing-side accumulators use extensible
+ *       (twisted Edwards) coordinates so each step needs only one extra point-addition formula.
+ *       Verification re-uses projective extended coordinates throughout.</li>
+ * </ul>
+ * <p>
+ * <b>Side-channel scope.</b> The signing path (which operates on the secret seed, the derived secret
+ * scalar, and the secret per-message nonce) is written to be constant-time at the Java level: the comb
+ * {@code scalarMultBase} walks all precomputed entries via mask-based {@code cmov} rather than a
+ * secret-indexed array load, conditional sign application uses XOR-with-mask {@code cnegate}, scalar
+ * recoding via {@code toSignedDigits} uses mask-driven {@code caddTo}, and {@code Scalar25519.reduce512}
+ * is fully unrolled straight-line arithmetic. This is sufficient against a remote network timing attacker
+ * but is not a substitute for a constant-time native implementation against a co-located
+ * cache-line-resolution adversary &mdash; JVM-level timing variance from JIT, GC and cache eviction is not
+ * addressable in pure Java. Verification routines (those suffixed {@code Var}) are deliberately
+ * variable-time and operate only on public material.
  */
 public abstract class Ed25519
 {
diff --git a/core/src/main/java/org/bouncycastle/math/ec/rfc8032/Ed448.java b/core/src/main/java/org/bouncycastle/math/ec/rfc8032/Ed448.java
@@ -17,6 +17,39 @@
  * <a href="https://ia.cr/2012/309">Mike Hamburg, "Fast and compact elliptic-curve cryptography"</a>. Standard
  * <a href="https://hyperelliptic.org/EFD/g1p/auto-edwards-projective.html">projective coordinates</a> are
  * used for most point arithmetic.
+ * <p>
+ * <b>Algorithm map.</b>
+ * <ul>
+ *   <li>Key generation &mdash; {@code generatePrivateKey} returns a 57-byte seed;
+ *       {@code generatePublicKey} (via {@code scalarMultBaseEncoded}) computes
+ *       {@code A = s * B} where {@code s} is the SHAKE-256-expanded clamped secret scalar
+ *       (RFC 8032 sec. 5.2.5), using the constant-time signed multi-comb {@code scalarMultBase}.</li>
+ *   <li>Signing &mdash; {@code sign} computes {@code R = r * B} (signed multi-comb) where
+ *       {@code r = SHAKE-256(dom4(F, C) || prefix || M, 912 bits) mod L}, then
+ *       {@code S = (r + k * s) mod L} (RFC 8032 sec. 5.2.6). Reduction modulo {@code L} uses
+ *       {@code Scalar448.reduce912} (Barrett-style, straight-line). No variable-base scalar
+ *       multiplication is performed.</li>
+ *   <li>Verification &mdash; {@code verify} runs the small-multiple basis-reduction trick of
+ *       <a href="https://ia.cr/2003/116">Antipa-Brown-Menezes-Struik-Vanstone</a> via
+ *       {@code Scalar448.reduceBasisVar} then evaluates the combined relation with Strauss-Shamir's
+ *       trick in {@code scalarMultStraus128Var}. Both routines are deliberately variable-time and
+ *       operate only on public material (signature, message, public key).</li>
+ *   <li>Coordinates &mdash; the precomputed base-point comb table lives in
+ *       <a href="https://hyperelliptic.org/EFD/g1p/auto-edwards-projective.html">affine</a> form
+ *       (matching {@code PointAffine} in {@code pointLookup}); the signing-side accumulator is
+ *       projective (X : Y : Z). Verification uses projective coordinates throughout.</li>
+ * </ul>
+ * <p>
+ * <b>Side-channel scope.</b> The signing path (which operates on the secret seed, the derived secret
+ * scalar, and the secret per-message nonce) is written to be constant-time at the Java level: the comb
+ * {@code scalarMultBase} walks all precomputed entries via mask-based {@code cmov} rather than a
+ * secret-indexed array load, conditional sign application uses XOR-with-mask {@code cnegate}, scalar
+ * recoding via {@code toSignedDigits} uses mask-driven {@code caddTo}, and {@code Scalar448.reduce912}
+ * is fully unrolled straight-line arithmetic. This is sufficient against a remote network timing attacker
+ * but is not a substitute for a constant-time native implementation against a co-located
+ * cache-line-resolution adversary &mdash; JVM-level timing variance from JIT, GC and cache eviction is not
+ * addressable in pure Java. Verification routines (those suffixed {@code Var}) are deliberately
+ * variable-time and operate only on public material.
  */
 public abstract class Ed448
 {
