vtrng 0.5.3__tar.gz

vtrng-0.5.3/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to VTRNG are documented here.
+Format based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.5.0] - 2026-03-
+
+### Added
+- PyPI package: `pip install vtrng`
+- Full README with examples, architecture diagram, benchmarks
+- GitHub Actions CI/CD (test on Windows/Linux/macOS)
+- Auto-publish to PyPI on git tag
+- Weekly certification workflow
+- Issue and PR templates
+- CONTRIBUTING.md, SECURITY.md
+- Makefile for common operations
+- Documentation (docs/)
+
+### Changed
+- Updated pyproject.toml for PyPI metadata
+- Version bumped to 0.5.0
+
+## [0.4.0] - 2026-02-20
+
+### Added
+- NIST SP 800-22 statistical test suite (11 tests)
+- Binary exporter for external tools (dieharder, ENT, TestU01)
+- TestU01 C wrapper
+- Automated test runner with tool detection
+- CLI commands: test, certify, export, bench
+- JSON certification report export
+- Shell scripts for external tools
+- 17 new test cases
+
+## [0.3.0] - 2026-02-10
+
+### Added
+- NIST SP 800-90B entropy estimation (9 estimators)
+- Continuous health testing (RCT + APT)
+- Startup assessment with 1024-sample validation
+- Min-entropy tracking
+- Conservative min(all estimators) approach
+
+## [0.2.0] 
+
+### Added
+- C extension with RDTSC for cycle-accurate timing
+- Background entropy collector daemon thread
+- Package structure (src layout)
+- Variable workload (prevents timing quantization)
+- Delta-of-deltas entropy extraction
+- Retry logic with backoff for health checks
+
+### Fixed
+- Repetition count test false positives on Windows
+- Health check too aggressive for quantized timers
+
+## [0.1.0]
+
+### Added
+- Initial prototype
+- CPU jitter, memory timing, thread race sources
+- Von Neumann debiasing + SHA-512 conditioning
+- 512-byte entropy pool with forward secrecy
+- Basic health monitoring
+- API: random_bytes, random_int, random_float, shuffle, etc.

vtrng-0.5.3/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to VTRNG
+
+Thanks for your interest! VTRNG aims to be the most transparent and
+well-tested pure-software TRNG. Every contribution helps.
+
+## How to Contribute
+
+### Bug Reports
+- Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md)
+- Include your OS, Python version, and CPU model
+- Include the full error traceback
+- Note if you're running in a VM/container
+
+### Feature Requests
+- Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md)
+
+### Code Contributions
+
+1. Fork the repo
+2. Create a feature branch: `git checkout -b my-feature`
+3. Make your changes
+4. Run tests: `make test`
+5. Run certification: `make certify`
+6. Submit a PR
+
+### Development Setup
+
+```bash
+git clone https://github.com/YOUR_USERNAME/vtrng.git
+cd vtrng
+python -m venv .venv
+source .venv/bin/activate  # or .venv\Scripts\activate on Windows
+pip install -e ".[dev]"
+make test
+```
+
+
+## Areas We Need Help
+### 🔴 High Priority
+- ARM/Apple Silicon optimization - CNTVCT_EL0 timing
+- Windows high-resolution timer - QueryPerformanceCounter
+- VM detection - auto-detect degraded environments
+### 🟡 Medium Priority
+- New entropy sources - GPU timing, disk I/O jitter, network jitter
+- FIPS 140-3 alignment - documentation and testing
+- Async API - await rng.random_bytes(32)
+### 🟢 Nice to Have
+- WebAssembly port - VTRNG in the browser
+- Rust port — for embedded/systems use
+- Benchmarks - more platforms, more CPUs
+- Code Standards
+- Type hints on all public functions
+- Docstrings with explanation of the physics/math
+- Tests for both positive cases (good data passes) and negative (bad data fails)
+- No external dependencies in core (only stdlib)
+
+
+## Security
+If you find a security vulnerability, DO NOT open a public issue.
+See [SECURITY.md](SECURITY.md).

vtrng-0.5.3/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TheDicee Devs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vtrng-0.5.3/MANIFEST.in

