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