signature

package
v0.31.9-HCU-test Latest Latest
Warning

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

 Go to latest Published: Jun 15, 2023 License: AGPL-3.0 Imports: 10 Imported by: 4

Documentation

Index

Constants

View Source 
const CheckSumLen = 4

CheckSumLen is fixed to be 4 bytes

View Source 
const SigLen = crypto.SignatureLenBLSBLS12381

Variables

View Source 
var (
	ErrInvalidSignatureFormat = errors.New("signature's binary format is invalid")

	ErrInsufficientShares = errors.New("insufficient threshold signature shares")

	// ErrIncompatibleBitVectorLength indicates that the bit vector's length is different than
	// the expected length, based on the supplied node list.
	ErrIncompatibleBitVectorLength = errors.New("bit vector has incompatible length")

	// ErrIllegallyPaddedBitVector indicates that the index vector was padded with unexpected bit values.
	ErrIllegallyPaddedBitVector = errors.New("index vector padded with unexpected bit values")

	// ErrInvalidChecksum indicates that the index vector's checksum is invalid
	ErrInvalidChecksum = errors.New("index vector's checksum is invalid")

	// ErrIdentityPublicKey indicates that the signer's public keys add up to the BLS identity public key.
	// Any signature would fail the cryptographic verification if verified against the
	// the identity public key. This case can only happen if public keys were forged to sum up to
	// an identity public key. If private keys are sampled uniformly at random, there is vanishing
	// probability of generating the aggregated identity public key. However, (colluding) byzantine
	// signers could force the generation of private keys that result in the identity aggregated key.
	ErrIdentityPublicKey = errors.New("aggregated public key is identity and aggregated signature is invalid")
)
View Source 
var (

	// RandomBeaconTag is used for threshold signatures in the random beacon
	RandomBeaconTag = tag("Random_Beacon")
	// ConsensusVoteTag is used for Consensus Hotstuff votes
	ConsensusVoteTag = tag("Consensus_Vote")
	// CollectorVoteTag is used for Collection Hotstuff votes
	CollectorVoteTag = tag("Collector_Vote")
	// ConsensusTimeoutTag is used for Consensus Active Pacemaker timeouts
	ConsensusTimeoutTag = tag("Consensus_Timeout")
	// CollectorTimeoutTag is used for Collector Active Pacemaker timeouts
	CollectorTimeoutTag = tag("Collector_Timeout")
	// ExecutionReceiptTag is used for execution receipts
	ExecutionReceiptTag = tag("Execution_Receipt")
	// ResultApprovalTag is used for result approvals
	ResultApprovalTag = tag("Result_Approval")
	// SPOCKTag is used to generate SPoCK proofs
	SPOCKTag = tag("SPoCK")
	// DKGMessageTag is used for DKG messages
	DKGMessageTag = tag("DKG_Message")
)

Functions

func CheckSumFromIdentities added in v0.26.1 

func CheckSumFromIdentities(identities []flow.Identifier) [CheckSumLen]byte

CheckSumFromIdentities returns checksum for the given identities

func CompareAndExtract added in v0.26.1 

func CompareAndExtract(canonicalList []flow.Identifier, checkSumPrefixedSignerIndices []byte) ([]byte, error)

CompareAndExtract reads the checksum from the given `checkSumPrefixedSignerIndices` and compares it with the checksum of the given identifier list. It returns the signer indices if the checksum matches. Inputs:

  • canonicalList is the canonical list from decoder's view
  • checkSumPrefixedSignerIndices is the signer indices created by the encoder, and prefixed with the checksum of the canonical list from encoder's view.

Expected error during normal operations:

  • ErrInvalidChecksum if the input is shorter than the expected checksum contained therein

func DecodeDoubleSig added in v0.26.1 

func DecodeDoubleSig(sigData []byte) (crypto.Signature, crypto.Signature, error)

