Crate penis 

Penis Protocol

A cryptographic protocol that enables verifiable hashing while maintaining data confidentiality. PENIS (Partially Executed Nth-round Intermediate State) allows generating SHA-256 compatible hashes that can be verified without revealing the entire input data.

Overview

The protocol operates by:

1. Pausing SHA-256 hash computation at a specified round (n)
2. Preserving intermediate state for confidential data portions
3. Allowing verification of the final hash without exposing confidential data

Security Considerations

• Always use security parameter n=40 for maximum security in production
• Values of n<32 are NOT recommended for sensitive data
• Values of n<16 are UNSAFE as they reveal unhashed data
• Values of n≥48 are invalid and cause implementation errors

Core Components

Generator

PenisGenerator creates intermediate hash states while preserving confidentiality of specified data ranges. It executes the hash computation up to the specified round n and produces verifiable intermediate states.

use penis::{PenisGenerator, SecsParam, DataRange, ToBeHashed};

// Initialize with maximum security (n=40)
let generator = PenisGenerator(SecsParam::new(40));

// Prepare data with confidential ranges
let tbh = ToBeHashed {
    data: b"Hello, World!".to_vec(),
    confidentials: vec![DataRange::new(0, 5)], // Keep "Hello" confidential
};

// Generate intermediate state
let penis = generator.execute(tbh);

Verifier

PenisVerifier validates and completes the hash computation from intermediate states without accessing the confidential data. It ensures the integrity of the final hash while maintaining data privacy.

use penis::{PenisVerifier, SecsParam, Penis};

// Initialize with same security parameter
let verifier = PenisVerifier(SecsParam::new(40));

// Resume hash computation from intermediate state
let final_state = verifier.resume(penis);
let hash = final_state.finalize();

Data Structures

• Penis: Represents the Partially Executed Nth-round Intermediate State
• PenisBlock: Represents either a confidential or public block in the hash computation
• PrivateBlock: Contains intermediate state and partial schedule array for confidential blocks
• State: Represents the internal state of SHA-256 hash computation
• DataRange: Specifies ranges of confidential data
• ToBeHashed: Contains input data and confidential ranges
• SecsParam: Security parameters controlling the protocol behavior

Best Practices

1. Security

   • Use n=40 for maximum security
   • Validate all input data
   • Implement additional encryption for network transmission
   • Monitor for timing attacks
   • Keep confidential ranges minimal

2. Performance

   • Pre-allocate vectors when possible
   • Reuse generator/verifier instances
   • Process large data in chunks
   • Monitor memory usage

3. Error Handling

   • Always check data range validity
   • Handle all error cases appropriately
   • Implement proper cleanup procedures
   • Avoid leaking sensitive information in errors

Example

use penis::*;

// Initialize with maximum security
let secs = SecsParam::new(40);
let generator = PenisGenerator(secs);

// Prepare data with confidential range
let data = b"Hello, World!".to_vec();
let confidential = DataRange::new(0, 5); // Keep "Hello" confidential
let tbh = ToBeHashed {
    data,
    confidentials: vec![confidential],
};

// Validate ranges
tbh.check_datarange().expect("Invalid data range");

// Generate intermediate state
let penis = generator.execute(tbh);

// Encode for transmission
let encoded = penis.encode_sparse();

/* --- Transmission... --- */

let secs = SecsParam::new(40);
let verifier = PenisVerifier(secs);

// Decode and verify
let decoded = Penis::decode_sparse(&encoded);
let final_state = verifier.resume(decoded);
let hash = final_state.finalize();

Structs

DataRange

Data range

Penis

Partially Executed Nth-round Intermediate State

PenisGenerator

Penis Generator

PenisVerifier

Penis Verifier

PrivateBlock

Private block containing intermediate state and partial schedule array

SecsParam

Security Parameter

State

SHA-256 internal state

ToBeHashed

ToBeHashed: Input data and confidential ranges

Enums

PenisBlock

Represents either a private (confidential) or public block in the hash computation