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 * 45 * Callers require 'Unlock' permission. 46 * 47 * Super-Encryption Key: 48 * When the device is unlocked (and password is non-null), Keystore stores in memory 49 * a super-encryption key derived from the password that protects UNLOCKED_DEVICE_REQUIRED 50 * keys; this key is wiped from memory when the device is locked. 51 * 52 * If unlockingSids is non-empty on lock, then before the super-encryption key is wiped from 53 * memory, a copy of it is stored in memory encrypted with a fresh AES key. This key is then 54 * imported into KM, tagged such that it can be used given a valid, recent auth token for any 55 * of the unlockingSids. 56 * 57 * Options for unlock: 58 * - If the password is non-null, the super-encryption key is re-derived as above. 59 * - If the password is null, then if a suitable auth token to access the encrypted 60 * Super-encryption key stored in KM has been sent to keystore (via addAuthToken), the 61 * encrypted super-encryption key is recovered so that UNLOCKED_DEVICE_REQUIRED keys can 62 * be used once again. 63 * - If neither of these are met, then the operation fails. 64 * 65 * ## Error conditions: 66 * `ResponseCode::PERMISSION_DENIED` - if the callers do not have the 'Unlock' permission. 67 * `ResponseCode::SYSTEM_ERROR` - if failed to perform lock/unlock operations due to various 68 * `ResponseCode::VALUE_CORRUPTED` - if the super key can not be decrypted. 69 * `ResponseCode::KEY_NOT_FOUND` - if the super key is not found. 70 * 71 * @param lockScreenEvent whether the lock screen locked or unlocked 72 * @param userId android user id 73 * @param password synthetic password derived from the user's LSKF, must be null on lock 74 * @param unlockingSids list of biometric SIDs for this user, ignored on unlock 75 */ onLockScreenEvent(in LockScreenEvent lockScreenEvent, in int userId, in @nullable byte[] password, in @nullable long[] unlockingSids)76 void onLockScreenEvent(in LockScreenEvent lockScreenEvent, in int userId, 77 in @nullable byte[] password, in @nullable long[] unlockingSids); 78 79 /** 80 * Allows Credstore to retrieve a HardwareAuthToken and a TimestampToken. 81 * Identity Credential Trusted App can run either in the TEE or in other secure Hardware. 82 * So, credstore always need to retrieve a TimestampToken along with a HardwareAuthToken. 83 * 84 * The passed in |challenge| parameter must always be non-zero. 85 * 86 * The returned TimestampToken will always have its |challenge| field set to 87 * the |challenge| parameter. 88 * 89 * This method looks through auth-tokens cached by keystore which match 90 * the passed-in |secureUserId|. 91 * The most recent matching auth token which has a |challenge| field which matches 92 * the passed-in |challenge| parameter is returned. 93 * In this case the |authTokenMaxAgeMillis| parameter is not used. 94 * 95 * Otherwise, the most recent matching auth token which is younger 96 * than |authTokenMaxAgeMillis| is returned. 97 * 98 * This method is called by credstore (and only credstore). 99 * 100 * The caller requires 'get_auth_token' permission. 101 * 102 * ## Error conditions: 103 * `ResponseCode::PERMISSION_DENIED` - if the caller does not have the 'get_auth_token' 104 * permission. 105 * `ResponseCode::SYSTEM_ERROR` - if failed to obtain an authtoken from the database. 106 * `ResponseCode::NO_AUTH_TOKEN_FOUND` - a matching auth token is not found. 107 * `ResponseCode::INVALID_ARGUMENT` - if the passed-in |challenge| parameter is zero. 108 */ getAuthTokensForCredStore(in long challenge, in long secureUserId, in long authTokenMaxAgeMillis)109 AuthorizationTokens getAuthTokensForCredStore(in long challenge, in long secureUserId, 110 in long authTokenMaxAgeMillis); 111 } 112