bls12381

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 16, 2021 License: Apache-2.0 Imports: 9 Imported by: 54

README

High Speed BLS12-381 Implementation in Go

Pairing Instance

A Group instance or a pairing engine instance is not suitable for concurrent processing since an instance has its own preallocated memory for temporary variables. A new instance must be created for each thread.

Base Field

x86 optimized base field is generated with kilic/fp and for native go is generated with goff. Generated codes are slightly edited in both for further requirements.

Scalar Field

Both standart big.Int module and x86 optimized implementation are available for scalar field elements and opereations.

Serialization

Point serialization is in line with zkcrypto library.

Hashing to Curve

Hashing to curve implementations for both G1 and G2 follows _XMD:SHA-256_SSWU_RO_ and _XMD:SHA-256_SSWU_NU_ suites as defined in v7 of irtf hash to curve draft.

Benchmarks

on 2.3 GHz i7

BenchmarkPairing  882553 ns/op

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var G1One = g1One
View Source 
var G2One = g2One

Functions

This section is empty.

Types

type E 

type E = fe12

E is type for target group element

func (*E) Equal 

func (g *E) Equal(g2 *E) bool

Equal returns true if given two element is equal, otherwise returns false

func (*E) IsOne 

func (e *E) IsOne() bool

IsOne returns true if given element equals to one

func (*E) One 

func (e *E) One() *E

One sets a new target group element to one

func (*E) Set 

func (e *E) Set(e2 *E) *E

Set copies given value into the destination

type Engine 

type Engine struct {
	G1 *G1
	G2 *G2
	// contains filtered or unexported fields
}

Engine is BLS12-381 elliptic curve pairing engine

func NewEngine 

func NewEngine() *Engine

NewEngine creates new pairing engine insteace.

func (*Engine) AddPair 

func (e *Engine) AddPair(g1 *PointG1, g2 *PointG2) *Engine

AddPair adds a g1, g2 point pair to pairing engine

func (*Engine) AddPairInv 

func (e *Engine) AddPairInv(g1 *PointG1, g2 *PointG2) *Engine

AddPairInv adds a G1, G2 point pair to pairing engine. G1 point is negated.

func (*Engine) Check 

func (e *Engine) Check() bool

Check computes pairing and checks if result is equal to one

func (*Engine) GT 

func (e *Engine) GT() *GT

GT returns target group instance.

func (*Engine) Reset 

func (e *Engine) Reset() *Engine

Reset deletes added pairs.

func (*Engine) Result 

func (e *Engine) Result() *E

Result computes pairing and returns target group element as result.

type Fr 

type Fr [4]uint64

func NewFr 

func NewFr() *Fr

func (*Fr) Add 

func (e *Fr) Add(a, b *Fr)

func (*Fr) Bit 

func (e *Fr) Bit(at int) bool

func (*Fr) Cmp 

func (e *Fr) Cmp(e1 *Fr) int

func (*Fr) Double 

func (e *Fr) Double(a *Fr)

func (*Fr) Equal 

func (e *Fr) Equal(e2 *Fr) bool

func (*Fr) Exp 

func (e *Fr) Exp(a *Fr, ee *big.Int)

func (*Fr) FromBytes 

func (e *Fr) FromBytes(in []byte) *Fr

func (*Fr) FromRed 

func (e *Fr) FromRed()

func (*Fr) Inverse 

func (e *Fr) Inverse(a *Fr)

func (*Fr) IsOne 

func (e *Fr) IsOne() bool

func (*Fr) IsRedOne 

func (e *Fr) IsRedOne() bool

func (*Fr) IsZero 

func (e *Fr) IsZero() bool

func (*Fr) Mul 

func (e *Fr) Mul(a, b *Fr)

func (*Fr) Neg 

func (e *Fr) Neg(a *Fr)

func (*Fr) One 

func (e *Fr) One() *Fr

func (*Fr) Rand 

func (e *Fr) Rand(r io.Reader) (*Fr, error)

func (*Fr) RedExp 

func (e *Fr) RedExp(a *Fr, ee *big.Int)

func (*Fr) RedFromBytes 

func (e *Fr) RedFromBytes(in []byte) *Fr

func (*Fr) RedInverse 

func (e *Fr) RedInverse(ei *Fr)

func (*Fr) RedMul 

func (e *Fr) RedMul(a, b *Fr)

func (*Fr) RedOne 

func (e *Fr) RedOne() *Fr

func (*Fr) RedSquare 

func (e *Fr) RedSquare(a *Fr)

func (*Fr) RedToBig 

func (e *Fr) RedToBig() *big.Int

