import { decodeStrictUtf8 } from "../domain/strictUtf8.js"; import { logicalPathNfc } from "../domain/artifactIdentity.js"; import { err, ok, type Result } from "../domain/result.js"; import { ANDROID_BOOT_MAGIC, VENDOR_BOOT_MAGIC, } from "../domain/androidBootImageFormat.js"; import { decodeLimit, malformedInput, ParseFailureError, truncatedInput, unsupportedInput, type LimitRef, } from "../domain/parseFailure.js"; import { BinaryReader } from "../domain/binaryContainer.js"; /** * Android boot (`ANDROID!`, versions 0-4) and vendor boot (`VNDRBOOT`, * versions 3-4) headers. Multi-byte header fields are little-endian. * Component bytes are located and bounded here; they are not decompressed, * executed, or signature-checked. */ export const ANDROID_BOOT_HEADER_PROBE_BYTES = 4096; export const AVB_FOOTER_SIZE = 64; const ANDROID_BOOT_MAGIC_BYTES = Buffer.from(ANDROID_BOOT_MAGIC); const VENDOR_BOOT_MAGIC_BYTES = Buffer.from(VENDOR_BOOT_MAGIC); const AVB_FOOTER_MAGIC_BYTES = Buffer.from("AVBf"); const BOOT_V3_PAGE_SIZE = 4096; const LEGACY_V0_SIZE = 1632; const LEGACY_V1_SIZE = 1648; const LEGACY_V2_SIZE = 1660; const MODERN_V3_SIZE = 1580; const MODERN_V4_SIZE = 1584; const VENDOR_V3_SIZE = 2112; const VENDOR_V4_SIZE = 2128; // v4 entry: size, offset, type, 32-byte name, 16 board-id words (108 bytes). const VENDOR_RAMDISK_ENTRY_SIZE = 108; const MAX_VENDOR_RAMDISKS = 4096; const MAX_RAMDISK_ENTRY_SIZE = 4096; const MAX_HEADER_SIZE = 1024 * 1024; const PAGE_MIN = 2048; const PAGE_MAX = 65536; const NAME_SIZE = 16; const BOOT_ARGS_SIZE = 512; const BOOT_EXTRA_ARGS_SIZE = 1024; const VENDOR_ARGS_SIZE = 2048; const RAMDISK_NAME_SIZE = 32; const BOARD_ID_BYTES = 64; const BOARD_ID_OFFSET = 12 + RAMDISK_NAME_SIZE; export type AndroidBootCompression = "gzip" | "lz4" | "zstd"; export interface AndroidBootComponentPlan { readonly role: | "kernel" | "ramdisk" | "second" | "recovery-dtbo" | "dtb" | "vendor-ramdisk" | "bootconfig" | "signature"; readonly path: string; readonly index: number; readonly offset: number; readonly size: number; readonly loadAddress: number | null; readonly ramdiskType: number | null; readonly ramdiskTypeName: string | null; readonly nameBytesHex: string | null; readonly boardIdHex: string | null; } export interface AndroidBootParse { readonly imageKind: "boot" | "vendor-boot"; readonly magic: typeof ANDROID_BOOT_MAGIC | typeof VENDOR_BOOT_MAGIC; readonly headerVersion: number; readonly pageSize: number; readonly headerSize: number; /** Bytes occupied by the page-aligned header before the first component. */ readonly headerOccupied: number; readonly osVersionRaw: number | null; readonly osVersion: string | null; readonly securityPatchLevel: string | null; readonly name: string | null; readonly nameBytesHex: string | null; readonly cmdline: string | null; readonly cmdlineBytesHex: string; readonly extraCmdline: string | null; readonly extraCmdlineBytesHex: string | null; readonly commandLine: string | null; readonly headerDigestHex: string | null; readonly kernelAddr: number | null; readonly ramdiskAddr: number | null; readonly secondAddr: number | null; readonly tagsAddr: number | null; readonly dtbAddr: number | null; readonly kernelSize: number | null; readonly ramdiskSize: number | null; readonly secondSize: number | null; readonly recoveryDtboSize: number | null; readonly recoveryDtboOffset: number | null; readonly dtbSize: number | null; readonly signatureSize: number | null; readonly vendorRamdiskSize: number | null; readonly vendorRamdiskTableEntryCount: number | null; readonly vendorRamdiskTableEntrySize: number | null; readonly bootconfigSize: number | null; readonly components: readonly AndroidBootComponentPlan[]; /** End of the last declared header or component byte. */ readonly dataEnd: number; /** Page-aligned end after the last component; trailing padding may be absent. */ readonly imageEnd: number; readonly limitations: readonly string[]; readonly tableRange: { readonly offset: number; readonly size: number; } | null; readonly vendorRamdiskSection: { readonly offset: number; readonly size: number; } | null; } export interface VendorRamdiskTableParse { readonly components: readonly AndroidBootComponentPlan[]; readonly limitations: readonly string[]; } export interface AvbFooterFacts { readonly present: boolean; readonly footerSize: typeof AVB_FOOTER_SIZE | null; readonly versionMajor: number | null; readonly versionMinor: number | null; readonly originalImageSize: number | null; readonly vbmetaOffset: number | null; readonly vbmetaSize: number | null; readonly limitations: readonly string[]; } /** The ParseFailure format of an Android boot or vendor boot image. */ const ANDROID_BOOT_FORMAT = "android-boot-image"; const formatError = (message: string): never => { throw malformedInput(ANDROID_BOOT_FORMAT, message); }; const capacityError = (message: string, limit: LimitRef): never => { throw decodeLimit(ANDROID_BOOT_FORMAT, message, limit); }; const HEADER_SIZE_LIMIT = { name: "Android boot image header_size", maximum: MAX_HEADER_SIZE, unit: "bytes", }; const VENDOR_RAMDISK_COUNT_LIMIT = { name: "Android vendor ramdisk table entry count", maximum: MAX_VENDOR_RAMDISKS, unit: "entries", }; const VENDOR_RAMDISK_ENTRY_SIZE_LIMIT = { name: "Android vendor ramdisk table entry size", maximum: MAX_RAMDISK_ENTRY_SIZE, unit: "bytes", }; /** Parser-owned fixed ceilings and their units for artifact recovery. */ export const ANDROID_BOOT_FIXED_LIMITS: ReadonlyMap< string, LimitRef & { readonly unit: string } > = new Map([ [HEADER_SIZE_LIMIT.name, HEADER_SIZE_LIMIT], [VENDOR_RAMDISK_COUNT_LIMIT.name, VENDOR_RAMDISK_COUNT_LIMIT], [VENDOR_RAMDISK_ENTRY_SIZE_LIMIT.name, VENDOR_RAMDISK_ENTRY_SIZE_LIMIT], ]); const parsed = (read: () => T): Result => { try { return ok(read()); } catch (cause) { if (!(cause instanceof ParseFailureError)) throw cause; return err(cause); } }; const requireBytes = (buffer: Buffer, length: number, what: string): void => { if (buffer.length < length) throw truncatedInput( ANDROID_BOOT_FORMAT, `${what} is truncated: ${buffer.length} bytes available, at least ${length} required`, { offset: buffer.length, field: what }, ); }; const u32 = (buffer: Buffer, offset: number): number => { requireBytes(buffer, offset + 4, "header"); return new BinaryReader(buffer, true, ANDROID_BOOT_FORMAT).u32(offset); }; const u64 = (buffer: Buffer, offset: number, what: string): number => { requireBytes(buffer, offset + 8, what); const reader = new BinaryReader(buffer, true, ANDROID_BOOT_FORMAT); const low = reader.u32(offset); const high = reader.u32(offset + 4); if (high > 0x1f_ffff) formatError(`${what} exceeds a safe integer`); return high * 0x1_0000_0000 + low; }; const u64be = (buffer: Buffer, offset: number, what: string): number => { requireBytes(buffer, offset + 8, what); const reader = new BinaryReader(buffer, false, ANDROID_BOOT_FORMAT); const high = reader.u32(offset); const low = reader.u32(offset + 4); if (high > 0x1f_ffff) formatError(`${what} exceeds a safe integer`); return high * 0x1_0000_0000 + low; }; const alignUp = (value: number, page: number): number => { if (!Number.isSafeInteger(value) || value < 0) formatError("a component extent is not a safe nonnegative integer"); const remainder = value % page; if (remainder === 0) return value; const aligned = value + (page - remainder); if (!Number.isSafeInteger(aligned)) formatError("a page-aligned component extent is not a safe integer"); return aligned; }; const endOf = (offset: number, size: number): number => { if ( !Number.isSafeInteger(offset) || !Number.isSafeInteger(size) || offset < 0 || size < 0 ) formatError("a component range is not a safe nonnegative extent"); const end = offset + size; if (!Number.isSafeInteger(end)) formatError("a component range overflows a safe integer"); return end; }; const requirePageSize = (value: number): number => { if ( !Number.isInteger(value) || value < PAGE_MIN || value > PAGE_MAX || (value & (value - 1)) !== 0 ) formatError( `page size ${value} is not a power of two from 2048 through 65536`, ); return value; }; const requireHeaderSize = ( value: number, minimum: number, maximum: number, ): number => { if (value > MAX_HEADER_SIZE) capacityError( `header_size ${value} exceeds the ${MAX_HEADER_SIZE} byte header bound`, HEADER_SIZE_LIMIT, ); if (!Number.isInteger(value) || value < minimum || value > maximum) formatError( `header_size ${value} is outside the supported range ${minimum} through ${maximum}`, ); return value; }; /** * Require the file to hold every declared header and component byte, and * return where those bytes end. Producers pad each component to the next * page, but the padding after the final one carries no data, so a file that * stops at the last declared byte is complete. */ const requireFileCovers = ( fileSize: number, headerSize: number, ranges: readonly ({ readonly offset: number; readonly size: number; } | null)[], ): number => { if (!Number.isSafeInteger(fileSize) || fileSize < 0) formatError("file size is not a safe nonnegative integer"); const dataEnd = ranges.reduce( (end, range) => range === null || range.size === 0 ? end : Math.max(end, endOf(range.offset, range.size)), headerSize, ); if (dataEnd > fileSize) throw truncatedInput( ANDROID_BOOT_FORMAT, `image is truncated: components end at byte ${dataEnd} but the file is ${fileSize} bytes`, { offset: fileSize, field: "components" }, ); return dataEnd; }; const untilNul = (bytes: Buffer): Buffer => { const nul = bytes.indexOf(0); return nul === -1 ? bytes : bytes.subarray(0, nul); }; const decodeText = (bytes: Buffer): string | null => { try { return decodeStrictUtf8(bytes, "preserve"); } catch { return null; } }; const decodeField = ( bytes: Buffer, ): { readonly text: string | null; readonly hex: string } => ({ text: decodeText(untilNul(bytes)), hex: bytes.toString("hex"), }); const commandFields = ( cmdlineBytes: Buffer, extraBytes: Buffer | null, ): Pick< AndroidBootParse, | "cmdline" | "cmdlineBytesHex" | "extraCmdline" | "extraCmdlineBytesHex" | "commandLine" > => { const cmdline = decodeField(cmdlineBytes); const extra = extraBytes === null ? null : decodeField(extraBytes); return { cmdline: cmdline.text, cmdlineBytesHex: cmdline.hex, extraCmdline: extra?.text ?? null, extraCmdlineBytesHex: extra?.hex ?? null, // A multibyte character can straddle the cmdline/extra_cmdline split, // so the joined line is decoded from the joined bytes. commandLine: extraBytes === null ? cmdline.text : decodeText( Buffer.concat([untilNul(cmdlineBytes), untilNul(extraBytes)]), ), }; }; const decodeOsVersion = ( raw: number, ): { readonly osVersion: string | null; readonly securityPatchLevel: string | null; readonly limitation: string | null; } => { const major = (raw >>> 25) & 0x7f; const minor = (raw >>> 18) & 0x7f; const patch = (raw >>> 11) & 0x7f; const year = (raw >>> 4) & 0x7f; const month = raw & 0xf; const osVersion = major === 0 && minor === 0 && patch === 0 ? null : `${String(major)}.${String(minor)}.${String(patch)}`; if (year === 0 && month === 0) return { osVersion, securityPatchLevel: null, limitation: null }; if (month < 1 || month > 12) return { osVersion, securityPatchLevel: null, limitation: `security patch month ${String(month)} is not a calendar month; the raw os_version field is retained`, }; const monthText = String(month).padStart(2, "0"); return { osVersion, securityPatchLevel: `${String(2000 + year)}-${monthText}`, limitation: null, }; }; const baseLimitations = ( imageKind: AndroidBootParse["imageKind"], ): string[] => [ "Command line, board name, and vendor ramdisk names are target-derived and untrusted.", ...(imageKind === "boot" ? [ "ANDROID! covers boot, init_boot, and recovery images; the header does not record which role the file had.", ] : []), ]; const component = ( role: AndroidBootComponentPlan["role"], path: string, offset: number, size: number, loadAddress: number | null, extra?: Partial< Pick< AndroidBootComponentPlan, | "index" | "ramdiskType" | "ramdiskTypeName" | "nameBytesHex" | "boardIdHex" > >, ): AndroidBootComponentPlan => ({ role, path, index: extra?.index ?? 0, offset, size, loadAddress, ramdiskType: extra?.ramdiskType ?? null, ramdiskTypeName: extra?.ramdiskTypeName ?? null, nameBytesHex: extra?.nameBytesHex ?? null, boardIdHex: extra?.boardIdHex ?? null, }); const place = ( components: AndroidBootComponentPlan[], cursor: number, page: number, planned: AndroidBootComponentPlan | null, ): number => { if (planned === null || planned.size === 0) return cursor; components.push(planned); return alignUp(endOf(cursor, planned.size), page); }; const bootParse = ( fields: Pick< AndroidBootParse, | "imageKind" | "magic" | "headerVersion" | "pageSize" | "headerSize" | "headerOccupied" | "cmdlineBytesHex" | "components" | "dataEnd" | "imageEnd" | "limitations" > & Partial, ): AndroidBootParse => ({ osVersionRaw: null, osVersion: null, securityPatchLevel: null, name: null, nameBytesHex: null, cmdline: null, extraCmdline: null, extraCmdlineBytesHex: null, commandLine: null, headerDigestHex: null, kernelAddr: null, ramdiskAddr: null, secondAddr: null, tagsAddr: null, dtbAddr: null, kernelSize: null, ramdiskSize: null, secondSize: null, recoveryDtboSize: null, recoveryDtboOffset: null, dtbSize: null, signatureSize: null, vendorRamdiskSize: null, vendorRamdiskTableEntryCount: null, vendorRamdiskTableEntrySize: null, bootconfigSize: null, tableRange: null, vendorRamdiskSection: null, ...fields, }); const RAMDISK_TYPE_NAMES: Readonly> = { 0: "none", 1: "platform", 2: "recovery", 3: "dlkm", }; const ramdiskTypeName = (value: number): string => RAMDISK_TYPE_NAMES[value] ?? "unknown"; const hasPrefix = (buffer: Buffer, bytes: readonly number[]): boolean => buffer.length >= bytes.length && bytes.every((byte, index) => buffer[index] === byte); /** gzip, lz4 frame, lz4 legacy, or zstd magic. Other prefixes stay unknown. */ export const compressionFromPrefix = ( prefix: Buffer, ): AndroidBootCompression | null => { if (hasPrefix(prefix, [0x1f, 0x8b])) return "gzip"; if (hasPrefix(prefix, [0x04, 0x22, 0x4d, 0x18])) return "lz4"; if (hasPrefix(prefix, [0x02, 0x21, 0x4c, 0x18])) return "lz4"; if (hasPrefix(prefix, [0x28, 0xb5, 0x2f, 0xfd])) return "zstd"; return null; }; const legacyStructSize = (version: number): number => { if (version === 0) return LEGACY_V0_SIZE; if (version === 1) return LEGACY_V1_SIZE; return LEGACY_V2_SIZE; }; const layoutLegacyTail = ( prefix: Buffer, version: number, page: number, cursor: number, components: AndroidBootComponentPlan[], limitations: string[], ): { readonly cursor: number; readonly recoveryDtboSize: number | null; readonly recoveryDtboOffset: number | null; readonly dtbSize: number | null; readonly dtbAddr: number | null; } => { if (version < 1) return { cursor, recoveryDtboSize: null, recoveryDtboOffset: null, dtbSize: null, dtbAddr: null, }; const recoveryDtboSize = u32(prefix, LEGACY_V0_SIZE); const recoveryDtboOffset = u64( prefix, LEGACY_V0_SIZE + 4, "recovery_dtbo offset", ); let next = cursor; if (recoveryDtboSize > 0) { if (recoveryDtboOffset % page !== 0) formatError( `recovery_dtbo offset ${recoveryDtboOffset} is not aligned to page size ${page}`, ); endOf(recoveryDtboOffset, recoveryDtboSize); if (recoveryDtboOffset < cursor) formatError("recovery_dtbo overlaps an earlier component"); if (recoveryDtboOffset > cursor) limitations.push( "Bytes between the sequential layout and recovery_dtbo were not exposed as entries.", ); components.push( component( "recovery-dtbo", "recovery_dtbo", recoveryDtboOffset, recoveryDtboSize, null, ), ); next = alignUp(endOf(recoveryDtboOffset, recoveryDtboSize), page); } if (version < 2) return { cursor: next, recoveryDtboSize, recoveryDtboOffset, dtbSize: null, dtbAddr: null, }; const dtbSize = u32(prefix, LEGACY_V1_SIZE); const dtbAddr = u64(prefix, LEGACY_V1_SIZE + 4, "dtb address"); return { cursor: place( components, next, page, dtbSize === 0 ? null : component("dtb", "dtb", next, dtbSize, dtbAddr), ), recoveryDtboSize, recoveryDtboOffset, dtbSize, dtbAddr, }; }; const parseLegacyBoot = ( prefix: Buffer, fileSize: number, headerVersion: number, ): AndroidBootParse => { const structSize = legacyStructSize(headerVersion); requireBytes(prefix, structSize, "header"); const pageSize = requirePageSize(u32(prefix, 36)); const headerSize = headerVersion === 0 ? LEGACY_V0_SIZE : requireHeaderSize( u32(prefix, LEGACY_V1_SIZE - 4), structSize, pageSize, ); const limitations = baseLimitations("boot"); if (headerVersion > 0 && headerSize > structSize) limitations.push( `Header bytes after the v${String(headerVersion)} structure were not decoded.`, ); const osRaw = u32(prefix, 44); const os = decodeOsVersion(osRaw); if (os.limitation !== null) limitations.push(os.limitation); const name = decodeField(prefix.subarray(48, 48 + NAME_SIZE)); const commands = commandFields( prefix.subarray(64, 64 + BOOT_ARGS_SIZE), prefix.subarray(608, 608 + BOOT_EXTRA_ARGS_SIZE), ); const components: AndroidBootComponentPlan[] = []; const kernelSize = u32(prefix, 8); const kernelAddr = u32(prefix, 12); const ramdiskSize = u32(prefix, 16); const ramdiskAddr = u32(prefix, 20); const secondSize = u32(prefix, 24); const secondAddr = u32(prefix, 28); let cursor = place( components, pageSize, pageSize, kernelSize === 0 ? null : component("kernel", "kernel", pageSize, kernelSize, kernelAddr), ); cursor = place( components, cursor, pageSize, ramdiskSize === 0 ? null : component("ramdisk", "ramdisk", cursor, ramdiskSize, ramdiskAddr), ); cursor = place( components, cursor, pageSize, secondSize === 0 ? null : component("second", "second", cursor, secondSize, secondAddr), ); const tail = layoutLegacyTail( prefix, headerVersion, pageSize, cursor, components, limitations, ); const dataEnd = requireFileCovers(fileSize, headerSize, components); return bootParse({ imageKind: "boot", magic: ANDROID_BOOT_MAGIC, headerVersion, pageSize, headerSize, headerOccupied: pageSize, osVersionRaw: osRaw, osVersion: os.osVersion, securityPatchLevel: os.securityPatchLevel, name: name.text, nameBytesHex: name.hex, ...commands, headerDigestHex: prefix.subarray(576, 608).toString("hex"), kernelAddr, ramdiskAddr, secondAddr, tagsAddr: u32(prefix, 32), dtbAddr: tail.dtbAddr, kernelSize, ramdiskSize, secondSize, recoveryDtboSize: tail.recoveryDtboSize, recoveryDtboOffset: tail.recoveryDtboOffset, dtbSize: tail.dtbSize, components, dataEnd, imageEnd: tail.cursor, limitations, }); }; const parseModernBoot = ( prefix: Buffer, fileSize: number, headerVersion: 3 | 4, ): AndroidBootParse => { const structSize = headerVersion === 4 ? MODERN_V4_SIZE : MODERN_V3_SIZE; requireBytes(prefix, structSize, "header"); const headerSize = requireHeaderSize( u32(prefix, 20), structSize, BOOT_V3_PAGE_SIZE, ); const limitations = baseLimitations("boot"); if (headerSize > structSize) limitations.push( `Header bytes after the v${String(headerVersion)} structure were not decoded.`, ); const osRaw = u32(prefix, 16); const os = decodeOsVersion(osRaw); if (os.limitation !== null) limitations.push(os.limitation); const commands = commandFields( prefix.subarray(44, 44 + BOOT_ARGS_SIZE + BOOT_EXTRA_ARGS_SIZE), null, ); const kernelSize = u32(prefix, 8); const ramdiskSize = u32(prefix, 12); const signatureSize = headerVersion === 4 ? u32(prefix, MODERN_V3_SIZE) : null; const components: AndroidBootComponentPlan[] = []; let cursor = place( components, BOOT_V3_PAGE_SIZE, BOOT_V3_PAGE_SIZE, kernelSize === 0 ? null : component("kernel", "kernel", BOOT_V3_PAGE_SIZE, kernelSize, null), ); cursor = place( components, cursor, BOOT_V3_PAGE_SIZE, ramdiskSize === 0 ? null : component("ramdisk", "ramdisk", cursor, ramdiskSize, null), ); cursor = place( components, cursor, BOOT_V3_PAGE_SIZE, signatureSize === null || signatureSize === 0 ? null : component("signature", "signature", cursor, signatureSize, null), ); const dataEnd = requireFileCovers(fileSize, headerSize, components); return bootParse({ imageKind: "boot", magic: ANDROID_BOOT_MAGIC, headerVersion, pageSize: BOOT_V3_PAGE_SIZE, headerSize, headerOccupied: BOOT_V3_PAGE_SIZE, osVersionRaw: osRaw, osVersion: os.osVersion, securityPatchLevel: os.securityPatchLevel, ...commands, kernelSize, ramdiskSize, signatureSize, components, dataEnd, imageEnd: cursor, limitations, }); }; const parseVendorTableHeader = ( prefix: Buffer, ): { readonly tableSize: number; readonly entryCount: number; readonly entrySize: number; readonly bootconfigSize: number; } => { const tableSize = u32(prefix, VENDOR_V3_SIZE); const entryCount = u32(prefix, VENDOR_V3_SIZE + 4); const entrySize = u32(prefix, VENDOR_V3_SIZE + 8); const bootconfigSize = u32(prefix, VENDOR_V3_SIZE + 12); if (entryCount > MAX_VENDOR_RAMDISKS) capacityError( `vendor ramdisk table declares more than ${MAX_VENDOR_RAMDISKS} entries`, VENDOR_RAMDISK_COUNT_LIMIT, ); if (entrySize > MAX_RAMDISK_ENTRY_SIZE) capacityError( `vendor ramdisk table entry size ${entrySize} exceeds the ${MAX_RAMDISK_ENTRY_SIZE} byte entry bound`, VENDOR_RAMDISK_ENTRY_SIZE_LIMIT, ); if (entryCount > 0 && entrySize < VENDOR_RAMDISK_ENTRY_SIZE) formatError( `vendor ramdisk table entry size ${entrySize} is smaller than the ${VENDOR_RAMDISK_ENTRY_SIZE}-byte v4 entry`, ); const product = entryCount * entrySize; if (!Number.isSafeInteger(product) || product !== tableSize) formatError( `vendor ramdisk table size ${tableSize} does not equal ${entryCount} entries of ${entrySize} bytes`, ); return { tableSize, entryCount, entrySize, bootconfigSize }; }; const parseVendorHeader = ( prefix: Buffer, fileSize: number, ): AndroidBootParse => { requireBytes(prefix, 12, "header"); const headerVersion = u32(prefix, 8); if (headerVersion !== 3 && headerVersion !== 4) throw unsupportedInput( ANDROID_BOOT_FORMAT, `vendor boot header version ${headerVersion} is unsupported`, { offset: 8, field: "header_version", undecodedContent: true }, ); const structSize = headerVersion === 4 ? VENDOR_V4_SIZE : VENDOR_V3_SIZE; requireBytes(prefix, structSize, "header"); const pageSize = requirePageSize(u32(prefix, 12)); const kernelAddr = u32(prefix, 16); const ramdiskAddr = u32(prefix, 20); const vendorRamdiskSize = u32(prefix, 24); const tagsAddr = u32(prefix, 2076); const name = decodeField(prefix.subarray(2080, 2080 + NAME_SIZE)); const headerSize = requireHeaderSize( u32(prefix, 2096), structSize, MAX_HEADER_SIZE, ); const dtbSize = u32(prefix, 2100); const dtbAddr = u64(prefix, 2104, "dtb address"); const table = headerVersion === 4 ? parseVendorTableHeader(prefix) : null; const limitations = baseLimitations("vendor-boot"); if (headerSize > structSize) limitations.push( `Header bytes after the v${String(headerVersion)} structure were not decoded.`, ); const headerOccupied = alignUp(headerSize, pageSize); const sectionOffset = headerOccupied; let cursor = vendorRamdiskSize === 0 ? sectionOffset : alignUp(endOf(sectionOffset, vendorRamdiskSize), pageSize); const components: AndroidBootComponentPlan[] = []; if (headerVersion === 3 && vendorRamdiskSize > 0) components.push( component( "vendor-ramdisk", "vendor_ramdisk", sectionOffset, vendorRamdiskSize, ramdiskAddr, ), ); cursor = place( components, cursor, pageSize, dtbSize === 0 ? null : component("dtb", "dtb", cursor, dtbSize, dtbAddr), ); const tableRange = table !== null && table.tableSize > 0 ? { offset: cursor, size: table.tableSize } : null; if (tableRange !== null) cursor = alignUp(endOf(tableRange.offset, tableRange.size), pageSize); const bootconfigSize = table?.bootconfigSize ?? null; cursor = place( components, cursor, pageSize, bootconfigSize === null || bootconfigSize === 0 ? null : component("bootconfig", "bootconfig", cursor, bootconfigSize, null), ); if (table !== null && table.entryCount === 0 && vendorRamdiskSize > 0) limitations.push( "Vendor ramdisk section bytes outside the ramdisk table were not exposed as entries.", ); const section = { offset: sectionOffset, size: vendorRamdiskSize }; const declared = [...components, section, tableRange]; const dataEnd = requireFileCovers(fileSize, headerSize, declared); return bootParse({ imageKind: "vendor-boot", magic: VENDOR_BOOT_MAGIC, headerVersion, pageSize, headerSize, headerOccupied, name: name.text, nameBytesHex: name.hex, ...commandFields(prefix.subarray(28, 28 + VENDOR_ARGS_SIZE), null), kernelAddr, ramdiskAddr, tagsAddr, dtbAddr, dtbSize, vendorRamdiskSize, vendorRamdiskTableEntryCount: table?.entryCount ?? null, vendorRamdiskTableEntrySize: table?.entrySize ?? null, bootconfigSize, components, dataEnd, imageEnd: cursor, limitations, tableRange, vendorRamdiskSection: section, }); }; const parseAndroidHeader = ( prefix: Buffer, fileSize: number, ): AndroidBootParse => { requireBytes(prefix, 44, "header"); const headerVersion = u32(prefix, 40); if (headerVersion <= 2) return parseLegacyBoot(prefix, fileSize, headerVersion); if (headerVersion === 3 || headerVersion === 4) return parseModernBoot(prefix, fileSize, headerVersion); throw unsupportedInput( ANDROID_BOOT_FORMAT, `header version ${headerVersion} is unsupported`, { offset: 40, field: "header_version", undecodedContent: true }, ); }; /** Decode one boot or vendor_boot header and its page-aligned component ranges. */ export const parseAndroidBootHeader = ( prefix: Buffer, fileSize: number, ): Result => parsed(() => { if (!Number.isSafeInteger(fileSize) || fileSize < 0) formatError("file size is not a safe nonnegative integer"); requireBytes(prefix, 8, "header"); if (prefix.subarray(0, 8).equals(ANDROID_BOOT_MAGIC_BYTES)) return parseAndroidHeader(prefix, fileSize); if (prefix.subarray(0, 8).equals(VENDOR_BOOT_MAGIC_BYTES)) return parseVendorHeader(prefix, fileSize); return formatError("magic is not ANDROID! or VNDRBOOT"); }); const vendorRamdiskPath = ( text: string | null, index: number, used: Set, ): string => { const base = text !== null && text.length > 0 && text !== "." && text !== ".." && !text.includes("/") ? // Inventory keys logical paths by their NFC spelling, so uniqueness // is checked in that spelling; name_bytes_hex keeps the stored bytes. logicalPathNfc(text) : `ramdisk-${String(index)}`; // `-` can itself match an earlier name (`x` beside `x-2`, or a // fallback `ramdisk-` beside a real name of that form). Keep // suffixing until the segment is unused. let unique = used.has(base) ? `${base}-${String(index)}` : base; let extra = 2; while (used.has(unique)) { unique = `${base}-${String(index)}-${String(extra)}`; extra += 1; } used.add(unique); return `vendor_ramdisk/${unique}`; }; const sectionCovered = ( entries: readonly AndroidBootComponentPlan[], sectionOffset: number, sectionSize: number, ): boolean => { let covered = 0; const spans = entries .map((entry) => ({ start: entry.offset - sectionOffset, end: entry.offset - sectionOffset + entry.size, })) .sort((left, right) => left.start - right.start); for (const span of spans) { if (span.start > covered) return false; covered = Math.max(covered, span.end); } return covered === sectionSize; }; const readVendorRamdiskTable = ( table: Buffer, input: { readonly entryCount: number; readonly entrySize: number; readonly sectionOffset: number; readonly sectionSize: number; }, ): VendorRamdiskTableParse => { if (input.entryCount > 0 && input.entrySize < VENDOR_RAMDISK_ENTRY_SIZE) formatError( `vendor ramdisk table entry size ${input.entrySize} is smaller than the ${VENDOR_RAMDISK_ENTRY_SIZE}-byte v4 entry`, ); const expected = input.entryCount * input.entrySize; requireBytes(table, expected, "vendor ramdisk table"); if (table.length > expected) formatError( `vendor ramdisk table is ${table.length} bytes, expected ${expected}`, ); const components: AndroidBootComponentPlan[] = []; const used = new Set(); const empty: number[] = []; let longer = false; for (let index = 0; index < input.entryCount; index += 1) { const base = index * input.entrySize; const size = u32(table, base); const offset = u32(table, base + 4); const ramdiskType = u32(table, base + 8); if (offset > input.sectionSize || size > input.sectionSize - offset) formatError( `vendor ramdisk table entry ${index} overruns the vendor ramdisk section`, ); // An empty fragment carries no bytes to expose, like other zero-sized // components; omit it rather than rejecting the image. if (size === 0) { empty.push(index); continue; } const fileOffset = endOf(input.sectionOffset, offset); endOf(fileOffset, size); const decoded = decodeField( table.subarray(base + 12, base + 12 + RAMDISK_NAME_SIZE), ); if (input.entrySize > VENDOR_RAMDISK_ENTRY_SIZE) longer = true; components.push( component( "vendor-ramdisk", vendorRamdiskPath(decoded.text, index, used), fileOffset, size, // ramdisk_addr is the assembled section's base; a fragment's placement // depends on bootloader selection, so it is not published per entry. null, { index, ramdiskType, ramdiskTypeName: ramdiskTypeName(ramdiskType), nameBytesHex: decoded.hex, boardIdHex: table .subarray( base + BOARD_ID_OFFSET, base + BOARD_ID_OFFSET + BOARD_ID_BYTES, ) .toString("hex"), }, ), ); } const ordered = [...components].sort( (left, right) => left.offset - right.offset || left.index - right.index, ); for (let index = 1; index < ordered.length; index += 1) { const previous = ordered[index - 1]; const current = ordered[index]; if ( previous !== undefined && current !== undefined && previous.offset + previous.size > current.offset ) formatError( `vendor ramdisk table entry ${current.index} overlaps entry ${previous.index}`, ); } const limitations: string[] = []; if (longer) limitations.push( `Vendor ramdisk table entries are longer than the ${String(VENDOR_RAMDISK_ENTRY_SIZE)}-byte v4 structure; trailing entry bytes were not decoded.`, ); if (empty.length > 0) limitations.push( `Vendor ramdisk table entries ${empty.join(", ")} declare no bytes and were omitted.`, ); if (!sectionCovered(components, input.sectionOffset, input.sectionSize)) limitations.push( "Vendor ramdisk section bytes outside the ramdisk table were not exposed as entries.", ); return { components, limitations }; }; /** Split a v4 vendor ramdisk table into non-overlapping section slices. */ export const parseVendorRamdiskTable = ( table: Buffer, input: { readonly entryCount: number; readonly entrySize: number; readonly sectionOffset: number; readonly sectionSize: number; }, ): Result => parsed(() => readVendorRamdiskTable(table, input)); const absentFooter = (limitations: readonly string[] = []): AvbFooterFacts => ({ present: false, footerSize: null, versionMajor: null, versionMinor: null, originalImageSize: null, vbmetaOffset: null, vbmetaSize: null, limitations, }); const rejectVbmetaOverlap = ( vbmeta: { readonly offset: number; readonly size: number }, fileSize: number, headerOccupied: number, components: readonly { readonly offset: number; readonly size: number }[], ): void => { if (vbmeta.size === 0) return; if (endOf(vbmeta.offset, vbmeta.size) > fileSize - AVB_FOOTER_SIZE) formatError("AVB vbmeta overlaps the footer"); const occupied = [{ offset: 0, size: headerOccupied }, ...components]; for (const componentRange of occupied) if ( componentRange.size > 0 && vbmeta.offset < componentRange.offset + componentRange.size && componentRange.offset < vbmeta.offset + vbmeta.size ) formatError( componentRange.offset === 0 ? "AVB vbmeta overlaps the boot image header" : `AVB vbmeta overlaps a component at offset ${componentRange.offset}`, ); }; const readAvbFooter = (input: { readonly fileSize: number; readonly dataEnd: number; readonly imageEnd: number; readonly headerOccupied: number; readonly components: readonly { readonly offset: number; readonly size: number; }[]; readonly tail: Buffer | null; }): AvbFooterFacts => { if (input.fileSize < input.dataEnd) throw truncatedInput( ANDROID_BOOT_FORMAT, `image is truncated: components end at byte ${input.dataEnd} but the file is ${input.fileSize} bytes`, { offset: input.fileSize, field: "components" }, ); // A footer follows the page-aligned image. A file that ends inside the // final page padding has no room for one. const trailing = input.fileSize - input.imageEnd; if (trailing <= 0) return absentFooter(); if (trailing < AVB_FOOTER_SIZE) return absentFooter([ `${trailing} trailing bytes follow the boot image and are shorter than a 64-byte AVB footer.`, ]); const tail = input.tail; if (tail === null || tail.length !== AVB_FOOTER_SIZE) return formatError("AVB footer bytes were not supplied"); if (!tail.subarray(0, 4).equals(AVB_FOOTER_MAGIC_BYTES)) return absentFooter([ `${trailing} trailing bytes follow the boot image and were not decoded as an AVB footer.`, ]); const originalImageSize = u64be(tail, 12, "AVB original image size"); const vbmetaOffset = u64be(tail, 20, "AVB vbmeta offset"); const vbmetaSize = u64be(tail, 28, "AVB vbmeta size"); if (originalImageSize < input.dataEnd) formatError( `AVB original image size ${originalImageSize} ends before boot image components at ${input.dataEnd}`, ); if (originalImageSize > input.fileSize - AVB_FOOTER_SIZE) formatError( `AVB original image size ${originalImageSize} overlaps the footer`, ); rejectVbmetaOverlap( { offset: vbmetaOffset, size: vbmetaSize }, input.fileSize, input.headerOccupied, input.components, ); return { present: true, footerSize: AVB_FOOTER_SIZE, versionMajor: new BinaryReader(tail, false, ANDROID_BOOT_FORMAT).u32(4), versionMinor: new BinaryReader(tail, false, ANDROID_BOOT_FORMAT).u32(8), originalImageSize, vbmetaOffset, vbmetaSize, limitations: [], }; }; /** * Report an AVB footer when the last 64 bytes start with AVBf and sit past * the page-aligned image. Sizes are recorded; the footer is not verified. */ export const inspectAvbFooter = (input: { readonly fileSize: number; readonly dataEnd: number; readonly imageEnd: number; readonly headerOccupied: number; readonly components: readonly { readonly offset: number; readonly size: number; }[]; readonly tail: Buffer | null; }): Result => parsed(() => readAvbFooter(input));