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
generatescom.android.build.boot.security_patch -> '2022-01-05'
VENDOR_SECURITY_PATCH := 2022-02-05
generatescom.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
generatescom.android.build.system.os_version -> '12.0.0'
BOOT_OS_VERSION := a.b.c
generatescom.android.build.boot.os_version -> 'a.b.c'
VENDOR_OS_VERSION := 12.0.1
generatescom.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;