{"id":27226100,"url":"https://github.com/cpscript/rust-quantumrng","last_synced_at":"2025-07-21T20:34:41.324Z","repository":{"id":287144278,"uuid":"963733705","full_name":"CPScript/Rust-QuantumRNG","owner":"CPScript","description":"A Quantum Random Number Generator (QRNG) that uses a \"quantum mechanical phenomena\" available through everyday hardware. Made available using \"Rust\"","archived":false,"fork":false,"pushed_at":"2025-04-10T06:38:20.000Z","size":27,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-10T07:39:43.117Z","etag":null,"topics":["mechanics","qrng","qrng-numbers","qrng-protocols","quantum-computing","rust","rust-qrng"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CPScript.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-04-10T06:08:05.000Z","updated_at":"2025-04-10T06:38:23.000Z","dependencies_parsed_at":"2025-04-10T07:39:49.089Z","dependency_job_id":"3a5bf3e9-bcc2-401d-9c58-5bea022b4db1","html_url":"https://github.com/CPScript/Rust-QuantumRNG","commit_stats":null,"previous_names":["cpscript/rust-quantumrng"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CPScript%2FRust-QuantumRNG","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CPScript%2FRust-QuantumRNG/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CPScript%2FRust-QuantumRNG/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CPScript%2FRust-QuantumRNG/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CPScript","download_url":"https://codeload.github.com/CPScript/Rust-QuantumRNG/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248214421,"owners_count":21066433,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mechanics","qrng","qrng-numbers","qrng-protocols","quantum-computing","rust","rust-qrng"],"created_at":"2025-04-10T11:47:04.853Z","updated_at":"2025-04-10T11:47:05.530Z","avatar_url":"https://github.com/CPScript.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Acknowledge\n\n\u003e This project builds upon theoretical and practical work in the field of quantum random number generation and applies these principles to consumer hardware.\n\n---\n\n## Overview\n\nThis project implements a high-performance, quantum random number generator (QRNG) that uses a \"quantum mechanical phenomena\" available through everyday hardware. Unlike algorithmic pseudo-random number generators (PRNGs), quantum randomness derives from fundamental physical indeterminism, providing truly unpredictable and statistically unbiased random bits.\n\n### Quantum Sources\n\nThe system provides three complementary approaches to make an attempt at quantum randomness:\n\n1. **Optical QRNG**: Exploits quantum shot noise in webcam CMOS sensors\n2. **Audio QRNG**: Captures Johnson-Nyquist noise in microphone electronics \n3. **Hardware QRNG**: Interfaces with Arduino-based photodiode quantum noise generators\n\n## Features\n\n- **Multiple Quantum Sources**: Flexibility to use webcams, microphones, or custom hardware\n- **Enterprise-Grade Architecture**: Modular design with clear separation of concerns\n- **Randomness Post-Processing**:\n  - Von Neumann debiasing for bias elimination\n  - SHA-3 cryptographic conditioning\n- **Comprehensive Quality Assessment**: Built-in statistical analysis and entropy estimation\n- **High-Performance Implementation**: Optimized Rust code with multi-threading capabilities\n- **Production-Ready Error Handling**: Graceful recovery from all I/O operations\n- **Format Flexibility**: Outputs binary or text formats for easy integration\n\n---\n\n# Technical Implementation\n\n## Easy Installation\n\n```bash\n# Clone repository\ngit clone https://github.com/CPScript/rust-quantumRNG.git\ncd QuantumRNG\n\n# Install dependencies (Ubuntu/Debian)\nsudo apt-get install libopencv-dev libasound2-dev\n\n# Build project\ncargo build --release\n```\n\n#### Usage Examples\n\n```bash\n# Generate 10,000 random bits using webcam quantum noise\n./QuantumRNG webcam --num-bits 10000 --output-file quantum_bits.bin\n\n# Generate 8,192 bits using microphone with debiasing and cryptographic hashing\n./QuantumRNG audio --num-bits 8192 --apply-debiasing --apply-hashing --output-file secure_random.bin\n\n# Generate 4,096 bits from Arduino-based hardware QRNG\n./QuantumRNG serial --port /dev/ttyUSB0 --num-bits 4096 --output-file hardware_qrng.bin\n```\n\n## Full installation\n\u003cdetails closed\u003e\n\u003csummary\u003eClick me to show!\u003c/summary\u003e\n\u003cbr\u003e\n  \n## 1. Environmental Prerequisites\n\n### 1.1. System Dependencies\n\n```bash\n# Debian/Ubuntu-based systems\nsudo apt update\nsudo apt install -y build-essential pkg-config libssl-dev \\\n    libopencv-dev libclang-dev cmake \\\n    libasound2-dev libudev-dev \\\n    arduino arduino-core arduino-mk\n\n# Fedora/RHEL-based systems\nsudo dnf install -y gcc gcc-c++ make pkg-config openssl-devel \\\n    opencv-devel clang-devel cmake \\\n    alsa-lib-devel systemd-devel \\\n    arduino arduino-devel\n    \n# Arch-based systems\nsudo pacman -S base-devel pkg-config openssl \\\n    opencv clang cmake \\\n    alsa-lib systemd-libs \\\n    arduino\n```\n\n### 1.2. Rust Toolchain Installation\n\n```bash\n# Install Rust using rustup\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\nsource $HOME/.cargo/env\n\n# Ensure stable toolchain\nrustup default stable\n\n# Install additional components\nrustup component add clippy rustfmt\n```\n\n## 2. Hardware Configuration\n\n### 2.1. Optical QRNG Setup (Webcam-based)\n\n1. **Connect a USB webcam** to your system\n2. **Create light-isolated environment** for optimal quantum noise:\n   ```\n   - Enclose webcam in opaque container (e.g., small cardboard box)\n   - Apply black electrical tape over lens leaving tiny aperture (0.5mm)\n   - Alternatively: use lens cap with single pinhole\n   ```\n3. **Verify hardware detection**:\n   ```bash\n   # List detected video devices\n   v4l2-ctl --list-devices\n   \n   # Test video capture (should show static/noise)\n   ffplay -f video4linux2 -input_format mjpeg -i /dev/video0 -video_size 160x120\n   ```\n\n### 2.2. Audio QRNG Setup (Microphone-based)\n\n1. **Connect microphone** (internal or external) \n2. **Create RF-isolated environment** (optional, for higher quality randomness):\n   ```\n   - Use shielded microphone if available\n   - Place in Faraday cage (metal mesh box/aluminum foil enclosure)\n   - Keep away from strong RF sources (Wi-Fi routers, etc.)\n   ```\n3. **Verify hardware detection**:\n   ```bash\n   # List audio devices\n   arecord -l\n   \n   # Test audio capture (should capture ambient noise)\n   arecord -d 5 -f S16_LE -r 44100 -c 1 test.wav \u0026\u0026 aplay test.wav\n   ```\n\n### 2.3. Hardware QRNG Setup (Arduino-based)\n\n1. **Circuit assembly**:\n   ```\n   Components:\n   - Arduino Uno/Nano/Pro Mini\n   - 1× Photodiode or reverse-biased LED (preferred: BPW34)\n   - 1× 1MΩ resistor\n   - 1× 10KΩ resistor (optional, for stability)\n   - Breadboard and jumper wires\n   \n   Connections:\n   +5V ── [1MΩ resistor] ── +── [Photodiode] ── GND\n                             │\n                      Analog Pin A0\n   ```\n\n2. **Upload firmware**:\n   ```bash\n   # Navigate to Arduino sketch directory\n   cd QuantumRNG/arduino\n   \n   # Compile and upload (adjust port as needed)\n   arduino-cli compile --fqbn arduino:avr:uno quantum_rng\n   arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:avr:uno quantum_rng\n   \n   # Alternative: Using Arduino IDE\n   # 1. Open arduino/quantum_rng.ino in Arduino IDE\n   # 2. Select board type (Tools \u003e Board \u003e Arduino Uno)\n   # 3. Select port (Tools \u003e Port \u003e /dev/ttyACM0)\n   # 4. Click Upload button\n   ```\n\n3. **Verify communication**:\n   ```bash\n   # Test serial output (should show stream of 0s and 1s)\n   screen /dev/ttyACM0 9600\n   # Press Ctrl+A then K to exit\n   ```\n\n## 3. Build Process\n\n### 3.1. Core Application Compilation\n\n```bash\n# Clone repository (if not done already)\ngit clone https://github.com/CPScript/QuantumRNG.git\ncd QuantumRNG\n\n# Build in development mode\ncargo build\n\n# Build optimized release binary\ncargo build --release\n\n# Run tests\ncargo test -- --nocapture\n```\n\n### 3.2. Compile-time Configuration (Optional)\n\nFor custom feature configurations, modify Cargo.toml:\n\n```toml\n# Add these lines under [features] section\n[features]\ndefault = [\"webcam\", \"audio\"]\nwebcam = [\"opencv\"]\naudio = [\"cpal\"]\nhardware = [\"serialport\"]\nall = [\"webcam\", \"audio\", \"hardware\"]\n```\n\nThen build with selected features:\n\n```bash\n# Build with only webcam support\ncargo build --release --no-default-features --features webcam\n\n# Build with all features\ncargo build --release --features all\n```\n\n## 4. Testing Protocol\n\n### 4.1. Functional Validation\n\n```bash\n# 1. Optical QRNG Test\n./target/release/QuantumRNG webcam --num-bits 1024 --output-file optical_test.bin\n\n# 2. Audio QRNG Test\n./target/release/QuantumRNG audio --num-bits 1024 --output-file audio_test.bin\n\n# 3. Hardware QRNG Test (adjust port as needed)\n./target/release/QuantumRNG serial --port /dev/ttyACM0 --num-bits 1024 --output-file hardware_test.bin\n```\n\n### 4.2. Quality Assurance Tests\n\n```bash\n# Generate larger sample for statistical testing\n./target/release/QuantumRNG webcam --num-bits 100000 --apply-debiasing --apply-hashing --output-file statistical_test.bin\n\n# Install randomness test suite (if not already installed)\nsudo apt install dieharder rng-tools\n\n# Basic entropy assessment\nrngtest -c 1000 \u003c statistical_test.bin\n\n# Comprehensive statistical analysis\ndieharder -a -f statistical_test.bin -g 201\n```\n\n### 4.3. Performance Benchmarking\n\n```bash\n# Time generation of 1 million bits\ntime ./target/release/QuantumRNG audio --num-bits 1000000 --output-file benchmark.bin\n\n# Run with Rust benchmark harness (requires nightly)\nrustup run nightly cargo bench\n```\n\n## 5. Troubleshooting Framework\n\n### 5.1. Diagnostic Procedures\n\n| Issue | Diagnosis Command | Solution |\n|-------|-------------------|----------|\n| Webcam access denied | `ls -la /dev/video*` | `sudo chmod a+rw /dev/video0` |\n| Arduino not detected | `ls -la /dev/tty*` | `sudo usermod -a -G dialout $USER` |\n| OpenCV library not found | `ldd ./target/debug/QuantumRNG` | `sudo apt install libopencv-dev` |\n| Audio device busy | `fuser -v /dev/snd/*` | Kill competing process |\n\n### 5.2. Hardware Signal Analysis\n\nFor validation of quantum noise quality:\n\n```bash\n# Install signal processing tools\nsudo apt install gnuplot sox\n\n# Record raw analog values from Arduino (modify quantum_rng.ino first)\n# Change: Serial.println(randomBit); → Serial.println(analogValue);\n# Then capture and visualize:\nstty -F /dev/ttyACM0 9600 raw\ncat /dev/ttyACM0 \u003e arduino_values.txt \u0026\nsleep 10\nkill $!\n\n# Plot noise distribution\ngnuplot -e \"set term png; set output 'noise_distribution.png'; \\\n  plot 'arduino_values.txt' using 1 with histeps title 'Noise Distribution'\"\n```\n\n## 6. Advanced Configuration\n\n### 6.1. Entropy Source Hybridization\n\nFor critical applications, combining multiple entropy sources:\n\n```bash\n# Generate bits from all sources\n./target/release/QuantumRNG webcam --num-bits 1024 --output-file source1.bin\n./target/release/QuantumRNG audio --num-bits 1024 --output-file source2.bin \n./target/release/QuantumRNG serial --port /dev/ttyACM0 --num-bits 1024 --output-file source3.bin\n\n# Create hybrid entropy pool (requires xxd)\nxxd -p source1.bin | tr -d '\\n' \u003e pool.hex\nxxd -p source2.bin | tr -d '\\n' | python3 -c \"\nimport sys\na=sys.stdin.read()\nb=open('pool.hex').read()\nmin_len = min(len(a),len(b))\nprint(''.join(hex(int(a[i:i+2],16)^int(b[i:i+2],16))[2:].zfill(2) \n      for i in range(0,min_len,2)))\" \u003e temp.hex\nxxd -p source3.bin | tr -d '\\n' | python3 -c \"\nimport sys\na=sys.stdin.read()\nb=open('temp.hex').read()\nmin_len = min(len(a),len(b))\nprint(''.join(hex(int(a[i:i+2],16)^int(b[i:i+2],16))[2:].zfill(2)\n      for i in range(0,min_len,2)))\" \u003e final.hex\n\n# Convert back to binary\nxxd -p -r final.hex \u003e hybrid_entropy.bin\n```\n\n---\n\n\u003c/details\u003e\n\n## Quantum Physics Background\n\n### Optical QRNG (Webcam)\n\nThe webcam implementation leverages quantum shot noise - statistical fluctuations in the number of photons detected by the CMOS sensor. These fluctuations arise from the quantum nature of light and are fundamentally random according to quantum mechanics.\n\nIn low-light conditions, CMOS sensors exhibit quantum-limited noise behavior, where randomness is dominated by the probabilistic arrival of individual photons. The software extracts the least significant bits from pixel values, which contain this quantum noise component.\n\n### Audio QRNG (Microphone)\n\nMicrophone-based randomness exploits Johnson-Nyquist noise - thermal agitation of charge carriers in conductors. At the quantum level, this noise arises from zero-point fluctuations in the electromagnetic field, governed by Heisenberg's uncertainty principle.\n\nWhen amplified in sensitive microphone electronics, these quantum fluctuations manifest in the least significant bits of audio samples, providing a continuous source of quantum randomness.\n\n### Hardware QRNG (Arduino)\n\nThe Arduino implementation utilizes avalanche noise in reverse-biased semiconductor junctions. This noise mechanism involves quantum tunneling effects where electrons spontaneously penetrate potential barriers that would be classically insurmountable.\n\nA simple circuit using a photodiode or LED, combined with appropriate amplification, can extract this quantum noise efficiently.\n\n## Performance Characteristics\n\n| Method | Bit Rate | Setup Complexity | Quantum Purity |\n|--------|----------|------------------|----------------|\n| Webcam | 1-5 Kbits/sec | Medium | Medium |\n| Audio | 10-20 Kbits/sec | Low | Low-Medium |\n| Arduino | 0.5-1 Kbits/sec | High | High |\n\n### Statistical Quality\n\nFor all methods, the raw bit streams typically achieve:\n- Bit balance: 0.48-0.52 (ideally 0.5)\n- Shannon entropy: 0.90-0.98 bits/bit (ideally 1.0)\n- First-order autocorrelation: \u003c 0.03 (ideally 0)\n\nPost-processing with Von Neumann debiasing and SHA-3 hashing significantly improves these metrics.\n\n## Testing Randomness Quality\n\nThe implementation includes basic statistical tests, but for production use, validate with established test suites:\n\n```bash\n# Export 1 million random bits\n./QuantumRNG webcam --num-bits 1000000 --output-file test.bin\n\n# Test with dieharder\ndieharder -a -f test.bin\n\n# Test with NIST Statistical Test Suite\n./assess 1000000 \u003c test.bin\n```\n\n## Security Considerations\n\nWhile this implementation brings quantum randomness to consumer hardware, it represents a \"best effort\" approach and should be assessed for your specific security requirements.\n\nFor applications requiring certified quantum randomness, consider:\n- Commercial hardware QRNGs\n- Quantum randomness beacon services (e.g., NIST Randomness Beacon)\n- Hybrid approaches combining this QRNG with existing CSPRNGs\n\n## Circuit Diagrams\n\n### Basic Arduino Quantum Noise Circuit\n\n```\n+5V ---[1MΩ resistor]---+---[Photodiode/LED]--- GND\n                         |\n                    Analog Input\n```\n\n### Enhanced Quantum Noise Circuit\n\n```\n+5V ---[1MΩ]--- Analog Pin ---[Zener diode 3.3V]--- GND\n```\n\n## Advanced Usage\n\n### Integration with Cryptographic Applications\n\n```rust\n// Example: Using quantum randomness for AES-256 key generation\nlet quantum_bits = std::fs::read(\"quantum_bits.bin\")?;\nlet key = \u0026quantum_bits[0..32]; // 256 bits for AES-256\nlet cipher = Aes256Gcm::new(key.into());\n```\n\n### Combining Multiple Quantum Sources\n\n```bash\n# Generate bits from multiple sources and combine them\n./QuantumRNG webcam --num-bits 1000 --output-file webcam.bin\n./QuantumRNG audio --num-bits 1000 --output-file audio.bin\n\n# Combine with XOR operation (in bash)\nxxd -p webcam.bin | tr -d '\\n' \u003e combined.hex\nxxd -p audio.bin | tr -d '\\n' | python -c \"import sys; \\\n  a=sys.stdin.read(); b=open('combined.hex').read(); \\\n  print(''.join(hex(int(a[i:i+2],16)^int(b[i:i+2],16))[2:] for i in range(0,len(a),2)))\" | \\\n  xxd -p -r \u003e quantum_bits.bin\n```\n\n## Future Directions\n\n- FPGA-based implementations for higher throughput\n- Integration with cloud-based quantum computers\n- Hardware-accelerated post-processing\n- Real-time entropy monitoring and quality control\n- Continuous randomness generation as a system service\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcpscript%2Frust-quantumrng","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcpscript%2Frust-quantumrng","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcpscript%2Frust-quantumrng/lists"}