Loading keymaster/4.0/IKeymasterDevice.hal +21 −4 Original line number Diff line number Diff line Loading @@ -374,10 +374,27 @@ interface IKeymasterDevice { /** * 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(); * Loading keymaster/4.0/support/include/keymasterV4_0/keymaster_tags.h +2 −0 Original line number Diff line number Diff line Loading @@ -356,6 +356,8 @@ inline bool operator==(const KeyParameter& a, const KeyParameter& b) { 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 */ Loading keymaster/4.0/types.hal +24 −0 Original line number Diff line number Diff line Loading @@ -219,6 +219,30 @@ enum Tag : uint32_t { 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 */ Loading Loading
keymaster/4.0/IKeymasterDevice.hal +21 −4 Original line number Diff line number Diff line Loading @@ -374,10 +374,27 @@ interface IKeymasterDevice { /** * 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(); * Loading
keymaster/4.0/support/include/keymasterV4_0/keymaster_tags.h +2 −0 Original line number Diff line number Diff line Loading @@ -356,6 +356,8 @@ inline bool operator==(const KeyParameter& a, const KeyParameter& b) { 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 */ Loading
keymaster/4.0/types.hal +24 −0 Original line number Diff line number Diff line Loading @@ -219,6 +219,30 @@ enum Tag : uint32_t { 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 */ Loading
