bls12381

Documentation

Overview

Package bls12381 provides bilinear pairings using the BLS12-381 curve.

A pairing system consists of three groups G1 and G2 (additive notation) and Gt (multiplicative notation) of the same order. Scalars can be used interchangeably between groups.

These groups have the same order equal to:

Order = 0x73eda753299d7d483339d80809a1d80553bda402fffe5bfeffffffff00000001

Serialization Format

Elements of G1 and G2 can be encoded in uncompressed form (the x-coordinate followed by the y-coordinate) or in compressed form (just the x-coordinate). G1 elements occupy 96 bytes in uncompressed form, and 48 bytes in compressed form. G2 elements occupy 192 bytes in uncompressed form, and 96 bytes in compressed form.

The most-significant three bits of a G1 or G2 encoding should be masked away before the coordinates are interpreted. These bits are used to unambiguously represent the underlying element:

* The most significant bit, when set, indicates that the point is in compressed form. Otherwise, the point is in uncompressed form.

* The second-most significant bit indicates that the point is at infinity. If this bit is set, the remaining bits of the group element's encoding should be set to zero.

* The third-most significant bit is set if (and only if) this point is in compressed form AND it is not the point at infinity AND its y-coordinate is the lexicographically largest of the two associated with the encoded x-coordinate.

|----------------------------------------------------|
|                Serialization Format                |
|-----|-------|-------|---------------|--------------|
| MSB | MSB-1 | MSB-2 |  Description  | Encoding     |
|-----|-------|-------|---------------|--------------|
|  0  |   X   |   X   | Uncompressed  |  e || x || y |
|  1  |   X   |   X   | Compressed    |  e || x      |
|-----|-------|-------|---------------|--------------|
|  X  |   0   |   X   | Non-Infinity  |  e || x || y |
|  X  |   1   |   X   | Infinity      |  e || 0 || 0 |
|-----|-------|-------|---------------|--------------|
|     |       |       | Compressed,   |              |
|  1  |   0   |   1   | Non-Infinity, |  e || x      |
|     |       |       | Big y-coord   |              |
|-----|-------|-------|---------------|--------------|
|     |       |       | Compressed,   |              |
|  1  |   0   |   0   | Non-Infinity, |  e || x      |
|     |       |       | Small y-coord |              |
|----------------------------------------------------|

Index

• Constants
• func Order() []byte
• type G1
  • func G1Generator() *G1
  • func (g *G1) Add(P, Q *G1)
  • func (g G1) Bytes() []byte
  • func (g G1) BytesCompressed() []byte
  • func (g *G1) Double()
  • func (g *G1) Encode(input, dst []byte)
  • func (g *G1) Hash(input, dst []byte)
  • func (g *G1) IsEqual(p *G1) bool
  • func (g *G1) IsIdentity() bool
  • func (g *G1) IsOnG1() bool
  • func (g *G1) Neg()
  • func (g *G1) ScalarMult(k *Scalar, P *G1)
  • func (g *G1) SetBytes(b []byte) error
  • func (g *G1) SetIdentity()
  • func (g G1) String() string
• type G2
  • func G2Generator() *G2
  • func (g *G2) Add(P, Q *G2)
  • func (g G2) Bytes() []byte
  • func (g G2) BytesCompressed() []byte
  • func (g *G2) Double()
  • func (g *G2) Encode(input, dst []byte)
  • func (g *G2) Hash(input, dst []byte)
  • func (g *G2) IsEqual(p *G2) bool
  • func (g *G2) IsIdentity() bool
  • func (g *G2) IsOnG2() bool
  • func (g *G2) Neg()
  • func (g *G2) ScalarMult(k *Scalar, P *G2)
  • func (g *G2) SetBytes(b []byte) error
  • func (g *G2) SetIdentity()
  • func (g G2) String() string
• type Gt
  • func Pair(P *G1, Q *G2) *Gt
  • func ProdPair(P []*G1, Q []*G2, n []*Scalar) *Gt
  • func ProdPairFrac(P []*G1, Q []*G2, signs []int) *Gt
  • func (z *Gt) Exp(x *Gt, n *Scalar)
  • func (z *Gt) Inv(x *Gt)
  • func (z Gt) IsEqual(x *Gt) bool
  • func (z Gt) IsIdentity() bool
  • func (z Gt) MarshalBinary() ([]byte, error)
  • func (z *Gt) Mul(x, y *Gt)
  • func (z *Gt) SetIdentity()
  • func (z *Gt) Sqr(x *Gt)
  • func (z Gt) String() string
  • func (z *Gt) UnmarshalBinary(b []byte) error
• type Scalar

Constants

const G1Size = 2 * ff.FpSize

G1Size is the length in bytes of an element in G1 in uncompressed form..

const G1SizeCompressed = ff.FpSize

G1SizeCompressed is the length in bytes of an element in G1 in compressed form.

const G2Size = 2 * ff.Fp2Size

G2Size is the length in bytes of an element in G2 in uncompressed form..

const G2SizeCompressed = ff.Fp2Size

G2SizeCompressed is the length in bytes of an element in G2 in compressed form.

const GtSize = ff.URootSize

GtSize is the length in bytes of an element in Gt.

const ScalarSize = ff.ScalarSize

Functions

func Order

func Order() []byte

Order returns the order of the pairing groups, returned as a big-endian slice.

Order = 0x73eda753299d7d483339d80809a1d80553bda402fffe5bfeffffffff00000001

Types

