Replace compile-time HMAC key with USB provisioning

ESP firmware: - Store HMAC key in NVS via Preferences library instead of compile-time hmac_key.h - KEY? responds with HMAC_KEY:<hex> (if provisioned) or NO_KEY - New SET_KEY:<64-hex> command stores key in NVS and responds OK - Boot messages updated to reflect provisioning state Android app: - UsbKeyReceiver detects NO_KEY response and auto-provisions: generates random 32-byte key via SecureRandom, sends SET_KEY, waits for OK, saves key to SharedPreferences - Read loop now breaks on both HMAC_KEY: and NO_KEY responses Cleanup: - Removed tools/generate_hmac_key.py and src/hmac_key.h - Removed hmac_key.h from .gitignore - README updated for new provisioning flow
2026-07-26 09:30:21 +02:00 · 2026-07-26 09:30:21 +02:00 · 9a84b05b8a
commit 9a84b05b8a
parent c707c21d7f
5 changed files with 155 additions and 116 deletions
--- a/README.md
+++ b/README.md
@ -71,22 +71,26 @@ De sequence counter reset naar 0 bij elke (re)connectie op de ESP. De app start

 #### Key management

- De HMAC key staat in `src/hmac_key.h` (niet in git, `.gitignore`)
- Een CLI-tool genereert een willekeurige key: `python3 tools/generate_hmac_key.py`
- De ESP print de key 5 seconden na opstarten naar serial
- **USB auto-read:** Sluit de ESP via USB-OTG aan op de telefoon → de app leest de key automatisch via USB serial (CDC-ACM). De ESP reageert op het commando `KEY?\n` met `HMAC_KEY:<hex>`. Geen encryptie nodig — fysieke connectie is de beveiliging.
+- De HMAC key wordt **niet meer meegecompileerd** — de ESP start zonder key en wordt geprovisioneerd via USB
+- De key wordt opgeslagen in **NVS** (Non-Volatile Storage) op de ESP via de Arduino `Preferences` library
+- **USB auto-provisioning:** Sluit de ESP via USB-OTG aan op de telefoon → de app stuurt `KEY?\n`. Als de ESP nog geen key heeft, antwoordt hij met `NO_KEY`. De app genereert dan een willekeurige 32-byte key (via `SecureRandom`), stuurt `SET_KEY:<hex>\n` naar de ESP, en slaat de key both op de ESP (NVS) als lokaal (SharedPreferences) op.
+- Als de ESP al wel een key heeft, antwoordt hij met `HMAC_KEY:<hex>` en de app slaat die op
 - Handmatige invoer: via het instellingenscherm in de Android app (64-teken hex string)
 - De app slaat de key op in SharedPreferences (overleeft app-herstarts)
 - Zo kan dezelfde app gebruikt worden voor meerdere ESP modules — each met een eigen key

-#### USB Serial Key Transfer Protocol
+#### USB Serial Protocol

 ```
 App → ESP:  KEY?\n
-ESP → App:  HMAC_KEY:C3F17B612B93E82C56B055FA9B04E84664ACE1EC4E889F2763F271B65A5B54AF\n
+ESP → App:  HMAC_KEY:C3F17B...AF\n     (als key bekend)
+ESP → App:  NO_KEY\n                    (als ESP nog geen key heeft)
+
+App → ESP:  SET_KEY:C3F17B...AF\n       (nieuwe key schrijven)
+ESP → App:  OK\n                        (bevestiging)
 ```

-De ESP luistert in `loop()` voor USB serial data. Bij `KEY?\n` antwoordt hij met de hex key. De Android `UsbKeyReceiver` (manifest-geregistreerde `BroadcastReceiver`) vangt `USB_DEVICE_ATTACHED` op, filtert op Espressif (vendor 0x303a), vraagt USB-permission, opent een CDC-ACM serial connectie, stuurt `KEY?\n`, en slaat de respons op in SharedPreferences.
+De ESP luistert in `loop()` voor USB serial data. Bij `KEY?\n` antwoordt hij met de hex key (`HMAC_KEY:<hex>`) of `NO_KEY`. Bij `SET_KEY:<64-hex>\n` slaat hij de key op in NVS en antwoordt `OK`. De Android `UsbKeyReceiver` (manifest-geregistreerde `BroadcastReceiver`) vangt `USB_DEVICE_ATTACHED` op, filtert op Espressif (vendor 0x303a), vraagt USB-permission, opent een CDC-ACM serial connectie, en handelt het hele provisioning-proces automatisch af.

 ### Beveiligingsanalyse

