1 // Copyright 2021, 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.maintenance; 16 17 import android.system.keystore2.Domain; 18 import android.system.keystore2.KeyDescriptor; 19 20 /** 21 * IKeystoreMaintenance interface exposes the methods for adding/removing users and changing the 22 * user's password. 23 * @hide 24 */ 25 @SensitiveData 26 interface IKeystoreMaintenance { 27 28 /** 29 * Allows LockSettingsService to inform keystore about adding a new user. 30 * Callers require 'ChangeUser' permission. 31 * 32 * ## Error conditions: 33 * `ResponseCode::PERMISSION_DENIED` - if the callers do not have the 'ChangeUser' permission. 34 * `ResponseCode::SYSTEM_ERROR` - if failed to delete the keys of an existing user with the same 35 * user id. 36 * 37 * @param userId - Android user id 38 */ onUserAdded(in int userId)39 void onUserAdded(in int userId); 40 41 /** 42 * Allows LockSettingsService to tell Keystore to create a user's superencryption keys and store 43 * them encrypted by the given secret. Requires 'ChangeUser' permission. 44 * 45 * ## Error conditions: 46 * `ResponseCode::PERMISSION_DENIED` - if caller does not have the 'ChangeUser' permission 47 * `ResponseCode::SYSTEM_ERROR` - if failed to initialize the user's super keys 48 * 49 * @param userId - Android user id 50 * @param password - a secret derived from the synthetic password of the user 51 * @param allowExisting - if true, then the keys already existing is not considered an error 52 */ initUserSuperKeys(in int userId, in byte[] password, in boolean allowExisting)53 void initUserSuperKeys(in int userId, in byte[] password, in boolean allowExisting); 54 55 /** 56 * Allows LockSettingsService to inform keystore about removing a user. 57 * Callers require 'ChangeUser' permission. 58 * 59 * ## Error conditions: 60 * `ResponseCode::PERMISSION_DENIED` - if the callers do not have the 'ChangeUser' permission. 61 * `ResponseCode::SYSTEM_ERROR` - if failed to delete the keys of the user being deleted. 62 * 63 * @param userId - Android user id 64 */ onUserRemoved(in int userId)65 void onUserRemoved(in int userId); 66 67 /** 68 * Allows LockSettingsService to tell Keystore that a user's LSKF is being removed, ie the 69 * user's lock screen is changing to Swipe or None. Requires 'ChangePassword' permission. 70 * 71 * ## Error conditions: 72 * `ResponseCode::PERMISSION_DENIED` - if caller does not have the 'ChangePassword' permission 73 * `ResponseCode::SYSTEM_ERROR` - if failed to delete the user's auth-bound keys 74 * 75 * @param userId - Android user id 76 */ onUserLskfRemoved(in int userId)77 void onUserLskfRemoved(in int userId); 78 79 /** 80 * This function deletes all keys within a namespace. It mainly gets called when an app gets 81 * removed and all resources of this app need to be cleaned up. 82 * 83 * @param domain - One of Domain.APP or Domain.SELINUX. 84 * @param nspace - The UID of the app that is to be cleared if domain is Domain.APP or 85 * the SEPolicy namespace if domain is Domain.SELINUX. 86 */ clearNamespace(Domain domain, long nspace)87 void clearNamespace(Domain domain, long nspace); 88 89 /** 90 * This function notifies the Keymint device of the specified securityLevel that 91 * early boot has ended, so that they no longer allow early boot keys to be used. 92 * ## Error conditions: 93 * `ResponseCode::PERMISSION_DENIED` - if the caller does not have the 'EarlyBootEnded' 94 * permission. 95 * A KeyMint ErrorCode may be returned indicating a backend diagnosed error. 96 */ earlyBootEnded()97 void earlyBootEnded(); 98 99 /** 100 * Migrate a key from one namespace to another. The caller must have use, grant, and delete 101 * permissions on the source namespace and rebind permissions on the destination namespace. 102 * The source may be specified by Domain::APP, Domain::SELINUX, or Domain::KEY_ID. The target 103 * may be specified by Domain::APP or Domain::SELINUX. 104 * 105 * ## Error conditions: 106 * `ResponseCode::PERMISSION_DENIED` - If the caller lacks any of the required permissions. 107 * `ResponseCode::KEY_NOT_FOUND` - If the source did not exist. 108 * `ResponseCode::INVALID_ARGUMENT` - If the target exists or if any of the above mentioned 109 * requirements for the domain parameter are not met. 110 * `ResponseCode::SYSTEM_ERROR` - An unexpected system error occurred. 111 */ migrateKeyNamespace(in KeyDescriptor source, in KeyDescriptor destination)112 void migrateKeyNamespace(in KeyDescriptor source, in KeyDescriptor destination); 113 114 /** 115 * Deletes all keys in all hardware keystores. Used when keystore is reset completely. After 116 * this function is called all keys with Tag::ROLLBACK_RESISTANCE in their hardware-enforced 117 * authorization lists must be rendered permanently unusable. Keys without 118 * Tag::ROLLBACK_RESISTANCE may or may not be rendered unusable. 119 */ deleteAllKeys()120 void deleteAllKeys(); 121 122 /** 123 * Returns a list of App UIDs that have keys associated with the given SID, under the 124 * given user ID. 125 * When a given user's LSKF is removed or biometric authentication methods are changed 126 * (addition of a fingerprint, for example), authentication-bound keys may be invalidated. 127 * This method allows the platform to find out which apps would be affected (for a given user) 128 * when a given user secure ID is removed. 129 * Callers require the `android.permission.MANAGE_USERS` Android permission 130 * (not SELinux policy). 131 * 132 * @param userId The affected user. 133 * @param sid The user secure ID - identifier of the authentication method. 134 * 135 * @return A list of APP UIDs, in the form of (AID + userId*AID_USER_OFFSET), that have 136 * keys auth-bound to the given SID. These values can be passed into the 137 * PackageManager for resolution. 138 */ getAppUidsAffectedBySid(in int userId, in long sid)139 long[] getAppUidsAffectedBySid(in int userId, in long sid); 140 } 141