blst

Documentation

Overview

Package blst implements a go-wrapper around a library implementing the the BLS12-381 curve and signature scheme. This package exposes a public API for verifying and aggregating BLS signatures used by Ethereum.

This implementation uses the library written by Supranational, blst.

Index

• func Aggregate(sigs []common.Signature) common.Signature
• func AggregatePublicKeys(pubs [][]byte) (common.PublicKey, error)
• func AggregateSignatures(sigs []common.Signature) common.Signature
• func IsZero(sKey []byte) bool
• func NewAggregateSignature() common.Signature
• func PublicKeyFromBytes(pubKey []byte) (common.PublicKey, error)
• func RandKey() (common.SecretKey, error)
• func SecretKeyFromBytes(privKey []byte) (common.SecretKey, error)
• func SignatureFromBytes(sig []byte) (common.Signature, error)
• func VerifyCompressed(signature, pub, msg []byte) bool
• func VerifyMultipleSignatures(sigs [][]byte, msgs [][32]byte, pubKeys []common.PublicKey) (bool, error)
• type PublicKey
  • func (p *PublicKey) Aggregate(p2 common.PublicKey) common.PublicKey
  • func (p *PublicKey) Copy() common.PublicKey
  • func (p *PublicKey) IsInfinite() bool
  • func (p *PublicKey) Marshal() []byte
• type Signature
  • func (s *Signature) AggregateVerify(pubKeys []common.PublicKey, msgs [][32]byte) bool
  • func (s *Signature) Copy() common.Signature
  • func (s *Signature) Eth2FastAggregateVerify(pubKeys []common.PublicKey, msg [32]byte) bool
  • func (s *Signature) FastAggregateVerify(pubKeys []common.PublicKey, msg [32]byte) bool
  • func (s *Signature) Marshal() []byte
  • func (s *Signature) Verify(pubKey common.PublicKey, msg []byte) bool

Functions

func Aggregate

func Aggregate(sigs []common.Signature) common.Signature

Aggregate is an alias for AggregateSignatures, defined to conform to BLS specification.

In IETF draft BLS specification: Aggregate(signature_1, ..., signature_n) -> signature: an

aggregation algorithm that compresses a collection of signatures
into a single signature.

In the Ethereum proof of stake specification: def Aggregate(signatures: Sequence[BLSSignature]) -> BLSSignature

Deprecated: Use AggregateSignatures.

func AggregatePublicKeys

func AggregatePublicKeys(pubs [][]byte) (common.PublicKey, error)

AggregatePublicKeys aggregates the provided raw public keys into a single key.

func AggregateSignatures

func AggregateSignatures(sigs []common.Signature) common.Signature

AggregateSignatures converts a list of signatures into a single, aggregated sig.

func IsZero

func IsZero(sKey []byte) bool

IsZero checks if the secret key is a zero key.

func NewAggregateSignature

func NewAggregateSignature() common.Signature

NewAggregateSignature creates a blank aggregate signature.

func PublicKeyFromBytes

func PublicKeyFromBytes(pubKey []byte) (common.PublicKey, error)

PublicKeyFromBytes creates a BLS public key from a BigEndian byte slice.

func RandKey

func RandKey() (common.SecretKey, error)

RandKey creates a new private key using a random method provided as an io.Reader.

func SecretKeyFromBytes

func SecretKeyFromBytes(privKey []byte) (common.SecretKey, error)

SecretKeyFromBytes creates a BLS private key from a BigEndian byte slice.

func SignatureFromBytes

func SignatureFromBytes(sig []byte) (common.Signature, error)

SignatureFromBytes creates a BLS signature from a LittleEndian byte slice.

func VerifyCompressed

func VerifyCompressed(signature, pub, msg []byte) bool

VerifyCompressed verifies that the compressed signature and pubkey are valid from the message provided.

func VerifyMultipleSignatures

func VerifyMultipleSignatures(sigs [][]byte, msgs [][32]byte, pubKeys []common.PublicKey) (bool, error)

