1 // Copyright 2020, The Android Open Source Project 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 package android.security.authorization; 16 17 import android.hardware.security.keymint.HardwareAuthToken; 18 import android.security.authorization.LockScreenEvent; 19 import android.security.authorization.AuthorizationTokens; 20 21 // TODO: mark the interface with @SensitiveData when the annotation is ready (b/176110256). 22 23 /** 24 * IKeystoreAuthorization interface exposes the methods for other system components to 25 * provide keystore with the information required to enforce authorizations on key usage. 26 * @hide 27 */ 28 @SensitiveData 29 interface IKeystoreAuthorization { 30 /** 31 * Allows the Android authenticators to hand over an auth token to Keystore. 32 * Callers require 'AddAuth' permission. 33 * ## Error conditions: 34 * `ResponseCode::PERMISSION_DENIED` - if the callers do not have the 'AddAuth' permission. 35 * `ResponseCode::SYSTEM_ERROR` - if failed to store the auth token in the database or if failed 36 * to add the auth token to the operation, if it is a per-op auth token. 37 * 38 * @param authToken The auth token created by an authenticator, upon user authentication. 39 */ addAuthToken(in HardwareAuthToken authToken)40 void addAuthToken(in HardwareAuthToken authToken); 41 42 /** 43 * Unlocks the keystore for the given user id. 44 * Callers require 'Unlock' permission. 45 * If a password was set, a password must be given on unlock or the operation fails. 46 * 47 * ## Error conditions: 48 * `ResponseCode::PERMISSION_DENIED` - if the callers do not have the 'Unlock' permission. 49 * `ResponseCode::SYSTEM_ERROR` - if failed to perform lock/unlock operations due to various 50 * `ResponseCode::VALUE_CORRUPTED` - if the super key can not be decrypted. 51 * `ResponseCode::KEY_NOT_FOUND` - if the super key is not found. 52 * 53 * @lockScreenEvent - Indicates what happened. 54 * * LockScreenEvent.UNLOCK if the screen was unlocked. 55 * * LockScreenEvent.LOCK if the screen was locked. 56 * 57 * @param userId - Android user id 58 * 59 * @param password - synthetic password derived by the user denoted by the user id 60 * 61 * @param unlockingSids - list of biometric SIDs for this user. This will be null when 62 * lockScreenEvent is UNLOCK, but may be non-null when 63 * lockScreenEvent is LOCK. 64 * 65 * When the device is unlocked, Keystore stores in memory 66 * a super-encryption key that protects UNLOCKED_DEVICE_REQUIRED 67 * keys; this key is wiped from memory when the device is locked. 68 * 69 * If unlockingSids is non-empty on lock, then before the 70 * super-encryption key is wiped from memory, a copy of it 71 * is stored in memory encrypted with a fresh AES key. 72 * This key is then imported into KM, tagged such that it can be 73 * used given a valid, recent auth token for any of the 74 * unlockingSids. 75 * 76 * Then, when the device is unlocked again, if a suitable auth token 77 * has been sent to keystore, it is used to recover the 78 * super-encryption key, so that UNLOCKED_DEVICE_REQUIRED keys can 79 * be used once again. 80 */ onLockScreenEvent(in LockScreenEvent lockScreenEvent, in int userId, in @nullable byte[] password, in @nullable long[] unlockingSids)81 void onLockScreenEvent(in LockScreenEvent lockScreenEvent, in int userId, 82 in @nullable byte[] password, in @nullable long[] unlockingSids); 83 84 /** 85 * Allows Credstore to retrieve a HardwareAuthToken and a TimestampToken. 86 * Identity Credential Trusted App can run either in the TEE or in other secure Hardware. 87 * So, credstore always need to retrieve a TimestampToken along with a HardwareAuthToken. 88 * 89 * The passed in |challenge| parameter must always be non-zero. 90 * 91 * The returned TimestampToken will always have its |challenge| field set to 92 * the |challenge| parameter. 93 * 94 * This method looks through auth-tokens cached by keystore which match 95 * the passed-in |secureUserId|. 96 * The most recent matching auth token which has a |challenge| field which matches 97 * the passed-in |challenge| parameter is returned. 98 * In this case the |authTokenMaxAgeMillis| parameter is not used. 99 * 100 * Otherwise, the most recent matching auth token which is younger 101 * than |authTokenMaxAgeMillis| is returned. 102 * 103 * This method is called by credstore (and only credstore). 104 * 105 * The caller requires 'get_auth_token' permission. 106 * 107 * ## Error conditions: 108 * `ResponseCode::PERMISSION_DENIED` - if the caller does not have the 'get_auth_token' 109 * permission. 110 * `ResponseCode::SYSTEM_ERROR` - if failed to obtain an authtoken from the database. 111 * `ResponseCode::NO_AUTH_TOKEN_FOUND` - a matching auth token is not found. 112 * `ResponseCode::INVALID_ARGUMENT` - if the passed-in |challenge| parameter is zero. 113 */ getAuthTokensForCredStore(in long challenge, in long secureUserId, in long authTokenMaxAgeMillis)114 AuthorizationTokens getAuthTokensForCredStore(in long challenge, in long secureUserId, 115 in long authTokenMaxAgeMillis); 116 } 117