Validate manifest channel, version floor, upgrade path, file paths and hashes #55

Summary

Reject manifests whose channel, version, upgrade path or file list is not acceptable, and check file hashes.

Problem / intent

A signed manifest can still be for the wrong channel, older than the device, skip a required intermediate version or list paths that escape the staging directory.

Proposed solution

Before listed files are downloaded: match manifest channel, signing-certificate channel and target channel; enforce the version floor, blocklist and min_upgrade_from; reject absolute paths, .., duplicates after normalisation and anything outside staging. After download: compare each file's SHA-256; the first mismatch returns a non-final redownload result so the file is deleted and fetched once more, and only a second mismatch is rejected.

• Depends on: Persist per-channel update state atomically and resume after reboot #50, Verify detached CMS signatures against an on-device trust root and revocation list #54
• Can proceed in parallel with: Check the compatibility matrix at verification, at boot and after rollback #56, Periodic health checks with warm-up and application-supplied probes #59

Contract

Checks run in this order; the first failure stops and returns its code:

1. Signature (Verify detached CMS signatures against an on-device trust root and revocation list #54).

2. Channel: the manifest's channel, the channel of the signing certificate and the channel being updated must all match; otherwise rejected_channel.

3. Version and paths:

   • not below the version floor (Keep a version floor, a local blocklist and unacknowledged results #52), otherwise rejected_downgrade; a target equal to the current version needs no action;
   • not on the blocklist (Keep a version floor, a local blocklist and unacknowledged results #52), otherwise rejected_blacklisted;
   • when the manifest sets min_upgrade_from, the current version is at least that version, otherwise rejected_upgrade_path;
   • every listed path is a normalised relative path: not absolute, no .., no duplicates after normalisation, and inside the version's staging directory; otherwise rejected_manifest.

   Listed files are fetched (Poll target versions and download in stages with resume and backoff #53) only after steps 1 to 3 pass.

4. Hashes: after download, each file's SHA-256 must match the manifest. The first mismatch deletes that file and returns a non-final redownload result; a second mismatch gives rejected_hash.

5. Version matrix (Check the compatibility matrix at verification, at boot and after rollback #56); a failure gives rejected_incompatible.

• Writes and extraction never follow symbolic links out of the staging directory.
• A rejection leaves the current version untouched, and nothing is switched.

Manifest fields read:

• Open: which fields of a model artifact's manifest carry its channel, version, files and required earlier version.

• Base image: the version is the RAUC bundle manifest's version, min_upgrade_from sits in a custom meta section of that manifest, and RAUC's compatible value is compared for channel and hardware. Steps 2 and 3 run on it after RAUC has verified the bundle and before it is installed.

• Open: the custom meta section and key that hold min_upgrade_from in a RAUC bundle manifest, and where the expected compatible value comes from.

• Open: the result for a manifest with a missing field, or with a version that is not in MAJOR.MINOR.PATCH form.

Acceptance criteria

• Unit tests, one per code: rejected_channel, rejected_downgrade, rejected_blacklisted, rejected_upgrade_path, rejected_manifest and rejected_hash are each returned by a manifest that breaks only that rule
• Unit test: a channel mismatch between each pair of manifest, signing certificate and target channel gives rejected_channel
• Unit test: a target equal to the current version returns no result and starts nothing
• Unit tests for paths: an absolute path, a path with .., two paths equal after normalisation, and a path through a symbolic link that leaves the staging directory are each rejected with rejected_manifest
• Unit test against a fake server: when a check in steps 1 to 3 fails, no listed file is requested
• Unit test: one hash mismatch deletes the file and fetches it once more, and passes if the new copy matches; a second mismatch gives rejected_hash
• Unit test: a RAUC bundle manifest with a lower version, or with an unmet min_upgrade_from, is rejected before install
• No deployment-specific content (organisation, site, equipment model, point table, register map or data sample) in code, tests or docs
• make verify passes

Area

• area:update — Update channels, artifact delivery, atomic switch and rollback