signature

Documentation

Index

• func NewRandomBeaconInspector(groupPublicKey crypto.PublicKey, publicKeyShares []crypto.PublicKey, ...) (*randomBeaconInspector, error)
• type BlockSignerDecoder
  • func NewBlockSignerDecoder(committee hotstuff.DynamicCommittee) *BlockSignerDecoder
  • func (b *BlockSignerDecoder) DecodeSignerIDs(header *flow.Header) (flow.IdentifierList, error)
• type ConsensusSigDataPacker
  • func NewConsensusSigDataPacker(committees hotstuff.Replicas) *ConsensusSigDataPacker
  • func (p *ConsensusSigDataPacker) Pack(view uint64, sig *hotstuff.BlockSignatureData) ([]byte, []byte, error)
  • func (p *ConsensusSigDataPacker) Unpack(signerIdentities flow.IdentityList, sigData []byte) (*hotstuff.BlockSignatureData, error)
• type EpochAwareRandomBeaconKeyStore
  • func NewEpochAwareRandomBeaconKeyStore(epochLookup module.EpochLookup, keys storage.SafeBeaconKeys) *EpochAwareRandomBeaconKeyStore
  • func (s *EpochAwareRandomBeaconKeyStore) ByView(view uint64) (crypto.PrivateKey, error)
• type NoopBlockSignerDecoder
  • func NewNoopBlockSignerDecoder() *NoopBlockSignerDecoder
  • func (b *NoopBlockSignerDecoder) DecodeSignerIDs(_ *flow.Header) (flow.IdentifierList, error)
• type RandomBeaconReconstructor
  • func NewRandomBeaconReconstructor(dkg hotstuff.DKG, randomBeaconInspector hotstuff.RandomBeaconInspector) *RandomBeaconReconstructor
  • func (r *RandomBeaconReconstructor) TrustedAdd(signerID flow.Identifier, sig crypto.Signature) (bool, error)
  • func (r *RandomBeaconReconstructor) Verify(signerID flow.Identifier, sig crypto.Signature) error
• type StaticRandomBeaconSignerStore
  • func NewStaticRandomBeaconSignerStore(beaconKey crypto.PrivateKey) *StaticRandomBeaconSignerStore
  • func (s *StaticRandomBeaconSignerStore) ByView(_ uint64) (crypto.PrivateKey, error)
• type WeightedSignatureAggregator
  • func NewWeightedSignatureAggregator(ids flow.IdentityList, pks []crypto.PublicKey, message []byte, dsTag string) (*WeightedSignatureAggregator, error)
  • func (w *WeightedSignatureAggregator) Aggregate() (flow.IdentifierList, []byte, error)
  • func (w *WeightedSignatureAggregator) TotalWeight() uint64
  • func (w *WeightedSignatureAggregator) TrustedAdd(signerID flow.Identifier, sig crypto.Signature) (uint64, error)
  • func (w *WeightedSignatureAggregator) Verify(signerID flow.Identifier, sig crypto.Signature) error

Functions

func NewRandomBeaconInspector

func NewRandomBeaconInspector(
	groupPublicKey crypto.PublicKey,
	publicKeyShares []crypto.PublicKey,
	threshold int,
	message []byte,
) (*randomBeaconInspector, error)

NewRandomBeaconInspector instantiates a new randomBeaconInspector. The constructor errors with a `model.ConfigurationError` in any of the following cases

• n is not between `ThresholdSignMinSize` and `ThresholdSignMaxSize`, for n the number of participants `n := len(publicKeyShares)`
• threshold value is not in interval [1, n-1]
• any input public key is not a BLS key

Types

type BlockSignerDecoder

type BlockSignerDecoder struct {
	hotstuff.DynamicCommittee
}

BlockSignerDecoder is a wrapper around the `hotstuff.DynamicCommittee`, which implements the auxiliary logic for de-coding signer indices of a block (header) to full node IDs

func NewBlockSignerDecoder

func NewBlockSignerDecoder(committee hotstuff.DynamicCommittee) *BlockSignerDecoder

func (*BlockSignerDecoder) DecodeSignerIDs

func (b *BlockSignerDecoder) DecodeSignerIDs(header *flow.Header) (flow.IdentifierList, error)

DecodeSignerIDs decodes the signer indices from the given block header into full node IDs. Note: A block header contains a quorum certificate for its parent, which proves that the consensus committee has reached agreement on validity of parent block. Consequently, the returned IdentifierList contains the consensus participants that signed the parent block. Expected Error returns during normal operations:

• signature.InvalidSignerIndicesError if signer indices included in the header do not encode a valid subset of the consensus committee
• state.ErrUnknownSnapshotReference if the input header is not a known incorporated block.

