192 lines
4.9 KiB
Groff
192 lines
4.9 KiB
Groff
.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
|