type G1

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

G1 is a point in the BLS12 curve over Fp.

func G1Generator

func G1Generator() *G1

G1Generator returns the generator point of G1.

func (*G1) Add

func (g *G1) Add(P, Q *G1)

Add updates g=P+Q.

func (G1) Bytes

func (g G1) Bytes() []byte

Bytes serializes a G1 element in uncompressed form.

func (G1) BytesCompressed

func (g G1) BytesCompressed() []byte

Bytes serializes a G1 element in compressed form.

func (*G1) Double

func (g *G1) Double()

Double updates g = 2g.

func (*G1) Encode

func (g *G1) Encode(input, dst []byte)

EncodeToCurve is a non-uniform encoding from an input byte string (and an optional domain separation tag) to elements in G1. This function must not be used as a hash function, otherwise use G1.Hash instead.

func (*G1) Hash

func (g *G1) Hash(input, dst []byte)

Hash produces an element of G1 from the hash of an input byte string and an optional domain separation tag. This function is safe to use when a random oracle returning points in G1 be required.

func (*G1) IsEqual

func (g *G1) IsEqual(p *G1) bool

IsEqual returns true if g and p are equivalent.

func (*G1) IsIdentity

func (g *G1) IsIdentity() bool

IsIdentity return true if the point is the identity of G1.

func (*G1) IsOnG1

func (g *G1) IsOnG1() bool

IsOnG1 returns true if the point is in the group G1.

func (*G1) Neg

func (g *G1) Neg()

Neg inverts g.

func (*G1) ScalarMult

func (g *G1) ScalarMult(k *Scalar, P *G1)

ScalarMult calculates g = kP.

func (*G1) SetBytes

func (g *G1) SetBytes(b []byte) error

SetBytes sets g to the value in bytes, and returns a non-nil error if not in G1.

func (*G1) SetIdentity

func (g *G1) SetIdentity()

SetIdentity assigns g to the identity element.

func (G1) String

func (g G1) String() string

type G2

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

G2 is a point in the twist of the BLS12 curve over Fp2.

func G2Generator

func G2Generator() *G2

G2Generator returns the generator point of G2.

func (*G2) Add

func (g *G2) Add(P, Q *G2)

Add updates g=P+Q.

func (G2) Bytes

func (g G2) Bytes() []byte

Bytes serializes a G2 element in uncompressed form.

func (G2) BytesCompressed

func (g G2) BytesCompressed() []byte

Bytes serializes a G2 element in compressed form.

func (*G2) Double

func (g *G2) Double()

Double updates g = 2g.

func (*G2) Encode

func (g *G2) Encode(input, dst []byte)

EncodeToCurve is a non-uniform encoding from an input byte string (and an optional domain separation tag) to elements in G2. This function must not be used as a hash function, otherwise use G2.Hash instead.

func (*G2) Hash

func (g *G2) Hash(input, dst []byte)

Hash produces an element of G2 from the hash of an input byte string and an optional domain separation tag. This function is safe to use when a random oracle returning points in G2 be required.

func (*G2) IsEqual

func (g *G2) IsEqual(p *G2) bool

IsEqual returns true if g and p are equivalent.

func (*G2) IsIdentity

func (g *G2) IsIdentity() bool

IsIdentity return true if the point is the identity of G2.

func (*G2) IsOnG2

func (g *G2) IsOnG2() bool

IsOnG2 returns true if the point is in the group G2.

func (*G2) Neg

func (g *G2) Neg()

Neg inverts g.

func (*G2) ScalarMult

func (g *G2) ScalarMult(k *Scalar, P *G2)

ScalarMult calculates g = kP.

func (*G2) SetBytes

func (g *G2) SetBytes(b []byte) error

SetBytes sets g to the value in bytes, and returns a non-nil error if not in G2.

func (*G2) SetIdentity

func (g *G2) SetIdentity()

SetIdentity assigns g to the identity element.

func (G2) String

func (g G2) String() string

type Gt

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

Gt represents an element of the output (multiplicative) group of a pairing.

func Pair

func Pair(P *G1, Q *G2) *Gt

Pair calculates the ate-pairing of P and Q.

func ProdPair

func ProdPair(P []*G1, Q []*G2, n []*Scalar) *Gt

ProdPair calculates the product of pairings, i.e., \Prod_i pair(Pi,Qi)^ni.

func ProdPairFrac

func ProdPairFrac(P []*G1, Q []*G2, signs []int) *Gt

ProdPairFrac computes the product e(P, Q)^sign where sign is 1 or -1

func (*Gt) Exp

func (z *Gt) Exp(x *Gt, n *Scalar)

Exp calculates z=x^n, where n is the exponent in big-endian order.

func (*Gt) Inv

func (z *Gt) Inv(x *Gt)

func (Gt) IsEqual

func (z Gt) IsEqual(x *Gt) bool

func (Gt) IsIdentity

func (z Gt) IsIdentity() bool

func (Gt) MarshalBinary

func (z Gt) MarshalBinary() ([]byte, error)

func (*Gt) Mul

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

func (*Gt) SetIdentity

func (z *Gt) SetIdentity()

func (*Gt) Sqr

func (z *Gt) Sqr(x *Gt)

func (Gt) String

func (z Gt) String() string

func (*Gt) UnmarshalBinary

func (z *Gt) UnmarshalBinary(b []byte) error

type Scalar

type Scalar = ff.Scalar

Scalar represents positive integers in the range 0 <= x < Order.