Documentation ¶
Overview ¶
Package bls12381 efficient elliptic curve, pairing and hash to curve implementation for bls12-381.
bls12-381: A Barreto--Lynn--Scott curve
embedding degree k=12 seed x₀=-15132376222941642752 𝔽r: r=52435875175126190479447740508185965837690552500527637822603658699938581184513 (x₀⁴-x₀²+1) 𝔽p: p=4002409555221667393417789825735904156556882819939007885332058136124031650490837864442687629129015664037894272559787 ((x₀-1)² ⋅ r(x₀)/3+x₀) (E/𝔽p): Y²=X³+4 (Eₜ/𝔽p²): Y² = X³+4(u+1) (M-type twist) r ∣ #E(Fp) and r ∣ #Eₜ(𝔽p²)
Extension fields tower:
𝔽p²[u] = 𝔽p/u²+1 𝔽p⁶[v] = 𝔽p²/v³-1-u 𝔽p¹²[w] = 𝔽p⁶/w²-v
optimal Ate loop size:
x₀
Security: estimated 126-bit level following [https://eprint.iacr.org/2019/885.pdf] (r is 255 bits and p¹² is 4569 bits)
Warning ¶
This code has been partially audited and is provided as-is. In particular, there is no security guarantees such as constant time implementation or side-channel attack resistance.
Index ¶
- Constants
- func Generators() (g1Jac G1Jac, g2Jac G2Jac, g1Aff G1Affine, g2Aff G2Affine)
- func NoSubgroupChecks() func(*Decoder)
- func PairingCheck(P []G1Affine, Q []G2Affine) (bool, error)
- func RawEncoding() func(*Encoder)
- type Decoder
- type Encoder
- type G1Affine
- func (p *G1Affine) Add(a, b *G1Affine) *G1Affine
- func (p *G1Affine) Bytes() (res [SizeOfG1AffineCompressed]byte)
- func (p *G1Affine) ClearCofactor(a *G1Affine) *G1Affine
- func (p *G1Affine) Equal(a *G1Affine) bool
- func (p *G1Affine) FromJacobian(p1 *G1Jac) *G1Affine
- func (p *G1Affine) IsInSubGroup() bool
- func (p *G1Affine) IsInfinity() bool
- func (p *G1Affine) IsOnCurve() bool
- func (p *G1Affine) Marshal() []byte
- func (p *G1Affine) MultiExp(points []G1Affine, scalars []fr.Element, config ecc.MultiExpConfig) (*G1Affine, error)
- func (p *G1Affine) Neg(a *G1Affine) *G1Affine
- func (p *G1Affine) RawBytes() (res [SizeOfG1AffineUncompressed]byte)
- func (p *G1Affine) ScalarMultiplication(a *G1Affine, s *big.Int) *G1Affine
- func (p *G1Affine) Set(a *G1Affine) *G1Affine
- func (p *G1Affine) SetBytes(buf []byte) (int, error)
- func (p *G1Affine) String() string
- func (p *G1Affine) Sub(a, b *G1Affine) *G1Affine
- func (p *G1Affine) Unmarshal(buf []byte) error
- type G1Jac
- func (p *G1Jac) AddAssign(a *G1Jac) *G1Jac
- func (p *G1Jac) AddMixed(a *G1Affine) *G1Jac
- func (p *G1Jac) ClearCofactor(a *G1Jac) *G1Jac
- func (p *G1Jac) Double(q *G1Jac) *G1Jac
- func (p *G1Jac) DoubleAssign() *G1Jac
- func (p *G1Jac) Equal(a *G1Jac) bool
- func (p *G1Jac) FromAffine(Q *G1Affine) *G1Jac
- func (p *G1Jac) IsInSubGroup() bool
- func (p *G1Jac) IsOnCurve() bool
- func (p *G1Jac) MultiExp(points []G1Affine, scalars []fr.Element, config ecc.MultiExpConfig) (*G1Jac, error)
- func (p *G1Jac) Neg(a *G1Jac) *G1Jac
- func (p *G1Jac) ScalarMultiplication(a *G1Jac, s *big.Int) *G1Jac
- func (p *G1Jac) ScalarMultiplicationAffine(a *G1Affine, s *big.Int) *G1Jac
- func (p *G1Jac) Set(a *G1Jac) *G1Jac
- func (p *G1Jac) String() string
- func (p *G1Jac) SubAssign(a *G1Jac) *G1Jac
- type G2Affine
- func (p *G2Affine) Add(a, b *G2Affine) *G2Affine
- func (p *G2Affine) Bytes() (res [SizeOfG2AffineCompressed]byte)
- func (p *G2Affine) ClearCofactor(a *G2Affine) *G2Affine
- func (p *G2Affine) Equal(a *G2Affine) bool
- func (p *G2Affine) FromJacobian(p1 *G2Jac) *G2Affine
- func (p *G2Affine) IsInSubGroup() bool
- func (p *G2Affine) IsInfinity() bool
- func (p *G2Affine) IsOnCurve() bool
- func (p *G2Affine) Marshal() []byte
- func (p *G2Affine) MultiExp(points []G2Affine, scalars []fr.Element, config ecc.MultiExpConfig) (*G2Affine, error)
- func (p *G2Affine) Neg(a *G2Affine) *G2Affine
- func (p *G2Affine) RawBytes() (res [SizeOfG2AffineUncompressed]byte)
- func (p *G2Affine) ScalarMultiplication(a *G2Affine, s *big.Int) *G2Affine
- func (p *G2Affine) Set(a *G2Affine) *G2Affine
- func (p *G2Affine) SetBytes(buf []byte) (int, error)
- func (p *G2Affine) String() string
- func (p *G2Affine) Sub(a, b *G2Affine) *G2Affine
- func (p *G2Affine) Unmarshal(buf []byte) error
- type G2Jac
- func (p *G2Jac) AddAssign(a *G2Jac) *G2Jac
- func (p *G2Jac) AddMixed(a *G2Affine) *G2Jac
- func (p *G2Jac) ClearCofactor(a *G2Jac) *G2Jac
- func (p *G2Jac) Double(q *G2Jac) *G2Jac
- func (p *G2Jac) DoubleAssign() *G2Jac
- func (p *G2Jac) Equal(a *G2Jac) bool
- func (p *G2Jac) FromAffine(Q *G2Affine) *G2Jac
- func (p *G2Jac) IsInSubGroup() bool
- func (p *G2Jac) IsOnCurve() bool
- func (p *G2Jac) MultiExp(points []G2Affine, scalars []fr.Element, config ecc.MultiExpConfig) (*G2Jac, error)
- func (p *G2Jac) Neg(a *G2Jac) *G2Jac
- func (p *G2Jac) ScalarMultiplication(a *G2Jac, s *big.Int) *G2Jac
- func (p *G2Jac) Set(a *G2Jac) *G2Jac
- func (p *G2Jac) String() string
- func (p *G2Jac) SubAssign(a *G2Jac) *G2Jac
- type GT
Constants ¶
const ID = ecc.BLS12_381
ID bls381 ID
const SizeOfG1AffineCompressed = 48
SizeOfG1AffineCompressed represents the size in bytes that a G1Affine need in binary form, compressed
const SizeOfG1AffineUncompressed = SizeOfG1AffineCompressed * 2
SizeOfG1AffineUncompressed represents the size in bytes that a G1Affine need in binary form, uncompressed
const SizeOfG2AffineCompressed = 48 * 2
SizeOfG2AffineCompressed represents the size in bytes that a G2Affine need in binary form, compressed
const SizeOfG2AffineUncompressed = SizeOfG2AffineCompressed * 2
SizeOfG2AffineUncompressed represents the size in bytes that a G2Affine need in binary form, uncompressed
const SizeOfGT = fptower.SizeOfGT
SizeOfGT represents the size in bytes that a GT element need in binary form
Variables ¶
This section is empty.
Functions ¶
func Generators ¶
Generators return the generators of the r-torsion group, resp. in ker(pi-id), ker(Tr)
func NoSubgroupChecks ¶
func NoSubgroupChecks() func(*Decoder)
NoSubgroupChecks returns an option to use in NewDecoder(...) which disable subgroup checks on the points the decoder will read. Use with caution, as crafted points from an untrusted source can lead to crypto-attacks.
func PairingCheck ¶
PairingCheck calculates the reduced pairing for a set of points and returns True if the result is One ∏ᵢ e(Pᵢ, Qᵢ) =? 1
This function doesn't check that the inputs are in the correct subgroup. See IsInSubGroup.
func RawEncoding ¶
func RawEncoding() func(*Encoder)
RawEncoding returns an option to use in NewEncoder(...) which sets raw encoding mode to true points will not be compressed using this option
Types ¶
type Decoder ¶
type Decoder struct {
// contains filtered or unexported fields
}
Decoder reads bls12-381 object values from an inbound stream
func NewDecoder ¶
NewDecoder returns a binary decoder supporting curve bls12-381 objects in both compressed and uncompressed (raw) forms
type Encoder ¶
type Encoder struct {
// contains filtered or unexported fields
}
Encoder writes bls12-381 object values to an output stream
func NewEncoder ¶
NewEncoder returns a binary encoder supporting curve bls12-381 objects
func (*Encoder) BytesWritten ¶
BytesWritten return total bytes written on writer
type G1Affine ¶
G1Affine point in affine coordinates
func BatchJacobianToAffineG1 ¶
BatchJacobianToAffineG1 converts points in Jacobian coordinates to Affine coordinates performing a single field inversion (Montgomery batch inversion trick).
func BatchScalarMultiplicationG1 ¶
BatchScalarMultiplicationG1 multiplies the same base by all scalars and return resulting points in affine coordinates uses a simple windowed-NAF like exponentiation algorithm
func EncodeToG1 ¶
EncodeToG1 hashes a message to a point on the G1 curve using the SSWU map. It is faster than HashToG1, but the result is not uniformly distributed. Unsuitable as a random oracle. dst stands for "domain separation tag", a string unique to the construction using the hash function https://www.ietf.org/archive/id/draft-irtf-cfrg-hash-to-curve-16.html#roadmap
func HashToG1 ¶
HashToG1 hashes a message to a point on the G1 curve using the SSWU map. Slower than EncodeToG1, but usable as a random oracle. dst stands for "domain separation tag", a string unique to the construction using the hash function https://www.ietf.org/archive/id/draft-irtf-cfrg-hash-to-curve-16.html#roadmap
func (*G1Affine) Add ¶
Add adds two point in affine coordinates. This should rarely be used as it is very inefficient compared to Jacobian
func (*G1Affine) Bytes ¶
func (p *G1Affine) Bytes() (res [SizeOfG1AffineCompressed]byte)
Bytes returns binary representation of p will store X coordinate in regular form and a parity bit we follow the BLS12-381 style encoding as specified in ZCash and now IETF
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.
func (*G1Affine) ClearCofactor ¶
ClearCofactor maps a point in curve to r-torsion
func (*G1Affine) FromJacobian ¶
FromJacobian rescales a point in Jacobian coord in z=1 plane
func (*G1Affine) IsInSubGroup ¶
IsInSubGroup returns true if p is in the correct subgroup, false otherwise
func (*G1Affine) IsInfinity ¶
IsInfinity checks if the point is infinity in affine, it's encoded as (0,0) (0,0) is never on the curve for j=0 curves
func (*G1Affine) MultiExp ¶
func (p *G1Affine) MultiExp(points []G1Affine, scalars []fr.Element, config ecc.MultiExpConfig) (*G1Affine, error)
MultiExp implements section 4 of https://eprint.iacr.org/2012/549.pdf
This call return an error if len(scalars) != len(points) or if provided config is invalid.
func (*G1Affine) RawBytes ¶
func (p *G1Affine) RawBytes() (res [SizeOfG1AffineUncompressed]byte)
RawBytes returns binary representation of p (stores X and Y coordinate) see Bytes() for a compressed representation
func (*G1Affine) ScalarMultiplication ¶
ScalarMultiplication computes and returns p = a ⋅ s
func (*G1Affine) SetBytes ¶
SetBytes sets p from binary representation in buf and returns number of consumed bytes
bytes in buf must match either RawBytes() or Bytes() output
if buf is too short io.ErrShortBuffer is returned
if buf contains compressed representation (output from Bytes()) and we're unable to compute the Y coordinate (i.e the square root doesn't exist) this function returns an error
this check if the resulting point is on the curve and in the correct subgroup
func (*G1Affine) String ¶
String returns the string representation of the point or "O" if it is infinity
type G1Jac ¶
G1Jac is a point with fp.Element coordinates
func (*G1Jac) AddAssign ¶
AddAssign point addition in montgomery form https://hyperelliptic.org/EFD/g1p/auto-shortw-jacobian-3.html#addition-add-2007-bl
func (*G1Jac) AddMixed ¶
AddMixed point addition http://www.hyperelliptic.org/EFD/g1p/auto-shortw-jacobian-0.html#addition-madd-2007-bl
func (*G1Jac) ClearCofactor ¶
ClearCofactor maps a point in E(Fp) to E(Fp)[r]
func (*G1Jac) Double ¶
Double doubles a point in Jacobian coordinates https://hyperelliptic.org/EFD/g1p/auto-shortw-jacobian-3.html#doubling-dbl-2007-bl
func (*G1Jac) DoubleAssign ¶
DoubleAssign doubles a point in Jacobian coordinates https://hyperelliptic.org/EFD/g1p/auto-shortw-jacobian-3.html#doubling-dbl-2007-bl
func (*G1Jac) FromAffine ¶
FromAffine sets p = Q, p in Jacobian, Q in affine
func (*G1Jac) IsInSubGroup ¶
IsInSubGroup returns true if p is on the r-torsion, false otherwise. Z[r,0]+Z[-lambdaG1Affine, 1] is the kernel of (u,v)->u+lambdaG1Affinev mod r. Expressing r, lambdaG1Affine as polynomials in x, a short vector of this Zmodule is 1, x². So we check that p+x²ϕ(p) is the infinity.
func (*G1Jac) MultiExp ¶
func (p *G1Jac) MultiExp(points []G1Affine, scalars []fr.Element, config ecc.MultiExpConfig) (*G1Jac, error)
MultiExp implements section 4 of https://eprint.iacr.org/2012/549.pdf
This call return an error if len(scalars) != len(points) or if provided config is invalid.
func (*G1Jac) ScalarMultiplication ¶
ScalarMultiplication computes and returns p = a ⋅ s see https://www.iacr.org/archive/crypto2001/21390189.pdf
func (*G1Jac) ScalarMultiplicationAffine ¶
ScalarMultiplicationAffine computes and returns p = a ⋅ s Takes an affine point and returns a Jacobian point (useful for KZG)
type G2Affine ¶
G2Affine point in affine coordinates
func BatchScalarMultiplicationG2 ¶
BatchScalarMultiplicationG2 multiplies the same base by all scalars and return resulting points in affine coordinates uses a simple windowed-NAF like exponentiation algorithm
func EncodeToG2 ¶
EncodeToG2 hashes a message to a point on the G2 curve using the SSWU map. It is faster than HashToG2, but the result is not uniformly distributed. Unsuitable as a random oracle. dst stands for "domain separation tag", a string unique to the construction using the hash function https://www.ietf.org/archive/id/draft-irtf-cfrg-hash-to-curve-16.html#roadmap
func HashToG2 ¶
HashToG2 hashes a message to a point on the G2 curve using the SSWU map. Slower than EncodeToG2, but usable as a random oracle. dst stands for "domain separation tag", a string unique to the construction using the hash function https://www.ietf.org/archive/id/draft-irtf-cfrg-hash-to-curve-16.html#roadmap
func (*G2Affine) Add ¶
Add adds two point in affine coordinates. This should rarely be used as it is very inefficient compared to Jacobian
func (*G2Affine) Bytes ¶
func (p *G2Affine) Bytes() (res [SizeOfG2AffineCompressed]byte)
Bytes returns binary representation of p will store X coordinate in regular form and a parity bit we follow the BLS12-381 style encoding as specified in ZCash and now IETF
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.
func (*G2Affine) ClearCofactor ¶
ClearCofactor maps a point in curve to r-torsion
func (*G2Affine) FromJacobian ¶
FromJacobian rescales a point in Jacobian coord in z=1 plane
func (*G2Affine) IsInSubGroup ¶
IsInSubGroup returns true if p is in the correct subgroup, false otherwise
func (*G2Affine) IsInfinity ¶
IsInfinity checks if the point is infinity in affine, it's encoded as (0,0) (0,0) is never on the curve for j=0 curves
func (*G2Affine) MultiExp ¶
func (p *G2Affine) MultiExp(points []G2Affine, scalars []fr.Element, config ecc.MultiExpConfig) (*G2Affine, error)
MultiExp implements section 4 of https://eprint.iacr.org/2012/549.pdf
This call return an error if len(scalars) != len(points) or if provided config is invalid.
func (*G2Affine) RawBytes ¶
func (p *G2Affine) RawBytes() (res [SizeOfG2AffineUncompressed]byte)
RawBytes returns binary representation of p (stores X and Y coordinate) see Bytes() for a compressed representation
func (*G2Affine) ScalarMultiplication ¶
ScalarMultiplication computes and returns p = a ⋅ s
func (*G2Affine) SetBytes ¶
SetBytes sets p from binary representation in buf and returns number of consumed bytes
bytes in buf must match either RawBytes() or Bytes() output
if buf is too short io.ErrShortBuffer is returned
if buf contains compressed representation (output from Bytes()) and we're unable to compute the Y coordinate (i.e the square root doesn't exist) this function returns an error
this check if the resulting point is on the curve and in the correct subgroup
func (*G2Affine) String ¶
String returns the string representation of the point or "O" if it is infinity
type G2Jac ¶
G2Jac is a point with fptower.E2 coordinates
func (*G2Jac) AddAssign ¶
AddAssign point addition in montgomery form https://hyperelliptic.org/EFD/g1p/auto-shortw-jacobian-3.html#addition-add-2007-bl
func (*G2Jac) AddMixed ¶
AddMixed point addition http://www.hyperelliptic.org/EFD/g1p/auto-shortw-jacobian-0.html#addition-madd-2007-bl
func (*G2Jac) ClearCofactor ¶
ClearCofactor maps a point in curve to r-torsion
func (*G2Jac) Double ¶
Double doubles a point in Jacobian coordinates https://hyperelliptic.org/EFD/g1p/auto-shortw-jacobian-3.html#doubling-dbl-2007-bl
func (*G2Jac) DoubleAssign ¶
DoubleAssign doubles a point in Jacobian coordinates https://hyperelliptic.org/EFD/g1p/auto-shortw-jacobian-3.html#doubling-dbl-2007-bl
func (*G2Jac) FromAffine ¶
FromAffine sets p = Q, p in Jacobian, Q in affine
func (*G2Jac) IsInSubGroup ¶
IsInSubGroup returns true if p is on the r-torsion, false otherwise. https://eprint.iacr.org/2021/1130.pdf, sec.4 ψ(p) = x₀ P
func (*G2Jac) MultiExp ¶
func (p *G2Jac) MultiExp(points []G2Affine, scalars []fr.Element, config ecc.MultiExpConfig) (*G2Jac, error)
MultiExp implements section 4 of https://eprint.iacr.org/2012/549.pdf
This call return an error if len(scalars) != len(points) or if provided config is invalid.
func (*G2Jac) ScalarMultiplication ¶
ScalarMultiplication computes and returns p = a ⋅ s see https://www.iacr.org/archive/crypto2001/21390189.pdf
type GT ¶
GT target group of the pairing
func FinalExponentiation ¶
FinalExponentiation computes the exponentiation (∏ᵢ zᵢ)ᵈ where d = (p¹²-1)/r = (p¹²-1)/Φ₁₂(p) ⋅ Φ₁₂(p)/r = (p⁶-1)(p²+1)(p⁴ - p² +1)/r we use instead d=s ⋅ (p⁶-1)(p²+1)(p⁴ - p² +1)/r where s is the cofactor 3 (Hayashida et al.)
func MillerLoop ¶
MillerLoop computes the multi-Miller loop ∏ᵢ MillerLoop(Pᵢ, Qᵢ)
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package bandersnatch provides bls12-381's twisted edwards "companion curve" defined on fr.
|
Package bandersnatch provides bls12-381's twisted edwards "companion curve" defined on fr. |
eddsa
Package eddsa provides EdDSA signature scheme on bls12-381's twisted edwards curve.
|
Package eddsa provides EdDSA signature scheme on bls12-381's twisted edwards curve. |
Package fp contains field arithmetic operations for modulus = 0x1a0111...ffaaab.
|
Package fp contains field arithmetic operations for modulus = 0x1a0111...ffaaab. |
Package fr contains field arithmetic operations for modulus = 0x73eda7...000001.
|
Package fr contains field arithmetic operations for modulus = 0x73eda7...000001. |
fft
Package fft provides in-place discrete Fourier transform.
|
Package fft provides in-place discrete Fourier transform. |
fri
Package fri provides the FRI (multiplicative) commitment scheme.
|
Package fri provides the FRI (multiplicative) commitment scheme. |
kzg
Package kzg provides a KZG commitment scheme.
|
Package kzg provides a KZG commitment scheme. |
mimc
Package mimc provides MiMC hash function using Miyaguchi–Preneel construction.
|
Package mimc provides MiMC hash function using Miyaguchi–Preneel construction. |
permutation
Package permutation provides an API to build permutation proofs.
|
Package permutation provides an API to build permutation proofs. |
plookup
Package plookup provides an API to build plookup proofs.
|
Package plookup provides an API to build plookup proofs. |
polynomial
Package polynomial provides polynomial methods and commitment schemes.
|
Package polynomial provides polynomial methods and commitment schemes. |
pkg
|
|
Package twistededwards provides bls12-381's twisted edwards "companion curve" defined on fr.
|
Package twistededwards provides bls12-381's twisted edwards "companion curve" defined on fr. |
eddsa
Package eddsa provides EdDSA signature scheme on bls12-381's twisted edwards curve.
|
Package eddsa provides EdDSA signature scheme on bls12-381's twisted edwards curve. |