blob: 14f30056e42b8fe08ec574be0f74f3fc8c36b7f7 [file] [log] [blame] [edit]
/*
* 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);
};