diff --git a/docs/guides/firmware/android-ota-payload.md b/docs/guides/firmware/android-ota-payload.md index 130ce153eb..d00429c974 100644 --- a/docs/guides/firmware/android-ota-payload.md +++ b/docs/guides/firmware/android-ota-payload.md @@ -52,7 +52,10 @@ not erase an earlier declared hash; a repeated scalar field keeps its last value. The resulting size and hash feed both inventory and extraction. Metadata and payload signature blobs are counted from the `Signatures` -protobuf. `signatures_verified` is always `false`: sizes and counts are +protobuf. A payload signature is declared when both `signatures_offset` and +`signatures_size` are present. Inventory preserves a lone field as manifest +metadata and leaves the payload signature blob size and count null. +`signatures_verified` is always `false`: sizes and counts are facts, not a cryptographic check. `payload_properties.txt` and `META-INF/com/android/metadata` beside a zip member are out of scope. A zip that already lists `payload.bin` still classifies that member by `CrAU` diff --git a/src/artifacts/AndroidOtaPayloadArtifactReader.ts b/src/artifacts/AndroidOtaPayloadArtifactReader.ts index b36f9a4a9d..a0254c98c7 100644 --- a/src/artifacts/AndroidOtaPayloadArtifactReader.ts +++ b/src/artifacts/AndroidOtaPayloadArtifactReader.ts @@ -215,31 +215,23 @@ export class AndroidOtaPayloadArtifactReader implements ArtifactReader { ); const first = parseAndroidOtaPayload(prefix, initial.size); if (!first.ok) throw parseFailure(first.error); - let payloadSignature: Uint8Array | undefined; - if ( - first.value.signaturesOffset !== null && - first.value.signaturesSize !== null && - first.value.signaturesSize > 0 - ) { - const start = header.value.blobOffset + first.value.signaturesOffset; - const end = start + first.value.signaturesSize; - if (Number.isSafeInteger(end) && end <= initial.size) { - payloadSignature = await readArtifactFileBytes( - handle, - start, - first.value.signaturesSize, - initial.size, - signal, - ); - } - } + const signatureRange = first.value.payloadSignatureRange; + const payloadSignature = + signatureRange === null + ? undefined + : await readArtifactFileBytes( + handle, + signatureRange.offset, + signatureRange.bytes, + initial.size, + signal, + ); await this.#source.read(signal); this.#assertOpen(signal); - const parsed = parseAndroidOtaPayload( - prefix, - initial.size, - payloadSignature, - ); + const parsed = + payloadSignature === undefined + ? first + : parseAndroidOtaPayload(prefix, initial.size, payloadSignature); if (!parsed.ok) throw parseFailure(parsed.error); this.#payload = parsed.value; this.#entries.clear(); diff --git a/src/domain/firmware/androidOtaPayload.fixture.ts b/src/domain/firmware/androidOtaPayload.fixture.ts index 555c6af8ab..6e0728f277 100644 --- a/src/domain/firmware/androidOtaPayload.fixture.ts +++ b/src/domain/firmware/androidOtaPayload.fixture.ts @@ -76,8 +76,8 @@ export interface AndroidOtaPayloadFixture { readonly apex?: readonly AndroidOtaApexFixture[]; readonly metadataSignature?: Uint8Array; readonly payloadSignature?: Uint8Array; - readonly signaturesOffset?: number; - readonly signaturesSize?: number; + readonly signaturesOffset?: number | null; + readonly signaturesSize?: number | null; readonly truncateTo?: number; } @@ -294,14 +294,16 @@ const encodeApex = ( const encodeManifest = ( fixture: AndroidOtaPayloadFixture, blob: { offset: number; chunks: Uint8Array[] }, - signaturesOffset: number, - signaturesSize: number, + signaturesOffset: number | null, + signaturesSize: number | null, ): Uint8Array => { const writer = new BinaryWriter(); const blockSize = fixture.blockSize ?? ANDROID_OTA_DEFAULT_BLOCK_SIZE; writer.tag(3, WireType.Varint).uint32(blockSize); - writer.tag(4, WireType.Varint).uint64(signaturesOffset); - writer.tag(5, WireType.Varint).uint64(signaturesSize); + if (signaturesOffset !== null) + writer.tag(4, WireType.Varint).uint64(signaturesOffset); + if (signaturesSize !== null) + writer.tag(5, WireType.Varint).uint64(signaturesSize); if (fixture.minorVersion !== undefined) writer.tag(12, WireType.Varint).uint32(fixture.minorVersion); for (const partition of fixture.partitions) { @@ -375,8 +377,14 @@ export const buildAndroidOtaPayload = ( androidOtaSignatureBlob(Buffer.from("payload-sig")); encodeManifest(fixture, layout, 0, payloadSignature.length); const data = Buffer.concat(layout.chunks); - const signaturesOffset = fixture.signaturesOffset ?? data.length; - const signaturesSize = fixture.signaturesSize ?? payloadSignature.length; + const signaturesOffset = + fixture.signaturesOffset === undefined + ? data.length + : fixture.signaturesOffset; + const signaturesSize = + fixture.signaturesSize === undefined + ? payloadSignature.length + : fixture.signaturesSize; const laidOut = { offset: 0, chunks: [] as Uint8Array[] }; const manifest = encodeManifest( fixture, diff --git a/src/domain/firmware/androidOtaPayload.test.ts b/src/domain/firmware/androidOtaPayload.test.ts index 2425588756..db0b7c2f28 100644 --- a/src/domain/firmware/androidOtaPayload.test.ts +++ b/src/domain/firmware/androidOtaPayload.test.ts @@ -394,6 +394,46 @@ it("names the extraction ceiling, not unsupported operations, for a large REPLAC }); }); +it.each([ + { signaturesOffset: 0, signaturesSize: null }, + { + signaturesOffset: null, + signaturesSize: ANDROID_OTA_MAX_SIGNATURE_BYTES + 1, + }, +])( + "reconstructs a partition when one payload signature coordinate is absent ($signaturesOffset, $signaturesSize)", + ({ signaturesOffset, signaturesSize }) => { + const data = Buffer.from("BOOT"); + const bytes = buildAndroidOtaPayload({ + signaturesOffset, + signaturesSize, + payloadSignature: new Uint8Array(), + partitions: [{ name: "boot", operations: [{ type: 0, data }] }], + }); + const parsed = parse(bytes); + expect(parsed).toMatchObject({ + ok: true, + value: { + signaturesOffset, + signaturesSize, + payloadSignatureBlobSize: null, + payloadSignatureCount: null, + blobTruncated: false, + }, + }); + if (!parsed.ok) throw parsed.error; + const { blobOffset } = parsed.value.header; + expect( + reconstructAndroidOtaPartition( + parsed.value.partitions[0]!, + parsed.value.blockSize, + (offset, length) => + bytes.subarray(blobOffset + offset, blobOffset + offset + length), + ), + ).toEqual({ ok: true, value: data }); + }, +); + it("refuses operation data that overruns the payload blob", () => { const bytes = buildAndroidOtaPayload({ partitions: [ diff --git a/src/domain/firmware/androidOtaPayload.ts b/src/domain/firmware/androidOtaPayload.ts index 0ffff2b2eb..752ef00bf2 100644 --- a/src/domain/firmware/androidOtaPayload.ts +++ b/src/domain/firmware/androidOtaPayload.ts @@ -278,6 +278,10 @@ export interface AndroidOtaPayload { readonly metadataSignatureBlobSize: number; readonly metadataSignatureCount: number | null; readonly payloadSignatureBlobSize: number | null; + readonly payloadSignatureRange: { + readonly offset: number; + readonly bytes: number; + } | null; readonly payloadSignatureCount: number | null; readonly partitions: readonly AndroidOtaPartition[]; readonly dynamicPartitionGroups: readonly AndroidOtaDynamicGroup[]; @@ -853,16 +857,9 @@ const decodeManifest = ( return; } if (field === 5 && wire === WireType.Varint) { - const size = unwrap(asSafeUint(reader.uint64(), "signatures_size")); - if (size > ANDROID_OTA_MAX_SIGNATURE_BYTES) - fail( - capacity( - "payload signature size", - ANDROID_OTA_MAX_SIGNATURE_BYTES, - "byte", - ), - ); - draft.signaturesSize = size; + draft.signaturesSize = unwrap( + asSafeUint(reader.uint64(), "signatures_size"), + ); return; } if (field === 12 && wire === WireType.Varint) { @@ -995,47 +992,49 @@ export const parseAndroidOtaPayload = ( metadataSignatureCount = counted.value; } } + // The manifest declares a payload signature only when both coordinates + // are present. Keep each raw field available for inventory. + const { signaturesOffset, signaturesSize } = manifest.value; + const signatureDeclaration = + signaturesOffset === null || signaturesSize === null + ? null + : { blobOffset: signaturesOffset, size: signaturesSize }; let payloadSignatureCount: number | null = null; - let payloadSignatureBlobSize: number | null = manifest.value.signaturesSize; - const signatureSlice = (): Uint8Array | undefined => { - if (payloadSignatureBytes !== undefined) return payloadSignatureBytes; - if ( - manifest.value.signaturesOffset === null || - manifest.value.signaturesSize === null || - manifest.value.signaturesSize === 0 - ) - return undefined; - const start = header.value.blobOffset + manifest.value.signaturesOffset; - const end = start + manifest.value.signaturesSize; - if (!Number.isSafeInteger(end) || end > bytes.length) return undefined; - return bytes.subarray(start, end); - }; - const payloadSignatureSlice = signatureSlice(); - if ( - payloadSignatureSlice !== undefined && - manifest.value.signaturesSize !== null - ) { - if (payloadSignatureSlice.length !== manifest.value.signaturesSize) + let payloadSignatureRange: AndroidOtaPayload["payloadSignatureRange"] = null; + let blobTruncated = fileSize < header.value.blobOffset; + if (signatureDeclaration !== null) { + const { blobOffset, size } = signatureDeclaration; + if (size > ANDROID_OTA_MAX_SIGNATURE_BYTES) return err( - malformed( - "payload signature blob length does not match signatures_size", + capacity( + "payload signature size", + ANDROID_OTA_MAX_SIGNATURE_BYTES, + "byte", ), ); - const counted = countAndroidOtaSignatures(payloadSignatureSlice); - if (!counted.ok) return counted; - payloadSignatureCount = counted.value; - } else if ( - payloadSignatureSlice !== undefined && - payloadSignatureSlice.length > 0 - ) { - const counted = countAndroidOtaSignatures(payloadSignatureSlice); - if (!counted.ok) return counted; - payloadSignatureCount = counted.value; - payloadSignatureBlobSize = payloadSignatureSlice.length; + const offset = header.value.blobOffset + blobOffset; + const end = offset + size; + if (!Number.isSafeInteger(end) || end > fileSize) blobTruncated = true; + else if (size > 0) payloadSignatureRange = { offset, bytes: size }; + const signature = + payloadSignatureBytes ?? + (payloadSignatureRange !== null && end <= bytes.length + ? bytes.subarray(offset, end) + : undefined); + if (signature !== undefined) { + if (signature.length !== size) + return err( + malformed( + "payload signature blob length does not match signatures_size", + ), + ); + const counted = countAndroidOtaSignatures(signature); + if (!counted.ok) return counted; + payloadSignatureCount = counted.value; + } } const blobAvailable = Math.max(0, fileSize - header.value.blobOffset); - let blobTruncated = fileSize < header.value.blobOffset; for (const partition of manifest.value.partitions) { for (const operation of partition.operations) { if (operation.dataLength === 0) continue; @@ -1043,27 +1042,17 @@ export const parseAndroidOtaPayload = ( if (!Number.isSafeInteger(end) || end < operation.dataOffset) return err(malformed("operation data extent overflows")); if ( - manifest.value.signaturesOffset !== null && - end > manifest.value.signaturesOffset + signatureDeclaration !== null && + end > signatureDeclaration.blobOffset ) return err( malformed( - `operation data extent ${String(operation.dataOffset)}+${String(operation.dataLength)} overruns the ${String(manifest.value.signaturesOffset)}-byte payload blob`, + `operation data extent ${String(operation.dataOffset)}+${String(operation.dataLength)} overruns the ${String(signatureDeclaration.blobOffset)}-byte payload blob`, ), ); if (end > blobAvailable) blobTruncated = true; } } - if ( - manifest.value.signaturesOffset !== null && - manifest.value.signaturesSize !== null - ) { - const declaredEnd = - header.value.blobOffset + - manifest.value.signaturesOffset + - manifest.value.signaturesSize; - if (fileSize < declaredEnd) blobTruncated = true; - } const nameState: PartitionNameState = { used: new Set(), @@ -1171,7 +1160,8 @@ export const parseAndroidOtaPayload = ( signaturesSize: manifest.value.signaturesSize, metadataSignatureBlobSize: header.value.metadataSignatureSize, metadataSignatureCount, - payloadSignatureBlobSize, + payloadSignatureBlobSize: signatureDeclaration?.size ?? null, + payloadSignatureRange, payloadSignatureCount, partitions, dynamicPartitionGroups: manifest.value.groups.map((group) => ({ diff --git a/tests/acceptance/androidOtaPayloadCli.test.ts b/tests/acceptance/androidOtaPayloadCli.test.ts index 51ced7e024..87f354d3be 100644 --- a/tests/acceptance/androidOtaPayloadCli.test.ts +++ b/tests/acceptance/androidOtaPayloadCli.test.ts @@ -12,6 +12,7 @@ import { artifactExtractionResultSchema, artifactInventoryResultSchema, } from "../../src/domain/artifactGraph.js"; +import { ANDROID_OTA_MAX_SIGNATURE_BYTES } from "../../src/domain/firmware/androidOtaPayload.js"; import { buildAndroidOtaPayload, deltaAndroidOtaPayload, @@ -19,6 +20,65 @@ import { v1AndroidOtaPayload, } from "../../src/domain/firmware/androidOtaPayload.fixture.js"; +cliTest.for([ + { signaturesOffset: 0, signaturesSize: null }, + { + signaturesOffset: null, + signaturesSize: ANDROID_OTA_MAX_SIGNATURE_BYTES + 1, + }, +])( + "preserves one declared OTA signature field and extracts the partition ($signaturesOffset, $signaturesSize)", + async ({ signaturesOffset, signaturesSize }, { cli }) => { + const root = await createTestTempDirectory("rea-ota-signature-field-cli-"); + const source = join(root, "payload.bin"); + const data = Buffer.from("BOOT"); + await writeFile( + source, + buildAndroidOtaPayload({ + signaturesOffset, + signaturesSize, + payloadSignature: new Uint8Array(), + partitions: [{ name: "boot", operations: [{ type: 0, data }] }], + }), + ); + const inspected = await cli.run({ + arguments: ["inspect-artifact", source, "--json"], + }); + expect(inspected.exitCode, inspected.stderr).toBe(0); + const inspection = artifactInspectionResultSchema.parse( + parseEvidence(inspected.json).normalized_result, + ); + const graph = artifactInventoryResultSchema.parse( + inspection.substeps[0]?.evidence.normalized_result, + ); + expect( + graph.occurrences.find((row) => row.logical_path === ".") + ?.format_metadata, + ).toMatchObject({ + kind: "android-ota-payload", + signatures_offset: signaturesOffset, + signatures_size: signaturesSize, + payload_signature_blob_size: null, + payload_signature_count: null, + }); + expect( + graph.occurrences.find((row) => row.logical_path === "boot.img") + ?.hash_status, + ).toBe("verified"); + const extracted = await cli.run({ + arguments: ["extract-artifact", source, "--json"], + environment: { TMPDIR: root, TMP: root, TEMP: root }, + }); + expect(extracted.exitCode, extracted.stderr).toBe(0); + const result = artifactExtractionResultSchema.parse( + parseEvidence(extracted.json).normalized_result, + ); + expect( + (await readFile(join(result.output_root, "boot.img"))).equals(data), + ).toBe(true); + }, +); + cliTest.for([false, true])( "retains split partition metadata and extracts verified bytes (hash first: %s)", async (hashFirst, { cli }) => {