1 /* 2 * Copyright (C) 2017 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 */ 16 17 package android.hardware.biometrics.fingerprint@2.1; 18 19 import IBiometricsFingerprintClientCallback; 20 21 interface IBiometricsFingerprint { 22 /** 23 * Set notification callback: 24 * Registers a user function that must receive notifications from the HAL 25 * This call must block if the HAL state machine is in busy state until HAL 26 * leaves the busy state. 27 * 28 * @return deviceId is a unique handle for this fingerprint device 29 */ 30 @callflow(next={"setActiveGroup"}) 31 @entry 32 setNotify(IBiometricsFingerprintClientCallback clientCallback) 33 generates (uint64_t deviceId); 34 35 /** 36 * Fingerprint pre-enroll enroll request: 37 * Generates a unique token to upper layers to indicate the start of 38 * an enrollment transaction. pre-enroll and post-enroll specify 39 * a pin/password cleared time window where enrollment is allowed. 40 * Pre-enroll only generates a challenge, a full hardwareAuthToken is 41 * generated by trustzone after verifying a pin/password/swipe. This is to 42 * ensure adding a new fingerprint template was preceded by some kind of 43 * credential confirmation (e.g. device password). 44 * 45 * @return 0 if function failed, a uint64_t of challenge otherwise. 46 */ 47 @callflow(next={"enroll", "postEnroll"}) 48 preEnroll() generates (uint64_t authChallenge); 49 50 /** 51 * Fingerprint enroll request: 52 * Switches the HAL state machine to collect and store a new fingerprint 53 * template. Switches back as soon as enroll is complete, signalled by 54 * (fingerprintMsg.type == FINGERPRINT_TEMPLATE_ENROLLING && 55 * fingerprintMsg.data.enroll.samplesRemaining == 0) 56 * or after timeoutSec seconds. 57 * The fingerprint template must be assigned to the group gid. 58 * 59 * @param hat a valid Hardware Authentication Token (HAT), generated 60 * as a result of a preEnroll() call. 61 * @param gid a framework defined fingerprint set (group) id. 62 * @param timeoutSec a timeout in seconds. 63 * 64 * @return debugErrno is a value the framework logs in case it is not 0. 65 * 66 * A notify() function may be called with a more detailed error structure. 67 */ 68 @callflow(next={"cancel", "enroll", "postEnroll", "remove"}) 69 enroll(uint8_t[69] hat, uint32_t gid, uint32_t timeoutSec) 70 generates (RequestStatus debugErrno); 71 72 /** 73 * Finishes the enroll operation and invalidates the preEnroll() generated 74 * challenge. This must be called at the end of a multi-finger enrollment 75 * session to indicate that no more fingers may be added. 76 * 77 * @return debugErrno is a value the framework logs in case it is not 0. 78 */ 79 @callflow(next={"authenticate", "setActiveGroup", "enumerate", "remove"}) 80 postEnroll() generates (RequestStatus debugErrno); 81 82 /** 83 * getAuthenticatorId: 84 * Returns a token associated with the current fingerprint set. This value 85 * must change whenever a new fingerprint is enrolled, thus creating a new 86 * fingerprint set. 87 * 88 * @return getAuthenticatorIdRet current authenticator id, 0 if function 89 * failed. 90 */ 91 @callflow(next={"authenticate"}) 92 getAuthenticatorId() generates (uint64_t AuthenticatorId); 93 94 /** 95 * Cancel pending enroll or authenticate, sending FINGERPRINT_ERROR_CANCELED 96 * to all running clients. Switches the HAL state machine back to the idle 97 * state. Unlike enrollDone() doesn't invalidate the preEnroll() challenge. 98 * 99 * @return debugErrno is a value the framework logs in case it is not 0. 100 */ 101 @callflow(next={"authenticate", "enroll", "enumerate", "remove", 102 "setActiveGroup"}) 103 cancel() generates (RequestStatus debugErrno); 104 105 /** 106 * Enumerate all the fingerprint templates found in the directory set by 107 * setActiveGroup(): 108 * For each template found a notify() must be called with: 109 * fingerprintMsg.type == FINGERPRINT_TEMPLATE_ENUMERATED 110 * fingerprintMsg.data.enumerated.finger indicating a template id 111 * fingerprintMsg.data.enumerated.remainingTemplates indicating how many more 112 * enumeration messages to expect. 113 * 114 * @return debugErrno is a value the framework logs in case it is not 0. 115 */ 116 @callflow(next={"remove", "enroll", "authenticate", "setActiveGroup"}) 117 enumerate() generates (RequestStatus debugErrno); 118 119 /** 120 * Fingerprint remove request: 121 * Deletes fingerprint template(s). 122 * Works only within the path set by setActiveGroup(). 123 * For each template found a notify() must be called with: 124 * fingerprintMsg.type == FINGERPRINT_TEMPLATE_REMOVED 125 * fingerprintMsg.data.removed.finger indicating the template id deleted 126 * fingerprintMsg.data.removed.remainingTemplates indicating how many more 127 * templates must be deleted by this operation. 128 * 129 * @param gid group id must match the last group set by setActiveGroup(). 130 * @param fid template id to delete or 0 to delete all templates within the 131 * current group. 132 * 133 * @return debugErrno is a value the framework logs in case it is not 0. 134 */ 135 @callflow(next={"enumerate", "authenticate", "cancel", "getAuthenticatorId", 136 "setActiveGroup"}) 137 remove(uint32_t gid, uint32_t fid) generates (RequestStatus debugErrno); 138 139 /** 140 * Restricts the HAL operation to a set of fingerprints belonging to a group 141 * provided. The caller must provide a path to a storage location within the 142 * user's data directory. 143 * 144 * @param gid the fingerprint group (set) id. 145 * @param storePath filesystem path to the template storage directory. 146 * 147 * @return debugErrno is a value the framework logs in case it is not 0. 148 */ 149 @callflow(next={"authenticate", "preEnroll", "enumerate", "remove"}) 150 setActiveGroup(uint32_t gid, string storePath) 151 generates (RequestStatus debugErrno); 152 153 /** 154 * Authenticates an operation identified by operationId 155 * 156 * @param operationId operation id. 157 * @param gid fingerprint group id. 158 * 159 * @return debugErrno is a value the framework logs in case it is not 0. 160 */ 161 @callflow(next={"cancel", "preEnroll", "remove"}) 162 authenticate(uint64_t operationId, uint32_t gid) 163 generates (RequestStatus debugErrno); 164 }; 165
