---

快速开始

# 安装
cargo install openentropy-cli

# 发现机器上的熵源
openentropy scan

# 对所有快速源进行基准测试
openentropy bench

# 输出 64 个随机十六进制字节
openentropy stream --format hex --bytes 64

# 实时 TUI 仪表板
openentropy monitor

默认仅使用快速源（<2s）。传递 --all 以包含较慢的源（DNS、TCP、GPU、BLE）。位置别名 all 也可用于兼容性。

外部 QRNG 硬件

大多数 OpenEntropy 源来自主机本身。OpenEntropy 还支持外部硬件设备（当它们连接且可发现时）：

• Crypta Labs QCicada USB QRNG — 作为 qcicada 源暴露。OpenEntropy 可以读取设备的量子输出，并对其进行基准测试、分析、记录或与主机源进行比较。设备自身的输出模式映射为 raw、sha256 和 samples，现在 OpenEntropy 使用来自 qcicada 0.2.2 的 QCicada 全新启动连续模式辅助函数，因此在进入连续模式后会丢弃一次已缓冲的设备输入，而不是从陈旧队列字节中提供第一次读取。参见 QCicada 手册。

Python

pip install openentropy

from openentropy import EntropyPool, detect_available_sources

sources = detect_available_sources()
print(f"{len(sources)} 个熵源可用")

pool = EntropyPool.auto()
source = sources[0]["name"]
data = pool.get_source_bytes(source, 256, conditioning="sha256")

从源码构建（原生扩展）：

git clone https://github.com/amenti-labs/openentropy.git && cd openentropy
pip install maturin
maturin develop

---

两类受众

安全工程师使用 OpenEntropy 验证熵质量并播种 CSPRNG：

openentropy analyze --profile security --output audit.md

研究人员使用 OpenEntropy 研究原始噪声特性：

openentropy analyze --profile deep --output analysis.json

安全工程师播种 CSPRNG、生成密钥，并用独立的硬件熵补充 /dev/urandom。SHA-256 条件化输出（--conditioning sha256，默认）产生密码学质量的随机字节。security 配置文件一次性启用 NIST 测试套件、最小熵分析和 SHA-256 条件化。

研究人员研究硬件子系统的原始噪声特性。传递 --conditioning raw 以获得未白化、无条件化的字节，从而保留每个源的实际噪声信号。deep 配置文件启用 100K 样本、互相关和 PEAR 风格的试验分析。

原始模式可实现：

• 硬件表征 — 测量单个噪声源的最小熵、自相关和频谱特性
• 芯片验证 — 比较不同芯片版本、热状态和电压域下的噪声特征
• 异常检测 — 监控熵源健康状况，发现硬件退化或篡改迹象
• 跨域分析 — 研究独立熵域之间的相关性（热噪声 vs 定时 vs IPC）

---

独特之处

大多数随机数生成器是伪随机的——一次性播种的确定性算法。OpenEntropy 持续从你的硬件中收集真实的物理噪声：

• 热噪声 — 三种独立的振荡器拍频（CPU晶振 vs 音频PLL、显示PLL、PCIe PHY PLL）
• 定时与微架构 — 时钟相位噪声、DRAM行缓冲冲突、推测执行差异、TLB shootdown、DVFS竞争、ICC总线争用、预取器状态、APRR JIT定时、ANE时钟域跨越
• I/O 和 IPC — 磁盘和NVMe延迟（包括IOKit传感器轮询、原始设备和Linux透传）、USB枚举、Mach端口IPC、管道缓冲区分配、kqueue事件、fsync日志
• GPU 和计算 — GPU 线程束分歧、IOSurface 跨域定时、神经引擎推理定时
• 调度和系统 — nanosleep 漂移、GCD 调度队列、线程生命周期、P/E核迁移、定时器合并、内核计数器、进程表快照
• 网络和传感器 — DNS 解析定时、TCP 握手方差、WiFi RSSI、BLE 环境射频、音频 ADC 噪声
• 深层硬件 — 双时钟域拍频、SITVA、AES-XTS 上下文切换、SEV 广播、COMMPAGE seqlock、SMC 热敏电阻、getentropy TRNG 重新播种

熵池通过 XOR 组合独立流。没有任何单一源故障能危及池。

条件化模式

条件是可选的且可配置的。在 CLI 上使用 --conditioning，在 HTTP API 上使用 ?conditioning=：

