Version Information in AVB properties

To support Keymaster version binding, the device bootloader is expected to provide the operating system (OS) version and the security patch level for each partition. The OS version and the security patch level are two separate key -> value pairs in the AVB properties. e.g.,

  • com.android.build.system.os_version -> '12'
  • com.android.build.system.security_patch -> '2022-02-05'
  • com.android.build.vendor.os_version -> '12'
  • com.android.build.vendor.security_patch -> '2022-02-05'
  • com.android.build.boot.os_version -> '12'
  • com.android.build.boot.security_patch -> '2022-02-05'

The device bootloader can get those AVB properties from a vbmeta image via avb_property_lookup(). Multiple vbmeta images can be loaded by avb_slot_verify() and will be stored in the AvbSlotVerifyData** out_data output parameter.

The default format of the version information

By default, the Android build system will use the following format for the OS version and the security patch, respectively.

The format of com.android.build.${partition}.os_version is A[.B.C], e.g., '12' or '12.0.0':

  • A: major version
  • B: minor version, defaults to zero when it is absent
  • C: sub-minor version, defaults to zero when it is absent

The format of com.android.build.${partition}.security_patch is YYYY-MM-DD.

By default the build system will only generate com.android.build.${partition}.security_patch for system, system_ext and product partitions. The device manufacturer is expected to set BOOT_SECURITY_PATCH, VENDOR_SECURITY_PATCH, etc., for non-system partitions. e.g.,

  • BOOT_SECURITY_PATCH := 2022-01-05 generates
    • com.android.build.boot.security_patch -> '2022-01-05'
  • VENDOR_SECURITY_PATCH := 2022-02-05 generates
    • com.android.build.vendor.security_patch -> '2022-02-05'

The device manufacturer can set *_SECURITY_PATCH to $(PLATFORM_SECURITY_PATCH) if it will always update all partitions to the version with the same security patch level.

  • BOOT_SECURITY_PATCH := $(PLATFORM_SECURITY_PATCH)
  • VENDOR_SECURITY_PATCH := $(PLATFORM_SECURITY_PATCH)

Specifying custom version information

Starting from Android 13, each device build can have a custom value for the OS version that can be recognized by the device bootloader. e.g.,

  • SYSTEM_OS_VERSION := 12.0.0 generates
    • com.android.build.system.os_version -> '12.0.0'
  • BOOT_OS_VERSION := a.b.c generates
    • com.android.build.boot.os_version -> 'a.b.c'
  • VENDOR_OS_VERSION := 12.0.1 generates
    • com.android.build.vendor.os_version -> '12.0.1'

The obsolete version information in the boot image header

Starting from Android 9, Keymaster version binding suggests removing os_version from the boot.img header.

For comparison, the obsolete usage of obtaining the version information from the boot image header is also described here. Note that the os_version field in the boot header combines both OS version and security patch level into a 32-bit unsigned integer. And this mechanism assumes that all images will be updated together, which is obsolete after partition modularization in Project Treble.

// Operating system version and security patch level.
// For version "A.B.C" and patch level "Y-M-D":
//   (7 bits for each of A, B, C; 7 bits for (Y-2000), 4 bits for M)
//   A = os_version[31:25]
//   B = os_version[24:18]
//   C = os_version[17:11]
//   Y = 2000 + os_version[10:4]
//   M = os-version[3:0]

uint32_t os_version;