19f8b5c7b1649c989c21fbb88781c36ed95e4d358Steven Moreland/* 29f8b5c7b1649c989c21fbb88781c36ed95e4d358Steven Moreland * Copyright (C) 2016 The Android Open Source Project 39f8b5c7b1649c989c21fbb88781c36ed95e4d358Steven Moreland * 49f8b5c7b1649c989c21fbb88781c36ed95e4d358Steven Moreland * Licensed under the Apache License, Version 2.0 (the "License"); 59f8b5c7b1649c989c21fbb88781c36ed95e4d358Steven Moreland * you may not use this file except in compliance with the License. 69f8b5c7b1649c989c21fbb88781c36ed95e4d358Steven Moreland * You may obtain a copy of the License at 79f8b5c7b1649c989c21fbb88781c36ed95e4d358Steven Moreland * 89f8b5c7b1649c989c21fbb88781c36ed95e4d358Steven Moreland * http://www.apache.org/licenses/LICENSE-2.0 99f8b5c7b1649c989c21fbb88781c36ed95e4d358Steven Moreland * 109f8b5c7b1649c989c21fbb88781c36ed95e4d358Steven Moreland * Unless required by applicable law or agreed to in writing, software 119f8b5c7b1649c989c21fbb88781c36ed95e4d358Steven Moreland * distributed under the License is distributed on an "AS IS" BASIS, 129f8b5c7b1649c989c21fbb88781c36ed95e4d358Steven Moreland * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 139f8b5c7b1649c989c21fbb88781c36ed95e4d358Steven Moreland * See the License for the specific language governing permissions and 149f8b5c7b1649c989c21fbb88781c36ed95e4d358Steven Moreland * limitations under the License. 159f8b5c7b1649c989c21fbb88781c36ed95e4d358Steven Moreland */ 16586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudovpackage android.hardware.gatekeeper@1.0; 17586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov 18586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudovinterface IGatekeeper { 19586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov 20586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov/** 21586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * Enrolls desiredPassword, which may be derived from a user selected pin 22586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * or password, with the private key used only for enrolling authentication 23586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * factor data. 24586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * 25586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * If there was already a password enrolled, current password handle must be 26586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * passed in currentPasswordHandle, and current password must be passed in 27586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * currentPassword. Valid currentPassword must verify() against 28586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * currentPasswordHandle. 29586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * 30586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * @param uid The Android user identifier 31586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * 32586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * @param currentPasswordHandle The currently enrolled password handle the user 33586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * wants to replace. May be empty only if there's no currently enrolled 34586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * password. Otherwise must be non-empty. 35586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * 36586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * @param currentPassword The user's current password in plain text. 37586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * it MUST verify against current_password_handle if the latter is not-empty 38586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * 39586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * @param desiredPassword The new password the user wishes to enroll in 40586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * plaintext. 41586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * 42586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * @return response 43586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * On success, data buffer must contain the new password handle referencing 44586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * the password provided in desiredPassword. 45586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * This buffer can be used on subsequent calls to enroll or 46586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * verify. On error, this buffer must be empty. 47586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * response.code must always contain operation completion status. 48586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * This method may return ERROR_GENERAL_FAILURE or ERROR_RETRY_TIMEOUT on 49586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * failure. It must return STATUS_OK on success. 50586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * If ERROR_RETRY_TIMEOUT is returned, response.timeout must be non-zero. 51586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov */ 52586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudovenroll(uint32_t uid, 53586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov vec<uint8_t> currentPasswordHandle, 54586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov vec<uint8_t> currentPassword, 55586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov vec<uint8_t> desiredPassword) 56586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov generates (GatekeeperResponse response); 57586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov 58586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov/** 59586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * Verifies that providedPassword matches enrolledPasswordHandle. 60586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * 61586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * Implementations of this module may retain the result of this call 62586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * to attest to the recency of authentication. 63586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * 64586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * On success, returns verification token in response.data, which shall be 65586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * usable to attest password verification to other trusted services. 66586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * 67586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * @param uid The Android user identifier 68586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * 69586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * @param challenge An optional challenge to authenticate against, or 0. 70586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * Used when a separate authenticator requests password verification, 71586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * or for transactional password authentication. 72586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * 73586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * @param enrolledPasswordHandle The currently enrolled password handle that 74586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * user wishes to verify against. Must be non-empty. 75586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * 76586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * @param providedPassword The plaintext password to be verified against the 77586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * enrolledPasswordHandle 78586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * 79586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * @return response 80586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * On success, a non-empty data buffer containing the 81586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * authentication token resulting from this verification is returned. 82586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * On error, data buffer must be empty. 83586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * response.code must always contain operation completion status. 84586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * This method may return ERROR_GENERAL_FAILURE or ERROR_RETRY_TIMEOUT on 85586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * failure. It must return STATUS_OK on success. 86586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * If password re-enrollment is necessary, it must return STATUS_REENROLL. 87586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * If ERROR_RETRY_TIMEOUT is returned, response.timeout must be non-zero. 88586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov */ 89586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudovverify(uint32_t uid, uint64_t challenge, 90586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov vec<uint8_t> enrolledPasswordHandle, 91586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov vec<uint8_t> providedPassword) 92586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov generates (GatekeeperResponse response); 93586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov 9440d3a9bd8c62714ee58f9363c4456f764aa5a95dAndreas Huber/** 95586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * Deletes the enrolledPasswordHandle associated with the uid. Once deleted 96586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * the user cannot be verified anymore. 97586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * This is an optional method. 98586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * 99586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * @param uid The Android user identifier 100586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * 101586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * @return response 102586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * response.code must always contain operation completion status. 103586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * This method may return ERROR_GENERAL_FAILURE or ERROR_RETRY_TIMEOUT on 104586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * failure. It must return STATUS_OK on success. 105586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * If not implemented, it must return ERROR_NOT_IMPLEMENTED. 106586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * If ERROR_RETRY_TIMEOUT is returned, response.timeout must be non-zero. 107586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov */ 108586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey PolyudovdeleteUser(uint32_t uid) generates (GatekeeperResponse response); 109586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov 11040d3a9bd8c62714ee58f9363c4456f764aa5a95dAndreas Huber/** 111586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * Deletes all the enrolled_password_handles for all uid's. Once called, 112586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * no users must be enrolled on the device. 113586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * This is an optional method. 114586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * 115586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * @return response 116586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * response.code must always contain operation completion status. 117586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * This method may return ERROR_GENERAL_FAILURE or ERROR_RETRY_TIMEOUT on 118586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * failure. It must return STATUS_OK on success. 119586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * If not implemented, it must return ERROR_NOT_IMPLEMENTED. 120586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov * If ERROR_RETRY_TIMEOUT is returned, response.timeout must be non-zero. 121586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov */ 122586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey PolyudovdeleteAllUsers() generates (GatekeeperResponse response); 123586a32fa67a078eddf552c8f50c3ec0d0ecc012aAlexey Polyudov}; 124