func (*Fr) RedToBytes 

func (e *Fr) RedToBytes() []byte

func (*Fr) Set 

func (e *Fr) Set(e2 *Fr) *Fr

func (*Fr) Square 

func (e *Fr) Square(a *Fr)

func (*Fr) Sub 

func (e *Fr) Sub(a, b *Fr)

func (*Fr) ToBig 

func (e *Fr) ToBig() *big.Int

func (*Fr) ToBytes 

func (e *Fr) ToBytes() []byte

func (*Fr) ToRed 

func (e *Fr) ToRed()

func (*Fr) Zero 

func (e *Fr) Zero() *Fr

type G1 

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

G1 is struct for G1 group.

func NewG1 

func NewG1() *G1

NewG1 constructs a new G1 instance.

func (*G1) Add 

func (g *G1) Add(r, p1, p2 *PointG1) *PointG1

Add adds two G1 points p1, p2 and assigns the result to point at first argument.

func (*G1) AddMixed 

func (g *G1) AddMixed(r, p1, p2 *PointG1) *PointG1

Add adds two G1 points p1, p2 and assigns the result to point at first argument. Expects the second point p2 in affine form.

func (*G1) Affine 

func (g *G1) Affine(p *PointG1) *PointG1

Affine returns the affine representation of the given point

func (*G1) AffineBatch 

func (g *G1) AffineBatch(p []*PointG1)

AffineBatch given multiple of points returns affine representations

func (*G1) ClearCofactor 

func (g *G1) ClearCofactor(p *PointG1) *PointG1

func (*G1) Double 

func (g *G1) Double(r, p *PointG1) *PointG1

Double doubles a G1 point p and assigns the result to the point at first argument.

func (*G1) EncodeToCurve 

func (g *G1) EncodeToCurve(msg, domain []byte) (*PointG1, error)

EncodeToCurve given a message and domain seperator tag returns the hash result which is a valid curve point. Implementation follows BLS12381G1_XMD:SHA-256_SSWU_NU_ suite at https://tools.ietf.org/html/draft-irtf-cfrg-hash-to-curve-06

func (*G1) Equal 

func (g *G1) Equal(p1, p2 *PointG1) bool

Equal checks if given two G1 point is equal in their affine form.

func (*G1) FromBytes 

func (g *G1) FromBytes(in []byte) (*PointG1, error)

FromBytes constructs a new point given uncompressed byte input. Input string is expected to be equal to 96 bytes and concatenation of x and y cooridanates. (0, 0) is considered as infinity.

func (*G1) FromCompressed 

func (g *G1) FromCompressed(compressed []byte) (*PointG1, error)

FromCompressed expects byte slice at least 48 bytes and given bytes returns a new point in G1. Serialization rules are in line with zcash library. See below for details. https://github.com/zcash/librustzcash/blob/master/pairing/src/bls12_381/README.md#serialization https://docs.rs/bls12_381/0.1.1/bls12_381/notes/serialization/index.html

func (*G1) FromUncompressed 

func (g *G1) FromUncompressed(uncompressed []byte) (*PointG1, error)

FromUncompressed expects byte slice at least 96 bytes and given bytes returns a new point in G1. Serialization rules are in line with zcash library. See below for details. https://github.com/zcash/librustzcash/blob/master/pairing/src/bls12_381/README.md#serialization https://docs.rs/bls12_381/0.1.1/bls12_381/notes/serialization/index.html

func (*G1) HashToCurve 

func (g *G1) HashToCurve(msg, domain []byte) (*PointG1, error)

HashToCurve given a message and domain seperator tag returns the hash result which is a valid curve point. Implementation follows BLS12381G1_XMD:SHA-256_SSWU_RO_ suite at https://tools.ietf.org/html/draft-irtf-cfrg-hash-to-curve-06

func (*G1) InCorrectSubgroup 

func (g *G1) InCorrectSubgroup(p *PointG1) bool

InCorrectSubgroup checks whether given point is in correct subgroup.

func (*G1) IsAffine 

func (g *G1) IsAffine(p *PointG1) bool

IsAffine checks a G1 point whether it is in affine form.

func (*G1) IsOnCurve 

func (g *G1) IsOnCurve(p *PointG1) bool

IsOnCurve checks a G1 point is on curve.

func (*G1) IsZero 

func (g *G1) IsZero(p *PointG1) bool

IsZero returns true if given point is equal to zero.

func (*G1) MapToCurve 

func (g *G1) MapToCurve(in []byte) (*PointG1, error)

