gosh_bls.rs

Overview

This file implements a BLS (Boneh–Lynn–Shacham) signature scheme abstraction named GoshBLS using the gosh_blst cryptographic library. It provides core functionalities for signing, verifying, and aggregating BLS signatures within the system. The file defines wrapper types for public keys, secret keys, and signatures, enhancing serialization, deserialization, and debugging capabilities.

The BLS signature scheme implemented here follows the minimal-pubkey-size variant (min_pk) from gosh_blst, using the BLS_SIG_BLS12381G2_XMD:SHA-256_SSWU_RO_NUL_ domain separation tag (DST). This DST ensures signature domain separation for security and interoperability.

Entities and Their Functionalities

Struct: GoshBLS

A zero-sized struct serving as the main entry point implementing the BLSSignatureScheme trait.

• Purpose: Provides static utility functions related to signature aggregation and serves as a marker type for the BLS scheme.

• Methods:

  • merge_all(signatures: &[Signature]) -> anyhow::Result<Signature>

    • Aggregates multiple BLS signatures into a single aggregated signature.

    • Parameters: Slice of Signature references.

    • Returns: A single aggregated Signature on success, or an error if aggregation fails.

    • Details: Internally uses gosh_blst::min_pk::AggregateSignature::aggregate with verification enabled.

    • Usage example:

      let agg_sig = GoshBLS::merge_all(&signatures)?;
      

Struct: Signature

A wrapper around gosh_blst::min_pk::Signature, enabling serialization, deserialization, hashing, equality, and debug output.

• Derives: Hash, Deserialize, Serialize, Clone, PartialEq, Eq, Debug.

• Methods:

  • empty() -> Self (test-only)

    • Returns a fixed, deterministic empty signature mainly for testing.

    • Uses a predefined byte array to generate a Signature.

• Default implementation: For testing, defaults to empty().

Struct: PubKey

A wrapper around gosh_blst::min_pk::PublicKey, supporting serialization, deserialization, hashing, equality, and debug output with abbreviated formatting.

• Derives: Hash, Deserialize, Serialize, Clone, PartialEq, Eq.

• Traits:

  • Implements Debug to show a truncated hex representation of the key.

  • Implements From for conversions from:

    • gosh_blst::min_pk::PublicKey

    • [u8; BLS_PUBLIC_KEY_LEN]

    • &[u8] slice

  • Implements FromStr for parsing a hex string into a PubKey.

  • Implements AsRef for borrowing the inner PublicKey.

• Default implementation: For testing, returns a fixed public key derived from zero key material.

Struct: Secret

A wrapper around gosh_blst::min_pk::SecretKey, supporting serialization, deserialization, and debug output.

• Derives: Deserialize, Serialize, Clone.

• Methods:

  • take_as_seed() -> [u8; 32]

    • Returns the secret key bytes as a 32-byte seed array.

  • Implements Debug to output the hex-encoded secret key bytes.

• Traits:

  • Implements From<[u8; BLS_SECRET_KEY_LEN]> for conversion from raw bytes.

  • Implements FromStr for parsing a hex string into a Secret.

• Default implementation: For testing, returns a fixed secret key from zero key material.

Trait Implementation: BLSSignatureScheme for GoshBLS

Implements the core BLS signature scheme interface:

• Associated Types:

  • PubKey = PubKey

  • Secret = Secret

  • Signature = Signature

• Functions:

  • sign(secret: &Secret, data: &TData) -> anyhow::Result<Signature>

    • Signs serialized data using the provided secret key.

    • Parameters:

      • secret: The secret key.

      • data: Any serializable data to sign.

    • Returns: A Signature on success.

    • Details: Uses bincode serialization and signs the serialized bytes with the secret key and DST.

  • verify(signature: &Signature, pubkeys_occurrences: &mut dyn Iterator<Item = &(PubKey, usize)>, data: &TData) -> anyhow::Result<bool>

    • Verifies that the signature is valid for the given data and aggregated public keys.

    • Parameters:

      • signature: The signature to verify.

      • pubkeys_occurrences: An iterator over public keys and their multiplicities (occurrences).

      • data: The signed data.

    • Returns: true if the signature is valid; otherwise false.

    • Details:

      • Flattens public keys according to their occurrences.

      • Aggregates the public keys using gosh_blst::min_pk::AggregatePublicKey::aggregate.

      • Serializes the data and verifies the signature against the aggregated public key.

      • Includes optional timing instrumentation gated by the timing feature.

  • merge(one: &Signature, another: &Signature) -> anyhow::Result<Signature>

    • Merges two signatures into a single aggregated signature.

    • Parameters:

      • one: First signature.

      • another: Second signature.

    • Returns: A new aggregated Signature or an error if merging fails.

    • Details: Uses gosh_blst::min_pk::AggregateSignature APIs to add the second signature to the first.

Important Implementation Details and Algorithms

• Domain Separation Tag (DST):
  The constant DST is a 43-byte array specifying the domain separation for BLS signatures, fixed as BLS_SIG_BLS12381G2_XMD:SHA-256_SSWU_RO_NUL_. This ensures signatures are bound to a specific domain and reduces risks of cross-protocol attacks.

• Signature Aggregation:
  Both merge and merge_all methods use gosh_blst's AggregateSignature APIs to perform signature aggregation. The merge_all method supports aggregating multiple signatures at once, while merge combines two signatures.

• Public Key Aggregation:
  The verify function aggregates multiple public keys weighted by their occurrences before verifying a signature. This allows verifying aggregated signatures from multiple signers efficiently.

• Serialization:
  Data to be signed or verified is serialized using bincode, providing a compact and consistent binary representation.

• Testing Defaults:
  The Default implementations for Signature, PubKey, and Secret provide fixed, deterministic values derived from zero key material, facilitating reproducible test cases.

• Error Handling:
  All critical operations return anyhow::Result to propagate errors with context, especially during aggregation and parsing failures.

Interactions With Other Components

• gosh_blst library:
  This file depends heavily on the gosh_blst crate, which provides the underlying cryptographic primitives and types (SecretKey, PublicKey, Signature, and aggregation types).

• crate::bls::BLSSignatureScheme trait:
  The GoshBLS struct implements this trait, which defines the interface for BLS signature schemes used throughout the system. This abstraction allows interchangeable signature scheme implementations.

• Serialization crates:
  Uses serde, serde_with, and bincode for serialization and deserialization of keys and signatures, enabling easy persistence and network transmission.

• Hex encoding:
  Utilized in Debug implementations and FromStr parsing for human-readable representation and string-based initialization of keys.

• Testing utilities:
  The test-only Default implementations and empty() method in Signature facilitate unit testing by providing known fixed keys and signatures.

Visual Diagram: Structure and Relationships of Main Types and Methods

classDiagram
class GoshBLS {
+merge_all(signatures)
}
class Signature {
+empty()
}
class PubKey {
+from_bytes()
+from_str()
}
class Secret {
+take_as_seed()
}
class BLSSignatureScheme {
+sign(secret, data)
+verify(signature, pubkeys, data)
+merge(one, another)
}
GoshBLS ..|> BLSSignatureScheme
GoshBLS o-- Signature
GoshBLS o-- PubKey
GoshBLS o-- Secret

This diagram illustrates the primary types (GoshBLS, Signature, PubKey, Secret) and their relationship to the BLSSignatureScheme trait, showing how GoshBLS implements the trait and composes the key and signature types.