ClockHash-256

A high-performance, cryptographic hash function designed specifically for blockchain consensus operations in ClockinChain. ClockHash-256 provides 256-bit security with exceptional performance and memory safety guarantees.

Table of Contents

• Features
• Installation
• Usage
• API Documentation
• Performance
• Security
• Algorithm Overview
• Testing
• Contributing
• License

Features

• 🚀 High Performance: ≥1.5 GB/s single-threaded on modern x86_64 CPUs
• 🔒 Cryptographic Security: 256-bit preimage resistance, 128-bit collision resistance
• 🛡️ Memory Safe: Zero unsafe code, guaranteed by Rust's ownership system
• 🔄 Domain Separation: Prevents cross-domain collision attacks
• 📦 no_std Compatible: Works in embedded and constrained environments
• ⚡ SIMD Optimized: Hardware acceleration on x86_64, ARM, and other architectures
• 🔄 Incremental Hashing: Stream large datasets efficiently
• ⏱️ Constant-Time: Timing attack resistant operations
• 🏗️ Zero Dependencies: Pure Rust implementation

Installation

Add this to your Cargo.toml:

[dependencies]
clock-hash = "1.0.0"

Feature Flags

• default: Includes std and bench features
• std: Enables standard library support (default)
• no_std: Disables standard library for embedded use
• simd: Enables SIMD optimizations (default on supported platforms)
• bench: Includes benchmarking utilities

For no_std environments:

[dependencies]
clock-hash = { version = "1.0.0", default-features = false, features = ["alloc"] }

Usage

Basic Hashing

use clock_hash::clockhash256;

fn main() {
    let data = b"Hello, ClockHash!";
    let hash = clockhash256(data);

    println!("Hash: {:x}", hash.iter().fold(String::new(), |mut acc, &b| {
        acc.push_str(&format!("{:02x}", b));
        acc
    }));
    // Output: 32-byte hash array
}

Domain-Separated Hashing

Prevent cross-domain collisions by using domain tags:

use clock_hash::{clockhash256_domain, tags};

fn hash_blockchain_data() {
    let block_data = b"block_header_data";
    let tx_data = b"transaction_data";

    // Hash block data with domain separation
    let block_hash = clockhash256_domain(tags::CLK_BLOCK, block_data);

    // Hash transaction data with domain separation
    let tx_hash = clockhash256_domain(tags::CLK_TX, tx_data);

    // These hashes will be different even if block_data == tx_data
    assert_ne!(block_hash, tx_hash);
}

Incremental Hashing

For large datasets or streaming data:

use clock_hash::ClockHasher;

fn hash_large_file() -> Result<(), Box<dyn std::error::Error>> {
    let mut hasher = ClockHasher::new();

    // Process data in chunks
    let chunks = vec![b"chunk1", b"chunk2", b"chunk3"];
    for chunk in chunks {
        hasher.update(chunk);
    }

    let final_hash = hasher.finalize();
    println!("Final hash: {:x}", final_hash.iter().fold(String::new(), |mut acc, &b| {
        acc.push_str(&format!("{:02x}", b));
        acc
    }));

    Ok(())
}

Domain Tags

ClockHash-256 supports the following domain tags for cryptographic separation:

API Documentation

📚 Full API Documentation

The API is designed to be simple and ergonomic:

• clockhash256(data: &[u8]) -> [u8; 32]: One-shot hashing
• clockhash256_domain(tag: u8, data: &[u8]) -> [u8; 32]: Domain-separated hashing
• ClockHasher: Incremental hasher struct
• tags: Predefined domain tag constants

Performance

ClockHash-256 is optimized for high throughput:

• Target: ≥1.5 GB/s single-threaded on modern x86_64
• SIMD: Hardware acceleration on AVX2/AVX-512, NEON, and other SIMD instruction sets
• Memory: Minimal memory footprint, suitable for constrained environments
• Scalability: Performance scales with CPU core count

Run benchmarks locally:

cargo bench

Security

ClockHash-256 is designed with security as the highest priority:

• 256-bit preimage resistance: Resistant to finding preimages
• 128-bit collision resistance: Resistant to finding collisions
• Domain separation: Prevents cross-domain collision attacks
• Constant-time operations: Immune to timing attacks
• Memory safety: Zero unsafe code, guaranteed by Rust
• Comprehensive testing: Property-based testing, fuzzing, and formal verification

For security-related issues, see our Security Policy.

Algorithm Overview

ClockHash-256 processes messages in 128-byte blocks using a novel construction:

1. ClockPermute: 16-round permutation with strong diffusion
2. S-box: 256-byte substitution table for nonlinearity
3. ClockMix: Message scrambling with avalanche effect
4. Output folding: Final compression to 256 bits

See RFC-0002 for the complete cryptographic specification.

Testing

ClockHash-256 has comprehensive test coverage:

# Run all tests
cargo test

# Run tests without default features
cargo test --no-default-features --features no_std

# Run fuzzing (requires nightly Rust)
cd fuzz && cargo fuzz run clockhash256_fuzz

# Run benchmarks
cargo bench

Test Coverage

• ✅ Unit tests for all public APIs
• ✅ Property-based testing with proptest
• ✅ Fuzzing with cargo-fuzz
• ✅ Cross-platform testing (Linux, macOS, Windows)
• ✅ no_std compatibility testing
• ✅ Security property verification
• ✅ Performance regression testing

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/Olyntar-Labs/clock-hash.git
cd clock-hash

# Run tests
cargo test

# Run benchmarks
cargo bench

# Check code formatting
cargo fmt --check

# Run linting
cargo clippy

Security Reviews

All changes undergo security review. See our Security Policy for vulnerability reporting.

Changelog

See CHANGELOG.md for version history and migration guides.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

ClockHash-256 - High-performance cryptography for blockchain consensus ⚡🔒