VerifyMultipleSignatures verifies a non-singular set of signatures and its respective pubkeys and messages. This method provides a safe way to verify multiple signatures at once. We pick a number randomly from 1 to max uint64 and then multiply the signature by it. We continue doing this for all signatures and its respective pubkeys. S* = S_1 * r_1 + S_2 * r_2 + ... + S_n * r_n P'_{i,j} = P_{i,j} * r_i e(S*, G) = \prod_{i=1}^n \prod_{j=1}^{m_i} e(P'_{i,j}, M_{i,j}) Using this we can verify multiple signatures safely.

Types

type PublicKey

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

PublicKey used in the BLS signature scheme.

func (*PublicKey) Aggregate

func (p *PublicKey) Aggregate(p2 common.PublicKey) common.PublicKey

Aggregate two public keys.

func (*PublicKey) Copy

func (p *PublicKey) Copy() common.PublicKey

Copy the public key to a new pointer reference.

func (*PublicKey) IsInfinite

func (p *PublicKey) IsInfinite() bool

IsInfinite checks if the public key is infinite.

func (*PublicKey) Marshal

func (p *PublicKey) Marshal() []byte

Marshal a public key into a LittleEndian byte slice.

type Signature

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

Signature used in the BLS signature scheme.

func (*Signature) AggregateVerify

func (s *Signature) AggregateVerify(pubKeys []common.PublicKey, msgs [][32]byte) bool

AggregateVerify verifies each public key against its respective message. This is vulnerable to rogue public-key attack. Each user must provide a proof-of-knowledge of the public key.

Note: The msgs must be distinct. For maximum performance, this method does not ensure distinct messages.

In IETF draft BLS specification: AggregateVerify((PK_1, message_1), ..., (PK_n, message_n),

signature) -> VALID or INVALID: an aggregate verification
algorithm that outputs VALID if signature is a valid aggregated
signature for a collection of public keys and messages, and
outputs INVALID otherwise.

In the Ethereum proof of stake specification: def AggregateVerify(pairs: Sequence[PK: BLSPubkey, message: Bytes], signature: BLSSignature) -> bool

Deprecated: Use FastAggregateVerify or use this method in spectests only.

func (*Signature) Copy

func (s *Signature) Copy() common.Signature

Copy returns a full deep copy of a signature.

func (*Signature) Eth2FastAggregateVerify

func (s *Signature) Eth2FastAggregateVerify(pubKeys []common.PublicKey, msg [32]byte) bool

Eth2FastAggregateVerify implements a wrapper on top of bls's FastAggregateVerify. It accepts G2_POINT_AT_INFINITY signature when pubkeys empty.

Spec code: def eth2_fast_aggregate_verify(pubkeys: Sequence[BLSPubkey], message: Bytes32, signature: BLSSignature) -> bool:

"""
Wrapper to ``bls.FastAggregateVerify`` accepting the ``G2_POINT_AT_INFINITY`` signature when ``pubkeys`` is empty.
"""
if len(pubkeys) == 0 and signature == G2_POINT_AT_INFINITY:
    return True
return bls.FastAggregateVerify(pubkeys, message, signature)

func (*Signature) FastAggregateVerify

func (s *Signature) FastAggregateVerify(pubKeys []common.PublicKey, msg [32]byte) bool

FastAggregateVerify verifies all the provided public keys with their aggregated signature.

In IETF draft BLS specification: FastAggregateVerify(PK_1, ..., PK_n, message, signature) -> VALID

or INVALID: a verification algorithm for the aggregate of multiple
signatures on the same message.  This function is faster than
AggregateVerify.

In the Ethereum proof of stake specification: def FastAggregateVerify(PKs: Sequence[BLSPubkey], message: Bytes, signature: BLSSignature) -> bool

func (*Signature) Marshal

func (s *Signature) Marshal() []byte

Marshal a signature into a LittleEndian byte slice.

func (*Signature) Verify

func (s *Signature) Verify(pubKey common.PublicKey, msg []byte) bool

Verify a bls signature given a public key, a message.

In IETF draft BLS specification: Verify(PK, message, signature) -> VALID or INVALID: a verification

algorithm that outputs VALID if signature is a valid signature of
message under public key PK, and INVALID otherwise.

In the Ethereum proof of stake specification: def Verify(PK: BLSPubkey, message: Bytes, signature: BLSSignature) -> bool