type ConsensusSigDataPacker

type ConsensusSigDataPacker struct {
	model.SigDataPacker
	// contains filtered or unexported fields
}

ConsensusSigDataPacker implements the hotstuff.Packer interface. The encoding method is RLP.

func NewConsensusSigDataPacker

func NewConsensusSigDataPacker(committees hotstuff.Replicas) *ConsensusSigDataPacker

NewConsensusSigDataPacker creates a new ConsensusSigDataPacker instance

func (*ConsensusSigDataPacker) Pack

func (p *ConsensusSigDataPacker) Pack(view uint64, sig *hotstuff.BlockSignatureData) ([]byte, []byte, error)

Pack serializes the block signature data into raw bytes, suitable to create a QC. To pack the block signature data, we first build a compact data type, and then encode it into bytes. Expected error returns during normal operations:

• none; all errors are symptoms of inconsistent input data or corrupted internal state.

func (*ConsensusSigDataPacker) Unpack

func (p *ConsensusSigDataPacker) Unpack(signerIdentities flow.IdentityList, sigData []byte) (*hotstuff.BlockSignatureData, error)

Unpack de-serializes the provided signature data. view is the view of the block that the aggregated sig is signed for sig is the aggregated signature data It returns:

• (sigData, nil) if successfully unpacked the signature data
• (nil, model.InvalidFormatError) if failed to unpack the signature data

type EpochAwareRandomBeaconKeyStore

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

EpochAwareRandomBeaconKeyStore provides an abstraction to query random beacon private key for a given view. Internally it indexes and caches the private keys by epoch.

func NewEpochAwareRandomBeaconKeyStore

func NewEpochAwareRandomBeaconKeyStore(epochLookup module.EpochLookup, keys storage.SafeBeaconKeys) *EpochAwareRandomBeaconKeyStore

func (*EpochAwareRandomBeaconKeyStore) ByView

func (s *EpochAwareRandomBeaconKeyStore) ByView(view uint64) (crypto.PrivateKey, error)

ByView returns the random beacon signer for signing objects at a given view. The view determines the epoch, which determines the DKG private key underlying the signer. It returns:

• (signer, nil) if DKG succeeded locally in the epoch of the view, signer is not nil
• (nil, model.ErrViewForUnknownEpoch) if no epoch found for given view
• (nil, module.ErrNoBeaconKeyForEpoch) if beacon key for epoch is unavailable
• (nil, error) if there is any exception

type NoopBlockSignerDecoder

type NoopBlockSignerDecoder struct{}

NoopBlockSignerDecoder does not decode any signer indices and consistently returns nil for the signing node IDs (auxiliary data)

func NewNoopBlockSignerDecoder

func NewNoopBlockSignerDecoder() *NoopBlockSignerDecoder

func (*NoopBlockSignerDecoder) DecodeSignerIDs

func (b *NoopBlockSignerDecoder) DecodeSignerIDs(_ *flow.Header) (flow.IdentifierList, error)

type RandomBeaconReconstructor

type RandomBeaconReconstructor struct {
	hotstuff.RandomBeaconInspector // a stateful object for this epoch. It's used for both verifying all sig shares and reconstructing the threshold signature.
	// contains filtered or unexported fields
}

RandomBeaconReconstructor implements hotstuff.RandomBeaconReconstructor. The implementation wraps the hotstuff.RandomBeaconInspector and translates the signer identity into signer index. It has knowledge about DKG to be able to map signerID to signerIndex

func NewRandomBeaconReconstructor

func NewRandomBeaconReconstructor(dkg hotstuff.DKG, randomBeaconInspector hotstuff.RandomBeaconInspector) *RandomBeaconReconstructor

func (*RandomBeaconReconstructor) TrustedAdd

func (r *RandomBeaconReconstructor) TrustedAdd(signerID flow.Identifier, sig crypto.Signature) (bool, error)

TrustedAdd adds a share to the internal signature shares store. There is no pre-check of the signature's validity _before_ adding it. It is the caller's responsibility to make sure the signature was previously verified. Nevertheless, the implementation guarantees safety (only correct threshold signatures are returned) through a post-check (verifying the threshold signature _after_ reconstruction before returning it). The function is thread-safe but locks its internal state, thereby permitting only one routine at a time to add a signature. Returns:

• (true, nil) if the signature has been added, and enough shares have been collected.
• (false, nil) if the signature has been added, but not enough shares were collected.

The following errors are expected during normal operations:

• model.InvalidSignerError if signerIndex is invalid (out of the valid range)
• model.DuplicatedSignerError if the signer has been already added
• other error if there is an unexpected exception.

func (*RandomBeaconReconstructor) Verify

