weierstrass

Documentation

Overview

Package weierstrass provides a standard interface for short-form Weierstrass elliptic curves over prime fields.

As a result, it may not be as efficient as the standard library's elliptic package to (which it was forked from) but it does allow for a uniform interface for a broader set of curves than just standard NIST curves with a = -3.

It is based on the following [pull request].

- [pull request]: https://github.com/golang/go/pull/26873

Index

• func GenerateKey(curve Curve, rand io.Reader) (pvt []byte, x, y *big.Int, err error)
• func Marshal(curve Curve, x, y *big.Int) []byte
• func MarshalCompressed(curve Curve, x, y *big.Int) []byte
• func Unmarshal(curve Curve, data []byte) (x, y *big.Int)
• func UnmarshalCompressed(curve Curve, data []byte) (x, y *big.Int)
• type Curve
  • func Stark() Curve
• type CurveParams
  • func (curve *CurveParams) Add(x1, y1, x2, y2 *big.Int) (*big.Int, *big.Int)
  • func (curve *CurveParams) Double(x1, y1 *big.Int) (*big.Int, *big.Int)
  • func (curve *CurveParams) IsOnCurve(x, y *big.Int) bool
  • func (curve *CurveParams) Params() *CurveParams
  • func (curve *CurveParams) ScalarBaseMult(k []byte) (*big.Int, *big.Int)
  • func (curve *CurveParams) ScalarMult(Bx, By *big.Int, k []byte) (*big.Int, *big.Int)

Functions

func GenerateKey

func GenerateKey(curve Curve, rand io.Reader) (pvt []byte, x, y *big.Int, err error)

GenerateKey returns a public/private key pair. The private key is generated using the given reader, which must return random data.

func Marshal

func Marshal(curve Curve, x, y *big.Int) []byte

Marshal converts a point on the curve into the uncompressed form specified in SEC 1, Version 2.0, Section 2.3.3. If the point is not on the curve (or is the conventional point at infinity), the behaviour is undefined.

func MarshalCompressed

func MarshalCompressed(curve Curve, x, y *big.Int) []byte

MarshalCompressed converts a point on the curve into the compressed form specified in SEC 1, Version 2.0, Section 2.3.3. If the point is not on the curve (or is the conventional point at infinity), the behaviour is undefined.

func Unmarshal

func Unmarshal(curve Curve, data []byte) (x, y *big.Int)

Unmarshal converts a point, serialized by Marshal, into an x, y pair. It is an error if the point is not in uncompressed form, is not on the curve, or is the point at infinity. On error, x = nil.

func UnmarshalCompressed

func UnmarshalCompressed(curve Curve, data []byte) (x, y *big.Int)

UnmarshalCompressed converts a point, serialized by MarshalCompressed, into an x, y pair. It is an error if the point is not in compressed form, is not on the curve, or is the point at infinity. On error, x = nil.

Types

type Curve

type Curve interface {
	// Params returns the parameters for the curve.
	Params() *CurveParams
	// IsOnCurve reports whether the given (x, y) lies on the curve.
	IsOnCurve(x, y *big.Int) bool
	// Add returns the sum of (x1, y1) and (x2, y2).
	Add(x1, y1, x2, y2 *big.Int) (x, y *big.Int)
	// Double returns 2 * (x, y).
	Double(x1, y1 *big.Int) (x, y *big.Int)
	// ScalarMult returns k*(Bx,By) where k is a number in big-endian.
	ScalarMult(x1, y1 *big.Int, k []byte) (x, y *big.Int)
	// ScalarBaseMult returns k * G, where G is the base point of the
	// group and k is an integer in big-endian.
	ScalarBaseMult(k []byte) (x, y *big.Int)
}

Curve represents a short-form Weierstrass curve.

The behaviour of [Add], [Double], and [ScalarMult] when the input is not a point on the curve is undefined.

Note that the conventional point at infinity (0, 0) is not considered on the curve, although it can be returned by [Add], [Double], [ScalarMult], or [ScalarBaseMult] (but not the Unmarshal or UnmarshalCompressed functions).

func Stark

func Stark() Curve

Stark returns a Curve which represents the STARK elliptic curve.

type CurveParams

type CurveParams struct {
	A      *big.Int // a coefficient.
	B      *big.Int // b coefficient.
	Gx, Gy *big.Int // Generator.
	N      *big.Int // Order of the generator.
	P      *big.Int // Order of the field.

	BitSize int    // Size of the field.
	Name    string // Canonical name of the curve.
}

CurveParams contains the parameters of an elliptic curve.

func (*CurveParams) Add

func (curve *CurveParams) Add(x1, y1, x2, y2 *big.Int) (*big.Int, *big.Int)

Add returns the sum of (x1, y1) and (x2, y2).

func (*CurveParams) Double

func (curve *CurveParams) Double(x1, y1 *big.Int) (*big.Int, *big.Int)

Double returns 2 * (x, y).

func (*CurveParams) IsOnCurve

func (curve *CurveParams) IsOnCurve(x, y *big.Int) bool

IsOnCurve reports whether the given (x, y) lies on the curve.

func (*CurveParams) Params

func (curve *CurveParams) Params() *CurveParams

Params returns the CurveParams of the curve.

CurveParams operates, internally, on Jacobian coordinates. For a given (x, y) position on the curve, the Jacobian coordinates are (x1, y1, z1) where x = x1/z1² and y = y1/z1³. The greatest speed-ups come when the whole calculation can be performed within the transform (as in [ScalarMult] and [ScalarBaseMult]). But even for [Add] and [Double], it's faster to apply and reverse the transform than to operate in affine coordinates.

func (*CurveParams) ScalarBaseMult

func (curve *CurveParams) ScalarBaseMult(k []byte) (*big.Int, *big.Int)

ScalarBaseMult returns k * G, where G is the base point of the group and k is an integer in big-endian.

func (*CurveParams) ScalarMult

func (curve *CurveParams) ScalarMult(Bx, By *big.Int, k []byte) (*big.Int, *big.Int)

ScalarMult returns k * (Bx, By) where k is a number in big-endian.