MCUboot Protected TLVs: Identify Which Metadata Is Covered by the Image Hash
Locate a metadata field by byte range before treating it as authenticated policy. In MCUboot, the protected TLV area participates in the image hash, while the following unprotected area contains verification material and other permitted records. “Unprotected” does not mean “ignored by validation,” and a familiar type identifier alone does not prove the field is inside the authenticated span.
This guide pins MCUboot v2.2.0. The worked profile is an ordinary unencrypted, uncompressed image using hash-then-sign verification. Pure-signature, encrypted, compressed and split-image configurations need their own trace. No image mutation or target validation was executed.
1. Map the actual image header fields
Read the generated image with a bounds-checked inspector using the exact release format. The tagged image header defines a 32-byte base structure, but ih_hdr_size gives the complete header span before the payload. Do not assume the payload always begins at byte 32.
Use H for that header span, I for ih_img_size, and P for ih_protect_tlv_size. For the scoped profile, the payload starts at H, protected metadata starts at H + I, and the hashed span ends at H + I + P.
Compute offsets relative to the image start, not blindly from the beginning of a whole flash partition. Transport containers and update-mode placement can add separate offsets. This article maps authentication coverage; it does not size slots or prescribe flash writes.
2. Include the protected area’s own header
The v2.2.0 design includes both the protected TLV information header and its entries in hash calculation. P is the complete protected area size, not just the sum of metadata values. When no protected area exists, P is zero.
| Region | Symbolic range | Coverage in this profile |
|---|---|---|
| Header span | 0 through H, end excluded | Included in image hash |
| Payload | H through H + I, end excluded | Included |
| Protected info header and entries | H + I through H + I + P, end excluded | Included when P is nonzero |
| Following unprotected TLV area | Begins at H + I + P | Outside this image-hash span; still parsed and checked |
The tagged header uses protected info magic 0x6908 and unprotected info magic 0x6907. Its TLV record header has a 16-bit type and 16-bit value length, both little-endian. Use that implementation definition rather than copying an older-looking 8-bit type layout from a documentation example.
3. Check structural agreement before policy meaning
In the tagged TLV iterator, a protected info header’s total must agree with the image header’s protected size. The iterator then expects the following unprotected information header. A nonzero protected size without the corresponding protected header is rejected by this initialization path.
For each inspected artifact, record H, I, P, both information-header locations and each entry’s type, value length and range. Check every addition and boundary against the actual available bytes before reading values. A custom inspector should never use an untrusted length to allocate or seek without a checked limit.
These checks establish a coherent layout; they do not establish authenticity or semantic validity. Keep malformed-layout rejection separate from signature failure when recording fixtures.
4. Explain why verification material can be outside the hash
The stored digest and signature cannot simply be assumed to authenticate themselves by appearing in a container. The verifier computes the covered image digest and checks the relevant records according to the compiled signing policy and trusted key source.
The v2.2.0 validation source performs those separate checks. It also restricts unprotected records to an allowlist when ALLOW_ROGUE_TLVS is not defined. The list includes verification and encryption-related record types; arbitrary policy metadata is not thereby permitted in the unprotected region.
Therefore changing an unprotected signature or hash record can still cause rejection. Conversely, a field being protected only means its bytes participate in the authenticated input when signature enforcement is correctly configured. The application or bootloader still needs to understand and enforce the field’s meaning.
5. Build a mutation matrix with distinct conclusions
| Proposed fixture | Expected evidence | Conclusion boundary |
|---|---|---|
| Approved image unchanged | Positive control passes intended verification | Baseline works |
| Protected metadata value changed; original digest retained | Hash mismatch | Covered-byte integrity is checked |
| Protected value and stored digest changed coherently; original signature retained | Required signature rejection | Authenticated policy bytes cannot be replaced merely by recomputing a digest |
| Protected size disagrees with its info header | Structural rejection | Layout consistency check is active |
| Policy record moved into unprotected area | Allowlist or policy validation rejects under the reviewed build | Location matters; type name alone is insufficient |
| Unprotected signature bytes changed | Signature validation rejects | Outside hash coverage does not mean unchecked |
Qualify the precise result for the compiled build. If an extension changes the unprotected allowlist or metadata interpretation, update the acceptance contract explicitly. Do not silently loosen validation to make a new record parse.
Hypothetical security-counter review
A release inspector displays a security-counter type and value, so a reviewer initially labels it authenticated. The byte map reveals the record was appended after the protected region rather than included inside it.
The corrected review requires the record in the intended protected location, valid structure, a matching covered digest and enforced signature verification. Separately, the configured rollback policy must consume that counter. Authenticating a value and enforcing a minimum value are different decisions.
6. Retain a coverage receipt
Deliver the exact image digest, MCUboot and image-tool revisions, compiled validation profile, symbolic/actual byte map and each fixture’s failure stage. Use only public artifact metadata in the receipt; no private keys are needed.
Run future tests on preserved copies or recoverable development devices, with original images retained. Recheck the coverage map whenever the tool, header span, metadata extensions or signing mode changes. A field list from an old release is not evidence of the new artifact’s authentication boundary.