@@ -0,0 +1,18 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+include SECURITY.md
+include pyproject.toml
+include setup.py
+
+recursive-include src/vtrng *.py *.c *.pyi
+recursive-include tests *.py
+recursive-include docs *.md
+recursive-include scripts *.sh
+recursive-include external *.c
+
+global-exclude __pycache__
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude *.egg-info

vtrng-0.5.3/PKG-INFO

@@ -0,0 +1,413 @@
+Metadata-Version: 2.4
+Name: vtrng
+Version: 0.5.3
+Summary: Very True Random Number Generator, pure-software TRNG from CPU jitter physics
+Author-email: TheDicee Devs <thediceedeveloper@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/TheDiceeDev/vtrng
+Project-URL: Documentation, https://github.com/TheDiceeDev/vtrng
+Project-URL: Repository, https://github.com/TheDiceeDev/vtrng
+Project-URL: Issues, https://github.com/TheDiceeDev/vtrng/issues
+Project-URL: Changelog, https://github.com/TheDiceeDev/vtrng
+Keywords: random,trng,rng,entropy,jitter,cryptography,security,nist,randomness,true-random,cpu-jitter,very true,very true rng
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Information Technology
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Scientific/Engineering
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: C
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENCE
+Provides-Extra: fast
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# 🎲 VTRNG
+
+### Very True Random Number Generator
+
+**Pure-software true randomness from CPU jitter physics.**  
+**No hardware dongles. No mouse wiggling. No lava lamps.**
+
+[![PyPI version](https://img.shields.io/pypi/v/vtrng?color=blue&label=PyPI)](https://pypi.org/project/vtrng/)
+[![Python](https://img.shields.io/pypi/pyversions/vtrng)](https://pypi.org/project/vtrng/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![CI](https://github.com/TheDiceeDev/vtrng/actions/workflows/ci.yml/badge.svg)](https://github.com/TheDiceeDev/vtrng/actions)
+[![Tests](https://img.shields.io/badge/NIST_SP_800--22-PASSED-brightgreen)](docs/certification.md)
+[![Tests](https://img.shields.io/badge/NIST_SP_800--90B-COMPLIANT-brightgreen)](docs/certification.md)
+
+[Documentation](docs/index.md) •
+[Installation](#installation) •
+[Quick Start](#quick-start) •
+[How It Works](#how-it-works) •
+[Certification](#certification) •
+[API Reference](#api-reference) •
+[FAQ](docs/index.md#faq)
+
+</div>
+
+---
+
+## What Is This?
+
+VTRNG is a **true random number generator** that runs entirely in
+software. It exploits the physical non-determinism of your CPU -
+thermal noise, cache timing jitter, pipeline hazards, and OS
+scheduling chaos - to generate genuine randomness without any
+special hardware.
+
+```python
+from vtrng import VTRNG
+
+rng = VTRNG()
+
+rng.random_bytes(32)          # 32 truly random bytes
+rng.random_int(1, 100)        # unbiased integer [1, 100]
+rng.random_float()            # float in [0.0, 1.0)
+rng.coin_flip()               # "heads" or "tails"
+rng.uuid4()                   # random UUID v4
+rng.shuffle([1, 2, 3, 4, 5])  # Fisher-Yates shuffle
+rng.dice(20, 4)               # roll 4d20
+```
+
+---
+
+## Quick links
+
+* Full docs: [docs/index.md](/docs/index.md) (this contains the detailed docs, certification info, and API reference)
+* Repo: `https://github.com/TheDiceeDev/vtrng`
+* PyPI: `https://pypi.org/project/vtrng/`
+
+---
+
+## Why Not Just Use `random` or `os.urandom()`?
+
+| Source         | Type     | How It Works                                            |
+| -------------- | -------- | ------------------------------------------------------- |
+| `random`       | ❌ PRNG   | Mersenne Twister - deterministic, predictable           |
+| `os.urandom()` | ✅ CSPRNG | OS entropy pool - good, but opaque                      |
+| `secrets`      | ✅ CSPRNG | Wrapper around `os.urandom()`                           |
+| **VTRNG**      | ✅ TRNG   | Direct physical noise → you control the entire pipeline |
+
+VTRNG gives you:
+
+* 🔍 **Full transparency** - every step from noise source to output is auditable
+* 📊 **Built-in certification** - NIST SP 800-22 and SP 800-90B test suites included
+* 🏥 **Continuous health monitoring** - refuses to output if entropy degrades
+* 🔬 **Assessed entropy** - knows how much randomness it’s producing
+* 🚫 **No trust required** - does not rely on an opaque OS implementation
+
+---
+
+## Installation
+
+**From PyPI (recommended):**
+
+```bash
+pip install vtrng
+```
+
+**With C extension (faster, uses RDTSC if available):**
+
+```bash
+pip install "vtrng[fast]"
+```
+
+**From source (developer):**
+
+```bash
+git clone https://github.com/TheDiceeDev/vtrng.git
+cd vtrng
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start
+
+### Basic usage
+
+```python
+from vtrng import VTRNG
+
+# Initialize (collects entropy, runs health checks)
+rng = VTRNG()
+
+# Generate random values
+secret_key = rng.random_bytes(32)
+pin = rng.random_int(0, 9999)
+probability = rng.random_float()
+token = rng.random_hex(16)
+session_id = rng.uuid4()
+```
+
+### Paranoia levels
+
+```python
+# Fast - CPU jitter only (~50ms per call)
+rng = VTRNG(paranoia=1)
+
+# Moderate - + memory timing (default, ~100ms)
+rng = VTRNG(paranoia=2)
+
+# Maximum - + thread racing (~500ms, highest entropy)
+rng = VTRNG(paranoia=3)
+```
+
+### Sequences & choices
+
+```python
+winner = rng.choice(["Alice", "Johntez", "Charlie"])
+team = rng.sample(players, k=5)        # 5 unique picks
+colors = rng.choices(["R", "G", "B"], k=10)  # with replacement
+
+deck = list(range(52))
+shuffled = rng.shuffle(deck)
+
+damage = sum(rng.dice(6, 3))  # 3d6
+```
+
+---
+
+## Diagnostics & Certification
+
+Quick diagnostics:
+
+```python
+rng.print_diagnostics()
+```
+
+Full NIST SP 800-90B entropy assessment:
+
+```python
+rng.nist_assessment(n_samples=4096)
+```
+
+Run SP 800-22 statistical test suite:
+
+```python
+from vtrng import SP800_22Suite
+suite = SP800_22Suite()
+suite.print_report(rng.random_bytes(125000))
+```
+
+Complete certification (SP 800-22 + dieharder + ENT):
+
+```python
+from vtrng import TestRunner
+runner = TestRunner(rng)
+runner.run_all()
+```
+
+---
+
+## CLI
+
+```bash
+python -m vtrng                    # interactive demo
+python -m vtrng test               # SP 800-22 statistical tests
+python -m vtrng assess             # SP 800-90B entropy assessment
+python -m vtrng certify            # run ALL test suites
+python -m vtrng export -o data.bin --size 10   # export 10MB
+python -m vtrng bench              # speed benchmark
+python -m vtrng diag               # full diagnostics
+```
+
+### Pipe to external tools
+
+* `dieharder`:
+
+```bash
+python -m vtrng export --stdout --size 20 | dieharder -a -g 200
+```
+
+* `ENT`:
+
+```bash
+python -m vtrng export -o random.bin --size 1 && ent random.bin
+```
+
+* `TestU01`:
+
+```bash
+python -m vtrng export -o random.bin --size 100
+./testu01_vtrng random.bin crush
+```
+
+> Notes: `dieharder`, `ENT`, and `TestU01` are useful external test tools. See [docs/certification.md](/docs/certification.md) for installation and integration notes.
+
+---
+
+## How It Works
+
+```
+PHYSICAL REALITY (non-deterministic)
+┌──────────────────────────────────┐
+│  Thermal noise in silicon        │
+│  Cache hit/miss timing           │
+│  Branch predictor state          │
+│  OS scheduler decisions          │
+│  DRAM refresh interference       │
+│  Dynamic frequency scaling       │
+│  Interrupt timing                │
+└──────────┬───────────────────────┘
+           │
+┌──────────▼───────────────────────┐
+│  LAYER 1: Entropy Sources        │
+│  CPU jitter · Memory timing      │
+│  Thread race conditions          │
+└──────────┬───────────────────────┘
+           │ raw timing samples
+┌──────────▼───────────────────────┐
+│  LAYER 2: Conditioning           │
+│  Von Neumann debiasing           │
+│  SHA-512 compression             │
+└──────────┬───────────────────────┘
+           │ clean entropy
+┌──────────▼───────────────────────┐
+│  LAYER 3: Entropy Pool           │
+│  512-byte XOR mixing pool        │
+│  SHA-512 extraction + feedback   │
+└──────────┬───────────────────────┘
+           │ random bytes
+┌──────────▼───────────────────────┐
+│  LAYER 4: Health Monitor         │
+│  Continuous: RCT + APT           │
+│  Periodic: 9 NIST estimators     │
+│  KILLS output if failing         │
+└──────────┬───────────────────────┘
+           │ verified random bytes
+┌──────────▼───────────────────────┐
+│  LAYER 5: Public API             │
+│  random_bytes() · random_int()   │
+│  random_float() · shuffle() · …  │
+└──────────────────────────────────┘
+```
+
+The key insight: identical code on the same CPU produces different
+nanosecond-precision timings every execution. This isn't a bug - it's
+physics. Cache state, thermal throttling, and OS interrupts create
+genuine noise at the hardware level.
+
+This is the same principle behind Linux kernel's jitterentropy RNG.
+
+---
+
+## Certification
+
+VTRNG includes three levels of statistical validation.
+
+**Built-in (always available)**
+
+* **NIST SP 800-90B** - 9 entropy estimators (source produces genuine entropy)
+* **NIST SP 800-22** - 11 statistical tests (output indistinguishable from random)
+
+**External (install separately)**
+
+* `dieharder` - ~115 tests (`apt install dieharder`)
+* `ENT` - 6 metrics (`apt install ent`)
+* `TestU01` - 15–160 tests (build from source)
+
+Run everything with one command:
+
+```bash
+python -m vtrng certify
+```
+
+See [docs/certification.md](/docs/certification.md) for the full certification report and reproducible test runs.
+
+---
+
+## Performance
+
+VTRNG is designed for **high-value randomness** (keys, tokens, seeds), not bulk data. For bulk workloads, seed a CSPRNG with VTRNG:
+
+```python
+import hashlib, hmac
+
+seed = rng.random_bytes(64)  # true random seed
+# use seed with HKDF, ChaCha20, or AES-CTR for bulk generation
+```
+
+---
+
+## Requirements
+
+* Python >= 3.9
+* OS: Windows, Linux, macOS (platforms with nanosecond timers)
+* CPU: modern CPU (x86, x86_64, ARM64, RISC-V)
+* No runtime pip dependencies (pure Python core), optional C extension for speed
+
+---
+
+## Security Considerations
+
+* ✅ Continuous entropy health monitoring
+
+* ✅ Refuses to output if health checks fail
+
+* ✅ Forward secrecy - pool state is mutated after extractions
+
+* ✅ No seed-file - fresh entropy collected each startup
+
+* ⚠️ Not constant-time - avoid for timing-sensitive crypto ops
+
+* ⚠️ VM/container behavior varies - health monitor will warn as needed
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](/CONTRIBUTING.md). We welcome:
+
+* Bug reports and fixes
+* New entropy sources
+* Performance improvements
+* Additional statistical tests
+* Platform-specific optimizations
+
+---
+
+## License
+
+MIT License - see [LICENSE](/LICENCE).
+
+
+```python
+# Copyright (c) 2026 TheDicee Devs
+# SPDX-License-Identifier: MIT
+# See LICENSE in project root.
+```
+
+---
+
+## Acknowledgments
+
+* Stephan Müller - `jitterentropy` (pioneer of CPU jitter entropy)
+* NIST SP 800-90B and SP 800-22 - test and estimator standards
+* BSI AIS 31 - German certification methodology
+* The Linux kernel random subsystem maintainers
+
+---
+
+<div align="center">
+VTRNG - Because your CPU is already a noise source. We just had to listen.
+</div>