MapToCurve given a byte slice returns a valid G1 point. This mapping function implements the Simplified Shallue-van de Woestijne-Ulas method. https://tools.ietf.org/html/draft-irtf-cfrg-hash-to-curve-06 Input byte slice should be a valid field element, otherwise an error is returned.

func (*G1) MulScalar 

func (g *G1) MulScalar(r, p *PointG1, e *Fr) *PointG1

MulScalar multiplies a point by given scalar value and assigns the result to point at first argument.

func (*G1) MulScalarBig 

func (g *G1) MulScalarBig(r, p *PointG1, e *big.Int) *PointG1

MulScalar multiplies a point by given scalar value in big.Int and assigns the result to point at first argument.

func (*G1) MultiExp 

func (g *G1) MultiExp(r *PointG1, points []*PointG1, scalars []*Fr) (*PointG1, error)

MultiExp calculates multi exponentiation. Given pairs of G1 point and scalar values `(P_0, e_0), (P_1, e_1), ... (P_n, e_n)`, calculates `r = e_0 * P_0 + e_1 * P_1 + ... + e_n * P_n`. Length of points and scalars are expected to be equal, otherwise an error is returned. Result is assigned to point at first argument.

func (*G1) MultiExpBig 

func (g *G1) MultiExpBig(r *PointG1, points []*PointG1, scalars []*big.Int) (*PointG1, error)

MultiExpBig calculates multi exponentiation. Scalar values are received as big.Int type. Given pairs of G1 point and scalar values `(P_0, e_0), (P_1, e_1), ... (P_n, e_n)`, calculates `r = e_0 * P_0 + e_1 * P_1 + ... + e_n * P_n`. Length of points and scalars are expected to be equal, otherwise an error is returned. Result is assigned to point at first argument.

func (*G1) Neg 

func (g *G1) Neg(r, p *PointG1) *PointG1

Neg negates a G1 point p and assigns the result to the point at first argument.

func (*G1) New 

func (g *G1) New() *PointG1

New creates a new G1 Point which is equal to zero in other words point at infinity.

func (*G1) One 

func (g *G1) One() *PointG1

One returns a new G1 Point which is equal to generator point.

func (*G1) Q 

func (g *G1) Q() *big.Int

Q returns group order in big.Int.

func (*G1) Sub 

func (g *G1) Sub(c, a, b *PointG1) *PointG1

Sub subtracts two G1 points p1, p2 and assigns the result to point at first argument.

func (*G1) ToBytes 

func (g *G1) ToBytes(p *PointG1) []byte

ToBytes serializes a point into bytes in uncompressed form. ToBytes returns (0, 0) if point is infinity.

func (*G1) ToCompressed 

func (g *G1) ToCompressed(p *PointG1) []byte

ToCompressed given a G1 point returns bytes in compressed form of the point. Serialization rules are in line with zcash library. See below for details. https://github.com/zcash/librustzcash/blob/master/pairing/src/bls12_381/README.md#serialization https://docs.rs/bls12_381/0.1.1/bls12_381/notes/serialization/index.html

func (*G1) ToUncompressed 

func (g *G1) ToUncompressed(p *PointG1) []byte

ToUncompressed given a G1 point returns bytes in uncompressed (x, y) form of the point. Serialization rules are in line with zcash library. See below for details. https://github.com/zcash/librustzcash/blob/master/pairing/src/bls12_381/README.md#serialization https://docs.rs/bls12_381/0.1.1/bls12_381/notes/serialization/index.html

func (*G1) Zero 

func (g *G1) Zero() *PointG1

Zero returns a new G1 Point which is equal to point at infinity.

type G2 

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

G2 is struct for G2 group.

func NewG2 

func NewG2() *G2

NewG2 constructs a new G2 instance.

func (*G2) Add 

func (g *G2) Add(r, p1, p2 *PointG2) *PointG2

Add adds two G2 points p1, p2 and assigns the result to point at first argument.

func (*G2) AddMixed 

func (g *G2) AddMixed(r, p1, p2 *PointG2) *PointG2

Add adds two G1 points p1, p2 and assigns the result to point at first argument. Expects the second point p2 in affine form.

func (*G2) Affine 

func (g *G2) Affine(p *PointG2) *PointG2

Affine calculates affine form of given G2 point.

func (*G2) AffineBatch 

func (g *G2) AffineBatch(p []*PointG2)

AffineBatch given multiple of points returns affine representations

func (*G2) ClearCofactor 

func (g *G2) ClearCofactor(p *PointG2) *PointG2

ClearCofactor maps given a G2 point to correct subgroup

func (*G2) Double 

func (g *G2) Double(r, p *PointG2) *PointG2

