envelope_hash.rs

Overview

This file provides functionality for computing a cryptographic hash of an Envelope containing an AckiNackiBlock using the SHA-256 hash algorithm. It defines a strongly typed wrapper for the hash output and implements serialization, deserialization, and debug formatting for it. The hash function ensures message integrity and allows unique identification of envelopes within the system.

Types and Structures

AckiNackiEnvelopeHash

pub struct AckiNackiEnvelopeHash(pub [u8; 32]);

• Purpose: Wraps a 32-byte array representing the SHA-256 hash of an Envelope containing an AckiNackiBlock.

• Derives:

  • Clone - allows duplication of hash instances.

  • Eq, PartialEq - supports equality comparison.

  • Serialize, Deserialize - supports (de)serialization via serde.

  • Hash - allows usage as keys in hash maps or sets.

• Serialization: Uses #[serde(transparent)] to treat the wrapper as its inner byte array for serialization purposes.

• Debug Implementation: Formats the hash as a hexadecimal string wrapped in AckiNackiEnvelopeHash<...> for human-readable debugging.

Debug Implementation Details

The Debug trait implementation customizes how instances of AckiNackiEnvelopeHash appear when printed with formatting macros like {:?}:

impl Debug for AckiNackiEnvelopeHash {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        write!(formatter, "AckiNackiEnvelopeHash<{}>", hex::encode(self.0))
    }
}

It converts the internal 32-byte hash into a lowercase hexadecimal string for clarity.

Functions

envelope_hash

pub fn envelope_hash(envelope: &Envelope<GoshBLS, AckiNackiBlock>) -> AckiNackiEnvelopeHash

• Parameters:

  • envelope: Reference to an Envelope parameterized on GoshBLS cryptographic scheme and containing an AckiNackiBlock.

• Returns: An AckiNackiEnvelopeHash instance representing the SHA-256 hash of the serialized envelope.

Functionality

1. Serializes the given Envelope using bincode serialization.

2. Creates a new SHA-256 hasher instance.

3. Feeds the serialized data into the hasher.

4. Finalizes the hash computation and converts the result into a fixed-size byte array.

5. Wraps the byte array into an AckiNackiEnvelopeHash struct and returns it.

Usage Example

let envelope: Envelope<GoshBLS, AckiNackiBlock> = /* obtain or create envelope */;
let hash = envelope_hash(&envelope);
println!("{:?}", hash); // Prints: AckiNackiEnvelopeHash<...hex string...>

Implementation Details

• Serialization: Uses bincode crate for binary serialization of the envelope, which provides compact and efficient encoding.

• Hashing: Utilizes sha2 crate's Sha256 implementation to compute a cryptographic hash ensuring data integrity and uniqueness.

• Error Handling: The serialization step uses unwrap(), which will panic if serialization fails. This implies the expectation that serialization errors are impossible or should be handled at a higher layer.

• Type Safety: The wrapper struct AckiNackiEnvelopeHash enforces type safety and semantic clarity when dealing with hashes of envelopes.

Interactions with Other Parts of the System

• Envelope: The Envelope type is imported from the bls::envelope module and represents signed messages or payload containers parameterized by cryptographic schemes and block types.

• GoshBLS: A specific BLS cryptographic scheme used as a parameter for the Envelope.

• AckiNackiBlock: The block type contained inside the Envelope, imported from the types module.

• Serialization and Hashing Libraries: Relies on external crates bincode for serialization, sha2 for hashing, and serde for (de)serialization traits.

• The hash produced by envelope_hash is primarily used for identifying envelopes uniquely, ensuring integrity, and may be used as keys in data structures or for cryptographic verification purposes.

Diagram

classDiagram
class AckiNackiEnvelopeHash {
+[u8; 32]
+Debug::fmt()
}
class Envelope {
<<generic>>
}
class GoshBLS
class AckiNackiBlock
AckiNackiEnvelopeHash --> Envelope : hashes
Envelope <|-- Envelope<GoshBLS, AckiNackiBlock>
envelope_hash() --> AckiNackiEnvelopeHash
envelope_hash() --> Envelope

The diagram illustrates the relationship between the main types and the hashing function in this file. envelope_hash takes an Envelope parameterized with GoshBLS and AckiNackiBlock and produces an AckiNackiEnvelopeHash instance. The AckiNackiEnvelopeHash struct wraps a byte array and implements the Debug trait.