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.hardware.security.keymint.HardwareAuthenticatorType; 19 import android.security.authorization.AuthorizationTokens; 20 21 /** 22 * IKeystoreAuthorization interface exposes the methods for other system components to 23 * provide keystore with the information required to enforce authorizations on key usage. 24 * @hide 25 */ 26 @SensitiveData 27 interface IKeystoreAuthorization { 28 /** 29 * Allows the Android authenticators to hand over an auth token to Keystore. 30 * Callers require 'AddAuth' permission. 31 * ## Error conditions: 32 * `ResponseCode::PERMISSION_DENIED` - if the callers do not have the 'AddAuth' permission. 33 * `ResponseCode::SYSTEM_ERROR` - if failed to store the auth token in the database or if failed 34 * to add the auth token to the operation, if it is a per-op auth token. 35 * 36 * @param authToken The auth token created by an authenticator, upon user authentication. 37 */ addAuthToken(in HardwareAuthToken authToken)38 void addAuthToken(in HardwareAuthToken authToken); 39 40 /** 41 * Tells Keystore that the device is now unlocked for a user. Requires the 'Unlock' permission. 42 * 43 * This method makes Keystore start allowing the use of the given user's keys that require an 44 * unlocked device, following the device boot or an earlier call to onDeviceLocked() which 45 * disabled the use of such keys. In addition, once per boot, this method must be called with a 46 * password before keys that require user authentication can be used. 47 * 48 * This method does two things to restore access to UnlockedDeviceRequired keys. First, it sets 49 * a flag that indicates the user is unlocked. This is always done, and it makes Keystore's 50 * logical enforcement of UnlockedDeviceRequired start passing. Second, it recovers and caches 51 * the user's UnlockedDeviceRequired super keys. This succeeds only in the following cases: 52 * 53 * - The (correct) password is provided, proving that the user has authenticated using LSKF or 54 * equivalent. This is the most powerful type of unlock. Keystore uses the password to 55 * decrypt the user's UnlockedDeviceRequired super keys from disk. It also uses the password 56 * to decrypt the user's AfterFirstUnlock super key from disk, if not already done. 57 * 58 * - The user's UnlockedDeviceRequired super keys are cached in biometric-encrypted form, and a 59 * matching valid HardwareAuthToken has been added to Keystore. I.e., class 3 biometric 60 * unlock is enabled and the user recently authenticated using a class 3 biometric. The keys 61 * are cached in biometric-encrypted form if onDeviceLocked() was called with a nonempty list 62 * of unlockingSids, and onNonLskfUnlockMethodsExpired() was not called later. 63 * 64 * - The user's UnlockedDeviceRequired super keys are already cached in plaintext. This is the 65 * case if onDeviceLocked() was called with weakUnlockEnabled=true, and 66 * onWeakUnlockMethodsExpired() was not called later. This case provides only 67 * Keystore-enforced logical security for UnlockedDeviceRequired. 68 * 69 * ## Error conditions: 70 * `ResponseCode::PERMISSION_DENIED` - if the caller does not have the 'Unlock' permission. 71 * `ResponseCode::VALUE_CORRUPTED` - if a super key can not be decrypted. 72 * `ResponseCode::KEY_NOT_FOUND` - if a super key is not found. 73 * `ResponseCode::SYSTEM_ERROR` - if another error occurred. 74 * 75 * @param userId The Android user ID of the user for which the device is now unlocked 76 * @param password If available, a secret derived from the user's synthetic password 77 */ onDeviceUnlocked(in int userId, in @nullable byte[] password)78 void onDeviceUnlocked(in int userId, in @nullable byte[] password); 79 80 /** 81 * Tells Keystore that the device is now locked for a user. Requires the 'Lock' permission. 82 * 83 * This method makes Keystore stop allowing the use of the given user's keys that require an 84 * unlocked device. This is enforced logically, and when possible it's also enforced 85 * cryptographically by wiping the UnlockedDeviceRequired super keys from memory. 86 * 87 * unlockingSids and weakUnlockEnabled specify the methods by which the device can become 88 * unlocked for the user, in addition to LSKF-equivalent authentication. 89 * 90 * unlockingSids is the list of SIDs of class 3 (strong) biometrics that can unlock. If 91 * unlockingSids is non-empty, then this method saves a copy of the UnlockedDeviceRequired super 92 * keys in memory encrypted by a new AES key that is imported into KeyMint and configured to be 93 * usable only when user authentication has occurred using any of the SIDs. This allows the 94 * keys to be recovered if the device is unlocked using a class 3 biometric. 95 * 96 * weakUnlockEnabled is true if the unlock can happen using a method that does not have an 97 * associated SID, such as a class 1 (convenience) biometric, class 2 (weak) biometric, or trust 98 * agent. These methods don't count as "authentication" from Keystore's perspective. In this 99 * case, Keystore keeps a copy of the UnlockedDeviceRequired super keys in memory in plaintext, 100 * providing only logical security for UnlockedDeviceRequired. 101 * 102 * ## Error conditions: 103 * `ResponseCode::PERMISSION_DENIED` - if the caller does not have the 'Lock' permission. 104 * 105 * @param userId The Android user ID of the user for which the device is now locked 106 * @param unlockingSids SIDs of class 3 biometrics that can unlock the device for the user 107 * @param weakUnlockEnabled Whether a weak unlock method can unlock the device for the user 108 */ onDeviceLocked(in int userId, in long[] unlockingSids, in boolean weakUnlockEnabled)109 void onDeviceLocked(in int userId, in long[] unlockingSids, in boolean weakUnlockEnabled); 110 111 /** 112 * Tells Keystore that weak unlock methods can no longer unlock the device for the given user. 113 * This is intended to be called after an earlier call to onDeviceLocked() with 114 * weakUnlockEnabled=true. It upgrades the security level of UnlockedDeviceRequired keys to 115 * that which would have resulted from calling onDeviceLocked() with weakUnlockEnabled=false. 116 * 117 * ## Error conditions: 118 * `ResponseCode::PERMISSION_DENIED` - if the caller does not have the 'Lock' permission. 119 * 120 * @param userId The Android user ID of the user for which weak unlock methods have expired 121 */ onWeakUnlockMethodsExpired(in int userId)122 void onWeakUnlockMethodsExpired(in int userId); 123 124 /** 125 * Tells Keystore that non-LSKF-equivalent unlock methods can no longer unlock the device for 126 * the given user. This is intended to be called after an earlier call to onDeviceLocked() with 127 * nonempty unlockingSids. It upgrades the security level of UnlockedDeviceRequired keys to 128 * that which would have resulted from calling onDeviceLocked() with unlockingSids=[] and 129 * weakUnlockEnabled=false. 130 * 131 * ## Error conditions: 132 * `ResponseCode::PERMISSION_DENIED` - if the caller does not have the 'Lock' permission. 133 * 134 * @param userId The Android user ID of the user for which non-LSKF unlock methods have expired 135 */ onNonLskfUnlockMethodsExpired(in int userId)136 void onNonLskfUnlockMethodsExpired(in int userId); 137 138 /** 139 * Allows Credstore to retrieve a HardwareAuthToken and a TimestampToken. 140 * Identity Credential Trusted App can run either in the TEE or in other secure Hardware. 141 * So, credstore always need to retrieve a TimestampToken along with a HardwareAuthToken. 142 * 143 * The passed in |challenge| parameter must always be non-zero. 144 * 145 * The returned TimestampToken will always have its |challenge| field set to 146 * the |challenge| parameter. 147 * 148 * This method looks through auth-tokens cached by keystore which match 149 * the passed-in |secureUserId|. 150 * The most recent matching auth token which has a |challenge| field which matches 151 * the passed-in |challenge| parameter is returned. 152 * In this case the |authTokenMaxAgeMillis| parameter is not used. 153 * 154 * Otherwise, the most recent matching auth token which is younger 155 * than |authTokenMaxAgeMillis| is returned. 156 * 157 * This method is called by credstore (and only credstore). 158 * 159 * The caller requires 'get_auth_token' permission. 160 * 161 * ## Error conditions: 162 * `ResponseCode::PERMISSION_DENIED` - if the caller does not have the 'get_auth_token' 163 * permission. 164 * `ResponseCode::SYSTEM_ERROR` - if failed to obtain an authtoken from the database. 165 * `ResponseCode::NO_AUTH_TOKEN_FOUND` - a matching auth token is not found. 166 * `ResponseCode::INVALID_ARGUMENT` - if the passed-in |challenge| parameter is zero. 167 */ getAuthTokensForCredStore(in long challenge, in long secureUserId, in long authTokenMaxAgeMillis)168 AuthorizationTokens getAuthTokensForCredStore(in long challenge, in long secureUserId, 169 in long authTokenMaxAgeMillis); 170 171 /** 172 * Returns the last successful authentication time since boot for the given user with any of the 173 * given authenticator types. This is determined by inspecting the cached auth tokens. 174 * 175 * ## Error conditions: 176 * `ResponseCode::NO_AUTH_TOKEN_FOUND` - if there is no matching authentication token found 177 */ getLastAuthTime(in long secureUserId, in HardwareAuthenticatorType[] authTypes)178 long getLastAuthTime(in long secureUserId, in HardwareAuthenticatorType[] authTypes); 179 } 180