Add security hardening, no_std support, fuzzing, and examples

Author: dcondrey

Cargo.toml

@@ -12,23 +12,32 @@ categories = ["cryptography", "authentication"]
 readme = "README.md"
 
 [dependencies]
-hmac = "0.12"
-sha2 = "0.10"
-serde = { version = "1.0", features = ["derive"] }
-serde_json = "1.0"
-thiserror = "2.0"
+hmac = { version = "0.12", default-features = false }
+sha2 = { version = "0.10", default-features = false }
+serde = { version = "1.0", default-features = false, features = ["derive", "alloc"] }
+serde_json = { version = "1.0", optional = true }
+thiserror = { version = "2.0", optional = true }
 getrandom = "0.3"
-zeroize = { version = "1.8", features = ["derive"] }
-subtle = "2.5"
+zeroize = { version = "1.8", default-features = false, features = ["derive", "alloc"] }
+subtle = { version = "2.5", default-features = false }
 rand = { version = "0.8", optional = true }
-hkdf = "0.12.4"
+hkdf = { version = "0.12.4", default-features = false }
+libm = "0.2"
 
 [dev-dependencies]
 rand = "0.8"
+criterion = "0.5"
+serde_json = "1.0"
+
+[[bench]]
+name = "benchmarks"
+harness = false
 
 [features]
-default = []
-# Enable hardware entropy collection (TSC, etc.)
-hardware = []
-# Enable random secret generation
-rand = ["dep:rand"]
+default = ["std"]
+# Enable standard library (required for Session, timing, serde_json)
+std = ["dep:serde_json", "dep:thiserror", "sha2/std", "hmac/std", "serde/std", "zeroize/std", "hkdf/std"]
+# Enable hardware entropy collection (TSC, etc.) - requires std for timing fallback
+hardware = ["std"]
+# Enable random secret generation - requires std
+rand = ["dep:rand", "std"]

README.md

