Format:Android OTA payload (payload.bin)
| 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