1/* 2 * Copyright (C) 2019 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.hardware.keymaster@4.1; 18 19import @4.0::ErrorCode; 20import @4.0::HardwareAuthToken; 21import @4.0::IKeymasterDevice; 22import @4.0::KeyParameter; 23import @4.0::KeyPurpose; 24import @4.0::OperationHandle; 25import @4.0::VerificationToken; 26 27/** 28 * @4.1::IKeymasterDevice is a minor extension to @4.0::IKeymasterDevice. It adds support for 29 * 30 * - Partial hardware enforcment of UNLOCKED_DEVICE_REQUIRED keys; 31 * - Device-unique attestaion; 32 * - Early boot only keys; 33 * - Better cleanup of operations when clients die without completing or aborting them. 34 * 35 * @4.1::IKeymasterDevice::attestKey() must produce attestations with keymasterVersion 41. An 36 * oversight in the original numbering left no room for minor versions, so starting with 4.1 the 37 * versions will be numbered as major_version * 10 + minor version. The addition of new attestable 38 * tags changes the attestation format again, slightly, so the attestationVersion must be 4. 39 */ 40@SensitiveData 41interface IKeymasterDevice extends @4.0::IKeymasterDevice { 42 /** 43 * Called by client to notify the IKeymasterDevice that the device is now locked, and keys with 44 * the UNLOCKED_DEVICE_REQUIRED tag should no longer be usable. When this function is called, 45 * the IKeymasterDevice should note the current timestamp, and attempts to use 46 * UNLOCKED_DEVICE_REQUIRED keys must be rejected with Error::DEVICE_LOCKED until an 47 * authentication token with a later timestamp is presented. If the `passwordOnly' argument is 48 * set to true the sufficiently-recent authentication token must indicate that the user 49 * authenticated with a password, not a biometric. 50 * 51 * Note that the IKeymasterDevice UNLOCKED_DEVICE_REQUIRED semantics are slightly different from 52 * the UNLOCKED_DEVICE_REQUIRED semantics enforced by keystore. Keystore handles device locking 53 * on a per-user basis. Because auth tokens do not contain an Android user ID, it's not 54 * possible to replicate the keystore enformcement logic in IKeymasterDevice. So from the 55 * IKeymasterDevice perspective, any user unlock unlocks all UNLOCKED_DEVICE_REQUIRED keys. 56 * Keystore will continue enforcing the per-user device locking. 57 * 58 * @param passwordOnly specifies whether the device must be unlocked with a password, rather 59 * than a biometric, before UNLOCKED_DEVICE_REQUIRED keys can be used. 60 * 61 * @param verificationToken is used by StrongBox implementations of IKeymasterDevice. It 62 * provides the StrongBox IKeymasterDevice with a fresh, MACed timestamp which it can use as the 63 * device-lock time, for future comparison against auth tokens when operations using 64 * UNLOCKED_DEVICE_REQUIRED keys are attempted. Unless the auth token timestamp is newer than 65 * the timestamp in the verificationToken, the device is still considered to be locked. 66 * Crucially, if a StrongBox IKeymasterDevice receives a deviceLocked() call with a verification 67 * token timestamp that is less than the timestamp in the last deviceLocked() call, it must 68 * ignore the new timestamp. TEE IKeymasterDevice implementations will receive an empty 69 * verificationToken (zero values and empty vectors) and should use their own clock as the 70 * device-lock time. 71 */ 72 deviceLocked(bool passwordOnly, VerificationToken verificationToken) generates (ErrorCode error); 73 74 /** 75 * Called by client to notify the IKeymasterDevice that the device has left the early boot 76 * state, and that keys with the EARLY_BOOT_ONLY tag may no longer be used. All attempts to use 77 * an EARLY_BOOT_ONLY key after this method is called must fail with Error::INVALID_KEY_BLOB. 78 */ 79 earlyBootEnded() generates (ErrorCode error); 80}; 81