TODO: to be removed in V3, replace by packer's unpack method DecodeDoubleSig decodes the signature data into a staking signature and an optional random beacon signature. The decoding assumes BLS with BLS12-381 is used. Cryptographic validity of signatures is _not_ checked. Decomposition of the sigData is purely done based on length. It returns:

  • staking signature, random beacon signature, nil: if sigData is twice the size of a BLS signature bytes long, we use the leading half as staking signature and the tailing half random beacon sig
  • staking signature, nil, nil: if sigData is the size of a BLS signature, we interpret sigData entirely as staking signature
  • nil, nil, ErrInvalidSignatureFormat if the sig type is invalid (covers nil or empty sigData)

func DecodeSigTypeToStakingAndBeaconSigners added in v0.26.1 

func DecodeSigTypeToStakingAndBeaconSigners(
	signers flow.IdentityList,
	sigType []byte,
) (flow.IdentityList, flow.IdentityList, error)

DecodeSigTypeToStakingAndBeaconSigners decodes the bit-vector `sigType` to the set of staking signer identities (`stakingSigners`) and the set of beacon signer identities (`beaconSigners`). Prerequisite:

  • The input `signers` must be the set of signers in their canonical order.

Expected Error returns during normal operations:

  • signature.IsInvalidSigTypesError if the given `sigType` does not encode a valid sequence of signature types

func DecodeSignerIndicesToIdentifiers added in v0.26.1 

func DecodeSignerIndicesToIdentifiers(
	canonicalIdentifiers flow.IdentifierList,
	prefixed []byte,
) (flow.IdentifierList, error)

DecodeSignerIndicesToIdentifiers decodes the given compacted bit vector into signerIDs Prerequisite:

  • The input `canonicalIdentifiers` must exhaustively list the set of authorized signers in their canonical order.

Expected Error returns during normal operations: * signature.InvalidSignerIndicesError if the given index vector `prefixed` does not encode a valid set of signers

func DecodeSignerIndicesToIdentities added in v0.26.1 

func DecodeSignerIndicesToIdentities(
	canonicalIdentities flow.IdentityList,
	prefixed []byte,
) (flow.IdentityList, error)

DecodeSignerIndicesToIdentities decodes the given compacted bit vector into node Identities. Prerequisite:

  • The input `canonicalIdentifiers` must exhaustively list the set of authorized signers in their canonical order.

Expected Error returns during normal operations: * signature.InvalidSignerIndicesError if the given index vector `prefixed` does not encode a valid set of signers

func DecodeSingleSig added in v0.26.1 

func DecodeSingleSig(sigData []byte) (encoding.SigType, crypto.Signature, error)

DecodeSingleSig decodes the signature data into a cryptographic signature and a type as required by the consensus design. Cryptographic validity of signatures is _not_ checked. It returns:

  • 0, nil, ErrInvalidSignatureFormat if the sig type is invalid (covers nil or empty sigData)
  • sigType, signature, nil if the sig type is valid and the decoding is done successfully.

func EncodeDoubleSig added in v0.26.1 

func EncodeDoubleSig(stakingSig crypto.Signature, beaconSig crypto.Signature) []byte

TODO: to be removed in V3, replace by packer's pack method EncodeDoubleSig encodes both the staking signature and random beacon signature into one sigData.

func EncodeIdentities added in v0.26.1 

func EncodeIdentities(identities []flow.Identifier) []byte

EncodeIdentities will concatenation all the identities into bytes

func EncodeSignerToIndicesAndSigType added in v0.26.1 

func EncodeSignerToIndicesAndSigType(
	canonicalIdentifiers flow.IdentifierList,
	stakingSigners flow.IdentifierList,
	beaconSigners flow.IdentifierList,
) (signerIndices []byte, sigTypes []byte, err error)

EncodeSignerToIndicesAndSigType encodes the given stakingSigners and beaconSigners into bit vectors for signer indices and sig types. PREREQUISITES:

  • The input `canonicalIdentifiers` must exhaustively list the set of authorized signers in their canonical order.
  • The inputs `stakingSigners` and `beaconSigners` are treated as sets, i.e. they should not contain any duplicates.
  • A node can be listed in either `stakingSigners` or `beaconSigners`. A node appearing in both lists constitutes an illegal input.
  • `stakingSigners` must be a subset of `canonicalIdentifiers`
  • `beaconSigners` must be a subset of `canonicalIdentifiers`