@ -123,33 +127,31 @@ De touch sensor en BLE werken onafzankelijk. Als de sensor losgelaten wordt en d

 De characteristic ondersteunt `WRITE` (encrypted) en `NOTIFY`. Writes vereisen een versleutelde link (bonding) plus HMAC-authenticatie.

-### HMAC Key genereren
+### Key provisioning

-Voordat de firmware gecompileerd kan worden, moet er een HMAC key gegenereerd worden:
+De firmware wordt zonder HMAC key gecompileerd. Bij de eerste opstart print de ESP:

-```bash
-python3 tools/generate_hmac_key.py
+```
+No HMAC key provisioned — connect USB and run SET_KEY
 ```

-Dit maakt `src/hmac_key.h` aan met een willekeurige 32-byte key en print de hex-representatie. Een bestaande key overschrijven:
+Sluit de ESP via USB aan op de telefoon met de app geinstalleerd. De app genereert automatisch een willekeurige key en stuurt deze naar de ESP. Na provisioning print de ESP bij opstarten:

-```bash
-echo "y" | python3 tools/generate_hmac_key.py
 ```
-
-> **Belangrijk:** `src/hmac_key.h` staat in `.gitignore` en wordt niet gecommit. De key moet op de ESP en in de app identiek zijn.
+HMAC key loaded from NVS
+HMAC Key: C3F17B...AF
+```

 ### Serial monitor

-Baudrate: **115200** (USB CDC). De firmware stuurt heartbeat-statussen elke 5 seconden, logt statuswijzigingen, en print de HMAC key 5 seconden na opstarten:
+Baudrate: **115200** (USB CDC). De firmware stuurt heartbeat-statussen elke 5 seconden, logt statuswijzigingen, en print de HMAC key (of de afwezigheid ervan) bij opstarten:

 ```
 === Atom VoiceS3R BLE Relay ===
+HMAC key loaded from NVS
 LED blink done, starting BLE...
 BLE: advertising started as 'AtomS3R-Relay'
-Printing HMAC key in 5 seconds...
 HMAC Key: C3F17B612B93E82C56B055FA9B04E84664ACE1EC4E889F2763F271B65A5B54AF
-Enter this key in the Android app > Settings.
 Setup done.
 [heartbeat] relay=OFF touch=no ble=disconnected
 BLE: device connected
@ -163,7 +165,6 @@ BLE: relay OFF (seq=2)
 > **Download-mode:** Houd de reset-knop ~2 seconden ingedrukt tot de groene LED aangaat, laat dan los. Het board is nu in download-mode.

 ```bash