@@ -734,6 +734,33 @@ cargo test --all-features
 cargo test --no-default-features
 ```
 
+### Fuzzing
+
+This crate includes fuzzing targets using `cargo-fuzz` to find edge cases and potential bugs:
+
+| Target | Description |
+|--------|-------------|
+| `fuzz_evidence_json` | JSON deserialization of Evidence and EvidenceChain |
+| `fuzz_human_model` | HumanModel validation with arbitrary jitter/IKI values |
+| `fuzz_evidence_verify` | Evidence verification and chain integrity |
+| `fuzz_jitter_compute` | Jitter computation with various parameters |
+
+```bash
+# Install cargo-fuzz (requires nightly)
+cargo install cargo-fuzz
+
+# Run a specific fuzz target
+cargo +nightly fuzz run fuzz_evidence_json
+
+# Run with a time limit (60 seconds)
+cargo +nightly fuzz run fuzz_human_model -- -max_total_time=60
+
+# Run all fuzz targets briefly
+for target in fuzz_evidence_json fuzz_human_model fuzz_evidence_verify fuzz_jitter_compute; do
+  cargo +nightly fuzz run $target -- -max_total_time=10
+done
+```
+
 ---
 
 ## FAQ

benches/benchmarks.rs

@@ -0,0 +1,70 @@
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+use physjitter::{
+    Evidence, EvidenceChain, HumanModel, HybridEngine, Jitter, JitterEngine, PureJitter,
+};
+
+fn bench_pure_jitter(c: &mut Criterion) {
+    let engine = PureJitter::default();
+    let secret = [42u8; 32];
+    let inputs = b"keystroke data";
+    let entropy = [0u8; 32].into();
+
+    c.bench_function("PureJitter::compute_jitter", |b| {
+        b.iter(|| engine.compute_jitter(black_box(&secret), black_box(inputs), black_box(entropy)))
+    });
+}
+
+fn bench_hybrid_engine(c: &mut Criterion) {
+    let engine = HybridEngine::default();
+    let secret = [42u8; 32];
+    let inputs = b"keystroke data";
+
+    c.bench_function("HybridEngine::sample", |b| {
+        b.iter(|| engine.sample(black_box(&secret), black_box(inputs)))
+    });
+}
+
+fn bench_evidence_chain_append(c: &mut Criterion) {
+    let secret = [42u8; 32];
+
+    c.bench_function("EvidenceChain::append", |b| {
+        b.iter_with_setup(
+            || EvidenceChain::with_secret(secret),
+            |mut chain| {
+                chain.append(Evidence::pure(1500));
+                chain
+            },
+        )
+    });
+}
+
+fn bench_human_model_validate(c: &mut Criterion) {
+    let model = HumanModel::default();
+    let jitters: Vec<Jitter> = (0..1000).map(|i| 500 + ((i * 37) % 2500) as u32).collect();
+
+    c.bench_function("HumanModel::validate (1000 samples)", |b| {
+        b.iter(|| model.validate(black_box(&jitters)))
+    });
+}
+
+fn bench_evidence_chain_verify_integrity(c: &mut Criterion) {
+    let secret = [42u8; 32];
+    let mut chain = EvidenceChain::with_secret(secret);
+    for i in 0..100 {
+        chain.append(Evidence::pure(500 + (i % 2500) as u32));
+    }
+
+    c.bench_function("EvidenceChain::verify_integrity (100 records)", |b| {
+        b.iter(|| chain.verify_integrity(black_box(&secret)))
+    });
+}
+
+criterion_group!(
+    benches,
+    bench_pure_jitter,
+    bench_hybrid_engine,
+    bench_evidence_chain_append,
+    bench_human_model_validate,
+    bench_evidence_chain_verify_integrity,
+);
+criterion_main!(benches);

examples/basic_session.rs

@@ -0,0 +1,47 @@
+//! Basic session usage example.
+//!
+//! Run with: `cargo run --example basic_session`
+
+use physjitter::Session;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Create a session with a secret key
+    // In production, derive this from a secure source!
+    let secret = [42u8; 32];
+    let mut session = Session::new(secret);
+
+    // Simulate typing keystrokes
+    let keystrokes = ["H", "e", "l", "l", "o", " ", "W", "o", "r", "l", "d", "!"];
+
+    println!("Simulating {} keystrokes...", keystrokes.len());
+
+    for keystroke in keystrokes {
+        let jitter_us = session.sample(keystroke.as_bytes())?;
+        println!("  '{}' -> {}μs jitter", keystroke, jitter_us);
+
+        // In a real application, you would apply this delay
+        // std::thread::sleep(std::time::Duration::from_micros(jitter_us as u64));
+    }
+
+    // Need more samples for validation
+    for i in 0..20 {
+        session.sample(format!("extra{}", i).as_bytes())?;
+    }
+
+    // Validate against human typing model
+    let result = session.validate();
+    println!("\nValidation Results:");
+    println!("  Is human: {}", result.is_human);
+    println!("  Confidence: {:.2}", result.confidence);
+    println!("  Anomalies: {}", result.anomalies.len());
+
+    // Export evidence
+    let _json = session.export_json()?;
+    println!(
+        "\nEvidence chain has {} records",
+        session.evidence().records.len()
+    );
+    println!("Physics ratio: {:.1}%", session.phys_ratio() * 100.0);
+
+    Ok(())
+}

examples/custom_engine.rs

@@ -0,0 +1,36 @@
+//! Custom engine configuration example.
+//!
+//! Run with: `cargo run --example custom_engine --features hardware`
+
+use physjitter::{HybridEngine, PhysJitter, PureJitter};
+
+fn main() {
+    // Create custom engines with specific parameters
+    let phys = PhysJitter::new(8) // Require 8 bits minimum entropy
+        .with_jitter_range(1000, 2000); // 1000-3000μs range
+
+    let pure = PureJitter::new(1000, 2000); // Matching range for fallback
+
+    let engine = HybridEngine::new(phys, pure).with_min_entropy(8);
+
+    println!("Custom engine created");
+    println!("  Physics available: {}", engine.phys_available());
+
+    // Sample some jitter
+    let secret = [42u8; 32];
+    for i in 0..5 {
+        let (jitter, evidence) = engine
+            .sample(&secret, format!("input{}", i).as_bytes())
+            .unwrap();
+        println!(
+            "  Sample {}: {}μs ({})",
+            i,
+            jitter,
+            if evidence.is_phys() {
+                "physics"
+            } else {
+                "pure"
+            }
+        );
+    }
+}

examples/verify_evidence.rs

@@ -0,0 +1,64 @@
+//! Evidence chain verification example.
+//!
+//! Run with: `cargo run --example verify_evidence`
+
+use physjitter::{Evidence, EvidenceChain, JitterEngine, PureJitter};
+
+fn main() {
+    let secret = [42u8; 32];
+    let engine = PureJitter::default();
+
+    // Build an evidence chain
+    let inputs: Vec<&[u8]> = vec![b"key1", b"key2", b"key3", b"key4", b"key5"];
+    let mut chain = EvidenceChain::with_secret(secret);
+
+    println!("Building evidence chain...");
+    for input in &inputs {
+        let jitter = engine.compute_jitter(&secret, input, [0u8; 32].into());
+        chain.append(Evidence::pure(jitter));
+        println!(
+            "  Added evidence for {:?} -> {}μs",
+            String::from_utf8_lossy(input),
+            jitter
+        );
+    }
+
+    // Verify chain integrity
+    println!("\nVerifying chain integrity...");
+    let integrity_ok = chain.verify_integrity(&secret);
+    println!(
+        "  Integrity check: {}",
+        if integrity_ok { "PASSED" } else { "FAILED" }
+    );
+
+    // Verify against original inputs
+    let chain_ok = chain.verify_chain(&secret, &inputs, &engine);
+    println!(
+        "  Chain verification: {}",
+        if chain_ok { "PASSED" } else { "FAILED" }
+    );
+
+    // Try with wrong inputs
+    let wrong_inputs: Vec<&[u8]> = vec![b"wrong1", b"wrong2", b"wrong3", b"wrong4", b"wrong5"];
+    let wrong_ok = chain.verify_chain(&secret, &wrong_inputs, &engine);
+    println!(
+        "  Wrong inputs check: {}",
+        if !wrong_ok {
+            "CORRECTLY REJECTED"
+        } else {
+            "ERROR"
+        }
+    );
+
+    // Tamper detection demo
+    println!("\nTamper detection demo...");
+    let mut tampered_chain = chain.clone();
+    if let Some(Evidence::Pure { jitter, .. }) = tampered_chain.records.get_mut(2) {
+        *jitter = 9999;
+    }
+    let tamper_detected = !tampered_chain.verify_integrity(&secret);
+    println!(
+        "  Tamper detected: {}",
+        if tamper_detected { "YES" } else { "NO" }
+    );
+}

fuzz/.gitignore

@@ -0,0 +1,4 @@
+target/
+corpus/
+artifacts/
+coverage/

fuzz/Cargo.toml

@@ -0,0 +1,47 @@
+[package]
+name = "physjitter-fuzz"
+version = "0.0.0"
+publish = false
+edition = "2021"
+
+[package.metadata]
+cargo-fuzz = true
+
+[dependencies]
+libfuzzer-sys = "0.4"
+arbitrary = { version = "1", features = ["derive"] }
+serde_json = "1.0"
+
+[dependencies.physjitter]
+path = ".."
+
+[[bin]]
+name = "fuzz_evidence_json"
+path = "fuzz_targets/fuzz_evidence_json.rs"
+test = false
+doc = false
+bench = false
+
+[[bin]]
+name = "fuzz_human_model"
+path = "fuzz_targets/fuzz_human_model.rs"
+test = false
+doc = false
+bench = false
+
+[[bin]]
+name = "fuzz_evidence_verify"
+path = "fuzz_targets/fuzz_evidence_verify.rs"
+test = false
+doc = false
+bench = false
+
+[[bin]]
+name = "fuzz_jitter_compute"
+path = "fuzz_targets/fuzz_jitter_compute.rs"
+test = false
+doc = false
+bench = false
+
+[workspace]
+members = ["."]

fuzz/fuzz_targets/fuzz_evidence_json.rs

@@ -0,0 +1,19 @@
+#![no_main]
+
+use libfuzzer_sys::fuzz_target;
+use physjitter::{Evidence, EvidenceChain};
+
+fuzz_target!(|data: &[u8]| {
+    // Fuzz Evidence deserialization
+    if let Ok(s) = std::str::from_utf8(data) {
+        // Try to parse as Evidence
+        let _ = serde_json::from_str::<Evidence>(s);
+
+        // Try to parse as EvidenceChain
+        let _ = serde_json::from_str::<EvidenceChain>(s);
+    }
+
+    // Also test with raw bytes interpreted as potentially valid JSON
+    let _ = serde_json::from_slice::<Evidence>(data);
+    let _ = serde_json::from_slice::<EvidenceChain>(data);
+});