create_signed.rs

Overview

This file provides functionality for creating cryptographically signed envelopes containing serialized data. It defines a trait and implements it for a generic envelope type specialized with the GoshBLS signature scheme. The primary purpose is to enable signing of arbitrary serializable data by nodes identified in a block keeper set, using BLS (Boneh–Lynn–Shacham) signatures. The file integrates cryptographic keys, node identification, and signature aggregation metadata to produce sealed (signed) envelopes.

Trait: CreateSealed<T>

The CreateSealed trait is a generic abstraction for creating sealed envelopes around data of type T. It requires the data to be serializable, cloneable, and safe for concurrent access.

Trait Definition

pub trait CreateSealed<T>
where
    T: Serialize + for<'b> Deserialize<'b> + Clone + Send + Sync + 'static,
{
    fn sealed(
        node_identifier: &NodeIdentifier,
        bk_set: &BlockKeeperSet,
        bls_keys_map: &HashMap<PubKey, (Secret, RndSeed)>,
        data: T,
    ) -> anyhow::Result<Envelope<GoshBLS, T>>;
}

Parameters

• node_identifier: &NodeIdentifier
  The unique identifier of the node that is producing the signed envelope.

• bk_set: &BlockKeeperSet
  A collection of block keeper nodes, providing access to node metadata including public keys and signer indices.

• bls_keys_map: &HashMap<PubKey, (Secret, RndSeed)>
  A map from public keys to their corresponding secret keys and random seeds used for signing.

• data: T
  The data payload to be signed and sealed inside the envelope.

Return Value

Returns an anyhow::Result wrapping an Envelope<GoshBLS, T> on success, or an error otherwise.

Usage

The trait is intended to be used where a signed envelope needs to be created from arbitrary data that must be authenticated cryptographically.

Implementation of CreateSealed<TData> for Envelope<GoshBLS, TData>

This implementation provides the actual logic to create a signed envelope using the GoshBLS signature scheme.

Method: sealed

fn sealed(
    node_identifier: &NodeIdentifier,
    bk_set: &BlockKeeperSet,
    bls_keys_map: &HashMap<PubKey, (Secret, RndSeed)>,
    data: TData,
) -> anyhow::Result<Self>

Implementation Details

1. Node Lookup
   Retrieves the block keeper data (bk_data) associated with the given node_identifier from the bk_set.
   If the node is not found, it returns a descriptive error including the list of valid node IDs.

2. Secret Key Retrieval
   Obtains the secret key and random seed tuple corresponding to the node's public key from the bls_keys_map.
   If the secret is missing, it triggers a shutdown process (start_shutdown()) and returns an error. This ensures that missing critical cryptographic material is handled as a fatal condition.

3. Data Signing
   Signs the input data using the BLS signature scheme implementation (GoshBLS) and the retrieved secret key.

4. Signature Occurrences Map
   Constructs a HashMap to record how many times the signature occurs, keyed by the signer's index. Initially, this map contains a single entry with the current signer's index and a count of 1.

5. Envelope Creation
   Calls Envelope::create() with the signature, signature occurrences map, and original data to generate the sealed envelope.

Return Value

Returns a Result containing the newly created Envelope with the signature and data, or an error if any step fails.

Example Usage

let envelope = Envelope::<GoshBLS, MyDataType>::sealed(
    &my_node_identifier,
    &my_block_keeper_set,
    &my_bls_keys_map,
    my_data,
)?;

Important Types and Their Roles

• Envelope<GoshBLS, T>
  Represents a data container that includes a cryptographic signature along with the serialized payload of type T. This type is defined elsewhere and supports BLS signature schemes.

• GoshBLS
  The BLS signature scheme implementation used to sign and verify data.

• BlockKeeperSet
  A collection that manages block keeper nodes, providing methods to fetch node data by identifier and iterate over node IDs.

• NodeIdentifier
  A unique key identifying a node within the system.

• PubKey and Secret
  Public and secret cryptographic keys used for signing and verification.

• RndSeed
  Random seed associated with secret keys for cryptographic operations.

• BLSSignatureScheme
  Trait defining the interface for BLS signature operations including signing.

• start_shutdown
  Function called to initiate shutdown when critical errors (like missing secret keys) occur.

Interaction with Other System Components

• This file depends on the cryptographic primitives and key management logic provided by the GoshBLS module and related BLS key types.

• It interacts with the BlockKeeperSet to identify valid nodes and obtain their public keys and signer indices.

• The Envelope type from the envelope module is used to package signed data.

• The signing operation uses the secret keys stored in bls_keys_map, linking cryptographic identity to node identities.

• Errors and system shutdowns are managed by invoking start_shutdown() from the helper module when necessary.

• The serialization and deserialization traits (Serialize, Deserialize) ensure that any data type used can be encoded/decoded for transmission and signing.

Diagram: Structure and Workflow of create_signed.rs

flowchart TD
A[CreateSealed Trait] -->|implemented for| B[Envelope<GoshBLS, TData>]
B --> C["sealed() Method"]
C --> D[Lookup NodeIdentifier in BlockKeeperSet]
D --> E{Found?}
E -- Yes --> F[Get PubKey and SignerIndex]
F --> G[Retrieve Secret from bls_keys_map]
G --> H{Secret Found?}
H -- Yes --> I[Sign data with Secret using GoshBLS]
I --> J[Create signature_occurrences map]
J --> K["Call Envelope::create(signature, occurrences, data)"]
K --> L[Return sealed Envelope]
E -- No --> M[Return Error: Node not in BlockKeeperSet]
H -- No --> N["Call start_shutdown()"]
N --> O[Return Error: Secret missing]

This flowchart depicts the main steps performed in the sealed method: node identification, key retrieval, signing, envelope creation, and error handling.