| /* | |
| * Copyright (C) 2017 The Android Open Source Project | |
| * | |
| * Licensed under the Apache License, Version 2.0 (the "License"); | |
| * you may not use this file except in compliance with the License. | |
| * You may obtain a copy of the License at | |
| * | |
| * http://www.apache.org/licenses/LICENSE-2.0 | |
| * | |
| * Unless required by applicable law or agreed to in writing, software | |
| * distributed under the License is distributed on an "AS IS" BASIS, | |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
| * See the License for the specific language governing permissions and | |
| * limitations under the License. | |
| */ | |
| package android.hardware.biometrics.fingerprint@2.1; | |
| import IBiometricsFingerprintClientCallback; | |
| interface IBiometricsFingerprint { | |
| /** | |
| * Set notification callback: | |
| * Registers a user function that must receive notifications from the HAL | |
| * This call must block if the HAL state machine is in busy state until HAL | |
| * leaves the busy state. | |
| * | |
| * @return deviceId is a unique handle for this fingerprint device | |
| */ | |
| @callflow(next={"setActiveGroup"}) | |
| @entry | |
| setNotify(IBiometricsFingerprintClientCallback clientCallback) | |
| generates (uint64_t deviceId); | |
| /** | |
| * Fingerprint pre-enroll enroll request: | |
| * Generates a unique token to upper layers to indicate the start of | |
| * an enrollment transaction. pre-enroll and post-enroll specify | |
| * a pin/password cleared time window where enrollment is allowed. | |
| * Pre-enroll only generates a challenge, a full hardwareAuthToken is | |
| * generated by trustzone after verifying a pin/password/swipe. This is to | |
| * ensure adding a new fingerprint template was preceded by some kind of | |
| * credential confirmation (e.g. device password). | |
| * | |
| * @return 0 if function failed, a uint64_t of challenge otherwise. | |
| */ | |
| @callflow(next={"enroll", "postEnroll"}) | |
| preEnroll() generates (uint64_t authChallenge); | |
| /** | |
| * Fingerprint enroll request: | |
| * Switches the HAL state machine to collect and store a new fingerprint | |
| * template. Switches back as soon as enroll is complete, signalled by | |
| * (fingerprintMsg.type == FINGERPRINT_TEMPLATE_ENROLLING && | |
| * fingerprintMsg.data.enroll.samplesRemaining == 0) | |
| * or after timeoutSec seconds. | |
| * The fingerprint template must be assigned to the group gid. | |
| * | |
| * @param hat a valid Hardware Authentication Token (HAT), generated | |
| * as a result of a preEnroll() call. | |
| * @param gid a framework defined fingerprint set (group) id. | |
| * @param timeoutSec a timeout in seconds. | |
| * | |
| * @return debugErrno is a value the framework logs in case it is not 0. | |
| * | |
| * A notify() function may be called with a more detailed error structure. | |
| */ | |
| @callflow(next={"cancel", "enroll", "postEnroll", "remove"}) | |
| enroll(uint8_t[69] hat, uint32_t gid, uint32_t timeoutSec) | |
| generates (RequestStatus debugErrno); | |
| /** | |
| * Finishes the enroll operation and invalidates the preEnroll() generated | |
| * challenge. This must be called at the end of a multi-finger enrollment | |
| * session to indicate that no more fingers may be added. | |
| * | |
| * @return debugErrno is a value the framework logs in case it is not 0. | |
| */ | |
| @callflow(next={"authenticate", "setActiveGroup", "enumerate", "remove"}) | |
| postEnroll() generates (RequestStatus debugErrno); | |
| /** | |
| * getAuthenticatorId: | |
| * Returns a token associated with the current fingerprint set. This value | |
| * must change whenever a new fingerprint is enrolled, thus creating a new | |
| * fingerprint set. | |
| * | |
| * @return getAuthenticatorIdRet current authenticator id, 0 if function | |
| * failed. | |
| */ | |
| @callflow(next={"authenticate"}) | |
| getAuthenticatorId() generates (uint64_t AuthenticatorId); | |
| /** | |
| * Cancel pending enroll or authenticate, sending FINGERPRINT_ERROR_CANCELED | |
| * to all running clients. Switches the HAL state machine back to the idle | |
| * state. Unlike enrollDone() doesn't invalidate the preEnroll() challenge. | |
| * | |
| * @return debugErrno is a value the framework logs in case it is not 0. | |
| */ | |
| @callflow(next={"authenticate", "enroll", "enumerate", "remove", | |
| "setActiveGroup"}) | |
| cancel() generates (RequestStatus debugErrno); | |
| /** | |
| * Enumerate all the fingerprint templates found in the directory set by | |
| * setActiveGroup(): | |
| * For each template found a notify() must be called with: | |
| * fingerprintMsg.type == FINGERPRINT_TEMPLATE_ENUMERATED | |
| * fingerprintMsg.data.enumerated.finger indicating a template id | |
| * fingerprintMsg.data.enumerated.remainingTemplates indicating how many more | |
| * enumeration messages to expect. | |
| * | |
| * @return debugErrno is a value the framework logs in case it is not 0. | |
| */ | |
| @callflow(next={"remove", "enroll", "authenticate", "setActiveGroup"}) | |
| enumerate() generates (RequestStatus debugErrno); | |
| /** | |
| * Fingerprint remove request: | |
| * Deletes fingerprint template(s). | |
| * Works only within the path set by setActiveGroup(). | |
| * For each template found a notify() must be called with: | |
| * fingerprintMsg.type == FINGERPRINT_TEMPLATE_REMOVED | |
| * fingerprintMsg.data.removed.finger indicating the template id deleted | |
| * fingerprintMsg.data.removed.remainingTemplates indicating how many more | |
| * templates must be deleted by this operation. | |
| * | |
| * @param gid group id must match the last group set by setActiveGroup(). | |
| * @param fid template id to delete or 0 to delete all templates within the | |
| * current group. | |
| * | |
| * @return debugErrno is a value the framework logs in case it is not 0. | |
| */ | |
| @callflow(next={"enumerate", "authenticate", "cancel", "getAuthenticatorId", | |
| "setActiveGroup"}) | |
| remove(uint32_t gid, uint32_t fid) generates (RequestStatus debugErrno); | |
| /** | |
| * Restricts the HAL operation to a set of fingerprints belonging to a group | |
| * provided. The caller must provide a path to a storage location within the | |
| * user's data directory. | |
| * | |
| * @param gid the fingerprint group (set) id. | |
| * @param storePath filesystem path to the template storage directory. | |
| * | |
| * @return debugErrno is a value the framework logs in case it is not 0. | |
| */ | |
| @callflow(next={"authenticate", "preEnroll", "enumerate", "remove"}) | |
| setActiveGroup(uint32_t gid, string storePath) | |
| generates (RequestStatus debugErrno); | |
| /** | |
| * Authenticates an operation identified by operationId | |
| * | |
| * @param operationId operation id. | |
| * @param gid fingerprint group id. | |
| * | |
| * @return debugErrno is a value the framework logs in case it is not 0. | |
| */ | |
| @callflow(next={"cancel", "preEnroll", "remove"}) | |
| authenticate(uint64_t operationId, uint32_t gid) | |
| generates (RequestStatus debugErrno); | |
| }; |