signature

func CheckSumFromIdentities ¶

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

CheckSumFromIdentities returns checksum for the given identities

func CompareAndExtract ¶

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 ¶

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 ¶

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 ¶

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 ¶

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 ¶

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 ¶

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 ¶

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

EncodeIdentities will concatenation all the identities into bytes

func EncodeSignerToIndicesAndSigType ¶

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 ¶

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 ¶

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 ¶

func IsDuplicatedSignerIdxError(err error) bool

IsDuplicatedSignerIdxError returns whether err is an DuplicatedSignerIdxError

func IsInsufficientSignaturesError ¶

func IsInsufficientSignaturesError(err error) bool

IsInsufficientSignaturesError returns whether err is an InsufficientSignaturesError

func IsInvalidSigTypesError ¶

func IsInvalidSigTypesError(err error) bool

IsInvalidSigTypesError returns whether err is an InvalidSigTypesError

func IsInvalidSignatureIncludedError ¶

func IsInvalidSignatureIncludedError(err error) bool

IsInvalidSignatureIncludedError returns whether err is an InvalidSignatureIncludedError

func IsInvalidSignerIdxError ¶

func IsInvalidSignerIdxError(err error) bool

IsInvalidSignerIdxError returns whether err is an InvalidSignerIdxError

func IsInvalidSignerIndicesError ¶

func IsInvalidSignerIndicesError(err error) bool

IsInvalidSignerIndicesError returns whether err is an InvalidSignerIndicesError

func NewBLSHasher ¶

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.

func NewDuplicatedSignerIdxErrorf ¶

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

func NewInsufficientSignaturesErrorf ¶

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

func NewInvalidSigTypesErrorf ¶

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

func NewInvalidSignatureIncludedErrorf ¶

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

func NewInvalidSignerIdxErrorf ¶

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

func NewInvalidSignerIndicesErrorf ¶

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

func PrefixCheckSum ¶

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

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

func RandomBeaconThreshold ¶

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 ¶

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