-# Zorg dat src/hmac_key.h bestaat (zo niet: python3 tools/generate_hmac_key.py)
 pio run --target upload
 ```

@ -179,7 +180,7 @@ Na het uploaden treedt er een harde reset op. Als het board in download-mode bli
 - **BLE Pairing:** De app initieert bonding (`createBond()`) na connectie; Just Works pairing verloopt zonder gebruikersinteractie
 - **MTU negotiatie:** Vraagt MTU 256 aan na service discovery (voor 37-byte HMAC packets)
 - **HMAC authenticatie:** Elk commando wordt ondertekend met HMAC-SHA256 + sequence counter
- **USB auto-read:** Bij aansluiten van de ESP via USB-OTG wordt de HMAC key automatisch gelezen en opgeslagen (BroadcastReceiver)
+- **USB auto-provisioning:** Bij aansluiten van de ESP via USB-OTG genereert de app een key als de ESP er nog geen heeft, of leest de bestaande key uit (BroadcastReceiver)
 - **Instellingenscherm:** Losse Activity voor het invoeren van de HMAC key (met oog-icoon om de key te tonen/verbergen), "Scan & Verbind" knop, en hint-tekst
 - **Permissies:** Vraagt BLUETOOTH_SCAN, BLUETOOTH_CONNECT en ACCESS_FINE_LOCATION aan (Android 12+)

@ -188,8 +189,8 @@ Na het uploaden treedt er een harde reset op. Als het board in download-mode bli
 1. Open de app
 2. Tik op het **tandwiel-icoon** rechtsboven
 3. De app toont een hint: _"Voer de HMAC sleutel in of sluit de relaismodule aan op de telefoon."_
-4. **Optie A — handmatig:** Voer de 64-teken hex key in (zelfde als de ESP op serial print). Tik op het **oog-icoon** om de key te tonen/verbergen. Tik **Opslaan**.
-5. **Optie B — automatisch:** Sluit de ESP via USB-OTG aan op de telefoon. Android vraagt USB-toestemming (1x). De key wordt automatisch gelezen en opgeslagen. Toast: "HMAC sleutel gelezen van ESP!"
+4. **Optie A — handmatig:** Voer de 64-teken hex key in. Tik op het **oog-icoon** om de key te tonen/verbergen. Tik **Opslaan**.
+5. **Optie B — automatisch (aanbevolen):** Sluit de ESP via USB-OTG aan op de telefoon. Android vraagt USB-toestemming (1x). De app leest de key uit of genereert een nieuwe als de ESP er nog geen heeft. Toast bevestigt de actie.
 6. Tik **Scan & Verbind** om op te slaan en direct BLE scannen te starten.

 De key wordt opgeslagen in SharedPreferences en overleeft app-herstarts. Bij geen key toont de hoofdapp "Geen HMAC sleutel - open Instellingen" en wordt er niet gescant.
@ -206,7 +207,7 @@ Vereisten:
 - Android SDK (API 34+)
 - Java 17+ (Java 26 werkt niet met Gradle 8.5 — gebruik Java 21)
 - Gradle 8.2.2 (via wrapper)
- USB host support (usb-serial-for-android library via JitPack)
+- USB host support (raw Android USB API, geen externe library)

 ```bash
 cd android
@ -230,47 +231,40 @@ adb install -r android/app/build/outputs/apk/debug/app-debug.apk

 ## Eerste keer setup

-1. **Genereer HMAC key:**
-   ```bash
-   python3 tools/generate_hmac_key.py
-   ```
-   Noteer de geprinte hex key.
-
-2. **Flash de ESP:**
+1. **Flash de ESP:**
   ```bash
   pio run -t upload
   ```

-3. **Installeer de app op de telefoon:**
+2. **Installeer de app op de telefoon:**
   ```bash
   adb install -r android/app/build/outputs/apk/debug/app-debug.apk
   ```

-4. **Voer de HMAC key in (kies één):**
+3. **Provision de HMAC key (kies één):**

-   **Optie A — USB auto-read (aanbevolen):**
+   **Optie A — USB auto-provisioning (aanbevolen):**
   - Sluit de ESP via USB-OTG aan op de telefoon
   - Android vraagt USB-toestemming (1x) — tik "Toestaan"
-   - De key wordt automatisch gelezen en opgeslagen (Toast bevestigt)
+   - De app detecteert dat de ESP geen key heeft, genereert er één, en stuurt deze naar de ESP
+   - Toast: "Nieuwe HMAC sleutel gegenereerd en naar ESP geschreven!"
   - Ontkoppel de ESP en zet hem op stroom

   **Optie B — handmatig:**
-   - Open de app → tandwiel-icoon → voer de hex key in → Opslaan
+   - Open de app → tandwiel-icoon → voer een 64-teken hex key in → Opslaan
+   - Let op: de ESP moet dan dezelfde key hebben (via USB provisioning of handmatig via serial `SET_KEY:<hex>`)