RETURN VALUES:

  • `signerIndices` is a bit vector. Let signerIndices[i] denote the ith bit of `signerIndices`.

    . ┌ 1 if and only if canonicalIdentifiers[i] is in `stakingSigners` or `beaconSigners` . signerIndices[i] = └ 0 otherwise

    Let `n` be the length of `canonicalIdentifiers`. `signerIndices` contains at least `n` bits, though, we right-pad it with tailing zeros to full bytes.

  • `sigTypes` is a bit vector. Let sigTypes[i] denote the ith bit of `sigTypes` . ┌ 1 if and only if the ith signer is in `beaconSigners` . sigTypes[i] = └ 0 if and only if the ith signer is in `stakingSigners` (Per prerequisite, we require that no signer is listed in both `beaconSigners` and `stakingSigners`)

Example: As an example consider the case where we have a committee C of 10 nodes in canonical oder 

C = [A,B,C,D,E,F,G,H,I,J]

where nodes [B,F] are stakingSigners and beaconSigners are [C,E,G,I,J].

  1. First return parameter: `signerIndices` - We start with a bit vector v that has |C| number of bits - If a node contributed either as staking signer or beacon signer, we set the respective bit to 1: . [A,B,C,D,E,F,G,H,I,J] . ↓ ↓ ↓ ↓ ↓ ↓ ↓ . 0,1,1,0,1,1,1,0,1,1 - Lastly, right-pad the resulting bit vector with 0 to full bytes. We have 10 committee members, so we pad to 2 bytes: . 01101110 11000000
  2. second return parameter: `sigTypes` - Here, we restrict our focus on the signers, which we encoded in the previous step. In our example, nodes [B,C,E,F,G,I,J] signed in canonical order. This is exactly the same order, as we have represented the signer in the last step. - For these 5 nodes in their canonical order, we encode each node's signature type as . bit-value 1: node was in beaconSigners . bit-value 0: node was in stakingSigners This results in the bit vector . [B,C,E,F,G,I,J] . ↓ ↓ ↓ ↓ ↓ ↓ ↓ . 0,1,0,1,1,1,1 - Again, we right-pad with zeros to full bytes, As we only had 7 signers, the sigType slice is 1byte long . 01011110

the signer indices is prefixed with a checksum of the canonicalIdentifiers, which can be used by the decoder to verify if the decoder is using the same canonicalIdentifiers as the encoder to decode the signer indices.

ERROR RETURNS During normal operations, no error returns are expected. This is because encoding signer sets is generally part of the node's internal work to generate messages. Hence, the inputs to this method come from other trusted components within the node. Therefore, any illegal input is treated as a symptom of an internal bug.

func EncodeSignersToIndices added in v0.26.1 

func EncodeSignersToIndices(
	canonicalIdentifiers flow.IdentifierList,
	signerIDs flow.IdentifierList,
) (signerIndices []byte, err error)

EncodeSignersToIndices encodes the given signerIDs into compacted bit vector. PREREQUISITES:

  • The input `canonicalIdentifiers` must exhaustively list the set of authorized signers in their canonical order.
  • The input `signerIDs` represents a set, i.e. it should not contain any duplicates.
  • `signerIDs` must be a subset of `canonicalIdentifiers`

RETURN VALUE:

  • `signerIndices` is a bit vector. Let signerIndices[i] denote the ith bit of `signerIndices`. . ┌ 1 if and only if canonicalIdentifiers[i] is in `signerIDs` . signerIndices[i] = └ 0 otherwise Let `n` be the length of `canonicalIdentifiers`. `signerIndices` contains at least `n` bits, though, we right-pad it with tailing zeros to full bytes.

Example: As an example consider the case where we have a committee C of 10 nodes in canonical oder 

C = [A,B,C,D,E,F,G,H,I,J]

