Harden signed SD and bootloader OTA
This commit is contained in:
1 parent
3d78d9c846
commit
d9f5dfa8a2
29 files changed
+1846
-408
No files matched your search
@@ -69,6 +69,11 @@ while the same link carries framed folder requests. BLE remains available.
|
||||
| nRF52 repeater, external QSPI | Full image or in-place delta | QSPI-aware exact-board OTAFIX bootloader and matched repeater build | Builds a full mOTA; adding `--base` requests a delta |
|
||||
| MeshTower V2 nRF52, microSD | Full image or in-place delta | SD-aware exact-board OTAFIX bootloader and compatible card | Builds a full mOTA; adding `--base` requests a delta |
|
||||
|
||||
MeshTower V2 microSD application and bootloader containers require an Ed25519 signature from a key in the
|
||||
device allowlist. Supply `--sign-key` when the runner must build a container, and install the BLM2-capable
|
||||
SD-aware bootloader locally before attempting application or bootloader OTA. Preview.12 requires USB/BLE
|
||||
DFU or SWD; see [MeshTower V2 microSD LoRa OTA](ota_meshtower_v2_sdcard.md).
|
||||
|
||||
The firmware inside a raw ZIP must have a valid MeshCore `EndF` trailer. An
|
||||
ESP32 merged/factory image is not an application image and is rejected. A
|
||||
generic vendor DFU ZIP may also be unusable if it does not contain the raw
|
||||
|
||||
@@ -18,6 +18,11 @@ Matched QSPI repeater targets and the MeshTower V2 microSD target can also insta
|
||||
complete container stays off-chip. See [nRF52 repeater OTA with external QSPI](ota_nrf52_qspi.md) and
|
||||
[MeshTower V2 microSD LoRa OTA](ota_meshtower_v2_sdcard.md).
|
||||
|
||||
MeshTower V2 microSD application and bootloader containers must be Ed25519-signed by a key in the device
|
||||
allowlist; pass `--sign-key` when building one. Its BLM2-capable SD-aware bootloader is also required before
|
||||
ordinary application or bootloader OTA can use the reset-retained authorization record. Upgrade preview.12
|
||||
locally over USB/BLE DFU or SWD first; there is no raw-card compatibility handoff.
|
||||
|
||||
## Temporary OTA channel used in this guide
|
||||
|
||||
| Setting | Value |
|
||||
|
||||
@@ -22,14 +22,16 @@ LoRa radio pinout.
|
||||
|
||||
## Card requirements
|
||||
|
||||
Use a FAT16, FAT32, or exFAT card with an MBR partition table whose first
|
||||
partition starts after sector 1. This is the normal layout produced by most SD
|
||||
formatters. GPT and unpartitioned "super-floppy" layouts are rejected.
|
||||
Use a FAT16, FAT32, or exFAT card accepted by the bundled SdFat version. The
|
||||
normal update path imposes no additional MBR/sector-1 layout requirement;
|
||||
filesystem layouts SdFat cannot mount are still rejected. MeshCore creates
|
||||
`/meshcore-ota.mota` as a contiguous file and passes its exact sector range to
|
||||
OTAFIX in reset-retained MCU RAM.
|
||||
|
||||
MeshCore creates `/meshcore-ota.mota` as a contiguous file. Sector 1, which is
|
||||
outside the partition, holds a checksummed bootloader handoff record. The
|
||||
firmware validates this gap before writing it; an incompatible card layout
|
||||
fails safely without modifying sector 1.
|
||||
MeshCore never reads or writes raw sector 1 and does not infer ownership from
|
||||
blank card sectors. Both application and bootloader OTA require a locally
|
||||
provisioned BLM2-capable bootloader that understands the retained-RAM record.
|
||||
Preview.12 must first be upgraded over USB/BLE DFU or SWD.
|
||||
|
||||
## Capacity and update types
|
||||
|
||||
@@ -43,7 +45,8 @@ For this S140 v6 target, the maximum application image including its `EndF`
|
||||
trailer is `0xC7000` bytes (815,104 bytes). To package a full self-update:
|
||||
|
||||
```bash
|
||||
motatool build --fw ./Heltec_tower_v2_sdcard-new.hex --out-dir ./motas
|
||||
motatool build --fw ./Heltec_tower_v2_sdcard-new.hex \
|
||||
--sign-key ./trusted-signer.key --out-dir ./motas
|
||||
motatool verify ./motas/*.mota
|
||||
```
|
||||
|
||||
@@ -57,19 +60,23 @@ motatool build \
|
||||
--fw ./Heltec_tower_v2_sdcard-new.hex \
|
||||
--patch-type in-place \
|
||||
--inplace-memory 0xC7000 \
|
||||
--sign-key ./trusted-signer.key \
|
||||
--out-dir ./motas
|
||||
motatool verify ./motas/*.mota
|
||||
```
|
||||
|
||||
The download is resumable because the partial `.mota` stays on the card.
|
||||
Once it reaches `ready`, `ota install` performs the final verification,
|
||||
publishes the bootloader handoff, and reboots. Keep the card inserted through
|
||||
the reboot and installation.
|
||||
publishes a one-reset authorization record, and reboots. SD application
|
||||
installation requires a valid signature from a key in the node's allowlist.
|
||||
Keep the card inserted through the reboot and installation.
|
||||
|
||||
The SD-aware bootloader is mandatory. `ota install` refuses to reboot if the
|
||||
bootloader capability marker does not advertise SD staging and the selected
|
||||
codec. Existing `Heltec_tower_v2_repeater` firmware continues to use the
|
||||
internal-flash delta path and is unchanged.
|
||||
The BLM2 retained-auth SD-aware bootloader is mandatory for application OTA.
|
||||
`ota install` refuses to reboot if its continuity metadata does not match the
|
||||
running S140 family/FWID/application layout or if its capability marker does
|
||||
not advertise SD staging and the selected codec. Existing
|
||||
`Heltec_tower_v2_repeater` firmware continues to use the internal-flash delta
|
||||
path and is unchanged.
|
||||
|
||||
## Signed bootloader update
|
||||
|
||||
@@ -78,14 +85,15 @@ It requires an already installed exact-board ABI-3 OTAFIX bootloader whose one
|
||||
unambiguous capability marker is exactly `0x09` (`SD|BOOT_UPDATE`) and whose
|
||||
codec mask is `0x0005` (`FULL|INPLACE`). Requiring both application codecs
|
||||
prevents a bootloader self-update from disabling either normal SD application
|
||||
path. It cannot bootstrap a stock or older bootloader; provision that
|
||||
prerequisite once over USB/BLE DFU or SWD.
|
||||
path. A stock bootloader still requires USB/BLE DFU or SWD. The sole remote
|
||||
bootstrap is intentionally absent: preview.12 and any other legacy-v1 image
|
||||
must be upgraded locally before either SD application or bootloader OTA.
|
||||
|
||||
The signed v3 container is exactly 41,330 bytes and carries a 40 KiB candidate
|
||||
for the installed `239A0071 / TOWER_V2_OTA` identity (boot target `1150F50E`).
|
||||
It uses the same contiguous `/meshcore-ota.mota` file and sector-1 handoff as an
|
||||
application update. GPREGRET `0x6B` plus the distinct SD source marker `0x53`
|
||||
selects the bootloader path; LoRa transport remains payload type `0x0C`.
|
||||
It uses the same contiguous `/meshcore-ota.mota` file as an application update.
|
||||
GPREGRET `0x6B` plus the distinct SD source marker `0x53` selects the bootloader
|
||||
path; LoRa transport remains payload type `0x0C`.
|
||||
|
||||
The application linker still ends at `0xED000`, but OTAFIX needs
|
||||
`0xE0000..0xEA000` as temporary scratch while replacing itself. Before a boot
|
||||
@@ -102,17 +110,33 @@ EndF-inclusive running image and must end by `0xE0000`; an undersized or
|
||||
oversized record refuses the operation and requires local DFU/SWD.
|
||||
|
||||
Because the card is removable, approval is bound to the exact bytes that were
|
||||
authenticated. MeshCore verifies the signature and signer allowlist over one
|
||||
exact local manifest copy, requires the streamed manifest on SD to remain
|
||||
byte-identical, and verifies the complete payload against that manifest. It
|
||||
then writes `APRV` and syncs the card. Before publishing the raw-sector
|
||||
handoff, it writes and readback-verifies a temporary 64-byte `MOTASDBL` token
|
||||
at `0xE0000` containing the exact container length and that signed manifest's
|
||||
`image_hash`. OTAFIX requires the parsed SD manifest, streamed payload, and
|
||||
final scratch image to match the same token. Replacing or changing the card
|
||||
after verification can therefore only make the boot update fail; it cannot
|
||||
authorize different bootloader bytes. The token page becomes the first
|
||||
scratch page during a successful update and is not permanently reserved.
|
||||
authenticated. For both fmt2 application and fmt3 bootloader packages,
|
||||
MeshCore authenticates one exact signed manifest, requires every streamed
|
||||
manifest byte to match it, and verifies the leaves, payload, and image. During
|
||||
that same pass it hashes the entire container with only the mutable four-byte
|
||||
`APRV` field normalized to zero. After writing and syncing `APRV`, MeshCore
|
||||
publishes a 72-byte `MOTASDA2` record at reset-retained RAM address
|
||||
`0x20006008`. The record binds package purpose/format, exact LBA range, card
|
||||
size, container length, and that normalized SHA-256. OTAFIX consumes and clears
|
||||
the record before reading the card; changing the card or file can only fail.
|
||||
A power loss erases the authorization and also fails closed.
|
||||
|
||||
For fmt3, MeshCore additionally writes and readback-verifies the temporary
|
||||
64-byte `MOTASDBL` token at `0xE0000`, binding the exact total and signed
|
||||
manifest `image_hash`. OTAFIX requires the parsed manifest, streamed payload,
|
||||
and final scratch image to match it. The token page becomes scratch during a
|
||||
successful boot update and is not permanently reserved.
|
||||
|
||||
Every new candidate also carries a backward-compatible `BLM2`/`SOFT`
|
||||
continuity extension next to its legacy embedded manifest. The complete
|
||||
76-byte envelope is fixed at final raw-image offset `0x9FB4`; a relocated copy
|
||||
is not a valid candidate. Its embedded
|
||||
bootloader version must equal the outer package version, match the runtime
|
||||
SoftDevice family/FWID, application base, and layout ABI, and be strictly newer
|
||||
than an installed BLM2 version. Preview values use low bytes `1..254` and a
|
||||
stable release uses `0xFF`; zero-preview and all-ones versions are invalid.
|
||||
Remote bootloader rollback is not supported; use local DFU/SWD when rollback
|
||||
or migration is intentional.
|
||||
|
||||
Bootloader packages are never autofetched or autoinstalled. Select and confirm
|
||||
one exact package manually:
|
||||
@@ -235,9 +259,9 @@ clean replacement instead of treating path existence as a valid cache hit.
|
||||
To prepare and load the card:
|
||||
|
||||
1. Format it as described under [Card requirements](#card-requirements). The
|
||||
easiest way to guarantee the expected layout is to insert it in the
|
||||
repeater, run `set sdcard format`, power the repeater off, and then move the
|
||||
card to the computer. Formatting destroys the existing card contents.
|
||||
easiest route is to insert it in the repeater, run `set sdcard format`, power
|
||||
the repeater off, and then move the card to the computer. Formatting destroys
|
||||
the existing card contents.
|
||||
2. Mount the card on the computer and create a directory named `mota` at the
|
||||
filesystem root. Do not use a nested directory such as `/firmware/mota`.
|
||||
3. Run `motatool verify FILE.mota` for every source file. Do not copy a file
|
||||
|
||||
@@ -2,9 +2,10 @@
|
||||
|
||||
Selected nRF52840 repeater LoRa-OTA builds can replace their matching OTAFIX
|
||||
bootloader without replacing the running application. This is a privileged
|
||||
maintenance path, not a normal firmware update. It cannot bootstrap a stock or
|
||||
older bootloader: install the exact ABI-3 self-update-capable OTAFIX build once
|
||||
over USB/BLE DFU or SWD.
|
||||
maintenance path, not a normal firmware update. A stock bootloader must first
|
||||
be replaced with the exact ABI-3 self-update-capable OTAFIX build over USB/BLE
|
||||
DFU or SWD. MeshTower SD also requires the BLM2 retained-auth version to be
|
||||
provisioned locally before either application or bootloader OTA.
|
||||
|
||||
## Storage layouts
|
||||
|
||||
@@ -28,17 +29,29 @@ replace `0xF4000..0xFE000`. The application linker remains at `0xED000`; a
|
||||
future application extending above `0xE0000` can still use application mOTA
|
||||
but must update its bootloader through local DFU/SWD.
|
||||
|
||||
The removable SD authorization is fail-closed. MeshCore directly authenticates
|
||||
one exact manifest, requires the streamed manifest on SD to remain
|
||||
byte-identical, and verifies its complete payload. After writing and syncing
|
||||
`APRV`, but before publishing the raw-sector handoff, it writes and
|
||||
readback-verifies a 64-byte `MOTASDBL` token at `0xE0000`. The token contains
|
||||
the exact container length and the authenticated signed manifest's
|
||||
`image_hash`. OTAFIX requires that same hash in the parsed manifest, the
|
||||
streamed raw payload, and the final scratch image. A card swap or mutation
|
||||
after application verification therefore causes refusal rather than
|
||||
authorizing different bytes; the token page is consumed as scratch during a
|
||||
successful update and is not a permanent reservation.
|
||||
The removable SD authorization is fail-closed for both application and
|
||||
bootloader packages. MeshCore directly authenticates one exact signed
|
||||
manifest, requires the streamed copy to remain byte-identical, verifies all
|
||||
leaves/payload/image bytes, and computes a normalized full-container SHA-256 in
|
||||
that same pass (`APRV` bytes are treated as zero). After syncing `APRV`, it
|
||||
publishes a 72-byte `MOTASDA2` record in reset-retained RAM at `0x20006008`.
|
||||
That record binds purpose/format, first LBA, sector count, total length, card
|
||||
sector count, and the normalized digest. OTAFIX copies, validates, and clears
|
||||
the record before SD access. A card swap/mutation or a power cycle therefore
|
||||
fails closed; there is no general sector-1 ownership inference.
|
||||
|
||||
For fmt3, MeshCore also writes and readback-verifies a 64-byte `MOTASDBL` token
|
||||
at `0xE0000`. That token contains the exact container length and the exact
|
||||
authenticated signed manifest `image_hash`. OTAFIX requires the same hash in
|
||||
the parsed manifest, streamed payload, and final scratch image. The page is
|
||||
consumed as scratch during success and is not permanently reserved.
|
||||
|
||||
The first BLM2-capable MeshTower bootloader cannot be delivered to preview.12
|
||||
through the retained-RAM protocol that preview.12 predates. MeshCore does not
|
||||
write a raw-sector compatibility record because a blank sector is not proof of
|
||||
ownership. Upgrade preview.12 through USB/BLE DFU or SWD. Both fmt2 application
|
||||
and fmt3 bootloader OTA then require the installed BLM2 metadata to match the
|
||||
live SoftDevice/application layout; neither MeshCore nor OTAFIX uses sector 1.
|
||||
|
||||
The internal path does not change the application linker or permanently set
|
||||
aside separate app-OTA, boot-package, and scratch regions. The ordinary
|
||||
@@ -105,6 +118,30 @@ duplicates and collisions with application target IDs. Generic image parsing
|
||||
can inspect a future canonical identity, but signing/building a package fails
|
||||
until that exact identity is in the qualified inventory.
|
||||
|
||||
## Embedded continuity and version policy
|
||||
|
||||
Every remotely supplied successor retains the legacy 44-byte CRC-valid `BLMF`
|
||||
v1 record for identity continuity and diagnostics. Immediately after that
|
||||
record is a 32-byte `BLM2`/`SOFT` extension. The complete 76-byte envelope is
|
||||
fixed at the final raw-image offset `0x9FB4`; relocated candidates are refused,
|
||||
while installed legacy-v1 discovery remains a generic diagnostic scan. The extension carries the actual packed
|
||||
bootloader version, SoftDevice family and FWID, application base, layout ABI,
|
||||
and zero compatibility/reserved fields; the legacy whole-image CRC covers the
|
||||
extension too. Scanners first count CRC-valid 44-byte base manifests, then
|
||||
interpret continuity only after one base identity remains. A malformed claimed
|
||||
extension therefore cannot make a duplicate identity disappear, and a sole
|
||||
half-present extension is rejected rather than treated as legacy.
|
||||
|
||||
MeshCore requires the candidate extension, exact equality between its embedded
|
||||
version and the signed outer mOTA version, and exact agreement with the running
|
||||
SoftDevice family/FWID/application layout. Qualified internal/QSPI paths may
|
||||
bootstrap a CRC-valid installed legacy-v1 image once; the SD path never does
|
||||
and requires local BLM2 provisioning. Once the installed bootloader has BLM2
|
||||
metadata, the candidate version must be strictly greater. Preview low bytes are `1..254`, a
|
||||
stable release uses `0xFF`, and low-byte zero or all-ones values are rejected.
|
||||
There is no remote rollback/migration override; intentional rollback uses
|
||||
USB/BLE DFU or SWD.
|
||||
|
||||
The `no_external_sensors` profiles omit optional/add-on sensor and GPS packages
|
||||
to preserve flash headroom. Board-integrated GPS can be retained by a board's
|
||||
recipe. The RAK3401 lean target specifically omits RAK12501/add-on GPS; use the
|
||||
@@ -156,9 +193,12 @@ Before writing `APRV`, the application authenticates and authorizes the
|
||||
package: exact v3 geometry, trusted Ed25519 signer, signed/embedded identity,
|
||||
one unambiguous capability marker, embedded CRC, sane vectors, complete
|
||||
Merkle/payload/image hashes, storage-specific safe live placement, and the
|
||||
typed MID/hash confirmation. On SD, `APRV` and the internal signed-image-hash
|
||||
token are synced and read back before the handoff becomes visible. OTAFIX consumes that application-written
|
||||
authorization and then
|
||||
typed MID/hash confirmation. The manifest root and target inside the received
|
||||
manifest must also equal the MID/target that opened the fetch before any store
|
||||
is allocated. On SD, `APRV`, the retained geometry/container authorization,
|
||||
and the internal signed-image-hash token are published in that order before
|
||||
the reset trigger. OTAFIX consumes that application-written authorization and
|
||||
then
|
||||
independently rechecks the safety/integrity subset: strict v3 structure,
|
||||
canonical identity/capabilities, vectors, full payload SHA, embedded manifest
|
||||
CRC, the applicable live `EndF`/bank-settings no-overlap geometry, the SD token
|
||||
@@ -173,13 +213,13 @@ headroom is insufficient, an unsupported external/ExtraFS role owns the target,
|
||||
the exact installed capability marker is absent or ambiguous, identity cannot be derived
|
||||
unambiguously, or any package check fails. Before the storage-specific
|
||||
scratch/copy step, the application and bootloader are unchanged. OTAFIX
|
||||
consumes the trigger and, for internal/QSPI storage, clears approval before its
|
||||
first scratch erase, so an interrupted operation cannot retry a partly
|
||||
consumed package. The SD backend cannot rewrite raw card sectors: its `APRV`
|
||||
and checksummed handoff may persist, but the one-shot GPREGRET trigger is
|
||||
consumed before validation and they remain inert unless the running app again
|
||||
authenticates and explicitly re-arms that package. Use USB/BLE DFU or SWD for
|
||||
initial provisioning and local recovery.
|
||||
consumes the trigger and authorization before its first destructive action, so
|
||||
an interrupted operation cannot automatically retry a partly consumed
|
||||
package. On SD, the retained-RAM authorization is zero-consumed before media
|
||||
access; `APRV` and the fmt3 flash token may persist but are inert without a new
|
||||
explicit authenticated re-arm and reset trigger. No SD raw-sector handoff is
|
||||
created or consumed.
|
||||
Use USB/BLE DFU or SWD for initial provisioning and local recovery.
|
||||
|
||||
For XIAO and ordinary external-QSPI details, see
|
||||
[nRF52 repeater LoRa OTA with external QSPI](ota_nrf52_qspi.md).
|
||||
@@ -212,9 +212,13 @@ The final command must reproduce both the complete staged manifest ID and the
|
||||
first eight bytes of its signed image hash. Before approval the application
|
||||
again checks package/root/payload/image hashes, Ed25519 signature and trusted
|
||||
allowlist, exact signed `XIAO_BL_...` ID, installed and incoming embedded
|
||||
manifest/CRC/name/board identity, vector table, and ABI-3 QSPI+boot-update
|
||||
continuity. A signed older bootloader that would remove remote update support
|
||||
is refused.
|
||||
manifest/CRC/name/board identity, vector table, ABI-3 QSPI+boot-update marker,
|
||||
and the adjacent CRC-covered `BLM2`/`SOFT` continuity extension at the exact
|
||||
final-image offset `0x9FB4`. The embedded
|
||||
boot version must equal the signed outer package version, the SoftDevice
|
||||
family/FWID/application base/layout ABI must match the running platform, and
|
||||
a successor to installed BLM2 must be strictly newer. Low-byte-zero and
|
||||
all-ones versions are invalid. Remote rollback is refused; use local DFU/SWD.
|
||||
|
||||
After the reply drains, GPREGRET `0x6B` and GPREGRET2 `0x51` enter the special
|
||||
OTAFIX path. `APRV` carries the app's signature/allowlist and explicit operator
|
||||
|
||||
+44
-12
@@ -271,14 +271,25 @@ A v3 bootloader package has a deliberately narrow, non-extensible profile:
|
||||
- signed `hw_id` exactly `XIAO_BL_28860044`/`XIAO_BL_28860045` for deployed XIAO, or the zero-padded
|
||||
32-byte `NRF_BL_<BOARD_ID>_<DEVICE_NAME>` for a generic target;
|
||||
- a sane nRF52840 vector table, exactly one CRC-valid embedded manifest v1 with the exact board/name pair,
|
||||
followed by the required CRC-covered `BLM2`/`SOFT` continuity extension (embedded boot version,
|
||||
SoftDevice family/FWID, application base, and layout ABI), with that complete 76-byte envelope at the
|
||||
canonical final-image offset `0x9FB4`,
|
||||
and exactly one `MOTABLDR` marker advertising ABI >= 3, both application codecs (`FULL|INPLACE`, mask
|
||||
`0x0005`), boot-update continuity, and the exact storage flags for the application layout (`0x09`
|
||||
MeshTower V2 SD, `0x0E` XIAO QSPI, or `0x0A` shared internal staging).
|
||||
|
||||
The incoming embedded identity must exactly match the installed CRC-valid bootloader identity. Both scans
|
||||
consider every aligned structurally valid candidate so magic bytes in a literal pool cannot shadow the real
|
||||
manifest. A package must be signed by a key already in the device's trusted allowlist; unlike ordinary
|
||||
manifest. Duplicate accounting counts each CRC-valid 44-byte base record before interpreting adjacent
|
||||
continuity metadata, so a corrupt or half-present `BLM2` extension cannot hide a second identity; after
|
||||
exactly one base record is selected, malformed claimed continuity fails closed. A package must be signed by
|
||||
a key already in the device's trusted allowlist; unlike ordinary
|
||||
application packages, there is no unsigned manual-install exception.
|
||||
The signed outer `fw_version` must equal the embedded boot version. Qualified internal/QSPI targets may
|
||||
bootstrap a CRC-valid legacy-v1 installed bootloader once; MeshTower SD instead requires local BLM2
|
||||
provisioning because it has no safe legacy media handoff. After bootstrap every remote successor must be strictly newer and match the live
|
||||
SoftDevice/application layout. Low-byte zero and all-ones boot versions are invalid. Remote rollback has no
|
||||
override and must use local DFU/SWD.
|
||||
|
||||
---
|
||||
|
||||
@@ -360,7 +371,13 @@ There is no separate availability structure. **Block `i` is present <=> `leaves[
|
||||
the staged container after a reboot - re-parse the stored manifest, recompute geometry, count present
|
||||
blocks, continue fetching the holes (or jump straight to COMPLETE). The checkpoint cadence (persist progress
|
||||
every N committed blocks) is runtime-tunable (`ota config checkpoint <N>`, 0 = only finalized containers
|
||||
resume). Stores keep `leaves[]` in RAM until flush and never auto-GC, preserving resumable progress.
|
||||
resume). Boot-time adoption is an automatic fetch decision: current `autofetch` must be enabled, the stored
|
||||
target must equal the node target, policy `signed` requires the signed bit, and an enabled running-version
|
||||
floor requires a strictly newer manifest. An explicit MID pull may deliberately resume an older or unsigned
|
||||
package and keeps target `0` as a MID-only wildcard. Stores keep `leaves[]` in RAM until flush and never
|
||||
auto-GC, preserving resumable progress. The debug/operator equivalent is `ota dev resume <MID8>`; after a
|
||||
reboot the MID is mandatory, while a no-argument form may only reuse a still-active session MID. It never
|
||||
uses the `nullptr` automatic-adoption path, so a malformed MID or no active MID fails closed.
|
||||
|
||||
**Flash-store note (RX-safe writes):** a flash page-erase halts the CPU (~85 ms on nRF52) and starves LoRa
|
||||
RX, so the flash stores (`OtaStoreFlashNrf52`/`OtaStoreFlashEsp32`) **coalesce writes to the erase unit**
|
||||
@@ -494,6 +511,11 @@ fetcher server (any node that has the mid)
|
||||
when all blocks present: verify full merkle_root + image_hash -> COMPLETE
|
||||
```
|
||||
|
||||
Before allocating or writing the selected store, the receiver parses the reassembled manifest and requires
|
||||
its `merkle_root` to equal the requested/wire `manifest_id` and its `target_id` to equal the catalog or
|
||||
explicit-pull target that opened the receive slot. The wire envelope and HAVE row are advisory; they cannot
|
||||
label and stage a different manifest.
|
||||
|
||||
### 8.4 Message bodies (transfer)
|
||||
|
||||
All offsets after the 1-byte type. Encoders/decoders in `OtaProtocol.cpp`; constants in `OtaManager.h`.
|
||||
@@ -630,8 +652,13 @@ transmission per hop.
|
||||
independent of signature.
|
||||
- **Signing & allowlist:** a node keeps a runtime allowlist of trusted Ed25519 signer pubkeys (none embedded
|
||||
in firmware; `ota key add/list/rm`). A `.mota` is eligible for **auto-install** only if signed by an
|
||||
allowlisted key, the signature verifies, and `image_hash` matches. Manual install permits unsigned packages,
|
||||
allowlisted key, the signature verifies, `image_hash` matches, and its nonzero signed `fw_version` is
|
||||
strictly greater than the running hash-valid EndF version. Both catalog admission and final automatic
|
||||
apply enforce the version floor, so a lying HAVE row cannot bypass it. Manual `ota install` is the explicit
|
||||
equal-version/rollback override and generally permits unsigned packages,
|
||||
but a package that claims to be signed must have a valid signature from an allowlisted key or it is rejected.
|
||||
The removable-SD target is stricter: every application install needs a valid allowlisted signature because
|
||||
the app mints an authenticated one-reset media authorization for OTAFIX.
|
||||
**Transfer needs no trust** - blocks are content-addressed against the manifest's merkle root.
|
||||
- **Policies (persisted):** `autofetch` in {off, any, signed} (default off) gates automatic block fetching of
|
||||
own-target adverts; `autoinstall` in {off, trusted} (default off) gates auto-apply of a COMPLETE signed +
|
||||
@@ -783,7 +810,7 @@ ota qspi | storage QSPI nRF52 only: JEDEC/SR1/stage/latched stor
|
||||
ota folder | fold [on|off] attach/detach an external .mota folder (host daemon) ; bare = list
|
||||
ota config | cfg | set [autofetch|autoinstall|checkpoint] ... show/set persisted policy
|
||||
ota key | keys [add|rm <hex>] trusted signer allowlist ; bare = list
|
||||
ota dev ... bring-up helpers (stage/recv/serve/verify)
|
||||
ota dev ... bring-up helpers (stage/recv/serve/resume <MID8>/verify)
|
||||
```
|
||||
|
||||
---
|
||||
@@ -840,22 +867,27 @@ ota dev ... bring-up helpers (stage/recv/serve/verify)
|
||||
Internal-bootloader-self-update builds are a stricter exception: because their ordinary linker may extend
|
||||
through `0xED000`, an absent/corrupt live `EndF` disables every internal staging pull before erase instead
|
||||
of trusting the legacy 608 KiB estimate.
|
||||
- **MeshTower V2 SD nRF52:** the application stores a contiguous `/meshcore-ota.mota` on microSD and
|
||||
publishes its raw sector range in a checksummed handoff record outside the MBR partition. The matching
|
||||
bootloader reads the card without mounting FAT, supports either a full image or an in-place delta,
|
||||
- **MeshTower V2 SD nRF52:** the application stores a contiguous `/meshcore-ota.mota` on microSD. After
|
||||
authenticating one exact signed manifest and verifying the leaves/payload/image, it hashes the exact full
|
||||
container with only `APRV` normalized to zero and publishes a 72-byte reset-retained `MOTASDA2` record.
|
||||
That record binds app-vs-boot purpose, format, raw sector range, total/card geometry, and normalized digest;
|
||||
OTAFIX consumes and clears it before reading the card. There is no normal sector-1 handoff or additional
|
||||
OTA-specific partition-layout requirement beyond what the bundled SdFat can mount. The matching
|
||||
bootloader reads the authorized sectors without mounting FAT, supports either a full image or an in-place delta,
|
||||
verifies the staged/full result hash, and never writes through `0xED000` where InternalFS begins. The
|
||||
exact SD repeater also accepts a manually selected, signed v3 bootloader package when installed and
|
||||
candidate markers are exactly `0x09` (`SD|BOOT_UPDATE`). MeshCore streams the same strict identity,
|
||||
CRC, vector, signature, MID/hash-confirmation, and complete-image checks from the SD file. GPREGRET
|
||||
`0x6B` plus GPREGRET2 `0x53` selects this privileged path. Both MeshCore and OTAFIX require a hash-valid
|
||||
live `EndF` ending by `0xE0000`; when a nonzero boot-settings bank CRC is active, its recorded size must
|
||||
also cover that complete live image and stop by `0xE0000`. MeshCore authenticates one exact manifest,
|
||||
verifies the streamed SD copy is byte-identical, writes and syncs `APRV`, then writes a readback-checked
|
||||
`MOTASDBL` token at `0xE0000` containing the exact total and signed `image_hash` before publishing the
|
||||
raw-sector handoff. OTAFIX binds the parsed manifest, streamed payload, and final scratch image to that
|
||||
also cover that complete live image and stop by `0xE0000`. For fmt3 MeshCore additionally writes a readback-checked
|
||||
`MOTASDBL` token at `0xE0000` containing the exact total and signed `image_hash`. OTAFIX binds the parsed manifest,
|
||||
streamed payload, and final scratch image to that
|
||||
token, so a removable-media change can only fail closed. OTAFIX then uses `0xE0000..0xEA000` as temporary scratch; the normal
|
||||
application linker remains at `0xED000` and ordinary application updates do not inherit this scratch
|
||||
headroom restriction.
|
||||
headroom restriction. Both fmt2 application apply and fmt3 bootloader apply require installed BLM2
|
||||
continuity matching the live S140 FWID/application layout. Preview.12 must be upgraded locally over
|
||||
USB/BLE DFU or SWD. MeshCore never writes a raw sector-1 handoff.
|
||||
- **Matched external-QSPI nRF52 repeaters:** the application reserves the board's dedicated QSPI NOR as a
|
||||
raw store beginning at offset zero. It obtains a 1-16 MiB capacity from JEDEC, checkpoints payload before
|
||||
leaf metadata, and verifies each erased/programmed page. GPREGRET2 `0x51` selects QSPI only when the
|
||||
|
||||
+36
-14
@@ -211,8 +211,11 @@ ota install
|
||||
|
||||
The node verifies the firmware one last time, and if everything checks out it installs it and **reboots
|
||||
into the new version**. If the check fails, it tells you why and does **not** install. Unsigned images
|
||||
install only through this explicit command. A signed image whose signer is not in the device allowlist is
|
||||
rejected; trusted signed images can auto-install only when that policy is enabled.
|
||||
normally install only through this explicit command. The MeshTower V2 SD target is stricter and requires an
|
||||
allowlisted signature even for a manual application install, because it authorizes removable-media bytes for
|
||||
the bootloader. A signed image whose signer is not in the device allowlist is rejected; trusted signed images
|
||||
can auto-install only when that policy is enabled and the signed version is strictly newer than the running
|
||||
hash-valid EndF version. Manual `ota install` remains the deliberate equal-version/rollback override.
|
||||
|
||||
After it reboots, run `ota status` to confirm the new version.
|
||||
|
||||
@@ -246,10 +249,13 @@ Copy both confirmation values exactly from the second `ota bootloader` reply.
|
||||
Ordinary `ota install` deliberately refuses this package. The privileged
|
||||
command requires an exact 40 KiB candidate payload in the fixed 41,330-byte
|
||||
container, a valid exact embedded identity/CRC and vector table, continued
|
||||
boot-update support, and a valid signature from a key already in `ota key`'s
|
||||
trusted allowlist. It preserves the running application while OTAFIX replaces
|
||||
itself; `blup:C8` in post-reboot `ota status` means success. Any node lacking
|
||||
this command or those capabilities must update its bootloader locally instead.
|
||||
boot-update support, required `BLM2`/`SOFT` continuity metadata at canonical
|
||||
raw-image offset `0x9FB4`, a boot version
|
||||
that exactly matches the package and is newer than installed BLM2, and a valid
|
||||
signature from a key already in `ota key`'s trusted allowlist. It preserves the
|
||||
running application while OTAFIX replaces itself; `blup:C8` in post-reboot
|
||||
`ota status` means success. Remote rollback is refused. Any node lacking this
|
||||
command or those capabilities must update its bootloader locally instead.
|
||||
|
||||
On an internal-flash target, the package shares the ordinary store below
|
||||
`0xED000` and bottom-aligns at `0xE2000`; there is no separate reserved scratch
|
||||
@@ -260,9 +266,14 @@ On the MeshTower V2 SD target, the application linker remains at `0xED000`, but
|
||||
bootloader replacement needs temporary scratch beginning at `0xE0000`. A
|
||||
hash-valid live `EndF` must therefore prove the complete current image ends by
|
||||
`0xE0000`. A CRC-bound boot-settings bank must cover that complete image while
|
||||
also ending by `0xE0000`. MeshCore binds approval to the exact authenticated
|
||||
signed image hash in an internal token before handing the removable SD card to
|
||||
OTAFIX, so a later card change fails instead of authorizing different bytes.
|
||||
also ending by `0xE0000`. MeshCore binds both application and bootloader SD
|
||||
approval to purpose, exact raw geometry, and a normalized SHA-256 in a
|
||||
reset-retained `MOTASDA2` record. Boot updates also bind the exact authenticated
|
||||
signed image hash in the E0000 token. OTAFIX consumes the retained record before
|
||||
media access, so a later card change or power cycle fails instead of authorizing
|
||||
different bytes. MeshCore never claims or writes raw sector 1. Both application
|
||||
and bootloader OTA wait until a matching BLM2 bootloader has been provisioned
|
||||
locally; preview.12 requires USB/BLE DFU or SWD first.
|
||||
Larger applications can continue to use normal application mOTA;
|
||||
only bootloader self-update is refused.
|
||||
See [the nRF52 bootloader-update guide](ota_nrf52_bootloader_update.md) for the
|
||||
@@ -309,7 +320,7 @@ ota config autofetch any # auto-DOWNLOAD any compatible update for this n
|
||||
ota config autofetch signed # auto-download only signed updates
|
||||
ota config autofetch off # back to manual (default)
|
||||
|
||||
ota config autoinstall trusted # auto-INSTALL a downloaded update IF it's signed by a key you trust
|
||||
ota config autoinstall trusted # auto-INSTALL only a trusted signed version newer than the running EndF
|
||||
ota config autoinstall off # never auto-install (default)
|
||||
|
||||
ota config advert 1440 # re-advertise every N minutes while temp radio is running
|
||||
@@ -321,8 +332,18 @@ ota config hops 0 # only exchange OTA with directly-connected node
|
||||
ota config # show the current settings
|
||||
```
|
||||
|
||||
These policies also govern automatic adoption of an interrupted staged download after reboot. `off` leaves
|
||||
it untouched, `signed` requires the stored manifest's signed flag, and automatic resume requires the stored
|
||||
target to match this node and its version to be newer than the running valid EndF. Reissuing an explicit
|
||||
`ota pull <MID8>` remains the deliberate override for an older or unsigned partial.
|
||||
For bring-up/debugging, `ota dev resume <MID8>` performs the same explicit MID-bound re-adoption without
|
||||
starting a new network fetch. After reboot it requires the MID; bare `ota dev resume` is accepted only while
|
||||
an active/requested session MID still exists, and malformed or missing identifiers are rejected.
|
||||
|
||||
Recommended for most people: leave both **off** and update by hand. Use `autoinstall trusted` only once
|
||||
you've added the signer's key (next section) and you trust them to push updates unattended.
|
||||
you've added the signer's key (next section) and you trust them to push updates unattended. Automatic
|
||||
admission and final apply both reject zero, equal, or older signed versions; a dishonest catalog version
|
||||
cannot bypass the manifest check. Use manual `ota pull` plus `ota install` for an intentional rollback.
|
||||
|
||||
The MeshTower V2 SD OTA target has a separate, default-on **archive** policy. It saves all mOTAs it sees
|
||||
to the SD card so the repeater can seed them later; this does not install them and does not change the
|
||||
@@ -345,9 +366,10 @@ ota key list # show trusted signers
|
||||
ota key rm <public-key-hex> # stop trusting one
|
||||
```
|
||||
|
||||
Only updates signed by a trusted key are eligible for auto-install. Manual `ota install` permits an unsigned
|
||||
package after all integrity, hardware, base, and bootloader checks pass. A signed package whose signer is not
|
||||
in the device allowlist is rejected rather than silently treated as unsigned.
|
||||
Only strictly newer updates signed by a trusted key are eligible for auto-install. Manual `ota install`
|
||||
permits an unsigned package after all integrity, hardware, base, and bootloader checks pass, except on the
|
||||
MeshTower V2 removable-SD path where all application installs must be signed and allowlisted. A signed
|
||||
package whose signer is not in the device allowlist is rejected rather than silently treated as unsigned.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in new issue
Block a user