Add support for BOOT and VENDOR patch levels to keymaster.
Bug: 68250869
Test: Manual. VTS testing is not possible.
Change-Id: Ifa2025ce31592dbeb274ee3a2c300a7de416ae1f
diff --git a/keymaster/4.0/IKeymasterDevice.hal b/keymaster/4.0/IKeymasterDevice.hal
index 5dac929..aef81c7 100644
--- a/keymaster/4.0/IKeymasterDevice.hal
+++ b/keymaster/4.0/IKeymasterDevice.hal
@@ -374,10 +374,27 @@
/**
* Upgrades an old key blob. Keys can become "old" in two ways: Keymaster can be upgraded to a
* new version with an incompatible key blob format, or the system can be updated to invalidate
- * the OS version and/or patch level. In either case, attempts to use an old key blob with
- * getKeyCharacteristics(), exportKey(), attestKey() or begin() must result in Keymaster
- * returning ErrorCode::KEY_REQUIRES_UPGRADE. The caller must use this method to upgrade the
- * key blob.
+ * the OS version (OS_VERSION tag), system patch level (OS_PATCHLEVEL tag), vendor patch level
+ * (VENDOR_PATCH_LEVEL tag), boot patch level (BOOT_PATCH_LEVEL tag) or other,
+ * implementation-defined patch level (keymaster implementers are encouraged to extend this HAL
+ * with a minor version extension to define validatable patch levels for other images; tags
+ * must be defined in the implemeter's namespace, starting at 10000). In either case,
+ * attempts to use an old key blob with getKeyCharacteristics(), exportKey(), attestKey() or
+ * begin() must result in Keymaster returning ErrorCode::KEY_REQUIRES_UPGRADE. The caller must
+ * use this method to upgrade the key blob.
+ *
+ * If upgradeKey is asked to update a key with any version or patch level that is higher than
+ * the current system version or patch level, it must return ErrorCode::INVALID_ARGUMENT. There
+ * is one exception: it is always permissible to "upgrade" from any OS_VERSION number to
+ * OS_VERSION 0. For example, if the key has OS_VERSION 080001, it is permisible to upgrade the
+ * key if the current system version is 080100, because the new version is larger, or if the
+ * current system version is 0, because upgrades to 0 are always allowed. If the system version
+ * were 080000, however, keymaster must return ErrorCode::INVALID_ARGUMENT because that value is
+ * smaller than 080001.
+ *
+ * Note that Keymaster versions 2 and 3 required that the system and boot images have the same
+ * patch level and OS version. This requirement is relaxed for Keymaster 4, and the OS version
+ * in the boot image footer is no longer used.
*
* @param keyBlobToUpgrade The opaque descriptor returned by generateKey() or importKey();
*
diff --git a/keymaster/4.0/support/include/keymasterV4_0/keymaster_tags.h b/keymaster/4.0/support/include/keymasterV4_0/keymaster_tags.h
index 73e03fb..0dfc735 100644
--- a/keymaster/4.0/support/include/keymasterV4_0/keymaster_tags.h
+++ b/keymaster/4.0/support/include/keymasterV4_0/keymaster_tags.h
@@ -356,6 +356,8 @@
case Tag::OS_PATCHLEVEL:
case Tag::MAC_LENGTH:
case Tag::AUTH_TIMEOUT:
+ case Tag::VENDOR_PATCHLEVEL:
+ case Tag::BOOT_PATCHLEVEL:
return a.f.integer == b.f.integer;
/* Long integer tags */
diff --git a/keymaster/4.0/types.hal b/keymaster/4.0/types.hal
index e890c6d..5714c4d 100644
--- a/keymaster/4.0/types.hal
+++ b/keymaster/4.0/types.hal
@@ -219,6 +219,30 @@
ATTESTATION_ID_MODEL = TagType:BYTES | 717, /* Used to provide the device's model name to be
* included in attestation */
+ /**
+ * Patch level of vendor image. The value is an integer of the form YYYYMM, where YYYY is the
+ * four-digit year when the vendor image was released and MM is the two-digit month. During
+ * each boot, the bootloader must provide the patch level of the vendor image to keymaser
+ * (mechanism is implemntation-defined). When keymaster keys are created or updated, the
+ * VENDOR_PATCHLEVEL tag must be cryptographically bound to the keys, with the current value as
+ * provided by the bootloader. When keys are used, keymaster must verify that the
+ * VENDOR_PATCHLEVEL bound to the key matches the current value. If they do not match,
+ * keymaster must return ErrorCode::KEY_REQUIRES_UPGRADE. The client must then call upgradeKey.
+ */
+ VENDOR_PATCHLEVEL = TagType:UINT | 718,
+
+ /**
+ * Patch level of boot image. The value is an integer of the form YYYYMM, where YYYY is the
+ * four-digit year when the boot image was released and MM is the two-digit month. During each
+ * boot, the bootloader must provide the patch level of the boot image to keymaser (mechanism is
+ * implemntation-defined). When keymaster keys are created or updated, the BOOT_PATCHLEVEL tag
+ * must be cryptographically bound to the keys, with the current value as provided by the
+ * bootloader. When keys are used, keymaster must verify that the BOOT_PATCHLEVEL bound to the
+ * key matches the current value. If they do not match, keymaster must return
+ * ErrorCode::KEY_REQUIRES_UPGRADE. The client must then call upgradeKey.
+ */
+ BOOT_PATCHLEVEL = TagType:UINT | 719,
+
/* Tags used only to provide data to or receive data from operations */
ASSOCIATED_DATA = TagType:BYTES | 1000, /* Used to provide associated data for AEAD modes. */
NONCE = TagType:BYTES | 1001, /* Nonce or Initialization Vector */