Double doubles a G2 point p and assigns the result to the point at first argument.

func (*G2) EncodeToCurve 

func (g *G2) EncodeToCurve(msg, domain []byte) (*PointG2, error)

EncodeToCurve given a message and domain seperator tag returns the hash result which is a valid curve point. Implementation follows BLS12381G1_XMD:SHA-256_SSWU_NU_ suite at https://tools.ietf.org/html/draft-irtf-cfrg-hash-to-curve-06

func (*G2) Equal 

func (g *G2) Equal(p1, p2 *PointG2) bool

Equal checks if given two G2 point is equal in their affine form.

func (*G2) FromBytes 

func (g *G2) FromBytes(in []byte) (*PointG2, error)

FromBytes constructs a new point given uncompressed byte input. Input string expected to be 192 bytes and concatenation of x and y values Point (0, 0) is considered as infinity.

func (*G2) FromCompressed 

func (g *G2) FromCompressed(compressed []byte) (*PointG2, error)

FromCompressed expects byte slice at least 96 bytes and given bytes returns a new point in G2. Serialization rules are in line with zcash library. See below for details. https://github.com/zcash/librustzcash/blob/master/pairing/src/bls12_381/README.md#serialization https://docs.rs/bls12_381/0.1.1/bls12_381/notes/serialization/index.html

func (*G2) FromUncompressed 

func (g *G2) FromUncompressed(uncompressed []byte) (*PointG2, error)

FromUncompressed expects byte slice at least 192 bytes and given bytes returns a new point in G2. Serialization rules are in line with zcash library. See below for details. https://github.com/zcash/librustzcash/blob/master/pairing/src/bls12_381/README.md#serialization https://docs.rs/bls12_381/0.1.1/bls12_381/notes/serialization/index.html

func (*G2) HashToCurve 

func (g *G2) HashToCurve(msg, domain []byte) (*PointG2, error)

HashToCurve given a message and domain seperator tag returns the hash result which is a valid curve point. Implementation follows BLS12381G1_XMD:SHA-256_SSWU_RO_ suite at https://tools.ietf.org/html/draft-irtf-cfrg-hash-to-curve-06

func (*G2) InCorrectSubgroup 

func (g *G2) InCorrectSubgroup(p *PointG2) bool

InCorrectSubgroup checks whether given point is in correct subgroup.

func (*G2) IsAffine 

func (g *G2) IsAffine(p *PointG2) bool

IsAffine checks a G2 point whether it is in affine form.

func (*G2) IsOnCurve 

func (g *G2) IsOnCurve(p *PointG2) bool

IsOnCurve checks a G2 point is on curve.

func (*G2) IsZero 

func (g *G2) IsZero(p *PointG2) bool

IsZero returns true if given point is equal to zero.

func (*G2) MapToCurve 

func (g *G2) MapToCurve(in []byte) (*PointG2, error)

MapToCurve given a byte slice returns a valid G2 point. This mapping function implements the Simplified Shallue-van de Woestijne-Ulas method. https://tools.ietf.org/html/draft-irtf-cfrg-hash-to-curve-05#section-6.6.2 Input byte slice should be a valid field element, otherwise an error is returned.

func (*G2) MulScalar 

func (g *G2) MulScalar(r, p *PointG2, e *Fr) *PointG2

MulScalar multiplies a point by given scalar value and assigns the result to point at first argument.

func (*G2) MulScalarBig 

func (g *G2) MulScalarBig(r, p *PointG2, e *big.Int) *PointG2

MulScalarBig multiplies a point by given scalar value in big.Int and assigns the result to point at first argument.

func (*G2) MultiExp 

func (g *G2) MultiExp(r *PointG2, points []*PointG2, scalars []*Fr) (*PointG2, error)

MultiExp calculates multi exponentiation. Given pairs of G2 point and scalar values `(P_0, e_0), (P_1, e_1), ... (P_n, e_n)`, calculates `r = e_0 * P_0 + e_1 * P_1 + ... + e_n * P_n`. Length of points and scalars are expected to be equal, otherwise an error is returned. Result is assigned to point at first argument.

func (*G2) MultiExpBig 

func (g *G2) MultiExpBig(r *PointG2, points []*PointG2, scalars []*big.Int) (*PointG2, error)

MultiExpBig calculates multi exponentiation. Scalar values are received as big.Int type. Given pairs of G2 point and scalar values `(P_0, e_0), (P_1, e_1), ... (P_n, e_n)`, calculates `r = e_0 * P_0 + e_1 * P_1 + ... + e_n * P_n`. Length of points and scalars are expected to be equal, otherwise an error is returned. Result is assigned to point at first argument.

