document how to replace ExtendedGroupElement

[kevinburke]

I have the following code that uses a fork of curve25519/internal/edwards25519:

func TestUnmarshalMarshal(t *testing.T) {
	pub, _, _ := Keypair(rand.Reader)

	var A edwards25519.ExtendedGroupElement
	var pubBytes [32]byte
	copy(pubBytes[:], pub)
	if !A.FromBytes(&pubBytes) {
		t.Fatalf("ExtendedGroupElement.FromBytes failed")
	}

	var pub2 [32]byte
	A.ToBytes(&pub2)

	if pubBytes != pub2 {
		t.Errorf("FromBytes(%v)->ToBytes does not round-trip, got %x\n", pubBytes, pub2)
	}
}

I looked for matching code in this library and I wasn't quite sure what the replacement for ExtendedGroupElement, FromBytes or ToBytes should be. (Unfortunately I don't understand the crypto primitives well enough to guess at what should be the case or suggest a solution.)

I would love to be able to rip out the internal/edwards25519 fork if I can help it.

[kevinburke]

Here's the reference for ExtendedGroupElement

// Group elements are members of the elliptic curve -x^2 + y^2 = 1 + d * x^2 *
// y^2 where d = -121665/121666.
//
// Several representations are used:
//   ProjectiveGroupElement: (X:Y:Z) satisfying x=X/Z, y=Y/Z
//   ExtendedGroupElement: (X:Y:Z:T) satisfying x=X/Z, y=Y/Z, XY=ZT
//   CompletedGroupElement: ((X:Z),(Y:T)) satisfying x=X/Z, y=Y/T
//   PreComputedGroupElement: (y+x,y-x,2dxy)
// 
// ... some code omitted
type ExtendedGroupElement struct {
	X, Y, Z, T FieldElement
}

[FiloSottile]

I think documenting the quirks of ed25519/internal/edwards25519 is a little out of scope, because that API is low-level and pretty idiosyncratic. The good news though is that the API of this package is safer and higher level, so it's lees likely you'll mess up with this than with the old one.

Generally, you'll want to replace ExtendedGroupElement with Point, FromBytes with SetBytes, and ToBytes with Bytes. In your example, it should just work. Let me know if you get stuck.

I'll add a couple examples for common operations to the docs.

[kevinburke]

Thanks!