Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit f3d74174 authored by Shawn Willden's avatar Shawn Willden
Browse files

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
parent 384eb8a2

current.txt

+2 −2
Original line number Diff line number Diff line
@@ -619,9 +619,9 @@ db47f4ceceb1f06c656f39caa70c557b0f8471ef59fd58611bea667ffca20101 android.hardwar 
bbeee9604128ede83ee755b67e73b5ad29e6e1dbac9ec41fea6ffe2745b0c50a android.hardware.identity@1.0::IIdentityCredential

96ce8aad80f4c476f25261f790d357c117e79e18474c7dadd850dac704bbe65e android.hardware.identity@1.0::IIdentityCredentialStore

6e1e28a96c90ba78d47257faea3f3bb4e6360affbbfa5822f0dc31211f9266ff android.hardware.identity@1.0::IWritableIdentityCredential

c228aaa27f66c48e147159a4f4996c5273191fece1b08de31bd171c61334855e android.hardware.keymaster@4.1::IKeymasterDevice

27ae3724053940462114228872b3ffaf0b8e6177d5ba97f5a76339d12b8a99dd android.hardware.keymaster@4.1::IKeymasterDevice

adb0efdf1462e9b2e742c0dcadd598666aac551f178be06e755bfcdf5797abd0 android.hardware.keymaster@4.1::IOperation

7a04ea5595ed418ca3e91c28b8bd7353dd988be9be7b0c8c9e64fb4b77bd4523 android.hardware.keymaster@4.1::types

ac429fca0da4ce91218768ec31b64ded88251f8a26d8c4f27c06abdc5b1926d9 android.hardware.keymaster@4.1::types

9e59fffceed0dd72a9799e04505db5f777bbbea1af0695ba4107ef6d967c6fda android.hardware.neuralnetworks@1.3::IDevice

258825966435b3ed08832055bb736d81516013e405f161d9ccde9a90cfcdde83 android.hardware.neuralnetworks@1.3::IPreparedModel

94e803236398bed1febb11cc21051bc42ec003700139b099d6c479e02a7ca3c3 android.hardware.neuralnetworks@1.3::IPreparedModelCallback

keymaster/4.1/IKeymasterDevice.hal

+26 −1
Original line number Diff line number Diff line
@@ -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

keymaster/4.1/types.hal

+23 −6
Original line number Diff line number Diff line
@@ -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,

};