Leopere
0314c598fb
- Remove CSPRNG fallback: pool now returns errors when camera entropy is insufficient instead of silently falling back to ChaCha20. Random data is only from camera input or not at all. - Fix throughput display: show Mbps/KB/s for smaller frame sizes, Gbps/MB/s for larger ones (actual frame size varies by pixel format). - Add RESEARCH.md note about pixel format impact on throughput. - Complete README API table with all endpoints (dice, password, coin, 8ball, cameras, docs, MCP). - Add docker-compose device mapping for Linux camera access with explanatory comments about macOS limitation. - Add macOS LaunchAgent scripts (install/uninstall/plist template). - Polish run-mac.sh with build step and clearer output. - Fix dead code warnings on library utility functions. - Add /logs/ to .gitignore for LaunchAgent log output. - Fix skill.md: remove stale CSPRNG fallback references. Co-authored-by: Cursor <cursoragent@cursor.com> |
||
|---|---|---|
| man | ||
| scripts | ||
| src | ||
| .cursorignore | ||
| .gitignore | ||
| .woodpecker.yml | ||
| Cargo.lock | ||
| Cargo.toml | ||
| Dockerfile | ||
| LICENSE | ||
| README.md | ||
| RESEARCH.md | ||
| TECHNICAL.md | ||
| docker-compose.yml | ||
| openssl-camera-qrng.cnf | ||
| skill.md | ||
README.md
Camera TRNG
TL;DR: Turn any webcam into a true random number generator. Cover the lens, run the server, get random bytes.
What is this?
Your webcam generates electrical noise even when the lens is covered. This noise comes from quantum effects in the sensor. This tool captures that noise and turns it into random numbers - the same approach used by LavaRnd.
Quick Start
1. Install
# Clone and build
git clone https://git.nixc.us/colin/camera-trng.git
cd camera-trng
cargo build --release
2. Cover Your Camera Lens
Use tape, a lens cap, or put the camera in a dark box. The camera should see nothing but blackness.
3. Run
macOS (native camera access via AVFoundation):
./scripts/run-mac.sh
Linux (native):
./target/release/camera-qrng
Linux (Docker with camera device):
docker compose up -d
Server starts at http://localhost:8787
Start with the OS (macOS LaunchAgent):
./scripts/install-launchagent.sh
Runs the compiled binary at login and keeps it running. Logs go to logs/. To remove: ./scripts/uninstall-launchagent.sh.
4. Get Random Bytes
# Get 32 random bytes (hex)
curl "http://localhost:8787/random?bytes=32&hex=true"
# Get 1KB of raw random data
curl "http://localhost:8787/random?bytes=1024" -o random.bin
# Continuous stream
curl -N "http://localhost:8787/stream"
Is it actually random?
Yes. This tool passes all NIST SP 800-22 statistical tests for randomness:
# Run the built-in test suite
./scripts/test-randomness.py --server http://localhost:8787
The output is cryptographic quality - suitable for generating encryption keys, secure tokens, etc.
API
| Endpoint | Description |
|---|---|
GET /random?bytes=N |
Get N random bytes (max 1MB) |
GET /random?bytes=N&hex=true |
Get N random bytes as hex string |
GET /stream |
Continuous stream of random bytes |
GET /stream?bytes=N |
Stream exactly N bytes then stop |
GET /dice?d=6&count=3 |
Roll quantum-random dice |
GET /password?length=24 |
Generate quantum-random password |
GET /coin |
Quantum coin flip |
GET /8ball?question=... |
Quantum Magic 8 Ball |
GET /cameras |
List available camera devices |
GET /health |
Health check with pool stats |
GET /docs |
API documentation page |
GET /.well-known/mcp.json |
MCP discovery endpoint |
Troubleshooting
macOS "Camera in use" error:
./scripts/release-camera.sh
./scripts/run-mac.sh
Docker on macOS: Docker on Mac runs Linux containers and cannot access the Mac camera. Use ./scripts/run-mac.sh instead.
Docker on Linux (explicit device):
docker run -d --device /dev/video0 -p 8787:8787 camera-trng
More Info
- TECHNICAL.md - Full API docs, CI/CD, configuration options
- RESEARCH.md - The science behind camera-based random number generation
License
CC-BY 4.0. See LICENSE.