From: Mark Wooding <mdw@distorted.org.uk>
Date: Tue, 25 Apr 2023 00:44:47 +0000 (+0100)
Subject: pub/x25519.h, pub/x448.h: Add descriptions of the curves.
X-Git-Url: https://git.distorted.org.uk/~mdw/catacomb/commitdiff_plain/6dbc50ef09e5065fa9eedffa342bc4c9762f31ad

pub/x25519.h, pub/x448.h: Add descriptions of the curves.
---

diff --git a/pub/x25519.h b/pub/x25519.h
index 56008df3..192f8db0 100644
--- a/pub/x25519.h
+++ b/pub/x25519.h
@@ -41,6 +41,17 @@
  * Since then, the name `Curve25519' has shifted somewhat, to refer to the
  * specific elliptic curve used, and the x-coordinate Diffie--Hellman
  * operation is now named `X25519'.
+ *
+ * The @x25519@ function essentially performs incompatible cofactor
+ * multiplication on the elliptic curve %$E(k)$% containing points %$(x, y)$%
+ * in %$\proj^2(k)$% satisfying the Montgomery-form equation
+ *
+ *	%$y^3 = x^3 + 486662 x^2 + x$% ,
+ *
+ * where $k = \gf{p}$, with $p = 2^{255} - 19$%.  The curve has
+ * %$n = (p + 1) + 221938542218978828286815502327069187962$% points; this is
+ * eight times a prime %$\ell$%.  The points with %$x$%-coordinate 9 have
+ * order %$\ell$%.
  */
 
 /*----- Header files ------------------------------------------------------*/
diff --git a/pub/x448.h b/pub/x448.h
index 4561d41a..42c9fb93 100644
--- a/pub/x448.h
+++ b/pub/x448.h
@@ -43,6 +43,18 @@
  * described in Hamburg's paper, since it doesn't involve the `Decaf'
  * cofactor elimination procedure.  Indeed, it looks very much like X25519
  * with Hamburg's curve slotted in in place of Bernstein's.
+ *
+ * The @x448@ function essentially performs incompatible cofactor
+ * multiplication on the elliptic curve %$E(k)$% containing points %$(x, y)$%
+ * in %$\proj^2(k)$% satisfying the Montgomery-form equation
+ *
+ *	%$y^3 = x^3 + 156326 x^2 + x$% ,
+ *
+ * where $k = \gf{p}$, with $p = \phi^2 - \phi - 1$%, where
+ * %$\phi = 2^{224}$%.  The curve has %$n = (p + 1) + {}$%
+ * %$28312320572429821613362531907042076847709625476988141958474579766324$%
+ * points; this is four times a prime %$\ell$%.  The points with
+ * %$x$%-coordinate 5 have order %$\ell$%.
  */
 
 /*----- Header files ------------------------------------------------------*/