1/* 2 * Copyright (C) 2016 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16package android.hardware.gatekeeper@1.0; 17 18interface IGatekeeper { 19 20/** 21 * Enrolls desiredPassword, which may be derived from a user selected pin 22 * or password, with the private key used only for enrolling authentication 23 * factor data. 24 * 25 * If there was already a password enrolled, current password handle must be 26 * passed in currentPasswordHandle, and current password must be passed in 27 * currentPassword. Valid currentPassword must verify() against 28 * currentPasswordHandle. 29 * 30 * @param uid The Android user identifier 31 * 32 * @param currentPasswordHandle The currently enrolled password handle the user 33 * wants to replace. May be empty only if there's no currently enrolled 34 * password. Otherwise must be non-empty. 35 * 36 * @param currentPassword The user's current password in plain text. 37 * it MUST verify against current_password_handle if the latter is not-empty 38 * 39 * @param desiredPassword The new password the user wishes to enroll in 40 * plaintext. 41 * 42 * @return response 43 * On success, data buffer must contain the new password handle referencing 44 * the password provided in desiredPassword. 45 * This buffer can be used on subsequent calls to enroll or 46 * verify. On error, this buffer must be empty. 47 * response.code must always contain operation completion status. 48 * This method may return ERROR_GENERAL_FAILURE or ERROR_RETRY_TIMEOUT on 49 * failure. It must return STATUS_OK on success. 50 * If ERROR_RETRY_TIMEOUT is returned, response.timeout must be non-zero. 51 */ 52enroll(uint32_t uid, 53 vec<uint8_t> currentPasswordHandle, 54 vec<uint8_t> currentPassword, 55 vec<uint8_t> desiredPassword) 56 generates (GatekeeperResponse response); 57 58/** 59 * Verifies that providedPassword matches enrolledPasswordHandle. 60 * 61 * Implementations of this module may retain the result of this call 62 * to attest to the recency of authentication. 63 * 64 * On success, returns verification token in response.data, which shall be 65 * usable to attest password verification to other trusted services. 66 * 67 * @param uid The Android user identifier 68 * 69 * @param challenge An optional challenge to authenticate against, or 0. 70 * Used when a separate authenticator requests password verification, 71 * or for transactional password authentication. 72 * 73 * @param enrolledPasswordHandle The currently enrolled password handle that 74 * user wishes to verify against. Must be non-empty. 75 * 76 * @param providedPassword The plaintext password to be verified against the 77 * enrolledPasswordHandle 78 * 79 * @return response 80 * On success, a non-empty data buffer containing the 81 * authentication token resulting from this verification is returned. 82 * On error, data buffer must be empty. 83 * response.code must always contain operation completion status. 84 * This method may return ERROR_GENERAL_FAILURE or ERROR_RETRY_TIMEOUT on 85 * failure. It must return STATUS_OK on success. 86 * If password re-enrollment is necessary, it must return STATUS_REENROLL. 87 * If ERROR_RETRY_TIMEOUT is returned, response.timeout must be non-zero. 88 */ 89verify(uint32_t uid, uint64_t challenge, 90 vec<uint8_t> enrolledPasswordHandle, 91 vec<uint8_t> providedPassword) 92 generates (GatekeeperResponse response); 93 94/** 95 * Deletes the enrolledPasswordHandle associated with the uid. Once deleted 96 * the user cannot be verified anymore. 97 * This is an optional method. 98 * 99 * @param uid The Android user identifier 100 * 101 * @return response 102 * response.code must always contain operation completion status. 103 * This method may return ERROR_GENERAL_FAILURE or ERROR_RETRY_TIMEOUT on 104 * failure. It must return STATUS_OK on success. 105 * If not implemented, it must return ERROR_NOT_IMPLEMENTED. 106 * If ERROR_RETRY_TIMEOUT is returned, response.timeout must be non-zero. 107 */ 108deleteUser(uint32_t uid) generates (GatekeeperResponse response); 109 110/** 111 * Deletes all the enrolled_password_handles for all uid's. Once called, 112 * no users must be enrolled on the device. 113 * This is an optional method. 114 * 115 * @return response 116 * response.code must always contain operation completion status. 117 * This method may return ERROR_GENERAL_FAILURE or ERROR_RETRY_TIMEOUT on 118 * failure. It must return STATUS_OK on success. 119 * If not implemented, it must return ERROR_NOT_IMPLEMENTED. 120 * If ERROR_RETRY_TIMEOUT is returned, response.timeout must be non-zero. 121 */ 122deleteAllUsers() generates (GatekeeperResponse response); 123}; 124