func (r *RandomBeaconReconstructor) Verify(signerID flow.Identifier, sig crypto.Signature) error

Verify verifies the signature share under the signer's public key and the message agreed upon. The function is thread-safe and wait-free (i.e. allowing arbitrary many routines to execute the business logic, without interfering with each other). It allows concurrent verification of the given signature. Returns :

• model.InvalidSignerError if signerID is invalid
• model.ErrInvalidSignature if signerID is valid but signature is cryptographically invalid
• other error if there is an unexpected exception.

type StaticRandomBeaconSignerStore

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

StaticRandomBeaconSignerStore is a simple implementation of module.RandomBeaconKeyStore that returns same key for each view. This structure was implemented for bootstrap process and should be used only for it.

func NewStaticRandomBeaconSignerStore

func NewStaticRandomBeaconSignerStore(beaconKey crypto.PrivateKey) *StaticRandomBeaconSignerStore

func (*StaticRandomBeaconSignerStore) ByView

func (s *StaticRandomBeaconSignerStore) ByView(_ uint64) (crypto.PrivateKey, error)

type WeightedSignatureAggregator

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

WeightedSignatureAggregator implements consensus/hotstuff.WeightedSignatureAggregator. It is a wrapper around module/signature.SignatureAggregatorSameMessage, which implements a mapping from node IDs (as used by HotStuff) to index-based addressing of authorized signers (as used by SignatureAggregatorSameMessage).

Similarly to module/signature.SignatureAggregatorSameMessage, this module assumes proofs of possession (PoP) of all identity public keys are valid.

func NewWeightedSignatureAggregator

func NewWeightedSignatureAggregator(
	ids flow.IdentityList,
	pks []crypto.PublicKey,
	message []byte,
	dsTag string,
) (*WeightedSignatureAggregator, error)

NewWeightedSignatureAggregator returns a weighted aggregator initialized with a list of flow identities, their respective public keys, a message and a domain separation tag. The identities represent the list of all possible signers. This aggregator is only safe if PoPs of all identity keys are valid. This constructor does not verify the PoPs but assumes they have been validated outside this module. The constructor errors if: - the list of identities is empty - if the length of keys does not match the length of identities - if one of the keys is not a valid public key.

A weighted aggregator is used for one aggregation only. A new instance should be used for each signature aggregation task in the protocol.

func (*WeightedSignatureAggregator) Aggregate

func (w *WeightedSignatureAggregator) Aggregate() (flow.IdentifierList, []byte, error)

Aggregate aggregates the signatures and returns the aggregated signature. The function performs a final verification and errors if the aggregated signature is invalid. This is required for the function safety since `TrustedAdd` allows adding invalid signatures. The function errors with:

• model.InsufficientSignaturesError if no signatures have been added yet
• model.InvalidSignatureIncludedError if:
• some signature(s), included via TrustedAdd, fail to deserialize (regardless of the aggregated public key) -- or all signatures deserialize correctly but some signature(s), included via TrustedAdd, are invalid (while aggregated public key is valid) -- model.InvalidAggregatedKeyError if all signatures deserialize correctly but the signer's staking public keys sum up to an invalid key (BLS identity public key). Any aggregated signature would fail the cryptographic verification under the identity public key and therefore such signature is considered invalid. Such scenario can only happen if staking public keys of signers were forged to add up to the identity public key. Under the assumption that all staking key PoPs are valid, this error case can only happen if all signers are malicious and colluding. If there is at least one honest signer, there is a negligible probability that the aggregated key is identity.

The function is thread-safe.

func (*WeightedSignatureAggregator) TotalWeight

func (w *WeightedSignatureAggregator) TotalWeight() uint64

TotalWeight returns the total weight presented by the collected signatures. The function is thread-safe

func (*WeightedSignatureAggregator) TrustedAdd

func (w *WeightedSignatureAggregator) TrustedAdd(signerID flow.Identifier, sig crypto.Signature) (uint64, error)

TrustedAdd adds a signature to the internal set of signatures and adds the signer's weight to the total collected weight, iff the signature is _not_ a duplicate.

The total weight of all collected signatures (excluding duplicates) is returned regardless of any returned error. The function errors with:

• model.InvalidSignerError if signerID is invalid (not a consensus participant)
• model.DuplicatedSignerError if the signer has been already added

The function is thread-safe.

func (*WeightedSignatureAggregator) Verify

func (w *WeightedSignatureAggregator) Verify(signerID flow.Identifier, sig crypto.Signature) error

Verify verifies the signature under the stored public keys and message. Expected errors during normal operations:

• model.InvalidSignerError if signerID is invalid (not a consensus participant)
• model.ErrInvalidSignature if signerID is valid but signature is cryptographically invalid

The function is thread-safe.