func (*G2) Neg 

func (g *G2) Neg(r, p *PointG2) *PointG2

Neg negates a G2 point p and assigns the result to the point at first argument.

func (*G2) New 

func (g *G2) New() *PointG2

New creates a new G2 Point which is equal to zero in other words point at infinity.

func (*G2) One 

func (g *G2) One() *PointG2

One returns a new G2 Point which is equal to generator point.

func (*G2) Q 

func (g *G2) Q() *big.Int

Q returns group order in big.Int.

func (*G2) Sub 

func (g *G2) Sub(c, a, b *PointG2) *PointG2

Sub subtracts two G2 points p1, p2 and assigns the result to point at first argument.

func (*G2) ToBytes 

func (g *G2) ToBytes(p *PointG2) []byte

ToBytes serializes a point into bytes in uncompressed form, returns (0, 0) if point is infinity.

func (*G2) ToCompressed 

func (g *G2) ToCompressed(p *PointG2) []byte

ToCompressed given a G2 point returns bytes in compressed form of the point. Serialization rules are in line with zcash library. See below for details. https://github.com/zcash/librustzcash/blob/master/pairing/src/bls12_381/README.md#serialization https://docs.rs/bls12_381/0.1.1/bls12_381/notes/serialization/index.html

func (*G2) ToUncompressed 

func (g *G2) ToUncompressed(p *PointG2) []byte

ToUncompressed given a G2 point returns bytes in uncompressed (x, y) form of the point. Serialization rules are in line with zcash library. See below for details. https://github.com/zcash/librustzcash/blob/master/pairing/src/bls12_381/README.md#serialization https://docs.rs/bls12_381/0.1.1/bls12_381/notes/serialization/index.html

func (*G2) Zero 

func (g *G2) Zero() *PointG2

Zero returns a new G2 Point which is equal to point at infinity.

type GT 

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

GT is type for target multiplicative group GT.

func NewGT 

func NewGT() *GT

NewGT constructs new target group instance.

func (*GT) Add 

func (g *GT) Add(c, a, b *E)

Add adds two field element `a` and `b` and assigns the result to the element in first argument.

func (*GT) Exp 

func (g *GT) Exp(c, a *E, s *big.Int)

Exp exponents an element `a` by a scalar `s` and assigns the result to the element in first argument.

func (*GT) FromBytes 

func (g *GT) FromBytes(in []byte) (*E, error)

FromBytes expects 576 byte input and returns target group element FromBytes returns error if given element is not on correct subgroup.

func (*GT) Inverse 

func (g *GT) Inverse(c, a *E)

Inverse inverses an element `a` and assigns the result to the element in first argument.

func (*GT) IsValid 

func (g *GT) IsValid(e *E) bool

IsValid checks whether given target group element is in correct subgroup.

func (*GT) Mul 

func (g *GT) Mul(c, a, b *E)

Mul multiplies two field element `a` and `b` and assigns the result to the element in first argument.

func (*GT) New 

func (g *GT) New() *E

New initializes a new target group element which is equal to one

func (*GT) Q 

func (g *GT) Q() *big.Int

Q returns group order in big.Int.

func (*GT) Square 

func (g *GT) Square(c, a *E)

Square squares an element `a` and assigns the result to the element in first argument.

func (*GT) Sub 

func (g *GT) Sub(c, a, b *E)

Sub subtracts two field element `a` and `b`, and assigns the result to the element in first argument.

func (*GT) ToBytes 

func (g *GT) ToBytes(e *E) []byte

ToBytes serializes target group element.

type PointG1 

type PointG1 [3]fe

PointG1 is type for point in G1 and used for both Affine and Jacobian point representation. A point is accounted as in affine form if z is equal to one.

func (*PointG1) IsAffine 

func (p *PointG1) IsAffine() bool

IsAffine checks a G1 point whether it is in affine form.

func (*PointG1) Set 

func (p *PointG1) Set(p2 *PointG1) *PointG1

func (*PointG1) Zero 

func (p *PointG1) Zero() *PointG1

type PointG2 

type PointG2 [3]fe2

PointG2 is type for point in G2 and used for both affine and Jacobian representation. A point is accounted as in affine form if z is equal to one.

func (*PointG2) IsAffine 

func (p *PointG2) IsAffine() bool

IsAffine checks a G1 point whether it is in affine form.

func (*PointG2) Set 

func (p *PointG2) Set(p2 *PointG2) *PointG2

Set copies valeus of one point to another.

func (*PointG2) Zero 

func (p *PointG2) Zero() *PointG2

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.