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 */
40interface IKeymasterDevice extends @4.0::IKeymasterDevice {
41    /**
42     * Called by client to notify the IKeymasterDevice that the device is now locked, and keys with
43     * the UNLOCKED_DEVICE_REQUIRED tag should no longer be usable.  When this function is called,
44     * the IKeymasterDevice should note the current timestamp, and attempts to use
45     * UNLOCKED_DEVICE_REQUIRED keys must be rejected with Error::DEVICE_LOCKED until an
46     * authentication token with a later timestamp is presented.  If the `passwordOnly' argument is
47     * set to true the sufficiently-recent authentication token must indicate that the user
48     * authenticated with a password, not a biometric.
49     *
50     * Note that the IKeymasterDevice UNLOCKED_DEVICE_REQUIRED semantics are slightly different from
51     * the UNLOCKED_DEVICE_REQUIRED semantics enforced by keystore.  Keystore handles device locking
52     * on a per-user basis.  Because auth tokens do not contain an Android user ID, it's not
53     * possible to replicate the keystore enformcement logic in IKeymasterDevice.  So from the
54     * IKeymasterDevice perspective, any user unlock unlocks all UNLOCKED_DEVICE_REQUIRED keys.
55     * Keystore will continue enforcing the per-user device locking.
56     *
57     * @param passwordOnly specifies whether the device must be unlocked with a password, rather
58     * than a biometric, before UNLOCKED_DEVICE_REQUIRED keys can be used.
59     *
60     * @param verificationToken is used by StrongBox implementations of IKeymasterDevice.  It
61     * provides the StrongBox IKeymasterDevice with a fresh, MACed timestamp which it can use as the
62     * device-lock time, for future comparison against auth tokens when operations using
63     * UNLOCKED_DEVICE_REQUIRED keys are attempted.  Unless the auth token timestamp is newer than
64     * the timestamp in the verificationToken, the device is still considered to be locked.
65     * Crucially, if a StrongBox IKeymasterDevice receives a deviceLocked() call with a verification
66     * token timestamp that is less than the timestamp in the last deviceLocked() call, it must
67     * ignore the new timestamp.  TEE IKeymasterDevice implementations will receive an empty
68     * verificationToken (zero values and empty vectors) and should use their own clock as the
69     * device-lock time.
70     */
71    deviceLocked(bool passwordOnly, VerificationToken verificationToken) generates (ErrorCode error);
72
73    /**
74     * Called by client to notify the IKeymasterDevice that the device has left the early boot
75     * state, and that keys with the EARLY_BOOT_ONLY tag may no longer be used.  All attempts to use
76     * an EARLY_BOOT_ONLY key after this method is called must fail with Error::INVALID_KEY_BLOB.
77     */
78    earlyBootEnded() generates (ErrorCode error);
79};
80