Javadoc corrections

Author: peterdettman

core/src/main/java/org/bouncycastle/math/ec/rfc7748/X25519.java

@@ -18,15 +18,16 @@
  *       {@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
+ *       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>
+ *       {@code A = 486662}. The final three doublings correspond to the
+ *       always-cleared low bits of the scalar; these clear the cofactor
+ *       to ensure a non-twist result.</li>
  *   <li>{@link #calculateAgreement} &mdash; {@link #scalarMult} followed
  *       by the RFC 7748 sec. 6.1 all-zero rejection.</li>
  * </ul>
@@ -206,7 +207,7 @@ 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):
+        // 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);

core/src/main/java/org/bouncycastle/math/ec/rfc7748/X448.java

@@ -14,19 +14,18 @@
  *       {@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[])}
+ *       computed as {@code k * B} on the 4-isogenous {@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>
+ *       converted to the curve448 {@code u} coordinate using the RFC
+ *       7748 sec. 4.2 4-isogeny 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>
+ *       {@code A = 156326}. The final two doublings correspond to the
+ *       always-cleared low bits of the scalar; these clear the cofactor
+ *       to ensure a non-twist result.</li>
  *   <li>{@link #calculateAgreement} &mdash; {@link #scalarMult} followed
  *       by the RFC 7748 sec. 6.2 all-zero rejection.</li>
  * </ul>
@@ -214,9 +213,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.
+        // 4-isogeny map edwards448 -> curve448 (RFC 7748 sec. 4.2): u = (y / x)^2.
+        // The Ed448 comb returns the X, Y of a result in projective coordinates (with Z elided);
+        // invert x and square the ratio.
         F.inv(x, x);
         F.mul(x, y, x);
         F.sqr(x, x);

core/src/main/java/org/bouncycastle/math/ec/rfc8032/Ed25519.java

@@ -31,11 +31,10 @@
  *       {@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>Verification &mdash; {@code verify} uses the basis reduction algorithm of
+ *       <a href="https://ia.cr/2020/454">Pornin</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.

core/src/main/java/org/bouncycastle/math/ec/rfc8032/Ed448.java

@@ -29,11 +29,10 @@
  *       {@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>Verification &mdash; {@code verify} uses the basis reduction algorithm of
+ *       <a href="https://ia.cr/2020/454">Pornin</a> via {@code Scalar448.reduceBasisVar} then evaluates the
+ *       combined relation with Strauss-Shamir's trick in {@code scalarMultStraus225Var}. 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