MCUboot Header Feature Admission: Check Encryption and Compression Flags Before Authentication

Check the image’s recognized feature flags against the exact loader build before interpreting a rejection as an authentication failure. MCUboot v2.2.0 has a header-admission gate that rejects unsupported encryption or compression features and certain contradictory flag pairs. Passing that gate only permits further processing.

This article examines boot_is_header_valid() in the tagged ordinary loader and the flag macros it uses. It does not supply a generic bootloader-upgrade sequence, approve a codec or prove that an admitted image can execute. All fixtures below are proposed source-level qualification cases; none was run.

1. Freeze the binary and header contract

Record the actual loader binary, resolved feature macros, relevant downstream patches, image header bytes and flash-area identity. Use final build evidence rather than an image producer’s settings: a producer can emit a feature the consumer does not implement.

Keep header interpretation separate from cryptographic policy. The feature flags identify processing needs; they do not identify an authorized signer or establish that the payload has the right meaning for the board.

The header function also checks image magic and checked size arithmetic before its feature tests. A fixture failing there never establishes the later feature decision. Preserve a valid structural baseline when testing flags.

2. Read the exact recognized masks

The image header definitions recognize encryption through the AES128 or AES256 flags. The compression mask includes LZMA1, LZMA2 and the ARM Thumb filter flag.

That last detail matters: a filter flag alone still counts as compressed for the disabled-feature gate. Do not write a consumer test that recognizes only the two codec bits and silently excludes the filter bit.

Use the source-defined constants from the pinned build in a later harness. Avoid unexplained numeric masks copied from another release. If a downstream format extends the flags, trace the extension and all consuming paths explicitly.

3. Build the feature-admission table

The following entries assume earlier structural checks pass. “Admitted here” means only that the scoped encryption/compression condition does not reject the header.

Feature configuration	Header condition	Scoped result
Encryption disabled	Either recognized encryption flag set	Reject
Encryption enabled	AES128 and AES256 both set	Reject contradictory pair
Encryption enabled	One encryption flag set	Admitted by this encryption condition
Decompression disabled	Any recognized compression-mask bit set	Reject, including filter-only
Decompression enabled	LZMA1 and LZMA2 both set	Reject contradictory pair
Decompression enabled	Only one codec bit, or filter-only	No rejection by the two-codec contradiction test

These outcomes follow the exact feature branches. Filter-only admission under enabled decompression is not evidence of a valid compressed representation. A required decoder, associated metadata or downstream processing can still fail.

The function is not a universal allowlist for every possible header bit. Do not generalize these recognized checks into a promise that all unknown flags are rejected. Qualification of a future extension needs the actual new format and consumer behavior.

4. Keep location-sensitive processing visible

The decompression-selection macro additionally checks whether the area is the relevant secondary image area. Therefore record which slot and image index a fixture represents; a flag alone does not establish that all later processing follows the same path.

Do not change several dimensions at once. Start with an unchanged area mapping and structural baseline, vary one flag condition, then separately evaluate the approved alternate location. Otherwise a different size or processing branch can mask the property being tested.

Likewise, do not interpret a copied primary image and a staged secondary image as interchangeable just because their displayed application versions match. Their packaging and transformation state may differ under the selected mode.

5. Design attributable fixtures

• Use a structurally valid unflagged baseline for each supported build configuration.
• Exercise each recognized encryption flag individually and together.
• Exercise each codec bit, the codec pair and the filter-only condition.
• Record the header-gate return before any later verification or decoding result.
• Repeat only the location-dependent cases needed by the product’s actual boot mode.

Use an isolated header harness or approved inert fixture environment. There is no need to execute deliberately malformed payloads, write live boot slots or change security settings merely to observe this predicate.

If a whole-boot test rejects before or after the header gate, keep that outcome distinct. A final “boot failed” message does not identify which condition was responsible. Any later on-device work requires preserved original artifacts, recoverable test equipment and its own authorization.

6. Require independent authentication evidence

The image-validation implementation has additional hash, signature and TLV processing. Header admission cannot stand in for those checks.

Similarly, authentic metadata does not establish that the chosen decoder can process the payload within resource limits, that a decryption provider is correctly integrated or that resulting code is suitable for the board. Keep separate report columns for header admission, authentication, transformation and final execution qualification.

Hypothetical feature mismatch

A fictional release pipeline emits a compression filter bit while targeting a loader built without decompression. Engineers initially suspect a signing problem because the device refuses the image. The source-derived matrix instead predicts rejection at the recognized-feature gate.

The useful next step is to reconcile the intended packaging and consumer capability through the approved release process, then repeat the relevant controls. Removing a signature requirement would not resolve the feature mismatch and is not part of this method.

7. Retain a versioned admission receipt

Save the binary identity, resolved macros, exact header condition, area context, observed gate result and later-stage evidence separately. Label missing execution results as untested. Revisit this receipt when updating the loader, changing feature configuration or extending the image format.

This produces a precise compatibility statement: a named build admits or rejects a named recognized-header condition at a named gate. It does not turn that limited result into a claim of complete image validity or safe boot.