Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:Android OTA payload (payload.bin)

From ReverseEngineering.wiki
Format
Magic CrAU
Extensions payload.bin
Endianness big (header), protobuf (manifest)
License Apache-2.0 (AOSP update_engine)
On this wiki Facts · Code · Notes · Topics

The update_engine payload inside an Android A/B OTA zip: magic 'CrAU', big-endian major version 2, a protobuf DeltaArchiveManifest listing per-partition InstallOperations (REPLACE*, SOURCE_COPY, SOURCE_BSDIFF, PUFFDIFF, ZERO...), data blobs and signatures.

Overview

An A/B (seamless) OTA package is a ZIP with payload.bin, payload_properties.txt and META-INF/com/android/metadata. payload.bin is the file update_engine applies to the inactive slot. A full payload carries every partition (minor_version 0); an incremental payload only works from one exact source build.

Layout

Offset Field Notes
0 magic[4] CrAU
4 major version u64, big-endian 2 in current payloads (only version 2 is supported by the parser; version 1 was the Chrome OS format)
12 manifest_size u64, big-endian length of the serialized DeltaArchiveManifest
20 metadata_signature_size u32, big-endian
24 manifest protobuf, not compressed
24 + manifest_size metadata signature serialized Signatures message, metadata_signature_size bytes
then data blobs each InstallOperation names data_offset and data_length
end payload signatures located by signatures_offset and signatures_size in the manifest

The fixed header is 24 bytes. Data offsets in operations are relative to the start of the blob area, which begins after the manifest and the metadata signature In update_engine's delta_performer.cc, buffer_offset_ counts the bytes received after metadata_size_ + metadata_signature_size_ (VerifyPayload requires the download size to equal metadata_size_ + metadata_signature_size_ + buffer_offset_), and CanPerformInstallOperation compares operation.data_offset() with buffer_offset_; so data_offset is relative to the first byte after the metadata signature (read, lineage-21.0 mirror of AOSP).

DeltaArchiveManifest (update_metadata.proto)

Field numbers: block_size 3 (default 4096), signatures_offset 4, signatures_size 5, minor_version 12, partitions 13 (repeated PartitionUpdate, in update order), max_timestamp 14, dynamic_partition_metadata 15, partial_update 16, apex_info 17, security_patch_level 18. Fields 1, 2 and 6-11 are reserved (major version 1 leftovers).

PartitionUpdate: partition_name 1, run_postinstall 2, postinstall_path 3, filesystem_type 4, new_partition_signature 5, old_partition_info 6 and new_partition_info 7 (PartitionInfo: size, hash), operations 8 (repeated InstallOperation), postinstall_optional 9, hash tree and FEC extents 10-16, version 17, merge_operations 18 (CowMergeOperation for Virtual A/B). Extent is start_block plus num_blocks in units of block_size.

DynamicPartitionMetadata lists groups (name, size, partition_names) and flags for snapshots and Virtual A/B compression (snapshot_enabled, vabc_enabled, vabc_compression_param, cow_version). The sizes feed the super partition layout, see Format:Android LP metadata.

InstallOperation types

Value Name Meaning
0 REPLACE write the attached data to the destination extents
1 REPLACE_BZ attached data is bzip2
2 MOVE deprecated
3 BSDIFF deprecated
4 SOURCE_COPY copy source extents to destination extents
5 SOURCE_BSDIFF bsdiff against the source partition
6 ZERO write zeros
7 DISCARD discard blocks (content undefined)
8 REPLACE_XZ attached data is xz
9 PUFFDIFF puffin diff
10 BROTLI_BSDIFF bsdiff compressed with brotli
11 ZUCCHINI
12 LZ4DIFF_BSDIFF
13 LZ4DIFF_PUFFDIFF

Fields of an operation: type 1, data_offset 2, data_length 3, src_extents 4, src_length 5, dst_extents 6, dst_length 7, data_sha256_hash 8. Unverified: a full payload therefore needs only REPLACE, REPLACE_BZ, REPLACE_XZ, ZERO and DISCARD; the diff types appear in incremental payloads.

The proto comments tie operations to minor versions (update_metadata.proto, read at dc84c255): SOURCE_COPY and SOURCE_BSDIFF need minor 2; REPLACE_XZ needs minor 3 (and major 2); ZERO, DISCARD and BROTLI_BSDIFF need minor 4; PUFFDIFF 5; ZUCCHINI 8; LZ4DIFF_BSDIFF and LZ4DIFF_PUFFDIFF 9. An operation also has field 9 src_sha256_hash (hash of the source blocks, checked before applying when present). data_offset and data_length are uint64 only from minor 6; older clients read them as uint32. In payload_constants.cc InstallOperationTypeName spells LZ4DIFF_PUFFDIFF as "LZ4DIFF_PUFFIDFF" (typo in log output; grep logs for that spelling) and kMinSupportedMinorPayloadVersion is set to the source version, 2. Unverified: how the full-payload minor 0 is exempted from that minimum (not traced in the consumer code).

Minor versions

0 full payload, 2 source operations, 3 operation source hashes, 4 brotli bsdiff, 5 puffdiff, 6 verity, 7 partial update, 8 zucchini, 9 LZ4DIFF.

Extracting

Parse the 24-byte header, decode the manifest with the .proto, then for each partition apply REPLACE* operations in order into an output file of num_blocks * block_size bytes. The result is a raw partition image (ext4, erofs, boot image...); see Format:Android boot image and Format:Android sparse image. Incremental payloads need the old partition images.

Signing: the metadata signature covers bytes 0 up to the signature; the payload signature covers the file except the metadata signature. Recognizing where the signatures sit is enough for analysis; nothing here helps to forge them.

Sources: AOSP platform/system/update_engine update_metadata.proto, payload_consumer/payload_constants.cc, payload_metadata.cc.

Code & repositories

  • https://android.googlesource.com/platform/system/update_engine @ dc84c2552b2d4cf00d2a843cb1c091d99d0499f1 · license: Apache-2.0 (declared by the contributor for the files used; GitHub reports Apache-2.0 (read from NOTICE) for the repository)
    update_metadata.proto, payload_consumer/payload_metadata.cc and payload_constants.cc
    Tested on: source read, not run · checked 2026-10-18; last activity 2025-03-13