OTA design: glossary, ADR 0003 (own signature check), plan

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT
2026-10-03 21:27:04 +02:00
parent 045c7c3e8f
commit e9efbcca4d
3 changed files with 61 additions and 0 deletions
@@ -0,0 +1,11 @@
+# Signed Update Files checked by the firmware, not ESP32 Secure Boot
+
+Firmware Updates are accepted only when their Update File carries a valid ECDSA P-256 signature over the image's SHA-256. The firmware itself checks it, against a public key compiled into it, before switching the boot partition. The private key lives outside the repository, in `~/.config/roro9stack/ota-key.pem`.
+
+We chose this over the ESP32's hardware Secure Boot. Secure Boot is enforced by the chip, but it burns eFuses one-way: a mistake bricks the device, and the device can never run unsigned firmware again, which makes recovery over USB harder. On a single development device, a software check that refuses unsigned pushes is enough, and it stays reversible: a new firmware can carry a new public key.
+
+## Consequences
+
+- Someone with physical USB access can still flash anything. Only Wi-Fi and SD card updates are guarded.
+- **Losing the private key** means the next update has to go over USB, carrying a new public key.
+- P-256 rather than Ed25519, because the firmware's TLS library (mbedTLS) already verifies it, so it costs no extra code.
@@ -0,0 +1,33 @@
+# OTA — Firmware Updates over Wi-Fi and from the SD card
+
+**Goal:** install new firmware without a USB cable. Push it from the PC over Wi-Fi, or drop it on the SD card. Unsigned images are refused, and a broken update rolls back by itself.
+
+## Decisions (design round 2026-10-03)
+
+| # | Decision |
+|---|---|
+| Q52 | Two sources: **push over Wi-Fi** from the PC, and **from the SD card**. Pulling from Gitea releases is deferred. |
+| Q53 | **Signed Update Files** (ECDSA P-256 over SHA-256). The private key stays in `~/.config/roro9stack/`, and the firmware embeds the public key (ADR 0003). |
+| Q54 | The device **always listens** for pushes on the LAN while Wi-Fi is Connected, announced as `roro9stack-<id>.local`. |
+| Q55 | New firmware runs on **Probation**. It's confirmed once booted, UI drawn, Services started, 30 s without a crash, and Wi-Fi connected (if configured). Otherwise **Rollback**. A Toast reports either outcome. |
+| Q56 | **Downgrades are allowed**, with "older than the installed version" shown. |
+| Q57 | A valid push **installs right away**: progress screen, then reboot. The reboot waits for Text Entry to end, 60 s at most. |
+
+## Done when
+
+- `scripts/ota_keygen.sh` creates the key pair once. The public key is committed; the private key never is.
+- `scripts/flash.sh --ota` builds, signs and pushes to `roro9stack-<id>.local`. The device shows progress, reboots, and a Toast confirms the new version.
+- An Update File with a bad signature, a truncated or corrupted image, or no signature is refused, and the device keeps running.
+- Settings → About → **Update from SD** lists the `.ota` files in `/updates` and installs one.
+- A firmware that crashes during Probation rolls back to the previous version, and says so after the reboot.
+
+## Work breakdown
+
+1. **Update File format** (host-tested): header (magic, format, version, image size, SHA-256), signature, image. A streaming parser that hashes as it goes and decides accept / refuse / downgrade. The signature verifier sits behind an interface, so tests can inject one.
+2. **PC side:** key generation, `make_ota.py` (wraps `firmware.bin` into a signed `.ota`), and the push client. `flash.sh --ota` ties them together.
+3. **Device:** the Update Service.
+   - A listener on TCP 3232 plus mDNS.
+   - Writes the image to the inactive app slot, with the ECDSA check through mbedTLS.
+   - A progress screen, and a reboot that waits out Text Entry.
+4. **Probation and Rollback:** the health checks, confirming the image, and detecting a rollback after reboot to report it.
+5. **Update from SD:** the same parser, fed from the Storage Service's task (all card access stays there).