MCUboot Trusted-Key Hash Provider: Qualify Output Length and Per-Image Identity
Accept a trusted-key hash provider only when its success result guarantees the correct image identity, a valid output length and fully initialized output bytes. A zero return code cannot substitute for those obligations. The provider is part of the authentication boundary, even when its implementation is small.
This guide pins MCUboot v2.2.0’s MCUBOOT_HW_KEY callback interface and caller. It addresses platform integration, not the separate image-tool choice between a public key and its hash. No device provisioning, secret access, fuse operation or callback test was performed.
1. Read the two meanings of the size parameter
The interface header defines image_index as the image being authenticated. The hash buffer is output. key_hash_size carries buffer capacity on entry and actual hash length on successful return. Zero indicates success; nonzero indicates failure.
Write both meanings into the platform specification. A provider must not treat the incoming value as permission to read that many bytes from any storage object, or leave it unchanged after producing fewer bytes while reporting success.
Define the approved digest representation and exact expected length for this build. That policy should identify the serialized public-key bytes and digest algorithm used for comparison. A human-readable fingerprint from another encoding is not an interchangeable trusted hash.
2. Trace what the caller actually consumes
In the hardware-key caller, MCUboot hashes the candidate public key, initializes the callback capacity from its local hash buffer, checks the callback status and passes the returned length into the hardened equality comparison.
Accordingly, integration review must establish the provider’s length and output guarantees. Do not infer that every invalid provider result is independently repaired by this caller. A successful storage read is also insufficient if the returned bytes belong to another image.
The scoped Zephyr key representation uses a mutable hardware-key slot. Retain the linked provider and validation path together; a source file with the expected function name is not proof that the production binary uses the intended implementation.
3. Define a fail-closed provider contract
The following is a proposed integration contract, not a claim that every upstream or vendor provider enforces it automatically.
| Condition | Required provider behavior |
|---|---|
| Known image index and valid trusted record | Return exactly the approved digest bytes and length |
| Insufficient output capacity | Fail without writing outside the supplied buffer |
| Unknown or unsupported image index | Fail; do not silently substitute another image’s identity |
| Missing, unreadable or malformed trusted record | Fail; do not manufacture a successful default digest |
| Zero, truncated or oversized record length | Reject under the approved full-digest policy |
| Partial storage read | Fail unless the complete validated record is obtained through the specified mechanism |
Require every byte counted in the successful output length to be initialized. Specify failure behavior for the size field and output buffer so tests can recognize partial results without ever using them for authentication.
If an existing platform deliberately uses a different digest-length policy, stop and review that contract and its security rationale separately. Do not silently reinterpret a short value as the complete expected identity.
4. Map image indexes to trusted identities
The hardware-key design assigns trusted-hash retrieval to the platform. The image-supplied public key is checked against that independent value before signature verification.
Create a mapping table for every supported image index: component purpose, trusted-record identifier, public fingerprint, digest encoding, owning provisioning policy and expected failure mode. Use public or sanitized identifiers only.
Make intentional shared identities explicit. Two components may share an approved signer, but an accidental “always read record zero” implementation should not pass merely because the first test image works. Test distinct synthetic identities when exercising index routing.
5. Qualify the provider before end-to-end boot tests
Begin with an isolated provider harness using synthetic public hashes and a mock trusted-storage interface. Place guard regions around its output buffer and vary the input capacity. The goal is to observe the provider contract without touching real trust storage.
| Proposed fixture | Evidence to retain |
|---|---|
| Exact required capacity and valid record | Status, exact length, complete byte equality and unchanged guards |
| Capacity one byte too small | Failure and no out-of-bounds write |
| Two indexes with different synthetic hashes | Correct routing for both, including reversed call order |
| Unknown index | Explicit failure rather than fallback identity |
| Read error or partial result | No successful authentication input returned |
| Malformed stored length | Rejection before trusting the output extent |
These fixtures are proposed and unexecuted. A host harness can establish the behavior of its tested provider implementation and mocks; it cannot establish hardware access control, persistence or resistance to physical manipulation.
Then qualify the actual integration with an approved positive image and a correctly formed image signed by a different authorized test identity. Attribute rejection to trusted-key comparison and signature policy, rather than an earlier format or version failure.
Hypothetical component-index mix-up
A fictional product has two independently authorized components. The provider’s first-image test passes, but its routing table returns the first component’s trusted hash for both indexes. The second image fails despite valid signing and packaging.
The correct diagnosis is a provider identity-routing mismatch. Changing the second image to match the mistakenly returned identity would conceal the defect and alter the intended authorization boundary. Fix and requalify the mapping through the approved process.
6. Approve the exact implementation and limits
Retain the provider source revision, linked binary identity, digest representation, index map and observed fixture results. Treat upstream revision changes or platform-storage substitutions as reasons to revisit the interface contract.
This review can identify missing evidence without alleging a deployed-device vulnerability. A product-security claim still needs platform-specific trust-storage and lifecycle evidence. The immediate deliverable is a precise, testable callback contract with explicit failure behavior.