-5. **Scan & Verbind:** Tik in instellingen op "Scan & Verbind" (of de app scant automatisch bij terugkeren naar het hoofdscherm)
+4. **Scan & Verbind:** Tik in instellingen op "Scan & Verbind" (of de app scant automatisch bij terugkeren naar het hoofdscherm)

-6. De app scant, paart (Just Works), en verbindt. Houd de HOLD-knop ingedrukt om het relais te schakelen.
+5. De app scant, paart (Just Works), en verbindt. Houd de HOLD-knop ingedrukt om het relais te schakelen.

 ## Projectstructuur

 ```
 sylvia-touch-relay/
 ├── platformio.ini              # PlatformIO configuratie (ESP32-S3)
-├── tools/
-│   └── generate_hmac_key.py    # CLI tool: genereert src/hmac_key.h
 ├── src/
-│   ├── main.cpp                # Firmware (BLE + HMAC + USB serial + sensor + relais)
-│   └── hmac_key.h              # Gegenereerd, niet in git (.gitignore)
+│   └── main.cpp                # Firmware (BLE + HMAC + NVS key storage + USB serial + sensor + relais)
 ├── android/
 │   ├── build.gradle            # Root Gradle config
 │   ├── settings.gradle         # JitPack repos voor usb-serial-for-android
@ -305,10 +299,9 @@ sylvia-touch-relay/
 - G1 en G2 zitten op de HY2.0-4P Grove poort. G5-G8, G38, G39 zitten op de onderste expantie-header.
 - De firmware gebruikt geen M5Unified library — alleen Arduino core + ESP32 BLE + mbedtls. Dit maakt de serial output betrouwbaarder via USB CDC.
 - `ARDUINO_USB_CDC_ON_BOOT=1` is ingeschakeld voor virtuele serial via USB.
- De HMAC key wordt via `#include "hmac_key.h"` in de firmware geincludeerd. Dit bestand is gegenereerd door `tools/generate_hmac_key.py` en staat in `.gitignore`.
+- De HMAC key wordt opgeslagen in NVS (Non-Volatile Storage) via de Arduino `Preferences` library. De key wordt niet meegecompileerd maar via USB provisioning door de Android app op de ESP gezet.
 - De app gebruikt `WRITE_TYPE_NO_RESPONSE` voor minimale latency — de encryptie en HMAC verificatie gebeuren op de link layer resp. application layer en zijn onafhankelijk van het write type.
 - De sequence counter start bij 1 (niet 0) om te voorkomen dat het eerste packet na connectie als replay wordt geweerd (`0 <= 0` is true in de `seq <= lastSeq` check).
- Für meerdere ESP modules met verschillende keys: genereer per module een eigen key, flash de firmware, en voer de juiste key in de app in. De app ondersteunt momenteel slechtséén key (opgeslagen in SharedPreferences).
+- Für meerdere ESP modules met verschillende keys: sluit elke ESP één voor één aan op de telefoon. De app genereert per ESP een eigen key en slaat deze op. De app ondersteunt momenteel slechtséén key tegelijk (opgeslagen in SharedPreferences).
 - De `UsbKeyReceiver` is een manifest-geregistreerde `BroadcastReceiver` voor `ACTION_USB_DEVICE_ATTACHED`. Hij filtert op Espressif (vendor 0x303a), vraagt USB-permission via `PendingIntent`, opent een CDC-ACM serial connectie (115200), stuurt `KEY?\n`, en slaat de respons op. Werkt ook als de app niet actief is.
- De USB serial library (`usb-serial-for-android` v3.7.3 via JitPack) ondersteunt CDC-ACM (ESP32-S3), FTDI, CP210x, CH340, PL2303, en meer.
- De `UsbKeyReceiver` doet serial I/O op een achtergrondthread (max 3s timeout) om ANR's te voorkomen.
+- De `UsbKeyReceiver` doet serial I/O op een achtergrondthread (max 5s timeout per poging, 5 retries) om ANR's te voorkomen.