kyokusen

type Curve interface {
	// NewPoint creates an identity point.
	NewPoint() Point
	// NewBasePoint creates the generate of this group.
	NewBasePoint() Point
	// NewScalar creates a scalar with the value of 0.
	NewScalar() Scalar
	// Name returns the name of this curve.
	//
	// This should be unique between curves.
	Name() string
	// ScalarBits returns the number of significant bits in a scalar.
	ScalarBits() int
	// SafeScalarBytes returns the number of random bytes need to sample a scalar through modular reduction.
	//
	// Usually, this is going to be the number of bytes in the scalar, plus an extra
	// security parameters worth of bytes, say 32. This is to make sure that the modular
	// reduction doesn't introduce any bias.
	SafeScalarBytes() int
	// Order returns a Modulus holding order of this group.
	Order() *saferith.Modulus
}

type Point interface {
	// You're free to implement the binary marshalling however you'd like.
	//
	// This marshalling should also work with the identity element, ideally,
	// but this isn't strictly necessary.
	encoding.BinaryMarshaler
	encoding.BinaryUnmarshaler
	// Curve returns the Elliptic Curve group associated with this type of Point.
	Curve() Curve
	// Add returns a new Point, by adding another Point to this one.
	//
	// This should not mutate this point.
	Add(Point) Point
	// Sub returns a new Point, by subtracting another Point from this one.
	//
	// This can be implemented with Add and Negate, but can be more efficient.
	//
	// This shouldn't mutate this point.
	Sub(Point) Point
	// Negate returns the negated version of this point.
	//
	// This does not mutate this point.
	Negate() Point
	// Equal checks if this point is equal to another.
	//
	// This check should, ideally, be done in constant time.
	Equal(Point) bool
	// IsIdentity checks if this is the identity element of this group.
	IsIdentity() bool
	// XScalar is an optional method, returning the x coordinate of this Point as a Scalar.
	//
	// This is used in ECDSA, but isn't available on every curve, necessarily.
	//
	// If you choose not to implement this method, simply return nil.
	XScalar() Scalar
}

type Scalar interface {
	// This should encode the Scalar as Big Endian bytes, without failure.
	encoding.BinaryMarshaler
	// This should decode the Scalar from Big Endian bytes.
	encoding.BinaryUnmarshaler
	// Curves returns the Curve associated with this kind of Scalar.
	Curve() Curve
	// Add mutates this Scalar, by adding in another.
	Add(Scalar) Scalar
	// Sub mutates this Scalar, by subtracting another.
	//
	// This should be equivalent to .Add(_.Negate()), but may be implemented faster,
	// and won't mutate its input.
	Sub(Scalar) Scalar
	// Negate mutates this Scalar, replacing it with its negation.
	Negate() Scalar
	// Mul mutates this Scalar, replacing it with another.
	Mul(Scalar) Scalar
	// Invert mutates this Scalar, replacing it with its multiplicative inverse.
	Invert() Scalar
	// Equal checks if this Scalar is equal to another.
	//
	// This check should be done in constant time.
	Equal(Scalar) bool
	// IsZero checks if this Scalar is equal to 0.
	//
	// This check should be done in constant time.
	//
	// While this can be accomplished through the Equal method, IsZero may
	// be implemented more efficiently.
	IsZero() bool
	// Set mutates this Scalar, replacing its value with another.
	Set(Scalar) Scalar
	// SetNat mutates this Scalar, replacing it with the value of a number.
	//
	// This number must be interpreted modulo the order of the group.
	SetNat(*saferith.Nat) Scalar
	// Act acts on a Point with this Scalar, returning a new Point.
	//
	// This shouldn't mutate the Scalar, or the Point.
	Act(Point) Point
	// Act acts on the Base Point with this Scalar, returning a new Point.
	//
	// This can be accomplished with Act, but can be made more efficient, in many cases.
	ActOnBase() Point
}