where nodes [B,F] are stakingSigners, and beaconSigners are [C,E,G,I,J].

  1. First return parameter: QC.signerIndices - We start with a bit vector v that has |C| number of bits - If a node contributed either as staking signer or beacon signer, we set the respective bit to 1: . [A,B,C,D,E,F,G,H,I,J] . ↓ ↓ ↓ ↓ ↓ ↓ ↓ . 0,1,1,0,1,1,1,0,1,1 - Lastly, right-pad the resulting bit vector with 0 to full bytes. We have 10 committee members, so we pad to 2 bytes: . 01101110 11000000

ERROR RETURNS During normal operations, no error returns are expected. This is because encoding signer sets is generally part of the node's internal work to generate messages. Hence, the inputs to this method come from other trusted components within the node. Therefore, any illegal input is treated as a symptom of an internal bug. canonicalIdentifiers represents all identities who are eligible to sign the given resource. It excludes identities who are ineligible to sign the given resource. For example, canonicalIdentifiers in the context of a cluster consensus quorum certificate would include authorized members of the cluster and exclude ejected members of the cluster, or unejected collection nodes from a different cluster. the signer indices is prefixed with a checksum of the canonicalIdentifiers, which can be used by the decoder to verify if the decoder is using the same canonicalIdentifiers as the encoder to decode the signer indices.

func EncodeSingleSig added in v0.26.1 

func EncodeSingleSig(sigType encoding.SigType, sig crypto.Signature) []byte

EncodeSingleSig encodes a single signature into signature data as required by the consensus design.

func IsDuplicatedSignerIdxError added in v0.23.9 

func IsDuplicatedSignerIdxError(err error) bool

IsDuplicatedSignerIdxError returns whether err is an DuplicatedSignerIdxError

func IsInsufficientSignaturesError added in v0.23.9 

func IsInsufficientSignaturesError(err error) bool

IsInsufficientSignaturesError returns whether err is an InsufficientSignaturesError

func IsInvalidSigTypesError added in v0.26.2 

func IsInvalidSigTypesError(err error) bool

IsInvalidSigTypesError returns whether err is an InvalidSigTypesError

func IsInvalidSignatureIncludedError added in v0.23.9 

func IsInvalidSignatureIncludedError(err error) bool

IsInvalidSignatureIncludedError returns whether err is an InvalidSignatureIncludedError

func IsInvalidSignerIdxError added in v0.23.9 

func IsInvalidSignerIdxError(err error) bool

IsInvalidSignerIdxError returns whether err is an InvalidSignerIdxError

func IsInvalidSignerIndicesError added in v0.26.2 

func IsInvalidSignerIndicesError(err error) bool

IsInvalidSignerIndicesError returns whether err is an InvalidSignerIndicesError

func NewBLSHasher added in v0.27.0 

func NewBLSHasher(tag string) hash.Hasher

NewBLSHasher returns a hasher to be used for BLS signing and verifying in the protocol and abstracts the hasher details from the protocol logic.

The hasher returned is the the expand-message step in the BLS hash-to-curve. It uses a xof (extendable output function) based on KMAC128. It therefore has 128-bytes outputs.

func NewDuplicatedSignerIdxErrorf added in v0.23.9 

func NewDuplicatedSignerIdxErrorf(msg string, args ...interface{}) error

func NewInsufficientSignaturesErrorf added in v0.23.9 

func NewInsufficientSignaturesErrorf(msg string, args ...interface{}) error

func NewInvalidSigTypesErrorf added in v0.26.2 

func NewInvalidSigTypesErrorf(msg string, args ...interface{}) error

func NewInvalidSignatureIncludedErrorf added in v0.23.9 

func NewInvalidSignatureIncludedErrorf(msg string, args ...interface{}) error

func NewInvalidSignerIdxErrorf added in v0.23.9 

func NewInvalidSignerIdxErrorf(msg string, args ...interface{}) error

func NewInvalidSignerIndicesErrorf added in v0.26.2 

func NewInvalidSignerIndicesErrorf(msg string, args ...interface{}) error

func PrefixCheckSum added in v0.26.1 

func PrefixCheckSum(canonicalList []flow.Identifier, signrIndices []byte) []byte

PrefixCheckSum prefix the given data with the checksum of the given identifier list

func RandomBeaconThreshold added in v0.23.9 

