RyanandClaude Sonnet 5.5
c1fcfb7b73
All Mermaid blocks in the docs now parse on 11.13.0 (the version bundled with Typora and Obsidian) and the embedded SVGs are rendered with it. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
39 lines
2.5 KiB
Markdown
39 lines
2.5 KiB
Markdown
# mqtt-security-test
|
|
|
|
Prototype of secure board enrollment over MQTT: a Go backend and two simulated boards (C with
|
|
libsodium, C++ with OpenSSL) talk through a real Mosquitto 2.1 broker with Dynamic Security, using an
|
|
X25519 key agreement so the broker password is never transmitted.
|
|
|
|
- **[DEMO.md](DEMO.md)**: what the demo is, what it does and the 19 checks each board performs.
|
|
- **[docker/README.md](docker/README.md)**: how to run it and read the web view.
|
|
- **Design docs** (copied from the backend repo, where they live under `docs/investigations/`; links to other
|
|
backend-repo files appear there as plain text):
|
|
- [docs/sn-as-username-process.md](docs/sn-as-username-process.md): the full raw board to FN to SN process with SN as the
|
|
broker username, with the threat model.
|
|
- [docs/enrollment-and-activation.md](docs/enrollment-and-activation.md): the FN-as-username and SN-as-username models compared.
|
|
- [docs/mqtt-dynamic-security-rnd.md](docs/mqtt-dynamic-security-rnd.md): the original R&D notes.
|
|
- The diagrams are written and checked against **Mermaid 11.13.0** (the version bundled with Typora and Obsidian);
|
|
the sequence diagrams are also embedded as SVG images rendered with that version, with the source under each.
|
|
- `go/`, `c/`, `c-libsodium/`, `cpp/`, `run.sh`, `run-libsodium.sh`: fixed-key programs that check the
|
|
crypto libraries against the RFC test vectors and against each other.
|
|
|
|
## Run locally
|
|
|
|
```bash
|
|
cd docker && ./run-docker.sh # web view on http://localhost:8099, with the "Run again" button
|
|
```
|
|
|
|
## Deployment
|
|
|
|
Every push to `main` runs `.gitea/workflows/deploy.yml` on the Gitea runner: it validates the compose
|
|
files, builds all images, redeploys the stack on the server's Docker daemon with the web view published on
|
|
**port 8099** (`http://<server-ip>:8099`) and fails unless both boards pass all checks.
|
|
The public web view cannot restart anything itself (that would need the Docker socket). Its **"Run again (via Gitea)"**
|
|
button opens the Gitea Actions page for `.gitea/workflows/restart.yml`; run that workflow there ("Run workflow") to replay
|
|
the whole demo on the server without rebuilding. Only people with access to the repository can do that. To run a stack
|
|
locally with a self-contained button instead, use `docker/run-docker.sh` (it adds `docker/compose.restart.yaml`, which
|
|
mounts the Docker socket: local use only).
|
|
|
|
The compose file contains **demo secrets** (broker and service passwords, a signing seed) that protect nothing
|
|
real. Do not reuse them anywhere else.
|