.TH CAMERA-QRNG 1 "February 2026" "camera-qrng 0.1.0" "User Commands"
.SH NAME
camera-qrng \- quantum random number generator using camera sensor thermal noise
.SH SYNOPSIS
.B camera-qrng
[\fIENVIRONMENT VARIABLES\fR]
.SH DESCRIPTION
.B camera-qrng
is a true random number generator that extracts entropy from camera sensor
thermal noise, following the LavaRnd methodology. It runs an HTTP server that
provides cryptographically secure random bytes on demand.
.PP
The camera sensor's dark current and thermal electron activity produce quantum
noise that is harvested as entropy. This approach provides high-throughput
random data suitable for cryptographic applications.
.SH SETUP REQUIREMENTS
.SS Cover the Camera Lens
.B CRITICAL:
The camera lens \fBmust\fR be covered for proper operation.
.PP
.RS 4
\(bu Use a lens cap or opaque tape
.br
\(bu Place camera in a light-proof enclosure
.br
\(bu Verify the camera captures pure black frames
.RE
.PP
Covering the lens isolates pure thermal noise from the sensor, eliminating
any scene-correlated data and providing a simpler security model.
.SS Release Camera on macOS
If you see "Lock Rejected" errors, another process is using the camera.
Run:
.PP
.RS 4
.nf
./scripts/release-camera.sh
.fi
.RE
.PP
This kills VDCAssistant/AppleCameraAssistant processes. Then restart the server.
.SS Verify Camera Access
List available cameras:
.PP
.RS 4
.nf
curl http://localhost:8787/cameras
.fi
.RE
.SH ENVIRONMENT
.TP
.B PORT
HTTP server port (default: 8787)
.TP
.B CAMERA_INDEX
Camera device index to use (default: 0). Use \fI/cameras\fR endpoint to list.
.TP
.B CAMERA_WIDTH
Requested camera width in pixels (default: 1920)
.TP
.B CAMERA_HEIGHT
Requested camera height in pixels (default: 1080)
.TP
.B CAMERA_MAX_RESOLUTION
Set to "1" or "true" to use maximum camera resolution instead of configured.
Higher resolution = more entropy per frame.
.SH API ENDPOINTS
.TP
.B GET /random
Returns random bytes. Query parameters:
.RS 4
\(bu \fBbytes\fR \- number of bytes (default: 32, max: 1048576)
.br
\(bu \fBhex\fR \- return as hex string (default: false)
.RE
.TP
.B GET /raw
Returns raw LSB bytes without cryptographic conditioning.
.TP
.B GET /stream
Continuous stream of random bytes. Each connected client receives unique data.
Query parameters: \fBbytes\fR (limit), \fBhex\fR.
.TP
.B GET /cameras
List available camera devices.
.TP
.B GET /health
Returns "ok" if server is running.
.TP
.B GET /.well-known/mcp.json
MCP (Model Context Protocol) discovery endpoint.
.SH EXAMPLES
.SS Start the server
.nf
# Default settings
camera-qrng

# Custom port and camera
PORT=9000 CAMERA_INDEX=1 camera-qrng

# Maximum resolution
CAMERA_MAX_RESOLUTION=1 camera-qrng
.fi
.SS Get random bytes
.nf
# 32 bytes as hex
curl "http://localhost:8787/random?hex=true"

# 1KB raw bytes to file
curl "http://localhost:8787/random?bytes=1024" -o random.bin

# Stream 1MB of random
curl "http://localhost:8787/stream?bytes=1048576" -o stream.bin
.fi
.SS Raspberry Pi Setup
.nf
# Enable camera in raspi-config
sudo raspi-config  # Interface Options > Camera > Enable

# Check camera device
ls /dev/video*

# Run with appropriate camera index
CAMERA_INDEX=0 camera-qrng
.fi
.SH HOW IT WORKS
.IP 1. 4
Opens the camera and maximizes gain/brightness/exposure settings
.IP 2. 4
Captures frames of pure sensor noise (no light = no scene data)
.IP 3. 4
Extracts the 2 LSBs from each pixel (highest entropy density)
.IP 4. 4
Hashes 256-byte chunks with SHA-256 (8:1 conditioning ratio)
.IP 5. 4
Mixes in timing and counter data for additional uniqueness
.PP
The camera automatically reconnects on errors (up to 5 retries with 500ms delay).
.SH PLATFORM SUPPORT
.TP
.B macOS (Apple Silicon, Intel)
Uses AVFoundation. May require releasing camera from other apps first.
.TP
.B Linux (x86_64, ARM/Raspberry Pi)
Uses V4L2. Ensure /dev/video* device permissions allow access.
.TP
.B Windows
Uses Media Foundation.
.SH OPENSSL PROVIDER
camera-qrng can be used as an OpenSSL 3.x provider for system-wide entropy:
.PP
.RS 4
.nf
# Set in openssl.cnf or via environment
OPENSSL_CONF=/path/to/openssl-camera-qrng.cnf openssl rand -hex 32
.fi
.RE
.SH SECURITY CONSIDERATIONS
.IP \(bu 4
\fBAlways cover the lens\fR \- Required for the intended security model
.IP \(bu 4
Gain is automatically maximized to amplify thermal noise
.IP \(bu 4
With lens covered, there is no side-channel information leakage
.IP \(bu 4
SHA-256 conditioning removes bias and ensures uniform distribution
.IP \(bu 4
For high-security applications, consider mixing with system entropy
.SH FILES
.TP
.I /dev/video*
Camera devices on Linux
.TP
.I openssl-camera-qrng.cnf
OpenSSL provider configuration
.SH EXIT STATUS
.TP
.B 0
Server started successfully
.TP
.B 1
Camera access error or configuration problem
.SH SEE ALSO
.BR openssl (1),
.BR v4l2-ctl (1)
.PP
LavaRnd Project: https://www.lavarnd.org/
.SH AUTHORS
Written for the camera-trng project.
.SH BUGS
Report bugs at: https://git.nixc.us/colin/camera-trng/issues