[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["缺少我需要的資訊","missingTheInformationINeed","thumb-down"],["過於複雜/步驟過多","tooComplicatedTooManySteps","thumb-down"],["過時","outOfDate","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["示例/程式碼問題","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-07-27 (世界標準時間)。"],[],[],null,["# Version binding\n\nIn Keymaster 1, all Keymaster keys were cryptographically bound to the device\n*Root of Trust*, or the Verified Boot key. In Keymaster 2 and 3, all\nkeys are also bound to the operating system and patch level of the system image.\nThis ensures that an attacker who discovers a weakness in an old\nversion of system or TEE software cannot roll a device back to the vulnerable\nversion and use keys created with the newer version. In addition, when a key\nwith a given version and patch level is used on a device that has been upgraded\nto a newer version or patch level, the key is upgraded before it can be used,\nand the previous version of the key invalidated. In this way, as the device is\nupgraded, the keys \\*ratchet\\* forward along with the device, but any\nreversion of the device to a previous release causes the keys to be\nunusable.\n\n\nTo support Treble's modular structure and break the binding of system.img to\nboot.img, Keymaster 4 changed the key version binding model to have separate\npatch levels for each partition. This allows each partition to be updated\nindependently, while still providing rollback protection.\n\nTo implement this version binding, the KeyMint trusted app (TA) needs a way to securely\nreceive the current OS version and patch levels, and to\nensure that the information it receives matches all the information about\nthe running system.\n\n- Devices with Android Verified Boot (AVB) can put all of the patch levels and the system version in vbmeta, so the bootloader can provide them to Keymaster. For chained partitions, the version info for the partition is in the chained vbmeta. In general, version information should be in the `vbmeta struct` that contains the verification data (hash or hashtree) for a given partition.\n- On devices without AVB:\n - Verified Boot implementations need to provide a hash of the version metadata to bootloader, so that bootloader can provide the hash to Keymaster.\n - `boot.img` can continue storing patch level in the header\n - `system.img` can continue storing patch level and OS version in read-only properties\n - `vendor.img` stores the patch level in the read-only property `ro.vendor.build.version.security_patch`.\n - The bootloader can provide a hash of all data validated by Verified Boot to Keymaster.\n- In Android 9, use the following tags to supply version information for the following partitions:\n - `VENDOR_PATCH_LEVEL`: `vendor` partition\n - `BOOT_PATCH_LEVEL`: `boot` partition\n - `OS_PATCH_LEVEL` and `OS_VERSION`: `system` partition. (`OS_VERSION` is removed from the `boot.img` header.\n- Keymaster implementations should treat all patch levels independently. Keys are usable if all version info matches the values associated with a key, and `IKeymaster::upgradeDevice()` rolls to a higher patch level if needed.\n\nHAL changes\n-----------\n\nTo support version binding and version attestation, Android 7.1 added the\ntags `Tag::OS_VERSION` and `Tag::OS_PATCHLEVEL` and the\nmethods `configure` and `upgradeKey`. The version tags\nare automatically added by Keymaster 2+ implementations to all newly generated\n(or updated) keys. Further, any attempt to use a key that doesn't have an OS\nversion or patch level matching the current system OS version or patch level,\nrespectively, is rejected with `ErrorCode::KEY_REQUIRES_UPGRADE`.\n\n\n`Tag::OS_VERSION` is a `UINT` value that represents the\nmajor, minor, and sub-minor portions of an Android system version as MMmmss,\nwhere MM is the major version, mm is the minor version and ss is the sub-minor\nversion. For example 6.1.2 would be represented as 060102.\n\n\n`Tag::OS_PATCHLEVEL` is a `UINT` value that represents the\nyear and month of the last update to the system as YYYYMM, where YYYY is the\nfour-digit year and MM is the two-digit month. For example, March 2016 would be\nrepresented as 201603.\n\n### UpgradeKey\n\n\nTo allow keys to be upgraded to the new OS version and patch level of the system\nimage, Android 7.1 added the `upgradeKey` method to the HAL:\n\n**Keymaster 3** \n\n```\n upgradeKey(vec keyBlobToUpgrade, vec upgradeParams)\n generates(ErrorCode error, vec upgradedKeyBlob);\n```\n\n**Keymaster 2** \n\n```\nkeymaster_error_t (*upgrade_key)(const struct keymaster2_device* dev,\n const keymaster_key_blob_t* key_to_upgrade,\n const keymaster_key_param_set_t* upgrade_params,\n keymaster_key_blob_t* upgraded_key);\n```\n\n- `dev` is the device structure\n- `keyBlobToUpgrade` is the key which needs to be upgraded\n- `upgradeParams` are parameters needed to upgrade the key. These include `Tag::APPLICATION_ID` and `Tag::APPLICATION_DATA`, which are necessary to decrypt the key blob, if they were provided during generation.\n- `upgradedKeyBlob` is the output parameter, used to return the new key blob.\n\n\nIf `upgradeKey` is called with a key blob that cannot be parsed or\nis otherwise invalid, it returns `ErrorCode::INVALID_KEY_BLOB`. If it\nis called with a key whose patch level is greater than the current system value,\nit returns `ErrorCode::INVALID_ARGUMENT`. If it is called with a key\nwhose OS version is greater than the current system value, and the system value\nis non-zero, it returns `ErrorCode::INVALID_ARGUMENT`. OS version\nupgrades from non-zero to zero are allowed. In the event of errors\ncommunicating with the secure world, it returns an appropriate error value (for example,\n`ErrorCode::SECURE_HW_ACCESS_DENIED`,\n`ErrorCode::SECURE_HW_BUSY`). Otherwise, it returns\n`ErrorCode::OK` and returns a new key blob in\n`upgradedKeyBlob`.\n\n\n`keyBlobToUpgrade` remains valid after the `upgradeKey`\ncall, and could theoretically be used again if the device were downgraded. In\npractice, keystore generally calls `deleteKey` on the\n`keyBlobToUpgrade` blob shortly after the call to\n`upgradeKey`. If `keyBlobToUpgrade` had tag\n`Tag::ROLLBACK_RESISTANT`, then `upgradedKeyBlob` should\nhave it as well (and should be rollback resistant).\n\nSecure configuration\n--------------------\n\n| **Note:** Keymaster 3 removed the Keymaster 2 method `configure`. The information previously provided to Keymaster HALs through `configure` is available in system properties files, and manufacturer implementations read those files during startup.\n\n\nTo implement version binding, the Keymaster TA needs a way to securely receive\nthe current OS version and patch level (version information), and to ensure that\nthe information it receives strongly matches the information about the running\nsystem.\n\n\nTo support secure delivery of version information to the TA, an [`OS_VERSION`\nfield](https://android.googlesource.com/platform/system/core/+/android-4.4_r1/mkbootimg/bootimg.h#48) has been added to the boot image header. The boot image build\nscript automatically populates this field. OEMs and Keymaster TA implementers\nneed to work together to modify device bootloaders to extract the version\ninformation from the boot image and pass it to the TA before the non-secure\nsystem is booted. This ensures that attackers cannot interfere with provisioning\nof version information to the TA.\n\n\nIt is also necessary to ensure that the system image has the same version\ninformation as the boot image. To that end, the configure method has been added\nto the Keymaster HAL: \n\n```\nkeymaster_error_t (*configure)(const struct keymaster2_device* dev,\n const keymaster_key_param_set_t* params);\n```\n\n\nThe `params` argument contains `Tag::OS_VERSION` and\n`Tag::OS_PATCHLEVEL`. This method is called by keymaster2 clients\nafter opening the HAL, but before calling any other methods. If any other method\nis called before configure, the TA returns\n`ErrorCode::KEYMASTER_NOT_CONFIGURED`.\n\n\nThe first time `configure` is called after the device boots, it\nshould verify that the version information provided matches what was provided by\nthe bootloader. If the version information doesn't match,\n`configure` returns `ErrorCode::INVALID_ARGUMENT`, and all\nother Keymaster methods continue returning\n`ErrorCode::KEYMASTER_NOT_CONFIGURED`. If the information matches,\n`configure` returns `ErrorCode::OK`, and other Keymaster\nmethods begin functioning normally.\n\n\nSubsequent calls to `configure` return the same value returned by the\nfirst call, and don't change the state of Keymaster.\n| **Note:** This process requires that all OTAs update both system and boot images; they can't be updated separately to keep the version information in sync.\n\n\nBecause `configure` is called by the system whose contents it is\nintended to validate, there is a narrow window of opportunity for an attacker to\ncompromise the system image and force it to provide version information that\nmatches the boot image, but which isn't the actual version of the system. The\ncombination of boot image verification, dm-verity validation of the system image\ncontents, and the fact that `configure` is called very early in the\nsystem boot should make this window of opportunity difficult to exploit."]]
