clock_hash/

lib.rs

#![cfg_attr(not(feature = "std"), no_std)]
#![warn(missing_docs)]

//! # ClockHash-256: Consensus Hash Function for ClockinChain
//!
//! ClockHash-256 is a deterministic, fixed-output cryptographic hash function designed
//! for ClockinChain consensus operations. It provides 256-bit security with domain separation
//! for multi-purpose blockchain use cases.
//!
//! ## Features
//!
//! - **256-bit security**: Preimage and collision resistance
//! - **Domain separation**: Different hash outputs for different use cases
//! - **no_std compatibility**: Works in embedded environments
//! - **Incremental hashing**: Stream data processing
//! - **Constant-time operations**: Side-channel resistant
//! - **Performance optimized**: ~1.5 GB/s target on modern hardware
//!
//! ## Quick Start
//!
//! ```rust
//! use clock_hash::clockhash256;
//!
//! let data = b"Hello, ClockinChain!";
//! let hash = clockhash256(data);
//! assert_eq!(hash.len(), 32);
//! ```
//!
//! ## Domain Separation
//!
//! ClockHash-256 uses domain separation to ensure different use cases produce
//! different hash outputs, preventing cross-domain collision attacks.
//!
//! ```rust
//! use clock_hash::{clockhash256_domain, clockhash256_with_domain, DomainTag, tags};
//!
//! let data = b"block header data";
//!
//! // Using domain bytes
//! let block_hash = clockhash256_domain(tags::CLK_BLOCK, data);
//!
//! // Using typed domain enum
//! let tx_hash = clockhash256_with_domain(DomainTag::Transaction, data);
//!
//! assert_ne!(block_hash, tx_hash); // Different domains = different hashes
//! ```
//!
//! ## Incremental Hashing
//!
//! For large or streaming data, use incremental hashing:
//!
//! ```rust
//! use clock_hash::ClockHasher;
//!
//! let mut hasher = ClockHasher::new();
//! hasher.update(b"part 1");
//! hasher.update(b"part 2");
//! hasher.update(b"part 3");
//! let hash = hasher.finalize();
//! ```
//!
//! ## Domain Use Cases
//!
//! ### Block Headers
//! ```rust
//! # use clock_hash::{clockhash256_with_domain, DomainTag};
//! let block_header = b"previous_hash || merkle_root || timestamp || ...";
//! let block_hash = clockhash256_with_domain(DomainTag::Block, block_header);
//! ```
//!
//! ### Transaction IDs
//! ```rust
//! # use clock_hash::{clockhash256_with_domain, DomainTag};
//! let tx_data = b"inputs || outputs || metadata";
//! let tx_id = clockhash256_with_domain(DomainTag::Transaction, tx_data);
//! ```
//!
//! ### Merkle Trees
//! ```rust
//! # use clock_hash::{clockhash256_with_domain, DomainTag};
//! let left_node = b"left child data";
//! let right_node = b"right child data";
//! let left_hash = clockhash256_with_domain(DomainTag::Merkle, left_node);
//! let right_hash = clockhash256_with_domain(DomainTag::Merkle, right_node);
//! let parent_data = [left_hash, right_hash].concat();
//! let parent_hash = clockhash256_with_domain(DomainTag::Merkle, &parent_data);
//! ```
//!
//! ### Signature Nonces
//! ```rust
//! # use clock_hash::{clockhash256_with_domain, DomainTag};
//! let secret_data = b"private_key || message || counter";
//! let nonce = clockhash256_with_domain(DomainTag::Nonce, secret_data);
//! ```
//!
//! ### Deterministic RNG
//! ```rust
//! # use clock_hash::{clockhash256_with_domain, DomainTag};
//! let seed_data = b"user_seed || domain_info";
//! let rng_seed = clockhash256_with_domain(DomainTag::Rng, seed_data);
//! ```
//!
//! ## Security Properties
//!
//! - **Preimage resistance**: Hard to find input for a given hash
//! - **Second preimage resistance**: Hard to find different input with same hash
//! - **Collision resistance**: Hard to find any two inputs with same hash
//! - **Avalanche effect**: Small input changes affect ~50% of output bits
//! - **Domain separation**: Different domains cannot collide
//!
//! ## Performance
//!
//! ClockHash-256 is optimized for modern hardware:
//! - **Throughput**: ~1.5 GB/s on x86_64 (target)
//! - **Memory**: Minimal footprint, cache-friendly
//! - **SIMD**: AVX2/AVX-512 acceleration available
//! - **no_std**: Zero heap allocations in core path

mod clockmix;
mod clockpermute;
pub mod constants;
pub mod cpuid;
mod domain;
mod hasher;
mod padding;
mod performance;
mod security;
pub mod utils;

#[cfg(feature = "simd")]
pub mod simd;

pub use constants::{IV, P0, P1, ROTATION_SCHEDULE, SBOX};
pub use domain::{DomainTag, clockhash256_domain, clockhash256_with_domain, tags};
pub use hasher::ClockHasher;
pub use performance::estimate_memory_usage;
#[cfg(feature = "std")]
pub use performance::{benchmark_sizes, measure_throughput, performance_stats, verify_performance};
#[cfg(all(feature = "simd", feature = "std"))]
pub use simd::dispatch::get_avx512_stats;
pub use security::{verify_avalanche, verify_collision_resistance, verify_domain_separation};
pub use utils::{rotl8, rotl64, rotr64};

// Expose primitive functions for benchmarking and testing
#[cfg(any(test, feature = "bench"))]
pub use clockmix::clock_mix;
#[cfg(any(test, feature = "bench"))]
pub use clockpermute::clock_permute;

/// Compute the ClockHash-256 hash of the input data.
///
/// This is the main entry point for computing ClockHash-256 hashes.
/// The function processes the input data in 128-byte blocks, applies
/// the ClockMix and ClockPermute operations, and produces a 32-byte hash.
///
/// # Arguments
///
/// * `data` - The input data to hash (can be any length)
///
/// # Returns
///
/// A 32-byte array containing the ClockHash-256 hash in little-endian format
///
/// # Examples
///
/// Basic usage:
/// ```rust
/// use clock_hash::clockhash256;
///
/// let data = b"Hello, world!";
/// let hash = clockhash256(data);
/// assert_eq!(hash.len(), 32);
/// // Hash is now available as a 32-byte array
/// ```
///
/// Hashing different inputs produces different outputs:
/// ```rust
/// # use clock_hash::clockhash256;
/// let hash1 = clockhash256(b"input1");
/// let hash2 = clockhash256(b"input2");
/// assert_ne!(hash1, hash2);
/// ```
///
/// Empty input:
/// ```rust
/// # use clock_hash::clockhash256;
/// let hash = clockhash256(b"");
/// // Still produces a valid 32-byte hash
/// assert_eq!(hash.len(), 32);
/// ```
///
/// # Performance
///
/// This function is optimized for performance:
/// - Processes data in 128-byte blocks
/// - Uses SIMD instructions when available
/// - Constant-time operations for security
/// - Minimal memory allocations
#[inline]
pub fn clockhash256(data: &[u8]) -> [u8; 32] {
    let mut hasher = ClockHasher::new();
    hasher.update(data);
    hasher.finalize()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_empty_string() {
        let hash = clockhash256(b"");
        // Test vector will be verified once implementation is complete
        assert_eq!(hash.len(), 32);
    }
}