camera-trng/README.md

# Camera TRNG

A minimal cross-platform true random number generator that extracts entropy from camera sensor noise.

## How It Works

Camera sensors exhibit thermal noise and shot noise at the pixel level. This noise is most concentrated in the least significant bits (LSBs) of each pixel value. This service:

1. Captures frames from the default camera at the lowest resolution
2. Extracts the 2 LSBs from each pixel (where thermal/shot noise dominates)
3. Hashes the LSBs with SHA-256 to whiten the data and remove any bias
4. Mixes in timing entropy for additional randomness

## Build

```bash
cargo build --release
```

## Run

```bash
./target/release/camera-trng
# Or set a custom port
PORT=9000 ./target/release/camera-trng
```

## Docker

Pull the pre-built image:

```bash
docker pull git.nixc.us/colin/camera-trng:latest
```

Run with camera access (Linux with V4L2):

```bash
docker run -d \
  --name camera-trng \
  --device /dev/video0:/dev/video0 \
  -p 8787:8787 \
  git.nixc.us/colin/camera-trng:latest
```

### Available Tags

| Tag | Description |
|-----|-------------|
| `latest` | Latest build from master branch |
| `<commit-sha>` | Specific commit (first 8 chars) |
| `<version>` | Semantic version tags (e.g., `v1.0.0`) |

## API

### GET /random

Returns random bytes from camera noise.

**Query Parameters:**
- `bytes` - Number of bytes to return (default: 32, max: 1024)
- `hex` - Return as hex string instead of raw bytes (default: false)

**Examples:**
```bash
# Get 32 random bytes as hex
curl "http://localhost:8787/random?hex=true"

# Get 64 raw random bytes
curl "http://localhost:8787/random?bytes=64" -o random.bin

# Get 256 bytes as hex
curl "http://localhost:8787/random?bytes=256&hex=true"
```

### GET /health

Returns `ok` if the server is running.

## Rate Limiting

- Maximum 4 concurrent requests
- Maximum 1024 bytes per request
- Returns 429 Too Many Requests when overloaded

## Cross-Platform Support

Uses `nokhwa` for camera access, supporting:
- macOS (AVFoundation)
- Windows (Media Foundation)
- Linux (V4L2)

## CI/CD Pipeline

This project uses Woodpecker CI to automatically build, test, and deploy.

### Pipeline Overview

```
┌─────────────────────────────────────────────────────────────────┐
│                        Woodpecker CI                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  On Push/PR to master:                                          │
│  ┌─────────┐                                                    │
│  │  test   │──┬──> build-linux-x86_64 ──> binary artifact       │
│  └─────────┘  │                                                 │
│               ├──> build-linux-aarch64 ──> binary artifact      │
│               │                                                 │
│               └──> build-image ──┬──> trivy-image (scan)        │
│                                  └──> sbom-image (SBOM)         │
│                                                                 │
│  Parallel checks: cargo-audit, trivy-fs, clippy, fmt-check      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Build Artifacts

| Artifact | Architecture | Description |
|----------|--------------|-------------|
| `camera-trng-linux-x86_64` | x86_64 | Linux AMD64 binary |
| `camera-trng-linux-aarch64` | aarch64 | Linux ARM64 binary (best-effort) |
| Docker Image | linux/amd64 | Container image |

### Docker Image Registry

Images are pushed to: `git.nixc.us/colin/camera-trng`

- **On push to master**: Tags `latest` and `<commit-sha>`
- **On version tag**: Tags `<version>` and `latest`

### Required Secrets

Configure these secrets in Woodpecker:

| Secret | Description |
|--------|-------------|
| `REGISTRY_USER` | Username for git.nixc.us registry |
| `REGISTRY_PASSWORD` | Password/token for git.nixc.us registry |
| `DOCKER_REGISTRY_USER` | Docker Hub username (for base images) |
| `DOCKER_REGISTRY_PASSWORD` | Docker Hub password/token |

### Security Scanning

The pipeline includes:
- **cargo-audit**: Scans Rust dependencies for known vulnerabilities
- **trivy-fs**: Scans filesystem and Cargo.lock for vulnerabilities
- **trivy-image**: Scans the built Docker image
- **SBOM generation**: Creates SPDX and CycloneDX SBOMs for dependencies

### Cross-Compilation Notes

**Linux x86_64**: Fully supported, built natively on CI runners.

**Linux aarch64**: Best-effort cross-compilation. May fail due to native camera library dependencies (libv4l). For production ARM64 builds, consider using native ARM64 runners.

**macOS/Windows**: Not built in CI due to native camera library requirements. Build locally:

```bash
# macOS
cargo build --release

# Windows (requires MSVC toolchain)
cargo build --release
```

### Local Docker Build

```bash
# Build locally
docker build -t camera-trng:local .

# Test locally (requires camera device)
docker run --rm --device /dev/video0 -p 8787:8787 camera-trng:local
```

## Security Notes

This is intended for hobby/experimental use. For cryptographic applications:
- Consider mixing with system entropy (`/dev/urandom`)
- The quality of randomness depends on camera sensor characteristics
- Environmental factors (lighting, temperature) affect noise levels