vtrng 0.5.3

Very True Random Number Generator, pure-software TRNG from CPU jitter physics

🎲 VTRNG

Very True Random Number Generator

Pure-software true randomness from CPU jitter physics.
No hardware dongles. No mouse wiggling. No lava lamps.

Documentation • Installation • Quick Start • How It Works • Certification • API Reference • FAQ

---

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.

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 (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):

pip install vtrng

With C extension (faster, uses RDTSC if available):

pip install "vtrng[fast]"

From source (developer):

git clone https://github.com/TheDiceeDev/vtrng.git
cd vtrng
pip install -e ".[dev]"

---

Quick Start

Basic usage

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

# 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

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:

rng.print_diagnostics()

Full NIST SP 800-90B entropy assessment:

rng.nist_assessment(n_samples=4096)

Run SP 800-22 statistical test suite:

from vtrng import SP800_22Suite
suite = SP800_22Suite()
suite.print_report(rng.random_bytes(125000))

Complete certification (SP 800-22 + dieharder + ENT):

from vtrng import TestRunner
runner = TestRunner(rng)
runner.run_all()

---

CLI

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:

python -m vtrng export --stdout --size 20 | dieharder -a -g 200

• ENT:

python -m vtrng export -o random.bin --size 1 && ent random.bin

• TestU01:

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 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:

python -m vtrng certify

See 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:

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. We welcome:

• Bug reports and fixes
• New entropy sources
• Performance improvements
• Additional statistical tests
• Platform-specific optimizations

---

License

MIT License - see LICENSE.

# 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

---

VTRNG - Because your CPU is already a noise source. We just had to listen.