RAUC Bundle Inspection and Installation: Bind Approval to the Manifest Hash

Save the manifest hash returned by inspection and pass that exact approved value into the later installation request. RAUC 1.14’s require-manifest-hash gate can reject a different manifest even when the replacement bundle is correctly signed and appears at the same path or URL.

This guide uses the 1.14 InspectBundle and InstallBundle D-Bus contract, with a verified verity bundle as the baseline. It does not use newer polling APIs or provide a live installation command. No bundle was signed, replaced or installed; the substitution cases are proposed qualification tests.

1. Identify what the approval is supposed to bind

A signature establishes acceptance under the configured trust policy. An operator may have reviewed a more specific release: particular images, compatibility data and hook declarations. If the distribution location changes between review and use, a different trusted release may otherwise satisfy signature verification.

The 1.14 reference documents info.manifest-hash as a string containing SHA256 over manifest content. The corresponding installation argument, args.require-manifest-hash, is also a string and compares the later bundle’s manifest with that expected value.

Make the approval record contain the returned manifest hash, reviewed metadata, target scope, approver or policy identity, approval revision and any validity conditions. Keep the transport locator separate. A renewed URL can refer to the same approved manifest; a reused URL can refer to a different one.

2. Preserve the returned hash rather than recreating it

Use the exact value from successful inspection. Do not hash the displayed release name, a selected subset of fields or a JSON rendering of the inspection response. The tagged manifest implementation computes the hash from manifest input content and exposes it through the inspection dictionary.

A client should validate that the required field is present and has the expected representation before offering approval. Missing, malformed or unsupported output is a failed inspection contract, not a reason to omit the later requirement.

Keep the reviewed information and hash in one immutable approval record. If the UI refreshes the metadata, it must not silently replace the stored hash while preserving an earlier approval. A newly inspected manifest requires the applicable new decision.

3. Carry the binding through installation admission

1. Inspect through the established RAUC interface with normal transport and bundle verification enabled.
2. Review the returned manifest information against the intended target and product policy.
3. Persist the approved manifest hash and associated conditions.
4. At dispatch, revalidate scheduling, target state and other current prerequisites.
5. Supply the stored hash as the string-valued require-manifest-hash argument.
6. Retain the actual installer result and distinguish it from later boot or health confirmation.

Do not omit the hash on retry, substitute a newly observed hash after mismatch, or turn a rejection into an automatic approval of the replacement. Return the operation to inspection and review when the intended artifact has changed.

Protect the approval record against unintended changes through the product’s existing access and integrity controls. A hash copied from an untrusted source is not an authorization decision.

4. Account for the exact plain-bundle limitation

In v1.14 do_install_bundle, normal bundle checking happens before the requested manifest comparison. A plain bundle is explicitly rejected when require-manifest-hash is supplied, because its manifest is not available at that point. A differing hash is also rejected before bundle mounting and later installation handlers.

Therefore, do not assume that successful inspection of a plain bundle means this installation-binding workflow supports it. Qualify the chosen format and deployed implementation before promising the feature. If a required deployment uses plain bundles, hold for a separately reviewed design instead of silently dropping the binding option.

This ordering describes the tagged implementation. It does not mean inspection or installation is a side-effect-free operation, or that no preparation happened before rejection. It identifies the specific hash gate’s place relative to bundle mounting and handlers.

5. Distinguish manifest identity from other identities

Identity	What it binds	Important limitation
Manifest hash	The manifest content inspected and later compared	Not a hash of the entire bundle or signature envelope
Whole-bundle digest	Exact distributed bundle bytes	Not the value expected by require-manifest-hash
Signer acceptance	Configured trust-policy decision	Still required independently of hash equality
Target eligibility	Current compatibility and product admission conditions	Can change after inspection even if the manifest is unchanged

Re-signing identical manifest content can preserve its manifest hash while changing the signature envelope. If approval specifically requires a particular signer or exact complete object, enforce that additional policy through a suitable reviewed mechanism. Do not describe manifest binding as enforcing every possible release identity.

Keep payload verification, compatibility checks and version restrictions enabled. A matching manifest hash does not authorize bypassing them, nor does it prove that the product will operate correctly after installation.

6. Qualify a correctly signed substitution

Prepare two non-sensitive, approved development bundles A and B with different manifest content. Both should be valid under the test trust policy so the negative case tests approval binding rather than an unrelated signature failure.

Test	Expected interpretation
Inspect A, approve A’s hash, install A	Hash gate permits continuation; other checks still decide outcome
Inspect A, replace locator content with B, require A’s hash	Reject manifest mismatch despite B’s valid signature
Matching hash but invalid signer	Normal trust validation must still reject
Plain bundle with required hash	Reject under the pinned 1.14 implementation
Inspection hash missing or unsupported argument	Fail the workflow rather than install unbound

Use a private fixture and recoverable development devices, with valuable data preserved. Do not replace an object in a shared production repository to run the test. Record exact artifacts, approval identity, error stage and absence of later installation-handler execution in the mismatch case.

Hypothetical changed release URL

An operator reviews bundle A at a release URL. Before dispatch, the publisher updates that URL to bundle B. Both are correctly signed. The stored A manifest hash makes the later request reject B instead of interpreting the old approval as permission for any trusted release.

The operator can then inspect B and decide whether to approve it. Keeping that decision explicit closes the inspection-to-install gap while preserving the independent trust and target checks the product still needs.