Introduction
Android Verified Boot (AVB, in the libavb library) lets a boot loader check that each partition is what the device's maker signed. The checking data is a vbmeta image: a small signed structure, in its own partition (vbmeta) or after the data of a partition (boot, vendor_boot, system ...) with a 64-byte footer in the partition's last bytes saying where it is. The layouts are in libavb's headers (avb_vbmeta_image.h, avb_footer.h, avb_descriptor.h and the descriptor headers, read as raw text, with avbtool.py; copies are in samples/androidboot/sources; the descriptions here are our own words). All numbers are big-endian, unlike the boot image headers.
Layout of a vbmeta image
A 256-byte header (AVB0), the authentication data block (the hash, then the signature, padded) and the auxiliary data block (the descriptors, the public key, the public key metadata, padded). The sizes of both blocks are in the header. The hash is over the header and the auxiliary block; the signature is an RSA signature made over the same data (avbtool.py signs the header and auxiliary blocks with the hash the algorithm names).
The vbmeta header
| Offset | Size | Field | What it holds |
|---|---|---|---|
| 0 | 4 | magic | AVB0 |
| 4 | 4 + 4 | required_libavb_version_major, minor | The libavb version needed to read this image (1.x). |
| 12 | 8 | authentication_data_block_size | The size of the authentication block. |
| 20 | 8 | auxiliary_data_block_size | The size of the auxiliary block. |
| 28 | 4 | algorithm_type | See the table below. |
| 32 | 8 + 8 | hash_offset, hash_size | The hash, inside the authentication block. |
| 48 | 8 + 8 | signature_offset, signature_size | The signature, inside the authentication block. |
| 64 | 8 + 8 | public_key_offset, public_key_size | The public key, inside the auxiliary block. |
| 80 | 8 + 8 | public_key_metadata_offset, public_key_metadata_size | Data about the key; size 0 for none. |
| 96 | 8 + 8 | descriptors_offset, descriptors_size | The descriptors, inside the auxiliary block. |
| 112 | 8 | rollback_index | Prevents rolling back to an older image. |
| 120 | 4 | flags | Bit 0 HASHTREE_DISABLED, bit 1 VERIFICATION_DISABLED. Zero unless this is a top-level vbmeta. |
| 124 | 4 | rollback_index_location | Where the rollback index is stored (the main vbmeta only). |
| 128 | 48 | release_string | The avbtool version that wrote it, zero-ended, for example "avbtool 1.0.0". |
| 176 | 80 | reserved | Zero. The header is 256 bytes. |
Algorithm types
| Value | Name | Hash | Signature |
|---|---|---|---|
| 0 | NONE | none | none |
| 1 | SHA256_RSA2048 | SHA-256, 32 bytes | RSA-2048, 256 bytes |
| 2 | SHA256_RSA4096 | SHA-256, 32 bytes | RSA-4096, 512 bytes |
| 3 | SHA256_RSA8192 | SHA-256, 32 bytes | RSA-8192, 1024 bytes |
| 4 | SHA512_RSA2048 | SHA-512, 64 bytes | RSA-2048, 256 bytes |
| 5 | SHA512_RSA4096 | SHA-512, 64 bytes | RSA-4096, 512 bytes |
| 6 | SHA512_RSA8192 | SHA-512, 64 bytes | RSA-8192, 1024 bytes |
The authentication data block
The hash and the signature, at the offsets in the header, padded to a multiple of 64 bytes. The viewer works out the hash (SHA-256 or SHA-512 over the header and the auxiliary block, as the algorithm says) and reports whether it equals the stored one: that needs no key. The signature is never checked. Checking it needs a public key the verifier already trusts, and the key inside the image proves nothing, because anyone can sign an image with their own key. The viewer shows the signature's size and its first bytes.
The auxiliary data block
The descriptors, the public key and the public key metadata, at the offsets in the header, padded to a multiple of 64 bytes.
The public key
An RSA key in avbtool's encoding (AvbRSAPublicKeyHeader): the key size in bits (32-bit), n0inv (32-bit, −1 / n[0] mod 232), then the modulus n and rr (R squared mod n), each as many bytes as the key has bits divided by 8, big-endian. The viewer shows the size, n0inv and the start of both, and the SHA-256 of the whole encoded key (the value people compare when they pin a key).
Descriptors
Each descriptor starts with a 64-bit tag and a 64-bit count of the bytes that follow (a multiple of 8). Tags: 0 property, 1 hashtree, 2 hash, 3 kernel command line, 4 chain partition. The viewer shows each with its fields; for a tag libavb does not define it shows the tag and the length.
Property (tag 0)
Two 64-bit lengths (key, value), then the key and a zero byte, then the value and a zero byte.
Hash (tag 2)
After the 16-byte descriptor header: image_size (8), hash_algorithm (32, a zero-ended name such as sha256), partition_name_len, salt_len, digest_len, flags (4 each; bit 0 DO_NOT_USE_AB: no default A/B slot suffix), 60 reserved bytes, then the partition name, the salt and the digest. A boot image's vbmeta uses this one: the digest is of the salt followed by the image.
Hashtree (tag 1)
For partitions too large to hash whole (dm-verity): dm_verity_version (4), image_size (8), tree_offset (8), tree_size (8), data_block_size (4), hash_block_size (4), fec_num_roots (4), fec_offset (8), fec_size (8), hash_algorithm (32), partition_name_len, salt_len, root_digest_len, flags (4 each; bit 0 DO_NOT_USE_AB, bit 1 CHECK_AT_MOST_ONCE), 60 reserved, then the name, salt and root digest.
Kernel command line (tag 3)
flags (4; bit 0 use only if the hashtree is not disabled, bit 1 use only if it is) and the length (4), then the command-line text.
Chain partition (tag 4)
Hands a partition over to its own vbmeta signed with another key: rollback_index_location, partition_name_len, public_key_len, flags (4 each), 60 reserved, then the partition name and the public key.
What the viewer shows
For a file that starts with AVB0 (a vbmeta.img): the header, the authentication block (hash with its check, signature), the auxiliary block (each descriptor with its fields, the public key, the metadata) and, if the file ends in one, the footer. For an Android boot image or vendor boot image with a footer: the footer and the vbmeta image it points at, as nodes at the end. The sizes and offsets are checked against each other (hash and signature sizes against the algorithm, offsets inside their blocks, reserved bytes zero).
The explorer calls a file a vbmeta image when it starts with AVB0 and the required libavb version is 1.x. The .img row asks for it by magic. The footer is found by looking at the end of a boot image or vendor boot image; a bare partition image that is neither is not recognised by its footer (a footer is at the end of the file and the explorer's rows match at the start).
Tested on vbmeta images built to the layout (hash computed with Node's crypto and compared, every descriptor tag, tampered hash and size fields). No real vbmeta image was found among public test data: this rests on the header text and on avbtool.py's source, and not on a real file.
Not described
Known, not yet covered
- Viewer: the signature is never verified, and no key is trusted: by design.
- Reference and viewer: the hash and hashtree descriptors' digests are shown but not checked, since the partition they cover is not in a vbmeta file.
- Reference: the public key metadata (avbtool's certificate use), the permanent attributes and certificates of Android Things / the "AVB certificate" tooling, and the A/B slot rules are not described.
- Viewer: a bare partition image with a footer and nothing recognisable in front of it is not recognised from its footer.
Unknown
- Reference: how real devices' vbmeta images use flags and descriptors beyond the header text: no real image was available.
Links
Specifications
- Android Verified Boot 2.0 – the README of libavb
- avb_vbmeta_image.h – the vbmeta header (AOSP, permissive licence stated in the file)
- avb_footer.h – the footer
Software
- avbtool – makes, inspects and signs vbmeta images