# Entropy-RNG: Camera-Based Random Number Generator

This project uses a live video feed from a network camera (e.g. an **Axis M1013**) to generate cryptographically secure random numbers. The camera is pointed at a high-contrast, ever-changing scene (e.g. ceiling and lamps) so the pixel data carries genuine entropy.

---

## How It Works

1. **Capture frame** — fetch a single MJPEG frame from the camera via OpenCV.
2. **Health check** — the raw JPEG bytes are run through FIPS 140-2 continuous tests (monobit, runs, long-run). A frozen or degraded frame is rejected before use.
3. **Extract entropy** — the frame is SHA-256 hashed to a 32-byte digest.
4. **DRBG** — the digest seeds a NIST SP 800-90A HMAC-DRBG (SHA-256), which generates the output bytes. The camera genuinely contributes entropy; the output is not just relabeled OS randomness.
5. **Emit** — hex to stdout, or raw bytes to a file/FIFO (`--out`).

---

## Requirements

- Python 3.10+
- `opencv-python`, `fastapi`, `uvicorn`, `pytest`

```bash
pip install -r requirements.txt
```

On Debian/Ubuntu you also need OpenCV runtime libs: `apt-get install libgl1 libglib2.0-0`.

---

## Local Usage

### Single number

```bash
python3 entropy.py --bit 256
```

### Loop, writing raw bytes to a FIFO for `rngd`

```bash
mkfifo /tmp/entropy.fifo
python3 entropy.py --loop --bit 512 --out /tmp/entropy.fifo &
sudo rngd -f -W 90% -x rdrand -x jitter -x pkcs11 -x rtlsdr \
  -O namedpipe:path:/tmp/entropy.fifo -O namedpipe:timeout:2
```

### Flags

| Flag | Default | Description |
|---|---|---|
| `--url` | `http://192.168.0.200/mjpg/video.mjpg` | Camera MJPEG stream URL |
| `--bit` | `256` | Bit length of each random number (multiple of 8) |
| `--single N` | `1` | Generate N numbers and exit |
| `--loop` | off | Run forever |
| `--interval` | `1.0` | Seconds between iterations in `--loop` |
| `--out PATH` | stdout | Append raw bytes to a file/FIFO instead of printing hex |
| `--no-health` | off | Disable FIPS 140-2 health checks |

`--loop` and `--single` are mutually exclusive.

---

## HTTP Service (for remote systems)

`api.py` runs the camera producer in a background thread and serves the latest entropy blob over HTTP, so other systems can pull entropy to seed their own pools.

### Run locally

```bash
uvicorn api:app --host 0.0.0.0 --port 8000
```

### Endpoints

| Method | Path | Auth | Returns |
|---|---|---|---|
| GET | `/` | none | service info |
| GET | `/healthz` | none | `{status: ok}` (liveness probe) |
| GET | `/entropy` | `X-API-Key` if configured | `{hex, bits, ts}` |

### Configuration (env vars)

| Var | Default | Description |
|---|---|---|
| `ENTROPY_CAMERA_URL` | `http://192.168.0.200/mjpg/video.mjpg` | Camera MJPEG URL |
| `ENTROPY_BITS` | `256` | Bits per blob |
| `ENTROPY_INTERVAL` | `1.0` | Seconds between frames |
| `ENTROPY_NO_HEALTH` | `0` | `1` disables health checks |
| `ENTROPY_API_KEY` | empty | Shared secret for `/entropy`; empty = no auth |

---

## Container Deployment

### Build and run

```bash
docker build -t entropy-rng .
docker run -d -p 8000:8000 \
  -e ENTROPY_CAMERA_URL=http://192.168.0.200/mjpg/video.mjpg \
  -e ENTROPY_API_KEY=changeme \
  entropy-rng
```

The container has a healthcheck against `/healthz`. The camera must be reachable from the container's network.

### Kubernetes notes

- **Replicas: 1.** Multiple pods hitting the same camera produce correlated output. Pin to a single replica.
- **Camera reachability** is the real constraint. Schedule the pod on a node that can reach the camera (use `nodeSelector` or a labeled node), or expose the camera via a `Service`.
- Store `ENTROPY_API_KEY` in a `Secret` and mount as an env var.
- Use an `Ingress` or `Service` for TLS termination in front of uvicorn.

---

## Consuming Remotely (seed another system's pool)

A remote Linux box can pull a blob and feed its kernel RNG via `rngd`:

```bash
curl -s -H "X-API-Key: changeme" https://entropy-svc.internal/entropy \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['hex'])" \
  | xxd -r -p > /tmp/entropy.fifo
sudo rngd -f -W 90% -x rdrand -x jitter -x pkcs11 -x rtlsdr \
  -O namedpipe:path:/tmp/entropy.fifo -O namedpipe:timeout:2
```

---

## Tests

```bash
pytest -q
```

Covers the HMAC-DRBG (determinism, reseed, length, reseed limit), health checks (random passes, frozen/all-ones/short/long-run rejected), a bit-balance smoke test, and the API endpoints including auth gating. Tests stub the camera, so they run without hardware.

---

## Notes

- Point the camera at a dynamic scene. A static frame will fail health checks and be rejected.
- The DRBG is reseeded from each frame, so output changes even if the camera noise is modest.
- Auth is a single shared secret for now. When you need per-client keys, rotate to HMAC-signed blobs or mTLS — the API layer is where that plugs in.