func RandomBeaconThreshold(size int) int

RandomBeaconThreshold returns the threshold (t) to allow the largest number of malicious nodes (m) assuming the protocol requires:

  • m<=t for unforgeability
  • n-m>=t+1 for robustness

func SplitCheckSum added in v0.26.1 

func SplitCheckSum(checkSumPrefixedSignerIndices []byte) ([CheckSumLen]byte, []byte, error)

SplitCheckSum splits the given bytes into two parts: - prefixed checksum of the canonical identifier list - the signerIndices Expected error during normal operations:

  • ErrInvalidChecksum if the input is shorter than the expected checksum contained therein

Types

type DuplicatedSignerIdxError added in v0.23.9 

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

DuplicatedSignerIdxError indicates that a signature from the respective signer index was already added

func (DuplicatedSignerIdxError) Error added in v0.23.9 

func (e DuplicatedSignerIdxError) Error() string

func (DuplicatedSignerIdxError) Unwrap added in v0.23.9 

func (e DuplicatedSignerIdxError) Unwrap() error

type InsufficientSignaturesError added in v0.23.9 

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

InsufficientSignaturesError indicates that not enough signatures have been stored to complete the operation.

func (InsufficientSignaturesError) Error added in v0.23.9 

func (e InsufficientSignaturesError) Error() string

func (InsufficientSignaturesError) Unwrap added in v0.23.9 

func (e InsufficientSignaturesError) Unwrap() error

type InvalidSigTypesError added in v0.26.2 

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

InvalidSigTypesError indicates that the given data not encode valid signature types

func (InvalidSigTypesError) Error added in v0.26.2 

func (e InvalidSigTypesError) Error() string

func (InvalidSigTypesError) Unwrap added in v0.26.2 

func (e InvalidSigTypesError) Unwrap() error

type InvalidSignatureIncludedError added in v0.23.9 

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

InvalidSignatureIncludedError indicates that some signatures, included via TrustedAdd, are invalid

func (InvalidSignatureIncludedError) Error added in v0.23.9 

func (e InvalidSignatureIncludedError) Error() string

func (InvalidSignatureIncludedError) Unwrap added in v0.23.9 

func (e InvalidSignatureIncludedError) Unwrap() error

type InvalidSignerIdxError added in v0.23.9 

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

InvalidSignerIdxError indicates that the signer index is invalid

func (InvalidSignerIdxError) Error added in v0.23.9 

func (e InvalidSignerIdxError) Error() string

func (InvalidSignerIdxError) Unwrap added in v0.23.9 

func (e InvalidSignerIdxError) Unwrap() error

type InvalidSignerIndicesError added in v0.26.2 

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

InvalidSignerIndicesError indicates that a bit vector does not encode a valid set of signers

func (InvalidSignerIndicesError) Error added in v0.26.2 

func (e InvalidSignerIndicesError) Error() string

func (InvalidSignerIndicesError) Unwrap added in v0.26.2 

func (e InvalidSignerIndicesError) Unwrap() error

type SignatureAggregatorSameMessage added in v0.23.9 

type SignatureAggregatorSameMessage struct{}

These functions are the non-relic versions of some public functions from the package. The functions are here to allow the build of flow-emulator, since the emulator is built without the "relic" build tag, and does not run the functions below.

func NewSignatureAggregatorSameMessage added in v0.23.9 

func NewSignatureAggregatorSameMessage(
	message []byte,
	dsTag string,
	publicKeys []crypto.PublicKey,
) (*SignatureAggregatorSameMessage, error)

func (*SignatureAggregatorSameMessage) Aggregate added in v0.23.9 

func (s *SignatureAggregatorSameMessage) Aggregate() ([]int, crypto.Signature, error)

func (*SignatureAggregatorSameMessage) TrustedAdd added in v0.23.9 

func (s *SignatureAggregatorSameMessage) TrustedAdd(signer int, sig crypto.Signature) error

func (*SignatureAggregatorSameMessage) Verify added in v0.23.9 

func (s *SignatureAggregatorSameMessage) Verify(signer int, sig crypto.Signature) (bool, error)

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.