Updates to KM4.1

This CL adds:

- The IDENTITY_CREDENTIAL_KEY tag.  This new tag is not actually used
  by Keymaster at all.  It's used by the new Identity Credential HAL in
  its key attestations, which use the Keymaster format and the Keymaster
  attestation key.

- A VerificationToken argument to deviceLocked, used for StrongBox
  implementations.

- Some error codes, including one to diagnose unprovisioned
  attestation keys/ids.

- Clarifications in the documentation.

Test: VtsHalKeymasterV41TargetTest
Change-Id: Iae7151e2d9b328dd73e5cd78e59687ef29bab4f0
Merged-In: Iae7151e2d9b328dd73e5cd78e59687ef29bab4f0

2 files changed, 49 insertions, 7 deletions

diff --git a/keymaster/4.1/IKeymasterDevice.hal b/keymaster/4.1/IKeymasterDevice.hal
index 64d2c9fedd..1456abe038 100644
--- a/keymaster/4.1/IKeymasterDevice.hal
+++ b/keymaster/4.1/IKeymasterDevice.hal
@@ -22,6 +22,8 @@ import @4.0::IKeymasterDevice;
 import @4.0::KeyParameter;
 import @4.0::KeyPurpose;
 import @4.0::OperationHandle;
+import @4.0::VerificationToken;
+
 import IOperation;
 
 /**
@@ -31,6 +33,11 @@ import IOperation;
  * - Device-unique attestaion;
  * - Early boot only keys;
  * - Better cleanup of operations when clients die without completing or aborting them.
+ *
+ * @4.1::IKeymasterDevice::attestKey() must produce attestations with keymasterVersion 41.  An
+ * oversight in the original numbering left no room for minor versions, so starting with 4.1 the
+ * versions will be numbered as major_version * 10 + minor version.  The addition of new attestable
+ * tags changes the attestation format again, slightly, so the attestationVersion must be 4.
  */
 interface IKeymasterDevice extends @4.0::IKeymasterDevice {
     /**
@@ -42,10 +49,28 @@ interface IKeymasterDevice extends @4.0::IKeymasterDevice {
      * set to true the sufficiently-recent authentication token must indicate that the user
      * authenticated with a password, not a biometric.
      *
+     * Note that the IKeymasterDevice UNLOCKED_DEVICE_REQUIRED semantics are slightly different from
+     * the UNLOCKED_DEVICE_REQUIRED semantics enforced by keystore.  Keystore handles device locking
+     * on a per-user basis.  Because auth tokens do not contain an Android user ID, it's not
+     * possible to replicate the keystore enformcement logic in IKeymasterDevice.  So from the
+     * IKeymasterDevice perspective, any user unlock unlocks all UNLOCKED_DEVICE_REQUIRED keys.
+     * Keystore will continue enforcing the per-user device locking.
+     *
      * @param passwordOnly specifies whether the device must be unlocked with a password, rather
      * than a biometric, before UNLOCKED_DEVICE_REQUIRED keys can be used.
+     *
+     * @param verificationToken is used by StrongBox implementations of IKeymasterDevice.  It
+     * provides the StrongBox IKeymasterDevice with a fresh, MACed timestamp which it can use as the
+     * device-lock time, for future comparison against auth tokens when operations using
+     * UNLOCKED_DEVICE_REQUIRED keys are attempted.  Unless the auth token timestamp is newer than
+     * the timestamp in the verificationToken, the device is still considered to be locked.
+     * Crucially, if a StrongBox IKeymasterDevice receives a deviceLocked() call with a verification
+     * token timestamp that is less than the timestamp in the last deviceLocked() call, it must
+     * ignore the new timestamp.  TEE IKeymasterDevice implementations will receive an empty
+     * verificationToken (zero values and empty vectors) and should use their own clock as the
+     * device-lock time.
      */
-    deviceLocked(bool passwordOnly) generates (ErrorCode error);
+    deviceLocked(bool passwordOnly, VerificationToken verificationToken) generates (ErrorCode error);
 
     /**
      * Called by client to notify the IKeymasterDevice that the device has left the early boot
diff --git a/keymaster/4.1/types.hal b/keymaster/4.1/types.hal
index bdf173113f..9e8b30e590 100644
--- a/keymaster/4.1/types.hal
+++ b/keymaster/4.1/types.hal
@@ -26,17 +26,34 @@ enum Tag : @4.0::Tag {
      * IKeymasterDevice::earlyBootEnded() is called.
      */
     EARLY_BOOT_ONLY = TagType:BOOL | 305,
+
     /**
      * DEVICE_UNIQUE_ATTESTATION is an argument to IKeymasterDevice::attestKey().  It indicates that
-     * attestation using a device-unique key is requested, rather than a batch key.  Only
-     * SecurityLevel::STRONGBOX IKeymasterDevices may support device-unique attestations.
-     * SecurityLevel::TRUSTED_ENVIRONMENT IKeymasterDevices must return ErrorCode::INVALID_ARGUMENT
-     * if they receive DEVICE_UNIQUE_ATTESTATION.  SecurityLevel::STRONGBOX IKeymasterDevices need
-     * not support DEVICE_UNIQUE_ATTESTATION, and return ErrorCode::CANNOT_ATTEST_IDS if they do not
-     * support it.
+     * attestation using a device-unique key is requested, rather than a batch key.  When a
+     * device-unique key is used, only the attestation certificate is returned; no additional
+     * chained certificates are provided.  It's up to the caller to recognize the device-unique
+     * signing key.  Only SecurityLevel::STRONGBOX IKeymasterDevices may support device-unique
+     * attestations.  SecurityLevel::TRUSTED_ENVIRONMENT IKeymasterDevices must return
+     * ErrorCode::INVALID_ARGUMENT if they receive DEVICE_UNIQUE_ATTESTATION.
+     * SecurityLevel::STRONGBOX IKeymasterDevices need not support DEVICE_UNIQUE_ATTESTATION, and
+     * return ErrorCode::CANNOT_ATTEST_IDS if they do not support it.
      *
      * IKeymasterDevice implementations that support device-unique attestation MUST add the
      * DEVICE_UNIQUE_ATTESTATION tag to device-unique attestations.
      */
     DEVICE_UNIQUE_ATTESTATION = TagType:BOOL | 720,
+
+    /**
+     * IDENTITY_CREDENTIAL_KEY is never used by IKeymasterDevice, is not a valid argument to key
+     * generation or any operation, is never returned by any method and is never used in a key
+     * attestation.  It is used in attestations produced by the IIdentityCredential HAL when that
+     * HAL attests to Credential Keys.  IIdentityCredential produces Keymaster-style attestations.
+     */
+    IDENTITY_CREDENTIAL_KEY = TagType:BOOL | 721,
+};
+
+enum ErrorCode : @4.0::ErrorCode {
+    EARLY_BOOT_ENDED = -73,
+    ATTESTATION_KEYS_NOT_PROVISIONED = -74,
+    ATTESTATION_IDS_NOT_PROVISIONED = -75,
 };