openentropy

测量并操作化硬件熵，用于研究和安全。

从设备硬件源收集熵，通过统计测试分析源质量，并通过 CLI、Rust、Python 和 HTTP 接口提供原始或条件化的输出。

一套用于熵研究、验证和加密部署的工作流。

由 Amenti Labs 开发

快速开始

# 安装
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=：

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

文档

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

致谢

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

• vikingdude81/qrng-analysis-toolkit

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

熵源

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

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

当前支持的外部硬件：

• 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：

flowchart TD
    Sources[Sources 63] --> Raw[raw samples]
    Raw --> Pool[Entropy Pool XOR combine]
    Pool --> Modes{Conditioning mode}
    Modes -->|default| Sha[sha256]
    Modes --> Vn[vonneumann]
    Modes -->|passthrough| RawMode[raw]
    Sha --> Output[Output surfaces]
    Vn --> Output
    RawMode --> Output
    Output --> Rust[Rust API]
    Output --> CLI[CLI and TUI]
    Output --> Http[HTTP Server]
    Output --> Pipe[Named Pipe]
    Output --> Py[Python SDK]

平台支持

库在运行时检测可用硬件，仅激活工作源。

从源码构建

需要 Rust 1.85+ 以及 macOS 或 Linux。

git clone https://github.com/amenti-labs/openentropy.git
cd openentropy
cargo build --release --workspace --exclude openentropy-python
cargo test --workspace --exclude openentropy-python
cargo install --path crates/openentropy-cli

Python 包

pip install maturin
maturin develop --release
python3 -c "from openentropy import EntropyPool; print(EntropyPool.auto().get_random_bytes(16).hex())"

贡献

参见 CONTRIBUTING.md。想法：

• 新的熵源（尤其是 Linux 专用）
• 性能改进
• 额外 NIST 测试实现
• Windows 平台支持

参考文献

• NIST SP 800-22: A Statistical Test Suite for Random and Pseudorandom Number Generators
• Bone, A. (2026): QRNG Analysis Toolkit — 混沌理论分析方法（Hurst 指数、Lyapunov 指数、关联维数、BiEntropy、Epiplexity）已根据数学定义用 Rust 重新实现，受此 Python 工具包启发
• Croll, G.J. (2013): BiEntropy — The Approximate Entropy of a Finite Binary String
• Hurst, H.E. (1951): Long-term storage capacity of reservoirs
• Rosenstein, M.T., Collins, J.J. & De Luca, C.J. (1993): A practical method for calculating largest Lyapunov exponents from small data sets
• Grassberger, P. & Procaccia, I. (1983): Measuring the strangeness of strange attractors
• Shannon, C.E. (1948): A Mathematical Theory of Communication

许可证

MIT — 版权所有 © 2026 Amenti Labs