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. For example:

  • 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 using avb_property_lookup(). Multiple vbmeta images can be loaded by avb_slot_verify() and are stored in the AvbSlotVerifyData** out_data output parameter.

The default format of the version information

By default, the Android build system uses 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], for example, 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 generates com.android.build.${partition}.security_patch for the system, system_ext, and product partitions. The device manufacturer is expected to set BOOT_SECURITY_PATCH, VENDOR_SECURITY_PATCH, and other patches, for nonsystem partitions. For example:

  • 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 always updates all partitions to the version with the same security patch level.

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

Specify custom version information

Starting in Android 13, each device build can have a custom value for the OS version that can be recognized by the device bootloader. For example:

  • 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;