openentropy_core/lib.rs
1//! # openentropy-core
2//!
3//! **Your computer is a hardware noise observatory.**
4//!
5//! `openentropy-core` is the core entropy harvesting library that extracts randomness
6//! from 38 unconventional hardware sources — clock jitter, DRAM row buffer timing,
7//! CPU speculative execution, Bluetooth RSSI, NVMe latency, and more.
8//!
9//! ## Quick Start
10//!
11//! ```no_run
12//! use openentropy_core::EntropyPool;
13//!
14//! // Auto-detect all available sources and create a pool
15//! let pool = EntropyPool::auto();
16//!
17//! // Get conditioned random bytes
18//! let random_bytes = pool.get_random_bytes(256);
19//! assert_eq!(random_bytes.len(), 256);
20//!
21//! // Check pool health
22//! let health = pool.health_report();
23//! println!("{}/{} sources healthy", health.healthy, health.total);
24//! ```
25//!
26//! ## Architecture
27//!
28//! Sources → Pool (concatenate) → Conditioning → Output
29//!
30//! Three output modes:
31//! - **Sha256** (default): SHA-256 conditioning mixes all source bytes with state,
32//! counter, timestamp, and OS entropy. Cryptographically strong output.
33//! - **VonNeumann**: debiases raw bytes without destroying noise structure.
34//! - **Raw** (`get_raw_bytes`): source bytes pass through unchanged — no hashing,
35//! no whitening, no mixing between sources.
36//!
37//! Raw mode preserves the actual hardware noise signal for researchers studying
38//! device entropy characteristics. Most QRNG APIs (ANU, Outshift) run DRBG
39//! post-processing that destroys the raw hardware signal. We don't.
40//!
41//! Every source implements the [`EntropySource`] trait. The [`EntropyPool`]
42//! collects from all registered sources and concatenates their byte streams.
43
44pub mod conditioning;
45pub mod platform;
46pub mod pool;
47pub mod source;
48pub mod sources;
49
50pub use conditioning::{
51 ConditioningMode, MinEntropyReport, QualityReport, condition, grade_min_entropy,
52 min_entropy_estimate, quick_min_entropy, quick_quality, quick_shannon,
53};
54pub use platform::{detect_available_sources, platform_info};
55pub use pool::{EntropyPool, HealthReport, SourceHealth, SourceInfoSnapshot};
56pub use source::{EntropySource, SourceCategory, SourceInfo};
57
58/// Library version (from Cargo.toml).
59pub const VERSION: &str = env!("CARGO_PKG_VERSION");