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 level for each partition. The OS version and the security 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_ -> '2022-02-05'
  • com.android.build.vendor.os_version -> '12'
  • com.android.build.vendor.security_ -> '2022-02-05'
  • com.android.build.boot.os_version -> '12'
  • com.android.build.boot.security_ -> '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 , 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_ is YYYY-MM-DD.

By default the build system generates com.android.build.${partition}.security_ for the system, system_ext, and product partitions. The device manufacturer is expected to set BOOT_SECURITY_, VENDOR_SECURITY_, and other es, for nonsystem partitions. For example:

  • BOOT_SECURITY_ := 2022-01-05 generates
    • com.android.build.boot.security_ -> '2022-01-05'
  • VENDOR_SECURITY_ := 2022-02-05 generates
    • com.android.build.vendor.security_ -> '2022-02-05'

The device manufacturer can set *_SECURITY_ to $(PLATFORM_SECURITY_) if it always updates all partitions to the version with the same security level.

  • BOOT_SECURITY_ := $(PLATFORM_SECURITY_)
  • VENDOR_SECURITY_ := $(PLATFORM_SECURITY_)

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 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  level.
// For version "A.B.C" and  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;