diff --git a/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/AcquiredInfo.aidl b/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/AcquiredInfo.aidl index 329a35dc49..df30dcae47 100644 --- a/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/AcquiredInfo.aidl +++ b/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/AcquiredInfo.aidl @@ -24,6 +24,6 @@ enum AcquiredInfo { SENSOR_DIRTY = 3, TOO_SLOW = 4, TOO_FAST = 5, - START = 6, - VENDOR = 7, + VENDOR = 6, + START = 7, } diff --git a/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/Error.aidl b/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/Error.aidl index 0298c126c4..6bd71b2d34 100644 --- a/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/Error.aidl +++ b/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/Error.aidl @@ -18,13 +18,11 @@ package android.hardware.biometrics.fingerprint; @Backing(type="byte") @VintfStability enum Error { - HW_UNAVAILABLE = 0, - UNABLE_TO_PROCESS = 1, - TIMEOUT = 2, - NO_SPACE = 3, - CANCELED = 4, - UNABLE_TO_REMOVE = 5, - LOCKOUT = 6, - LOCKOUT_PERMANENT = 7, + HW_UNAVAILABLE = 1, + UNABLE_TO_PROCESS = 2, + TIMEOUT = 3, + NO_SPACE = 4, + CANCELED = 5, + UNABLE_TO_REMOVE = 6, VENDOR = 8, } diff --git a/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/IFingerprint.aidl b/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/IFingerprint.aidl index 9cbf343181..6ca6d16eb3 100644 --- a/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/IFingerprint.aidl +++ b/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/IFingerprint.aidl @@ -20,7 +20,6 @@ package android.hardware.biometrics.fingerprint; interface IFingerprint { android.hardware.biometrics.fingerprint.SensorProps[] getSensorProps(); android.hardware.biometrics.fingerprint.ISession createSession(in int sensorId, in int userId, in android.hardware.biometrics.fingerprint.ISessionCallback cb); - void setLockoutCallback(in android.hardware.biometrics.fingerprint.ILockoutCallback cb); void generateChallenge(in int sensorId, in int userId, in int timeoutSec, in android.hardware.biometrics.fingerprint.IGenerateChallengeCallback cb); void revokeChallenge(in int sensorId, in int userId, in long challenge, in android.hardware.biometrics.fingerprint.IRevokeChallengeCallback cb); } diff --git a/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ILockoutCallback.aidl b/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ILockoutCallback.aidl deleted file mode 100644 index 88aabbf487..0000000000 --- a/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ILockoutCallback.aidl +++ /dev/null @@ -1,24 +0,0 @@ -/////////////////////////////////////////////////////////////////////////////// -// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE. // -/////////////////////////////////////////////////////////////////////////////// - -// This file is a snapshot of an AIDL interface (or parcelable). Do not try to -// edit this file. It looks like you are doing that because you have modified -// an AIDL interface in a backward-incompatible way, e.g., deleting a function -// from an interface or a field from a parcelable and it broke the build. That -// breakage is intended. -// -// You must not make a backward incompatible changes to the AIDL files built -// with the aidl_interface module type with versions property set. The module -// type is used to build AIDL files in a way that they can be used across -// independently updatable components of the system. If a device is shipped -// with such a backward incompatible change, it has a high risk of breaking -// later when a module using the interface is updated, e.g., Mainline modules. - -package android.hardware.biometrics.fingerprint; -@VintfStability -interface ILockoutCallback { - oneway void onLockoutTimed(in int sensorId, in int userId, in long durationMillis); - oneway void onLockoutPermanent(in int sensorId, in int userId); - oneway void onLockoutCleared(in int sensorId, in int userId); -} diff --git a/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ISession.aidl b/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ISession.aidl index 06c8623bf5..c1f66e3b1f 100644 --- a/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ISession.aidl +++ b/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ISession.aidl @@ -19,7 +19,7 @@ package android.hardware.biometrics.fingerprint; @VintfStability interface ISession { android.hardware.biometrics.common.ICancellationSignal enroll(in int cookie, in android.hardware.keymaster.HardwareAuthToken hat); - android.hardware.biometrics.common.ICancellationSignal authenticate(in int cookie, in long keystoreOperationId); + android.hardware.biometrics.common.ICancellationSignal authenticate(in int cookie, in long operationId); android.hardware.biometrics.common.ICancellationSignal detectInteraction(in int cookie); void enumerateEnrollments(in int cookie); void removeEnrollments(in int cookie, in int[] enrollmentIds); diff --git a/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ISessionCallback.aidl b/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ISessionCallback.aidl index 614044790a..74ec07774c 100644 --- a/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ISessionCallback.aidl +++ b/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ISessionCallback.aidl @@ -21,8 +21,12 @@ interface ISessionCallback { void onStateChanged(in int cookie, in android.hardware.biometrics.fingerprint.SessionState state); void onAcquired(in android.hardware.biometrics.fingerprint.AcquiredInfo info, in int vendorCode); void onError(in android.hardware.biometrics.fingerprint.Error error, in int vendorCode); - void onEnrollmentProgress(in int enrollmentId, int remaining, int vendorCode); - void onAuthenticated(in int enrollmentId, in android.hardware.keymaster.HardwareAuthToken hat); + void onEnrollmentProgress(in int enrollmentId, int remaining); + void onAuthenticationSucceeded(in int enrollmentId, in android.hardware.keymaster.HardwareAuthToken hat); + void onAuthenticationFailed(); + void onLockoutTimed(in long durationMillis); + void onLockoutPermanent(); + void onLockoutCleared(); void onInteractionDetected(); void onEnrollmentsEnumerated(in int[] enrollmentIds); void onEnrollmentsRemoved(in int[] enrollmentIds); diff --git a/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/SessionState.aidl b/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/SessionState.aidl index 38ca1e052b..97f1a1e987 100644 --- a/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/SessionState.aidl +++ b/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/SessionState.aidl @@ -25,5 +25,6 @@ enum SessionState { ENUMERATING_ENROLLMENTS = 4, REMOVING_ENROLLMENTS = 5, GETTING_AUTHENTICATOR_ID = 6, - RESETTING_LOCKOUT = 7, + INVALIDATING_AUTHENTICATOR_ID = 7, + RESETTING_LOCKOUT = 8, } diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/AcquiredInfo.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/AcquiredInfo.aidl index 8cb78339c4..adb1c78cb2 100644 --- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/AcquiredInfo.aidl +++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/AcquiredInfo.aidl @@ -19,13 +19,49 @@ package android.hardware.biometrics.fingerprint; @VintfStability @Backing(type="byte") enum AcquiredInfo { + /** + * A high quality fingerprint image was detected, no further user interaction is necessary. + */ GOOD, + + /** + * Not enough of a fingerprint was detected. Reposition the finger, or a longer swipe needed. + */ PARTIAL, + + /** + * Image doesn't contain enough detail for recognition. + */ INSUFFICIENT, + + /** + * The sensor needs to be cleaned. + */ SENSOR_DIRTY, + + /** + * For swipe-type sensors, the swipe was too slow and not enough data was collected. + */ TOO_SLOW, + + /** + * For swipe-type sensors, the swipe was too fast and not enough data was collected. + */ TOO_FAST, + + /** + * Vendor-specific acquisition message. See ISessionCallback#onAcquired vendorCode + * documentation. + */ + VENDOR, + + /** + * This message represents the earliest message sent at the beginning of the authentication + * pipeline. It is expected to be used to measure latency. For example, in a camera-based + * authentication system it's expected to be sent prior to camera initialization. Note this + * should be sent whenever authentication is started or restarted. The framework may measure + * latency based on the time between the last START message and the onAuthenticated callback. + */ START, - VENDOR } diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/Error.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/Error.aidl index cc79de7b05..014a4c032a 100644 --- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/Error.aidl +++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/Error.aidl @@ -19,14 +19,58 @@ package android.hardware.biometrics.fingerprint; @VintfStability @Backing(type="byte") enum Error { - HW_UNAVAILABLE, + /** + * Used for testing, and to keep subsequent numbering consistent with older HIDLs. + */ + // NO_ERROR = 0, + + /** + * A hardware error has occurred that cannot be resolved. For example, I2C failure or a broken + * sensor. + */ + HW_UNAVAILABLE = 1, + + /** + * The implementation is unable to process the request. For example, invalid arguments were + * supplied. + */ UNABLE_TO_PROCESS, + + /** + * The current operation took too long to complete. + */ TIMEOUT, + + /** + * No space available to store additional enrollments. + */ NO_SPACE, + + /** + * The operation was canceled. See common::ICancellationSignal. + */ CANCELED, + + /** + * The implementation was unable to remove an enrollment. + * See ISession#removeEnrollments. + */ UNABLE_TO_REMOVE, - LOCKOUT, - LOCKOUT_PERMANENT, - VENDOR + + /** + * Reserved to maintain backwards compatibility. See ISessionCallback#onLockoutTimed instead. + */ + // LOCKOUT = 7, + + /** + * Used to enable vendor-specific error messages. + */ + VENDOR = 8, + + /** + * Reserved to maintain backwards compatibility. See ISessionCallback#onLockoutPermanent + * instead. + */ + // LOCKOUT_PERMANENT = 9, } diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/IFingerprint.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/IFingerprint.aidl index 57319b2906..0c8ebc534b 100644 --- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/IFingerprint.aidl +++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/IFingerprint.aidl @@ -17,7 +17,6 @@ package android.hardware.biometrics.fingerprint; import android.hardware.biometrics.fingerprint.IGenerateChallengeCallback; -import android.hardware.biometrics.fingerprint.ILockoutCallback; import android.hardware.biometrics.fingerprint.IRevokeChallengeCallback; import android.hardware.biometrics.fingerprint.ISession; import android.hardware.biometrics.fingerprint.ISessionCallback; @@ -72,36 +71,6 @@ interface IFingerprint { */ ISession createSession(in int sensorId, in int userId, in ISessionCallback cb); - /** - * setLockoutCallback: - * - * Sets a callback to notify the framework lockout changes. Note - * that lockout is user AND sensor specific. In other words, there is a - * separate lockout state for each (user, sensor) pair. For example, the - * following is a valid state on a multi-sensor device: - * ------------------------------------------------------------------ - * | SensorId | UserId | FailedAttempts | LockedOut | LockedUntil | - * |----------|--------|----------------|-----------|---------------| - * | 0 | 0 | 1 | false | x | - * | 1 | 0 | 5 | true | | - * | 0 | 10 | 0 | false | x | - * | 1 | 10 | 0 | false | x | - * ------------------------------------------------------------------ - * - * Lockout may be cleared in the following ways: - * 1) ISession#resetLockout - * 2) After a period of time, according to a rate-limiter. - * - * In addition, lockout states MUST persist after device reboots, HAL - * crashes, etc. - * - * See the Android CDD section 7.3.10 for the full set of lockout and - * rate-limiting requirements. - * - * @param cb Used to notify the framework of lockout changes. - */ - void setLockoutCallback(in ILockoutCallback cb); - /** * generateChallenge: * diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ILockoutCallback.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ILockoutCallback.aidl deleted file mode 100644 index 4b31a38e52..0000000000 --- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ILockoutCallback.aidl +++ /dev/null @@ -1,60 +0,0 @@ -/* - * Copyright (C) 2020 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; - -@VintfStability -oneway interface ILockoutCallback { - /** - * Notifies the framework that the user has just entered the Error::LOCKOUT state. This must be - * sent in the following scenarios: - * 1) The user just attempted authentication and was rejected, resulting in a timed lockout. - * 2) The framework just created a session for a sensorId/userId pair that has not been - * created since the HAL started (e.g. there is no active or idle session for this - * sensorId/userId pair. - * - * @param sensorId Sensor for which the user is locked out. - * @param userId User for which the sensor is locked out. - * @param durationMillis Remaining duration of the lockout. - */ - void onLockoutTimed(in int sensorId, in int userId, in long durationMillis); - - /** - * Notifies the framework that the user has just entered the Error::LOCKOUT_PERMANENT state. - * This must be sent in the following scenarios: - * 1) The user just attempted authentication and was rejected, resulting in a permanent lockout. - * 2) The framework just created a session for a sensorId/userId pair that has not been - * created since the HAL started (e.g. there is no active or idle session for this - * sensorId/userId pair. - * - * @param sensorId Sensor for which the user is locked out. - * @param userId User for which the sensor is locked out. - */ - void onLockoutPermanent(in int sensorId, in int userId); - - /** - * Notifies the framework that lockout has been cleared for this sensorId/userId pair. This - * can happen in the following scenarios: - * 1) A timed lockout has ended (e.g. original durationMillis specified in #onLockoutTimed - * has expired. - * 2) See ISession#resetLockout. - * - * @param sensorId Sensor for which the user's lockout is cleared. - * @param userId User for the sensor's lockout is cleared. - */ - void onLockoutCleared(in int sensorId, in int userId); -} - diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl index e2d23a6160..d0f546a41f 100644 --- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl +++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl @@ -19,20 +19,194 @@ package android.hardware.biometrics.fingerprint; import android.hardware.biometrics.common.ICancellationSignal; import android.hardware.keymaster.HardwareAuthToken; +/** + * Operations that can be performed for unique sessions retrieved via IFingerprint#createSession. + * Methods defined within this interface can be split into the following categories: + * 1) Methods associated with a state (see the SessionState enum). State-based operations are + * handled by the HAL in FIFO order. + * 1a) Cancellable state-based operations. If a cancellable operation is in-progress and the + * framework requests a subsequent state-based operation, the implementation should finish + * the operation via ISessionCallback#onError with Error::CANCELED. + * 1b) Non-cancellable state-based operations. These operations should fully complete before the + * next state-based operation can be started. + * 2) Methods without a state. These methods may be invoked by the framework depending on its + * use case. For example on devices with sensors of FingerprintSensorType::UNDER_DISPLAY_*, + * ISession#onFingerDown may be invoked while the HAL is in SessionState::ENROLLING, + * SessionState::AUTHENTICATING, or SessionState::DETECTING_INTERACTION. + * + * If the HAL has multiple operations in its queue, it is not required to notify the framework + * of SessionState::IDLING between each operation. However, it must notify the framework when all + * work is completed. See ISessionCallback#onStateChanged. For example, the following is a valid + * sequence of ISessionCallback#onStateChanged invocations: SessionState::IDLING --> + * SessionState::ENROLLING --> SessionState::ENUMERATING_ENROLLMENTS --> SessionState::IDLING. + */ @VintfStability interface ISession { /** * Methods applicable to any fingerprint type. */ + /** + * enroll: + * + * A request to add a fingerprint enrollment. + * + * Once the HAL is able to start processing the enrollment request, it must + * notify the framework via ISessionCallback#onStateChanged with + * SessionState::ENROLLING. + * + * At any point during enrollment, if a non-recoverable error occurs, + * the HAL must notify the framework via ISessionCallback#onError with + * the applicable enrollment-specific error, and then send + * ISessionCallback#onStateChanged(cookie, SessionState::IDLING) if no + * subsequent operation is in the queue. + * + * Before capturing fingerprint data, the implementation must first + * verify the authenticity and integrity of the provided HardwareAuthToken. + * In addition, it must check that the challenge within the provided + * HardwareAuthToken is valid. See IFingerprint#generateChallenge. + * If any of the above checks fail, the framework must be notified + * via ISessionCallback#onError and the HAL must notify the framework when + * it returns to the idle state. See Error::UNABLE_TO_PROCESS. + * + * During enrollment, the implementation may notify the framework + * via ISessionCallback#onAcquired with messages that may be used to guide + * the user. This callback can be invoked multiple times if necessary. + * Similarly, the framework may be notified of enrollment progress changes + * via ISessionCallback#onEnrollmentProgress. Once the framework is notified + * that there are 0 "remaining" steps, the framework may cache the + * "enrollmentId". See ISessionCallback#onEnrollmentProgress for more info. + * The HAL must notify the framework once it returns to the idle state. + * + * When a finger is successfully added and before the framework is notified + * of remaining=0, the implementation MUST update and associate this + * (sensorId, userId) pair with a new new entropy-encoded random identifier. + * See ISession#getAuthenticatorId for more information. + * + * @param cookie An identifier used to track subsystem operations related + * to this call path. The client must guarantee that it is + * unique per ISession. + * @param hat See above documentation. + */ ICancellationSignal enroll(in int cookie, in HardwareAuthToken hat); - ICancellationSignal authenticate(in int cookie, in long keystoreOperationId); + /** + * authenticate: + * + * A request to start looking for fingerprints to authenticate. + * + * Once the HAL is able to start processing the authentication request, it must notify framework + * via ISessionCallback#onStateChanged with SessionState::AUTHENTICATING. + * + * At any point during authentication, if a non-recoverable error occurs, the HAL must notify + * the framework via ISessionCallback#onError with the applicable authentication-specific error, + * and then send ISessionCallback#onStateChanged(cookie, SessionState::IDLING) if no + * subsequent operation is in the queue. + * + * During authentication, the implementation may notify the framework via + * ISessionCallback#onAcquired with messages that may be used to guide the user. This callback + * can be invoked multiple times if necessary. + * + * The HAL must notify the framework of accepts/rejects via ISessionCallback#onAuthentication*. + * + * The authentication lifecycle ends when either + * 1) A fingerprint is accepted, and ISessionCallback#onAuthenticationSucceeded is invoked, or + * 2) Any non-recoverable error occurs (such as lockout). See the full list of + * authentication-specific errors in the Error enum. + * + * Note that upon successful authentication, the lockout counter for this (sensorId, userId) + * pair must be cleared. + * + * Note that upon successful authentication, ONLY sensors configured as SensorStrength::STRONG + * are allowed to create and send a HardwareAuthToken to the framework. See the Android CDD for + * more details. For SensorStrength::STRONG sensors, the HardwareAuthToken's "challenge" field + * must be set with the operationId passed in during #authenticate. If the sensor is NOT + * SensorStrength::STRONG, the HardwareAuthToken MUST be null. + * + * @param cookie An identifier used to track subsystem operations related to this call path. The + * client must guarantee that it is unique per ISession. + * @param operationId For sensors configured as SensorStrength::STRONG, this must be used ONLY + * upon successful authentication and wrapped in the HardwareAuthToken's + * "challenge" field and sent to the framework via + * ISessionCallback#onAuthenticated. The operationId is an opaque identifier + * created from a separate secure subsystem such as, but not limited to + * KeyStore/KeyMaster. The HardwareAuthToken can then be used as an + * attestation for the provided operation. For example, this is used + * to unlock biometric-bound auth-per-use keys (see + * setUserAuthenticationParameters in KeyGenParameterSpec.Builder and + * KeyProtection.Builder. + */ + ICancellationSignal authenticate(in int cookie, in long operationId); + /** + * detectInteraction: + * + * A request to start looking for fingerprints without performing matching. + * + * Once the HAL is able to start processing this request, it must notify the framework via + * ISessionCallback#onStateChanged with SessionState::DETECTING_INTERACTION. + * + * The framework will use this method in cases where determing user presence is required, but + * identifying/authentication is not. For example, when the device is encrypted (first boot) or + * in lockdown mode. + * + * At any point during detectInteraction, if a non-recoverable error occurs, the HAL must notify + * the framework via ISessionCallback#onError with the applicable error, and then send + * ISessionCallback#onStateChanged(cookie, SessionState::IDLING) if no subsequent operation is + * in the queue. + * + * The implementation must only check for a fingerprint-like image was detected (e.g. to + * minimize interactions due to non-fingerprint objects), and the lockout counter must not + * be modified. + * + * Upon detecting any fingerprint, the implementation must invoke + * ISessionCallback#onInteractionDetected. + * + * The lifecycle of this operation ends when either + * 1) Any fingerprint is detected and the framework is notified via + * ISessionCallback#onInteractiondetected + * 2) The operation was cancelled by the framework (see ICancellationSignal) + * 3) The HAL ends the operation, for example when a subsequent operation pre-empts this one. + * + * Note that if the operation is canceled, the implementation must notify the framework via + * ISessionCallback#onError with Error::CANCELED. + * + * @param cookie An identifier used to track subsystem operations related to this call path. + * The framework will guarantee that it is unique per ISession. + */ ICancellationSignal detectInteraction(in int cookie); + /* + * enumerateEnrollments: + * + * A request to enumerate (list) the enrollments for this (sensorId, userId) pair. The + * framework typically uses this to ensure that its cache is in sync with the HAL. + * + * Once the HAL is able to start processing this request, it must notify the framework via + * ISessionCallback#onStateChanged with SessionState::ENUMERATING_ENROLLMENTS. + * + * The implementation must then notify the framework with a list of enrollments applicable + * for the current session via ISessionCallback#onEnrollmentsEnumerated. + * + * @param cookie An identifier used to track subsystem operations related to this call path. + * The framework will guarantee that it is unique per ISession. + */ void enumerateEnrollments(in int cookie); + /** + * removeEnrollments: + * + * A request to remove the enrollments for this (sensorId, userId) pair. + * + * Once the HAL is able to start processing this request, it must notify the framework via + * ISessionCallback#onStateChanged with SessionState::REMOVING_ENROLLMENTS. + * + * After removing the enrollmentIds from everywhere necessary (filesystem, secure subsystems, + * etc), the implementation must notify the framework via ISessionCallback#onEnrollmentsRemoved. + * + * @param cookie An identifier used to track subsystem operations related to this call path. + * The framework will guarantee that it is unique per ISession. + */ void removeEnrollments(in int cookie, in int[] enrollmentIds); /** @@ -45,9 +219,10 @@ interface ISession { * The following only applies to sensors that are configured as * SensorStrength::STRONG. * - * The authenticatorId is used during key generation and key import to to - * associate a key (in KeyStore / KeyMaster) with the current set of - * enrolled fingerprints. For example, the following public Android APIs + * The authenticatorId is a (sensorId, user)-specific identifier which + * can be used during key generation and key import to to associate a + * key (in KeyStore / KeyMaster) with the current set of enrolled + * fingerprints. For example, the following public Android APIs * allow for keys to be invalidated when the user adds a new enrollment * after the key was created: * KeyGenParameterSpec.Builder.setInvalidatedByBiometricEnrollment and @@ -66,7 +241,7 @@ interface ISession { * 4) MUST be an entropy-encoded random number * * @param cookie An identifier used to track subsystem operations related - * to this call path. The framework will guarantee that it is + * to this call path. The client must guarantee that it is * unique per ISession. */ void getAuthenticatorId(in int cookie); @@ -84,9 +259,15 @@ interface ISession { * * When invoked by the framework, the implementation must perform the * following sequence of events: - * 1) Verify the authenticity and integrity of the provided HAT + * 1) Verify the authenticity and integrity of the provided HAT. If this + * check fails, the HAL must invoke ISessionCallback#onError with + * Error::UNABLE_TO_PROCESS and return to + * SessionState::IDLING if no subsequent work is in the queue. * 2) Verify that the timestamp provided within the HAT is relatively - * recent (e.g. on the order of minutes, not hours). + * recent (e.g. on the order of minutes, not hours). If this check fails, + * the HAL must invoke ISessionCallback#onError with + * Error::UNABLE_TO_PROCESS and return to SessionState::IDLING + * if no subsequent work is in the queue. * 3) Update the authenticatorId with a new entropy-encoded random number * 4) Persist the new authenticatorId to non-ephemeral storage * 5) Notify the framework that the above is completed, via @@ -100,7 +281,7 @@ interface ISession { * across multiple biometric HALs as necessary. * * @param cookie An identifier used to track subsystem operations related - * to this call path. The framework will guarantee that it is + * to this call path. The client must guarantee that it is * unique per ISession. * @param hat HardwareAuthToken that must be validated before proceeding * with this operation. @@ -110,34 +291,103 @@ interface ISession { /** * resetLockout: * - * Requests the implementation to clear the lockout counter. Upon receiving - * this request, the implementation must perform the following: + * Requests the implementation to clear the lockout counter. Upon receiving this request, the + * implementation must perform the following: * 1) Verify the authenticity and integrity of the provided HAT - * 2) Verify that the timestamp provided within the HAT is relatively - * recent (e.g. on the order of minutes, not hours). + * 2) Verify that the timestamp provided within the HAT is relatively recent (e.g. on the + * order of minutes, not hours). + * If either of the checks fail, the HAL must invoke ISessionCallback#onError with + * Error::UNABLE_TO_PROCESS and return to SessionState::IDLING if no subsequent work is in the + * queue. * - * Upon successful verification, the HAL must notify the framework via - * ILockoutCallback#onLockoutChanged(sensorId, userId, 0). + * Upon successful verification, the HAL must clear the lockout counter and notify the framework + * via ISessionCallback#onLockoutCleared. * - * If verification was uncessful, the HAL must notify the framework via - * ILockoutCallback#onLockoutChanged(sensorId, userId, remaining_time). + * Note that lockout is user AND sensor specific. In other words, there is a separate lockout + * state for each (user, sensor) pair. For example, the following is a valid state on a + * multi-sensor device: + * ------------------------------------------------------------------ + * | SensorId | UserId | FailedAttempts | LockedOut | LockedUntil | + * |----------|--------|----------------|-----------|---------------| + * | 0 | 0 | 1 | false | x | + * | 1 | 0 | 5 | true | | + * | 0 | 10 | 0 | false | x | + * | 1 | 10 | 0 | false | x | + * ------------------------------------------------------------------ + * + * Lockout may be cleared in the following ways: + * 1) ISession#resetLockout + * 2) After a period of time, according to a rate-limiter. + * + * Note that the "FailedAttempts" counter must be cleared upon successful fingerprint + * authentication. For example, if SensorId=0 UserId=0 FailedAttempts=1, and a successful + * fingerprint authentication occurs, the counter for that (SensorId, UserId) pair must be reset + * to 0. + * + * In addition, lockout states MUST persist after device reboots, HAL crashes, etc. + * + * See the Android CDD section 7.3.10 for the full set of lockout and rate-limiting + * requirements. * * @param cookie An identifier used to track subsystem operations related - * to this call path. The framework will guarantee that it is + * to this call path. The client must guarantee that it is * unique per ISession. * @param hat HardwareAuthToken See above documentation. */ void resetLockout(in int cookie, in HardwareAuthToken hat); - /** * Methods for notifying the under-display fingerprint sensor about external events. */ + /** + * onPointerDown: + * + * This method only applies to sensors that are configured as + * FingerprintSensorType::UNDER_DISPLAY_*. If invoked erroneously by the framework for sensors + * of other types, the HAL must treat this as a no-op and return immediately. + * + * For sensors of type FingerprintSensorType::UNDER_DISPLAY_*, this method is used to notify the + * HAL of display touches. This method can be invoked when the session is in one of the + * following states: SessionState::ENROLLING, SessionState::AUTHENTICATING, or + * SessionState::DETECTING_INTERACTION. + * + * Note that the framework will only invoke this method if the event occurred on the display + * on which this sensor is located. + * + * Note that for sensors which require illumination such as + * FingerprintSensorType::UNDER_DISPLAY_OPTICAL, and where illumination is handled below + * the framework, this is a good time to start illuminating. + * + * @param pointerId See android.view.MotionEvent#getPointerId + * @param x The distance in pixels from the left edge of the display. + * @param y The distance in pixels from the top edge of the display. + * @param minor See android.view.MotionEvent#getTouchMinor + * @param major See android.view.MotionEvent#getTouchMajor + */ void onPointerDown(in int pointerId, in int x, in int y, in float minor, in float major); + /** + * onPointerUp: + * + * This method only applies to sensors that are configured as + * FingerprintSensorType::UNDER_DISPLAY_*. If invoked for sensors of other types, the HAL must + * treat this as a no-op and return immediately. + * + * @param pointerId See android.view.MotionEvent#getPointerId + */ void onPointerUp(in int pointerId); + /* + * onUiReady: + * + * This method only applies to sensors that are configured as + * FingerprintSensorType::UNDER_DISPLAY_OPTICAL. If invoked for sensors of other types, the HAL + * must treat this as a no-op and return immediately. + * + * For FingerprintSensorType::UNDER_DISPLAY_OPTICAL where illumination is handled above the + * HAL, the framework will invoke this method to notify that the illumination has started. + */ void onUiReady(); } diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl index c608d65569..33a93e59b4 100644 --- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl +++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl @@ -23,29 +23,162 @@ import android.hardware.keymaster.HardwareAuthToken; @VintfStability interface ISessionCallback { + /** + * Used to notify the framework of session state changes. See ISession for more information. + */ void onStateChanged(in int cookie, in SessionState state); + /** + * This method must only be used to notify the framework during the following states: + * 1) SessionState::ENROLLING + * 2) SessionState::AUTHENTICATING + * 3) SessionState::DETECTING_INTERACTION + * + * These messages may be used to provide user guidance multiple times if necessary per + * operation. + * + * @param info See the AcquiredInfo enum. + * @param vendorCode Only valid if info == AcquiredInfo::VENDOR. + */ void onAcquired(in AcquiredInfo info, in int vendorCode); + /** + * This method must only be used to notify the framework during the following states: + * 1) SessionState::ENROLLING + * 2) SessionState::AUTHENTICATING + * 3) SessionState::DETECTING_INTERACTION + * 4) SessionState::INVALIDATING_AUTHENTICATOR_ID + * 5) SessionState::RESETTING_LOCKOUT + * + * These messages may be used to notify the framework or user that a non-recoverable error + * has occurred. The operation is finished, and the HAL must proceed with the next operation + * or return to SessionState::IDLING if the queue is empty. + * + * Note that cancellation (see common::ICancellationSignal) and preemption most be followed with + * an Error::CANCELED message. + * + * @param error See the Error enum. + * @param vendorCode Only valid if error == Error::VENDOR. + */ void onError(in Error error, in int vendorCode); - void onEnrollmentProgress(in int enrollmentId, int remaining, int vendorCode); + /** + * This method must only be used to notify the framework during the following state: + * 1) SessionState::ENROLLING + * + * @param enrollmentId Unique stable identifier for the enrollment that's being added by this + * ISession#enroll invocation. + * @param remaining Remaining number of steps before enrollment is complete. + */ + void onEnrollmentProgress(in int enrollmentId, int remaining); - void onAuthenticated(in int enrollmentId, in HardwareAuthToken hat); + /** + * This method must only be used to notify the framework during SessionState::AUTHENTICATING. + * + * Used to notify the framework upon successful authentication. Note that the authentication + * lifecycle ends when either 1) a fingerprint is accepted, or 2) an error occurred. The + * authentication lifecycle does NOT end when a fingerprint is rejected. + * + * @param enrollmentId Fingerprint that was accepted. + * @param hat If the sensor is configured as SensorStrength::STRONG, a non-null attestation that + * a fingerprint was accepted. The HardwareAuthToken's "challenge" field must be set + * with the operationId passed in during ISession#authenticate. If the sensor is NOT + * SensorStrength::STRONG, the HardwareAuthToken MUST be null. + */ + void onAuthenticationSucceeded(in int enrollmentId, in HardwareAuthToken hat); + /** + * This method must only be used to notify the framework during SessionState::AUTHENTICATING. + * + * Used to notify the framework upon rejected attempts. Note that the authentication + * lifecycle ends when either 1) a fingerprint is accepted, or 2) an occurred. The + * authentication lifecycle does NOT end when a fingerprint is rejected. + */ + void onAuthenticationFailed(); + + /** + * This method must only be used to notify the framework during SessionState::AUTHENTICATING. + * + * Authentication is locked out due to too many unsuccessful attempts. This is a rate-limiting + * lockout, and authentication can be restarted after a period of time. See + * ISession#resetLockout. + * + * @param sensorId Sensor for which the user is locked out. + * @param userId User for which the sensor is locked out. + * @param durationMillis Remaining duration of the lockout. + */ + void onLockoutTimed(in long durationMillis); + + /** + * This method must only be used to notify the framework during SessionState::AUTHENTICATING. + * + * Authentication is disabled until the user unlocks with their device credential + * (PIN/Pattern/Password). See ISession#resetLockout. + * + * @param sensorId Sensor for which the user is locked out. + * @param userId User for which the sensor is locked out. + */ + void onLockoutPermanent(); + + /** + * Notifies the framework that lockout has been cleared for this (sensorId, userId) pair. + * + * Note that this method can be used to notify the framework during any state. + * + * Lockout can be cleared in the following scenarios: + * 1) A timed lockout has ended (e.g. durationMillis specified in previous #onLockoutTimed + * has expired. + * 2) See ISession#resetLockout. + * + * @param sensorId Sensor for which the user's lockout is cleared. + * @param userId User for the sensor's lockout is cleared. + */ + void onLockoutCleared(); + + /** + * This method must only be used to notify the framework during + * SessionState::DETECTING_INTERACTION + * + * Notifies the framework that user interaction occurred. See ISession#detectInteraction. + */ void onInteractionDetected(); + /** + * This method must only be used to notify the framework during + * SessionState::ENUMERATING_ENROLLMENTS. + * + * Notifies the framework of the current enrollments. See ISession#enumerateEnrollments. + * + * @param enrollmentIds A list of enrollments for the session's (userId, sensorId) pair. + */ void onEnrollmentsEnumerated(in int[] enrollmentIds); + /** + * This method must only be used to notify the framework during + * SessionState::REMOVING_ENROLLMENTS. + * + * Notifies the framework that the specified enrollments are removed. + * + * @param enrollmentIds The enrollments that were removed. + */ void onEnrollmentsRemoved(in int[] enrollmentIds); /** - * A callback invoked when ISession#getAuthenticatorId is invoked. + * This method must only be used to notify the framework during + * SessionState::GETTING_AUTHENTICATOR_ID. + * + * Notifies the framework with the authenticatorId corresponding to this session's + * (userId, sensorId) pair. + * + * @param authenticatorId See the above documentation. */ void onAuthenticatorIdRetrieved(in long authenticatorId); /** - * A callback invoked when ISession#invalidateAuthenticatorId has completed. + * This method must only be used to notify the framework during + * SessionState::INVALIDATING_AUTHENTICATOR_ID. + * + * See ISession#invalidateAuthenticatorId for more information. */ void onAuthenticatorIdInvalidated(); } diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/SessionState.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/SessionState.aidl index 3b4ba184e6..405b011b31 100644 --- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/SessionState.aidl +++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/SessionState.aidl @@ -19,13 +19,49 @@ package android.hardware.biometrics.fingerprint; @VintfStability @Backing(type="byte") enum SessionState { + /** + * The HAL is not processing any session requests. + */ IDLING, + + /** + * The HAL is processing the ISession#enroll request. + */ ENROLLING, + + /** + * The HAL is processing the ISession#authenticate request. + */ AUTHENTICATING, + + /** + * The HAL is processing the ISession#detectInteraction request. + */ DETECTING_INTERACTION, + + /** + * The HAL is processing the ISession#enumerateEnrollments request. + */ ENUMERATING_ENROLLMENTS, + + /** + * The HAL is processing the ISession#removeEnrollments request. + */ REMOVING_ENROLLMENTS, + + /** + * The HAL is processing the ISession#getAuthenticatorId request. + */ GETTING_AUTHENTICATOR_ID, + + /** + * The HAL is processing the ISession#invalidateAuthenticatorId request. + */ + INVALIDATING_AUTHENTICATOR_ID, + + /** + * The HAL is processing the ISession#resetLockout request. + */ RESETTING_LOCKOUT } diff --git a/biometrics/fingerprint/aidl/default/Fingerprint.cpp b/biometrics/fingerprint/aidl/default/Fingerprint.cpp index b3bd4e7a29..b907bf1d31 100644 --- a/biometrics/fingerprint/aidl/default/Fingerprint.cpp +++ b/biometrics/fingerprint/aidl/default/Fingerprint.cpp @@ -61,11 +61,6 @@ ndk::ScopedAStatus Fingerprint::createSession(int32_t /*sensorId*/, int32_t /*us return ndk::ScopedAStatus::ok(); } -ndk::ScopedAStatus Fingerprint::setLockoutCallback( - const std::shared_ptr& /*cb*/) { - return ndk::ScopedAStatus::ok(); -} - ndk::ScopedAStatus Fingerprint::generateChallenge( int32_t /*sensorId*/, int32_t /*userId*/, int32_t /*timeoutSec*/, const std::shared_ptr& /*cb*/) { diff --git a/biometrics/fingerprint/aidl/default/Fingerprint.h b/biometrics/fingerprint/aidl/default/Fingerprint.h index 463d07db13..59cdd441fc 100644 --- a/biometrics/fingerprint/aidl/default/Fingerprint.h +++ b/biometrics/fingerprint/aidl/default/Fingerprint.h @@ -28,9 +28,6 @@ class Fingerprint : public BnFingerprint { const std::shared_ptr& cb, std::shared_ptr* _aidl_return) override; - ndk::ScopedAStatus setLockoutCallback( - const std::shared_ptr& cb) override; - ndk::ScopedAStatus generateChallenge( int32_t sensorId, int32_t userId, int32_t timeoutSec, const std::shared_ptr& cb) override; diff --git a/biometrics/fingerprint/aidl/vts/VtsHalBiometricsFingerprintTargetTest.cpp b/biometrics/fingerprint/aidl/vts/VtsHalBiometricsFingerprintTargetTest.cpp index 9590d68000..496badc741 100644 --- a/biometrics/fingerprint/aidl/vts/VtsHalBiometricsFingerprintTargetTest.cpp +++ b/biometrics/fingerprint/aidl/vts/VtsHalBiometricsFingerprintTargetTest.cpp @@ -60,16 +60,32 @@ class SessionCallback : public BnSessionCallback { return ndk::ScopedAStatus::ok(); } - ndk::ScopedAStatus onEnrollmentProgress(int32_t /*enrollmentId*/, int32_t /*remaining*/, - int32_t /*vendorCode*/) override { + ndk::ScopedAStatus onEnrollmentProgress(int32_t /*enrollmentId*/, + int32_t /*remaining*/) override { return ndk::ScopedAStatus::ok(); } - ndk::ScopedAStatus onAuthenticated(int32_t /*enrollmentId*/, + ndk::ScopedAStatus onAuthenticationSucceeded(int32_t /*enrollmentId*/, const keymaster::HardwareAuthToken& /*hat*/) override { return ndk::ScopedAStatus::ok(); } + ndk::ScopedAStatus onAuthenticationFailed() override { + return ndk::ScopedAStatus::ok(); + } + + ndk::ScopedAStatus onLockoutTimed(int64_t /*durationMillis*/) override { + return ndk::ScopedAStatus::ok(); + } + + ndk::ScopedAStatus onLockoutPermanent() override { + return ndk::ScopedAStatus::ok(); + } + + ndk::ScopedAStatus onLockoutCleared() override { + return ndk::ScopedAStatus::ok(); + } + ndk::ScopedAStatus onInteractionDetected() override { return ndk::ScopedAStatus::ok(); } ndk::ScopedAStatus onEnrollmentsEnumerated(