penis 0.1.1

//! # 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.
//!
//! ```rust
//! 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.
//!
//! ```ignore
//! 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
//!
//! ```rust
//! 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();
//! ```
#![no_std]
extern crate alloc;

mod consts;
mod hashfns;
mod penis;
mod penis_generator;
mod penis_verifier;
mod primitivefns;
mod structs;
mod utils;
pub use penis::Penis;
pub use penis_generator::PenisGenerator;
pub use penis_verifier::PenisVerifier;
pub use structs::{DataRange, PenisBlock, PrivateBlock, SecsParam, State, ToBeHashed};