From d084b1987ff8290e777292855b782c4ea2b30efc Mon Sep 17 00:00:00 2001 From: ShuaixinHuang <1836656514@qq.com> Date: Thu, 19 Nov 2026 02:03:10 +0800 Subject: [PATCH] fix(artifacts): verify Android OTA operation data hashes (#12043) --- docs/guides/firmware/android-ota-payload.md | 4 +- .../AndroidOtaPayloadArtifactReader.test.ts | 36 ++++++++ .../firmware/androidOtaPayload.fixture.ts | 3 + src/domain/firmware/androidOtaPayload.test.ts | 83 ++++++++++++++++++- src/domain/firmware/androidOtaPayload.ts | 32 ++++++- 5 files changed, 152 insertions(+), 6 deletions(-) diff --git a/docs/guides/firmware/android-ota-payload.md b/docs/guides/firmware/android-ota-payload.md index c1a6754440..227ec7f0bb 100644 --- a/docs/guides/firmware/android-ota-payload.md +++ b/docs/guides/firmware/android-ota-payload.md @@ -57,7 +57,9 @@ magic; zip inventory does not recurse into its partitions. A partition is reconstructed only when every install operation is REPLACE, ZERO or REPLACE_ZSTD (via `node:zlib` zstd), the new size is known and at -most 32 MiB, and every needed blob extent is present. The reconstructed +most 32 MiB, and every needed blob extent is present. When an operation +declares `data_sha256_hash`, REA checks its stored blob bytes before writing +or decompressing them. A mismatch prevents reconstruction. The reconstructed image is checked against `new_partition_info.hash` when that hash is present. Any other operation type leaves the occurrence inventoried with `hash_status: unavailable` and refuses extraction of that member. diff --git a/src/artifacts/AndroidOtaPayloadArtifactReader.test.ts b/src/artifacts/AndroidOtaPayloadArtifactReader.test.ts index 58ebdc8ee1..283e202569 100644 --- a/src/artifacts/AndroidOtaPayloadArtifactReader.test.ts +++ b/src/artifacts/AndroidOtaPayloadArtifactReader.test.ts @@ -340,3 +340,39 @@ it("applies the caller's integrity policy to a partition hash mismatch", async ( await resourceScope.close(); } }); + +it("checks the stored OTA operation bytes when a partition hash is absent", async () => { + const original = Buffer.from("BOOT"); + const dataHash = createHash("sha256").update(original).digest(); + for (const data of [original, Buffer.from("BOAT")]) { + const path = await writeCarrier( + "payload.bin", + buildAndroidOtaPayload({ + partitions: [ + { + name: "boot", + omitNewHash: true, + operations: [{ type: 0, data, dataHash }], + }, + ], + }), + ); + const reader = new AndroidOtaPayloadArtifactReader(path); + try { + for await (const entry of reader.entries()) { + expect(entry.path).toBe("boot.img"); + const opened = reader.open(entry).then(buffer); + if (data === original) { + expect((await opened).equals(original)).toBe(true); + } else { + await expect(opened).rejects.toMatchObject({ + reason: "integrity", + message: expect.stringContaining("operation 0"), + }); + } + } + } finally { + await reader.close(); + } + } +}); diff --git a/src/domain/firmware/androidOtaPayload.fixture.ts b/src/domain/firmware/androidOtaPayload.fixture.ts index d804d46b5e..eac70092b5 100644 --- a/src/domain/firmware/androidOtaPayload.fixture.ts +++ b/src/domain/firmware/androidOtaPayload.fixture.ts @@ -19,6 +19,7 @@ export interface AndroidOtaOperationFixture { readonly data?: Uint8Array; readonly dataOffset?: number; readonly dataLength?: number; + readonly dataHash?: Uint8Array; readonly dstExtents?: readonly AndroidOtaExtentFixture[]; readonly srcExtents?: readonly AndroidOtaExtentFixture[]; } @@ -183,6 +184,8 @@ const encodeOperation = ( encodeExtent(writer, extent); writer.join(); } + if (operation.dataHash !== undefined) + writer.tag(8, WireType.LengthDelimited).bytes(operation.dataHash); }; const encodePartition = ( diff --git a/src/domain/firmware/androidOtaPayload.test.ts b/src/domain/firmware/androidOtaPayload.test.ts index f5d17042b2..c11adda7b0 100644 --- a/src/domain/firmware/androidOtaPayload.test.ts +++ b/src/domain/firmware/androidOtaPayload.test.ts @@ -164,6 +164,7 @@ it("counts an unknown InstallOperation type as unknown", () => { it("reconstructs REPLACE_ZSTD payloads", () => { const plain = Buffer.from("zstd-partition-bytes"); + const compressed = zstdCompressSync(plain); const bytes = buildAndroidOtaPayload({ partitions: [ { @@ -171,7 +172,8 @@ it("reconstructs REPLACE_ZSTD payloads", () => { operations: [ { type: 14, - data: zstdCompressSync(plain), + data: compressed, + dataHash: createHash("sha256").update(compressed).digest(), dstExtents: [{ startBlock: 0, numBlocks: 1 }], }, ], @@ -235,6 +237,7 @@ it("refuses distinct operation data past the read budget as a capacity limit", ( typeName: "REPLACE", dataOffset: 0, dataLength: ANDROID_OTA_MAX_OPERATION_DATA_BYTES + 1, + dataHashHex: null, srcExtents: [], dstExtents: [{ startBlock: 0, numBlocks: 1 }], }, @@ -722,3 +725,81 @@ it("keeps duplicate partition naming linear at the partition count limit", () => `${name}-${String(ANDROID_OTA_MAX_PARTITIONS - 1)}.img`, ); }); + +it("treats empty operation digests as absent and rejects malformed lengths", () => { + const data = Buffer.from("BOOT"); + for (const dataHash of [Buffer.alloc(0), Buffer.alloc(31)]) { + const parsed = parse( + buildAndroidOtaPayload({ + partitions: [ + { + name: "boot", + omitNewHash: true, + operations: [{ type: 0, data, dataHash }], + }, + ], + }), + ); + if (dataHash.length === 0) { + expect(parsed).toMatchObject({ + ok: true, + value: { partitions: [{ operations: [{ dataHashHex: null }] }] }, + }); + } else { + expect(parsed).toMatchObject({ + ok: false, + error: { + message: expect.stringContaining( + "data_sha256_hash must be 32 bytes or empty", + ), + }, + }); + } + } +}); + +it("compares each digest claim when operation data is shared", () => { + const data = Buffer.alloc(4096, 0x42); + const expected = createHash("sha256").update(data).digest(); + const conflicting = Buffer.alloc(32); + const bytes = buildAndroidOtaPayload({ + partitions: [ + { + name: "boot", + newSize: 8192, + omitNewHash: true, + operations: [ + { type: 0, data, dataHash: expected }, + { + type: 0, + dataOffset: 0, + dataLength: data.length, + dataHash: conflicting, + dstExtents: [{ startBlock: 1, numBlocks: 1 }], + }, + ], + }, + ], + }); + const parsed = parse(bytes); + if (!parsed.ok) throw parsed.error; + const [partition] = parsed.value.partitions; + if (partition === undefined) throw new Error("Missing boot partition"); + const { blobOffset } = parsed.value.header; + const blob = bytes.subarray(blobOffset, blobOffset + data.length); + expect( + reconstructAndroidOtaPartition( + partition, + parsed.value.blockSize, + () => blob, + ), + ).toMatchObject({ + ok: false, + error: { + _tag: "AndroidOtaPayloadIntegrityFailure", + message: expect.stringContaining("operation 1"), + declaredHashHex: conflicting.toString("hex"), + observedHashHex: expected.toString("hex"), + }, + }); +}); diff --git a/src/domain/firmware/androidOtaPayload.ts b/src/domain/firmware/androidOtaPayload.ts index 783167b605..8266c0857c 100644 --- a/src/domain/firmware/androidOtaPayload.ts +++ b/src/domain/firmware/androidOtaPayload.ts @@ -217,6 +217,7 @@ export interface AndroidOtaInstallOperation { readonly typeName: string; readonly dataOffset: number; readonly dataLength: number; + readonly dataHashHex: string | null; readonly srcExtents: readonly AndroidOtaExtent[]; readonly dstExtents: readonly AndroidOtaExtent[]; } @@ -428,6 +429,7 @@ interface OperationDraft { typeCode: number; dataOffset: number; dataLength: number; + dataHashHex: string | null; srcExtents: ExtentDraft[]; dstExtents: ExtentDraft[]; } @@ -537,6 +539,7 @@ const decodeOperation = ( typeCode: 0, dataOffset: 0, dataLength: 0, + dataHashHex: null, srcExtents: [], dstExtents: [], }; @@ -569,6 +572,13 @@ const decodeOperation = ( ); return; } + if (field === 8 && wire === WireType.LengthDelimited) { + const digest = reader.bytes(); + if (digest.length !== 0 && digest.length !== 32) + fail(malformed("operation data_sha256_hash must be 32 bytes or empty")); + operation.dataHashHex = digest.length === 0 ? null : hex(digest); + return; + } reader.skip(wire); }); if (!walked.ok) return walked; @@ -1058,6 +1068,7 @@ export const parseAndroidOtaPayload = ( typeName: INSTALL_OPERATION_NAMES[operation.typeCode] ?? "unknown", dataOffset: operation.dataOffset, dataLength: operation.dataLength, + dataHashHex: operation.dataHashHex, srcExtents: operation.srcExtents.map((extent) => ({ startBlock: extent.startBlock, numBlocks: extent.numBlocks, @@ -1393,9 +1404,9 @@ const hasCompleteExtentCoverage = ( }; /** - * Rebuild a full-payload partition image. A declared-hash mismatch fails - * unless `verifyDeclaredHash` is false, which leaves that decision to a caller - * that applies its own integrity policy to the returned bytes. + * Rebuild a full-payload partition image after checking declared blob hashes. + * A partition image hash mismatch fails unless `verifyDeclaredHash` is false, + * which leaves that decision to a caller applying its own integrity policy. */ export const reconstructAndroidOtaPartition = ( partition: AndroidOtaPartition, @@ -1409,8 +1420,10 @@ export const reconstructAndroidOtaPartition = ( const budget = chargeReconstructionWork(partition.operations, blockSize); if (!budget.ok) return budget; const image = Buffer.alloc(size); + // The reader shares one byte array for repeated references to the same blob. + const blobHashes = new WeakMap(); try { - for (const operation of partition.operations) { + for (const [index, operation] of partition.operations.entries()) { if (operation.typeCode === 6) { const written = writeExtents( image, @@ -1432,6 +1445,17 @@ export const reconstructAndroidOtaPartition = ( `operation data for ${partition.name} is truncated: expected ${String(operation.dataLength)} bytes`, ), ); + if (operation.dataHashHex !== null) { + const observed = blobHashes.get(raw) ?? sha256Hex(raw); + blobHashes.set(raw, observed); + if (operation.dataHashHex !== observed) + return err({ + _tag: "AndroidOtaPayloadIntegrityFailure", + message: `Android OTA partition ${partition.name} operation ${String(index)} data hash mismatch`, + declaredHashHex: operation.dataHashHex, + observedHashHex: observed, + }); + } let payload: Uint8Array = raw; if (operation.typeCode === 14) { const dstBytes = destinationExtentBytes(