jubjub

README

Jubjub

This an implementation of the Jubjub curve from Zcash Sapling. It is correct and has a complete API driven primarily by the need to do Sapling note decryption. The structure of the code is inspired by several related implementations I've worked on, including ristretto255's internals and the edwards25519 package now maintained by Filippo Valsorda. A refinement expressed here more strongly than in those libraries is that points, scalars, and field elements are not meant to be constructed but should be parsed from existing bytes (and thus subject to checks) or produced by operations within the curve context. This should help developers avoid common situations where a type contains an unexpectedly incorrect value. However, those types do know how to subsequently encode themselves without further reference to the curve, since they already know what they are.

While the library strives to be clear, due to its origins in a personal project it's neither fast nor especially robust against misuse. Feel free to get in touch if you would like it to become those things.

Documentation

Overview

Package jubjub provides an implementation of the Jubjub elliptic curve used in Zcash.

Index

• Variables
• type FieldElement
  • func (z *FieldElement) Add(x, y *FieldElement) *FieldElement
  • func (z *FieldElement) Cmp(x *FieldElement) int
  • func (z *FieldElement) Equals(x *FieldElement) bool
  • func (z *FieldElement) Exp(x, y *FieldElement) *FieldElement
  • func (z *FieldElement) ModInverse(x *FieldElement) *FieldElement
  • func (z *FieldElement) ModSqrt(x *FieldElement) *FieldElement
  • func (z *FieldElement) Mul(x, y *FieldElement) *FieldElement
  • func (z *FieldElement) Neg(x *FieldElement) *FieldElement
  • func (z *FieldElement) Set(x *FieldElement) *FieldElement
  • func (z *FieldElement) Sub(x, y *FieldElement) *FieldElement
  • func (z *FieldElement) ToBytes() []byte
• type Jubjub
  • func Curve() *Jubjub
  • func (curve *Jubjub) Add(p1 *Point, p2 *Point) *Point
  • func (curve *Jubjub) Decompress(compressed []byte) (*Point, error)
  • func (curve *Jubjub) Double(p1 *Point) *Point
  • func (curve *Jubjub) FeFromBytes(in []byte) *FieldElement
  • func (curve *Jubjub) Generator() *Point
  • func (curve *Jubjub) Identity() *Point
  • func (curve *Jubjub) ScalarFromBig(n *big.Int) (*Scalar, error)
  • func (curve *Jubjub) ScalarFromBytes(in []byte) (*Scalar, error)
  • func (curve *Jubjub) ScalarMult(scalar *Scalar, point *Point) (*Point, error)
  • func (curve *Jubjub) SubgroupGenerator() *Point
• type Point
  • func (p *Point) Add(p1 *Point, p2 *Point) *Point
  • func (p *Point) Clone() *Point
  • func (p *Point) Compress() []byte
  • func (p *Point) Double(p1 *Point) *Point
  • func (p *Point) Equals(q *Point) bool
  • func (p *Point) IsIdentity() bool
  • func (p *Point) IsOnCurve() bool
  • func (p *Point) MarshalBinary() ([]byte, error)
  • func (p *Point) MulByCofactor() *Point
  • func (p *Point) Neg(q *Point) *Point
  • func (p *Point) UnmarshalBinary(compressed []byte) error
• type Scalar
  • func (sc Scalar) ToBytes() []byte

Variables

var (
	ErrInvalidPoint error = errors.New("not a valid jubjub point")
	ErrIdentity           = errors.New("point was in the h-torsion")
)

var (
	ErrScalarOutOfRange = errors.New("scalar was not in the correct range")
)

Types

type FieldElement

type FieldElement struct {
	// contains filtered or unexported fields
}

FieldElement is an element of an arbitrary integer field.

func (*FieldElement) Add

func (z *FieldElement) Add(x, y *FieldElement) *FieldElement

Add sets z to the sum x+y, reducing the result by the field order, and returns z.

func (*FieldElement) Cmp

func (z *FieldElement) Cmp(x *FieldElement) int

Cmp compares x and y and returns

-1 if x < y
 0 if x == y
+1 if x > y

func (*FieldElement) Equals

func (z *FieldElement) Equals(x *FieldElement) bool

Equals compares two field elements and returns true if they are equal.

func (*FieldElement) Exp

func (z *FieldElement) Exp(x, y *FieldElement) *FieldElement

Exp sets z = x**y mod |m| (i.e. the sign of m is ignored), and returns z. If m == nil or m == 0, z = x**y unless y <= 0 then z = 1. If m > 0, y < 0, and x and n are not relatively prime, z is unchanged and nil is returned. m is always the order of the field.

func (*FieldElement) ModInverse

func (z *FieldElement) ModInverse(x *FieldElement) *FieldElement

ModInverse sets z to the multiplicative inverse of x in the field and returns z.

func (*FieldElement) ModSqrt

func (z *FieldElement) ModSqrt(x *FieldElement) *FieldElement

ModSqrt sets z to a square root of x in the field if such a square root exists, and returns z. If x is not a square in the field, ModSqrt leaves z unchanged and returns nil.

func (*FieldElement) Mul