模式	标志	描述
SHA-256（默认）	--conditioning sha256	SHA-256 条件化。加密级输出。
Von Neumann	--conditioning vonneumann	仅去偏——去除偏差，同时保留更多原始信号结构。
原始	--conditioning raw	无处理。零白化的源字节——为研究保留实际硬件噪声信号。

原始模式使得 OpenEntropy 对研究有用。大多数 HWRNG API 运行 DRBG 后处理，使每个源看起来像均匀随机字节，破坏了研究人员需要的信息。原始输出保留每个源的噪声结构：偏差、自相关、频谱特征和跨源相关性。详见 条件化。

---

文档

• 文档站点：https://amenti-labs.github.io/openentropy/
• PyPI 包：https://pypi.org/project/openentropy/

文档	描述
源目录	包含物理解释和平台说明的源目录
CLI 参考	完整命令参考和示例
条件化	原始 vs VonNeumann vs SHA-256 条件化模式
试验分析方法	PEAR 风格 200 位试验、校准门限和参考文献
遥测模型	实验性 telemetry_v1 上下文模型和集成点
Rust API 参考	核心 Rust API 接口
架构	Crate 结构和设计决策
Python SDK	PyO3 绑定和 Python API 参考
示例	Rust 和 Python 代码示例
故障排除	常见问题和修复
安全	威胁模型和负责披露

---

致谢

扩展的统计分析路线图和方法清单受到了以下项目的启发：

• vikingdude81/qrng-analysis-toolkit

我们感谢开源工作对塑造这一比较性 QRNG/PRNG 分析面的帮助。

---

熵源

当前源注册表涵盖 13 个基于机制的类别；实际可用性因平台而异：

类别	数量
热	4
定时	7
调度	6
IO	6
IPC	4
微架构	16
GPU	3
网络	3
系统	6
信号	3
传感器	4
量子	1

有关每个源的完整描述、平台可用性和物理说明，请参见 源目录。

当前支持的外部硬件：

• qcicada — Crypta Labs QCicada USB QRNG（手册）

---

CLI 参考

有关完整的命令参考和示例，请参见 CLI 参考。

最常用的工作流：

openentropy scan
openentropy bench
openentropy stream --format hex --bytes 64
openentropy analyze --profile security         # NIST 套件 + 熵 + sha256
openentropy analyze --profile deep             # 100K + 取证 + 互相关 + 试验
openentropy record clock_jitter --duration 30s
openentropy sessions sessions/<id> --profile deep
openentropy compare sessions/<id-a> sessions/<id-b> --profile deep

在 sessions 上，预设仅在提供特定会话路径时应用。openentropy sessions 不带路径始终保持在列表模式。

PEAR 风格的试验方法参考文献（200 位试验、终端 Z、加权 Stouffer 组合、校准门控）记录在 试验分析方法 中。

---

Rust API

[dependencies]
openentropy-core = "0.12"

use openentropy_core::{ConditioningMode, EntropyPool, detect_available_sources};

let sources = detect_available_sources();
println!("{} sources available", sources.len());

let pool = EntropyPool::auto();
let source = pool.source_names()[0].clone();
let bytes = pool
    .get_source_bytes(&source, 256, ConditioningMode::Sha256)
    .unwrap();
let health = pool.health_report();

以编程方式分析和比较熵数据：

use openentropy_core::{full_analysis, compare, trial_analysis};

let data = pool.get_source_raw_bytes(&source, 5000).unwrap();

// 每个源的统计分析
let analysis = full_analysis(&source, &data);
println!("香农熵: {:.4} bits/byte", analysis.shannon_entropy);

// 两个流的差异比较
let other = pool.get_source_raw_bytes(&source, 5000).unwrap();
let diff = compare("stream_a", &data, "stream_b", &other);

// PEAR 风格试验分析
let trials = trial_analysis(&data, &Default::default());
println!("终端 Z: {:.4}, p = {:.4}", trials.terminal_z, trials.terminal_p_value);

混沌理论分析（区分真正随机性与确定性混沌）：

use openentropy_core::chaos::chaos_analysis;

let result = chaos_analysis(&data);
println!("Hurst H={:.4}, Lyapunov λ={:.4}, D₂={:.4}",
    result.hurst.hurst_exponent,
    result.lyapunov.lyapunov_exponent,
    result.correlation_dimension.dimension);

---

架构

Cargo 工作区包含 6 个 crate：