micheleandCursor
7d3369b098
Initialise NVS before integration startup, recover from encrypted-partition mismatches without re-enabling encryption, and improve provisioning logs and POST body handling. Co-authored-by: Cursor <cursoragent@cursor.com>
70 lines
3.0 KiB
Markdown
70 lines
3.0 KiB
Markdown
# Flash and NVS encryption (T8)
|
||
|
||
> **Current bring-up (2026):** `sdkconfig.defaults` keeps
|
||
> `CONFIG_NVS_ENCRYPTION` and `CONFIG_SECURE_FLASH_ENC_ENABLED` **disabled**
|
||
> for Si4684 board validation. Wi-Fi credentials are stored in **plain NVS**.
|
||
> After flashing firmware that previously used encrypted NVS, run
|
||
> `idf.py erase-flash flash` once so the partition format matches (or rely on
|
||
> automatic NVS erase on `ESP_ERR_NVS_WRONG_ENCRYPTION` at boot).
|
||
|
||
DigiRadio stores Wi-Fi credentials, preset lists, audio profiles, and the last
|
||
preset index in the `digiradio` NVS namespace. Firmware **0.8.3+** enables:
|
||
|
||
| Layer | Kconfig | Effect |
|
||
|-------|---------|--------|
|
||
| Flash encryption | `CONFIG_SECURE_FLASH_ENC_ENABLED` | On-chip transparent flash ciphertext |
|
||
| Mode (default) | `CONFIG_SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT` | Plaintext download still allowed for bring-up |
|
||
| NVS encryption | `CONFIG_NVS_ENCRYPTION` | XTS-AES over NVS entries; keys in `nvs_keys` partition |
|
||
| Partition table | `partitions.csv` | `nvs`, `otadata`, `ota_0`/`ota_1`, `dsp`, `nvs_keys` |
|
||
|
||
Implementation: `secure_store::initEncryptedStorage()` (called from
|
||
`NetBootstrap` before any `NvsSecureStore` access). With `CONFIG_NVS_ENCRYPTION`,
|
||
ESP-IDF `nvs_flash_init()` loads or generates keys in the first `nvs_keys`
|
||
partition automatically (ESP-IDF v5.5 NVS Encryption guide).
|
||
|
||
**No encryption keys are stored in this repository.**
|
||
|
||
## First flash (virgin ESP32-S3)
|
||
|
||
```bash
|
||
cd Software
|
||
idf.py set-target esp32s3
|
||
idf.py erase-flash flash monitor
|
||
```
|
||
|
||
Provision Wi-Fi via SoftAP UI, save a preset, reboot — credentials should
|
||
survive `STA` reconnect.
|
||
|
||
## Migrating from plain NVS (pre-0.8.3 dev boards)
|
||
|
||
Encryption changes the on-flash layout. **Erase once** before using encrypted
|
||
firmware:
|
||
|
||
```bash
|
||
idf.py erase-flash flash
|
||
```
|
||
|
||
Users must re-provision Wi-Fi and presets after erase.
|
||
|
||
## Production release mode
|
||
|
||
After HIL sign-off, build with the production overlay
|
||
(`sdkconfig.defaults.production`) so flash encryption uses **RELEASE** mode.
|
||
This limits future plaintext downloads — follow Espressif’s flash encryption
|
||
checklist for ESP32-S3 before shipping units.
|
||
|
||
## HIL checklist (requires hardware — pending)
|
||
|
||
- [ ] Boot log shows `NvsPlatformInit: NVS encryption enabled` and flash encryption enabled
|
||
- [ ] `POST /api/wifi` → reboot → STA connects without re-provisioning
|
||
- [ ] Preset save/recall and `last_preset` survive power cycle
|
||
- [ ] Audio profile round-trip after reboot
|
||
- [ ] `espefuse.py summary` shows expected `SPI_BOOT_CRYPT_CNT` after first encrypted boot
|
||
- [ ] Optional: UART hex dump of NVS region shows non-plaintext SSID (do not log secrets in CI)
|
||
|
||
## References
|
||
|
||
- ESP-IDF v5.5 — [NVS Encryption (ESP32-S3)](https://docs.espressif.com/projects/esp-idf/en/v5.5.3/esp32s3/api-reference/storage/nvs_encryption.html)
|
||
- ESP-IDF v5.5 — [Flash Encryption (ESP32-S3)](https://docs.espressif.com/projects/esp-idf/en/v5.5.3/esp32s3/security/flash-encryption.html)
|
||
- `Software/partitions.csv`, `Software/sdkconfig.defaults`
|