func (z *FieldElement) Mul(x, y *FieldElement) *FieldElement

Mul sets z to the product x*y, reducing the result by the field order, and returns z.

func (*FieldElement) Neg

func (z *FieldElement) Neg(x *FieldElement) *FieldElement

Neg sets z to -x and returns z.

func (*FieldElement) Set

func (z *FieldElement) Set(x *FieldElement) *FieldElement

Set sets z to x and returns z.

func (*FieldElement) Sub

func (z *FieldElement) Sub(x, y *FieldElement) *FieldElement

Sub sets z to the difference x-y, reducing the result by the field order, and returns z.

func (*FieldElement) ToBytes

func (z *FieldElement) ToBytes() []byte

ToBytes converts z to a little-endian bytestring and returns the bytes.

type Jubjub

type Jubjub struct {
	// contains filtered or unexported fields
}

Jubjub provides a context for working with the Jubjub elliptic curve.

func Curve

func Curve() *Jubjub

Curve initializes a bunch of values needed for working with the Jubjub curve and returns a handle to that context.

func (*Jubjub) Add

func (curve *Jubjub) Add(p1 *Point, p2 *Point) *Point

Add adds p1+p2 and returns a newly allocated result point.

func (*Jubjub) Decompress

func (curve *Jubjub) Decompress(compressed []byte) (*Point, error)

Decompress reads a compressed Edwards point and returns that point or an error if it is invalid.

func (*Jubjub) Double

func (curve *Jubjub) Double(p1 *Point) *Point

Double adds p1+p1 and returns a newly allocated result point.

func (*Jubjub) FeFromBytes

func (curve *Jubjub) FeFromBytes(in []byte) *FieldElement

FeFromBytes reads a field element from little-endian bytes and returns it. If the value is larger than the size of the field, FeFromBytes will return a reduced value.

func (*Jubjub) Generator

func (curve *Jubjub) Generator() *Point

Generator returns a generator for the full 8*q group on Jubjub, the positive point with y-value 11.

func (*Jubjub) Identity

func (curve *Jubjub) Identity() *Point

Identity returns the curve's identity point

func (*Jubjub) ScalarFromBig

func (curve *Jubjub) ScalarFromBig(n *big.Int) (*Scalar, error)

ScalarFromBig converts a big.Int into a Scalar value in the correct range. If the value of the Int is outside the order of the subgroup, ScalarFromBig additionally returns an error indicating this was the case.

func (*Jubjub) ScalarFromBytes

func (curve *Jubjub) ScalarFromBytes(in []byte) (*Scalar, error)

ScalarFromBytes reads a scalar value from little-endian bytes and returns it. If the value of the Int is outside the order of the subgroup, ScalarFromBytes reduces it.

func (*Jubjub) ScalarMult

func (curve *Jubjub) ScalarMult(scalar *Scalar, point *Point) (*Point, error)

ScalarMult multiplies the point by the scalar and returns a newly allocated result point. It returns an error if the point is not on the curve.

func (*Jubjub) SubgroupGenerator

func (curve *Jubjub) SubgroupGenerator() *Point

SubgroupGenerator returns a generator for the prime-order subgroup of Jubjub.

type Point

type Point struct {
	// contains filtered or unexported fields
}

Point is a point on Jubjub.

func (*Point) Add

func (p *Point) Add(p1 *Point, p2 *Point) *Point

Add sets p to the sum p1+p2 and returns p.

func (*Point) Clone

func (p *Point) Clone() *Point

Clone returns a newly allocated copy of p.

func (*Point) Compress

func (p *Point) Compress() []byte

Compress returns a representation of the point in compressed Edwards y format, ignoring whether or not the point is valid. If you are not confident in the provenance of your point, use MarshalBinary directly to receive the error from the check.

func (*Point) Double

func (p *Point) Double(p1 *Point) *Point

Double sets p to the sum p1+p1 and returns p.

func (*Point) Equals

func (p *Point) Equals(q *Point) bool

Equals returns true if p == q and false if they are not.

func (*Point) IsIdentity

func (p *Point) IsIdentity() bool

IsIdentity returns true if the point is the identity point, and false if not.

func (*Point) IsOnCurve

func (p *Point) IsOnCurve() bool

IsOnCurve returns true if the point is on the curve and false if not.

func (*Point) MarshalBinary

func (p *Point) MarshalBinary() ([]byte, error)

MarshalBinary returns the point in "compressed Edwards y" format.

func (*Point) MulByCofactor

func (p *Point) MulByCofactor() *Point

MulByCofactor sets p to the value of h*p and returns p.

func (*Point) Neg

func (p *Point) Neg(q *Point) *Point

Neg sets p to the negated form of q and returns p.

func (*Point) UnmarshalBinary

func (p *Point) UnmarshalBinary(compressed []byte) error

UnmarshalBinary reads a Jubjub point in compressed Edwards y format and attempts to decompress it.

type Scalar

type Scalar struct {
	// contains filtered or unexported fields
}

Scalar is an element of an internally-specified subgroup of specific curve.

func (Scalar) ToBytes

func (sc Scalar) ToBytes() []byte

ToBytes reduces then converts the scalar to a little-endian bytestring.