70f004c45b
Also un-ignores docs/ directory so project documentation (specs, plans) is tracked in git. Individual research files remain gitignored.
68 lines
2.3 KiB
Markdown
68 lines
2.3 KiB
Markdown
# Device UUID Pairing — Design
|
|
|
|
**Datum:** 2026-07-29
|
|
**Status:** goedgekeurd
|
|
|
|
## Doel
|
|
|
|
Voorkomen dat twee ESP-telefoon paren in dezelfde ruimte met elkaars ESP verbinden. Elk ESP-telefoon paar deelt een unieke UUID die tijdens key exchange wordt uitgewisseld.
|
|
|
|
## Flow
|
|
|
|
### Verse ESP (geen UUID, geen HMAC key)
|
|
|
|
1. ESP boot, genereert random UUID (16 bytes via `esp_random()`), slaat op in NVS
|
|
2. ESP start BLE advertising als `"SylDa_Server"` (UUID nog onbekend bij app)
|
|
3. App opent Settings → Key Exchange
|
|
4. App stuurt `KEY?` over USB CDC, ESP antwoordt `NO_KEY`
|
|
5. App genereert random 32-byte HMAC key + 16-byte UUID
|
|
6. App stuurt `SET_KEY:<64 hex>` → ESP slaat op → `OK`
|
|
7. App stuurt `SET_ID:<32 hex>` → ESP slaat op → `OK`
|
|
8. App slaat beide op in EncryptedSharedPreferences
|
|
9. App keert terug naar main, start scan
|
|
|
|
### Bestaand paar (beide hebben UUID + HMAC key)
|
|
|
|
1. App stuurt `KEY?`, ESP antwoordt `DEVICE_ID:<32 hex>\nHMAC_KEY:<64 hex>`
|
|
2. App slaat beide op
|
|
3. Klaar
|
|
|
|
### BLE connectie
|
|
|
|
1. App scant op BLE service UUID `4fafc201-...` (niet op naam)
|
|
2. Bij elke gevonden device: connect, discover services
|
|
3. Lees UUID characteristic (READ-only)
|
|
4. UUID match → zet relay knoppen actief
|
|
5. UUID mismatch → disconnect, voeg address toe aan `triedAddresses`, herstart scan
|
|
6. Relay commands blijven HMAC-beveiligd zoals voorheen
|
|
|
|
## Componenten
|
|
|
|
### Firmware (`src/main.cpp`)
|
|
|
|
| Item | Details |
|
|
|------|---------|
|
|
| NVS key `"uuid"` | 16 bytes, namespace `"hmac"` |
|
|
| UUID generatie | `esp_random()` per byte, alleen bij eerste boot |
|
|
| BLE naam | `"SylDa_Server"` |
|
|
| UUID characteristic | Nieuwe READ-only characteristic, los UUID |
|
|
| `KEY?` response | `DEVICE_ID:32HEX\nHMAC_KEY:64HEX` of `NO_KEY` |
|
|
| `SET_ID:32HEX` | Nieuw commando, slaat UUID in NVS |
|
|
|
|
### Android — PrefsHelper
|
|
|
|
- `PREF_UUID = "device_uuid"` (EncryptedSharedPreferences)
|
|
|
|
### Android — SettingsActivity
|
|
|
|
- `readKeyFromEsp()`: parse `DEVICE_ID:` lijn
|
|
- `KeyResult.Success` krijgt `deviceUuid` veld
|
|
- Bij `NO_KEY`: app genereert UUID + stuurt `SET_KEY` en `SET_ID`
|
|
|
|
### Android — MainActivity
|
|
|
|
- `loadState()`: laadt UUID
|
|
- `startScan()`: `ScanFilter` op service UUID
|
|
- `onScanResult`: connect bij elke match (naam genegeerd)
|
|
- `gattCallback.onMtuChanged`: lees UUID characteristic, verify
|
|
- UUID mismatch: disconnect, `triedAddresses.add(address)`, herstart scan
|