Adapting ed448 for using the internal ted448 package.

ecc/decaf/decaf.go

@@ -1,12 +1,40 @@
-// Package decaf provides operations on a prime-order group derived from the goldilocks curve.
+// Package decaf provides a prime-order group derived from a quotient of
+// Edwards curves.
 //
-// Its internal implementation uses the twist of the goldilocks curve.
-// This implementation uses Decaf v1.0 of the encoding.
+// Decaf Group
 //
-// References:
-//  - https://www.shiftleft.org/papers/decaf/
-//  - https://www.shiftleft.org/papers/goldilocks
-//  - https://sourceforge.net/p/ed448goldilocks/code/ci/v1.0/tree/
+// Decaf (3) is a prime-order group constructed as a quotient of groups. A Decaf
+// element can be represented by any point in the coset P+J[2], where J is a
+// Jacobi quartic and J[2] are its 2-torsion points.
+// Since P+J[2] has four points, Decaf specifies rules to choose one canonical
+// representative, which has a unique encoding. Two representations are
+// equivalent if they belong to the same coset.
+//
+// The types Elt and Scalar provide methods to perform arithmetic operations on
+// the Decaf group.
+//
+// Version
+//
+// This implementation uses Decaf v1.0 of the encoding (see (4) for a complete
+// specification).
+//
+// Internals
+//
+// Decaf uses as internal representation the curve
+//   ted448: ax^2+y^2 = 1 + dx^2y^2, where a=-1 and d=-39082.
+// This curve is 4-degree isogeneous to the Goldilocks curve, and 2-degree
+// isogeneous to the Jacobi quartic. The ted448 curve was chosen because it
+// provides faster arithmetic operations.
+//
+// References
+//
+// (1) https://www.shiftleft.org/papers/goldilocks
+//
+// (2) https://tools.ietf.org/html/rfc7748
+//
+// (3) https://doi.org/10.1007/978-3-662-47989-6_34 and https://www.shiftleft.org/papers/decaf
+//
+// (4) https://sourceforge.net/p/ed448goldilocks/code/ci/v1.0/tree/
 package decaf
 
 import (
@@ -16,7 +44,7 @@ import (
 	fp "github.com/cloudflare/circl/math/fp448"
 )
 
-// Version targets Decaf v1.0 of the encoding. As implemented in https://sourceforge.net/p/ed448goldilocks/code/ci/v1.0/tree/.
+//  Decaf v1.0 of the encoding.
 const Version = "v1.0"
 
 // Elt is an element of the Decaf group. It must be always initialized using