Updating documentation of ted448 internal package.

internal/ted448/constants.go

@@ -1,15 +1,8 @@
-// Package ted448 provides operations on the twist curve of goldilocks.
-//
-// This curve is defined as
-//  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 provides fast
-// arithmetic operations due to a=-1.
 package ted448
 
 import fp "github.com/cloudflare/circl/math/fp448"
 
-var ( // All these values are in RFC-7748 (https://tools.ietf.org/html/rfc7748).
+var (
 	// genX is the x-coordinate of the generator of ted448 curve.
 	genX = fp.Elt{
 		0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
@@ -30,8 +23,8 @@ var ( // All these values are in RFC-7748 (https://tools.ietf.org/html/rfc7748).
 		0x08, 0x24, 0xca, 0x78, 0x30, 0xc1, 0x06, 0x8d,
 		0xd4, 0x86, 0x42, 0xf0, 0x14, 0xde, 0x08, 0x85,
 	}
-	// ParamD is -39082 in Fp. The D parameter of the ted448 curve.
-	ParamD = fp.Elt{
+	// paramD is -39082 in Fp. The D parameter of the ted448 curve.
+	paramD = fp.Elt{
 		0x55, 0x67, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
 		0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
 		0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,

internal/ted448/curve.go

@@ -1,3 +1,26 @@
+// Package ted448 provides operations on a twist curve of the Goldilocks curve.
+//
+// The twist curve is defined over Fp = GF(2^448-2^224-1) as
+//  ted448: ax^2+y^2 = 1 + dx^2y^2, where a=-1 and d=-39082.
+// The ted448 curve provides fast arithmetic operations due to a=-1.
+//
+// Isogenies
+//
+// The ted448 curve is 4-degree isogeneous to the Goldilocks curve, and the
+// explicit map Iso4 is given in [Ham, Sec 2].
+//
+// The ted448 curve is 2-degree isogeneous to the Jacobi quartic used in Decaf.
+//
+// Generator Point
+//
+// The generator of ted448 is returned by Generator(), and is equal to
+// Iso4(Gx,Gy), where (Gx,Gy) is the generator of the Goldilocks curve.
+//
+// References
+//
+// [Ham] Twisting Edwards curves with isogenies, Hamburg. (https://www.shiftleft.org/papers/isogeny)
+//
+// [RFC7748] Elliptic Curves for Security (https://rfc-editor.org/rfc/rfc7748.txt)
 package ted448
 
 import (
@@ -18,6 +41,9 @@ func Generator() Point { return Point{X: genX, Y: genY, Z: fp.One(), Ta: genX, T
 // Order returns the number of points in the prime subgroup.
 func Order() Scalar { return order }
 
+// ParamD returns the number of points in the prime subgroup.
+func ParamD() fp.Elt { return paramD }
+
 // IsOnCurve returns true if the point lies on the curve.
 func IsOnCurve(P *Point) bool {
 	eq0 := *P != Point{}
@@ -29,7 +55,7 @@ func IsOnCurve(P *Point) bool {
 	fp.Sqr(z2, &P.Z)         // z^2
 	fp.Sqr(t2, t)            // t^2
 	fp.Sub(lhs, y2, x2)      // -x^2 + y^2, since a=-1
-	fp.Mul(rhs, t2, &ParamD) // dt^2
+	fp.Mul(rhs, t2, &paramD) // dt^2
 	fp.Add(rhs, rhs, z2)     // z^2 + dt^2
 	fp.Sub(lhs, lhs, rhs)    // ax^2 + y^2 - (z^2 + dt^2)
 	eq1 := fp.IsZero(lhs)

internal/ted448/point.go

@@ -6,7 +6,9 @@ import (
 	fp "github.com/cloudflare/circl/math/fp448"
 )
 
-// Point defines a point on the ted448 curve.
+// Point defines a point on the ted448 curve using extended projective
+// coordinates. Thus, for any affine point (x,y) it holds x=X/Z, y = Y/Z, and
+// T = Ta*Tb = X*Y/Z.
 type Point struct{ X, Y, Z, Ta, Tb fp.Elt }
 
 type prePointAffine struct{ addYX, subYX, dt2 fp.Elt }
@@ -31,7 +33,7 @@ func (P *Point) cneg(b uint) {
 
 // Double updates P with 2P.
 func (P *Point) Double() {
-	// This is formula (7) from "ed448 Edwards Curves Revisited" by
+	// This is formula (7) from "Twisted Edwards Curves Revisited" by
 	// Hisil H., Wong K.KH., Carter G., Dawson E. (2008)
 	// https://doi.org/10.1007/978-3-540-89255-7_20
 	Px, Py, Pz, Pta, Ptb := &P.X, &P.Y, &P.Z, &P.Ta, &P.Tb
@@ -59,7 +61,7 @@ func (P *Point) mixAddZ1(Q *prePointAffine) {
 
 // coreAddition calculates P=P+Q for curves with A=-1.
 func (P *Point) coreAddition(Q *prePointAffine) {
-	// This is the formula following (5) from "ed448 Edwards Curves Revisited" by
+	// Formula as in Eq.(5) of "Twisted Edwards Curves Revisited" by
 	// Hisil H., Wong K.KH., Carter G., Dawson E. (2008)
 	// https://doi.org/10.1007/978-3-540-89255-7_20
 	Px, Py, Pz, Pta, Ptb := &P.X, &P.Y, &P.Z, &P.Ta, &P.Tb
@@ -166,7 +168,7 @@ func (P *prePointProy) FromPoint(Q *Point) {
 	fp.Add(&P.addYX, &Q.Y, &Q.X)    // addYX = X + Y
 	fp.Sub(&P.subYX, &Q.Y, &Q.X)    // subYX = Y - X
 	fp.Mul(&P.dt2, &Q.Ta, &Q.Tb)    // T = ta*tb
-	fp.Mul(&P.dt2, &P.dt2, &ParamD) // D*T
+	fp.Mul(&P.dt2, &P.dt2, &paramD) // D*T
 	fp.Add(&P.dt2, &P.dt2, &P.dt2)  // dt2 = 2*D*T
 	fp.Add(&P.z2, &Q.Z, &Q.Z)       // z2 = 2*Z
 }

internal/ted448/scalar.go

@@ -1,6 +1,7 @@
 package ted448
 
 import (
+	"crypto/rand"
 	"encoding/binary"
 	"math/bits"
 
@@ -174,8 +175,8 @@ func (z *Scalar) FromBytes(x []byte) {
 // Red reduces z mod order.
 func (z *Scalar) Red() { var t scalar64; t.fromScalar(z); t.modOrder(); t.toScalar(z) }
 
-// Neg calculates z = -z mod order.
-func (z *Scalar) Neg() { z.Sub(&order, z) }
+// Neg calculates z = -x mod order.
+func (z *Scalar) Neg(x *Scalar) { z.Sub(&order, x) }
 
 // Add calculates z = x+y mod order.
 func (z *Scalar) Add(x, y *Scalar) {
@@ -217,3 +218,16 @@ func (z *Scalar) Mul(x, y *Scalar) {
 	z64.modOrder()
 	z64.toScalar(z)
 }
+
+// Inv calculates z = 1/x mod order.
+func (z *Scalar) Inv(x *Scalar) {
+	var t, r Scalar
+	_, _ = rand.Read(r[:])
+	r.Red()
+	t.Mul(x, &r)
+	bigT := conv.BytesLe2BigInt(t[:])
+	bigOrder := conv.BytesLe2BigInt(order[:])
+	bigT.ModInverse(bigT, bigOrder)
+	conv.BigInt2BytesLe(z[:], bigT)
+	z.Mul(z, &r)
+}

internal/ted448/scalar_test.go

@@ -2,7 +2,6 @@ package ted448_test
 
 import (
 	"crypto/rand"
-	"encoding/binary"
 	"math/big"
 	"testing"
 
@@ -78,12 +77,19 @@ func TestScalar(t *testing.T) {
 			func(z, x, y *ted448.Scalar) { z.Mul(x, y) },
 			func(z, x, y *big.Int) { z.Mul(x, y) })
 	})
+	t.Run("Inv", func(t *testing.T) {
+		order := ted448.Order()
+		bigOrder := conv.BytesLe2BigInt(order[:])
+		testOp(t,
+			func(z, x, y *ted448.Scalar) { z.Inv(x) },
+			func(z, x, y *big.Int) { z.ModInverse(x, bigOrder) })
+	})
 }
 
 func BenchmarkScalar(b *testing.B) {
 	var k [2 * ted448.ScalarSize]byte
 	var x, y, z ted448.Scalar
-	_ = binary.Read(rand.Reader, binary.LittleEndian, x[:])
+	_, _ = rand.Read(x[:])
 	b.Run("Add", func(b *testing.B) {
 		for i := 0; i < b.N; i++ {
 			z.Add(&x, &y)
@@ -104,4 +110,9 @@ func BenchmarkScalar(b *testing.B) {
 			z.FromBytes(k[:])
 		}
 	})
+	b.Run("Inv", func(b *testing.B) {
+		for i := 0; i < b.N; i++ {
+			z.Inv(&x)
+		}
+	})
 }