Evolution-x/hardware_interfaces
1
0
Fork 0
mirror of https://github.com/Evolution-X/hardware_interfaces synced 2026-02-01 11:36:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge changes I0b7e7ab3,I92db9b22,I24615333,I7ca0365b

Browse Source 
* changes:
  Move lockout callbacks to ISessionCallback
  Finish remainder of documentation.
  Minor API changes and additional documentation for IFingerprint
  Update fingerprint #authenticate interfaces & documentation
This commit is contained in:
Kevin Chyn
2020-09-23 20:24:39 +00:00
committed by Android (Google) Code Review
parent 8fa716a72f ef79d661ba
commit ac378f41fa
17 changed files with 562 additions and 168 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/AcquiredInfo.aidl
View File

@@ -24,6 +24,6 @@ enum AcquiredInfo {
SENSOR_DIRTY = 3,
TOO_SLOW = 4,
TOO_FAST = 5,
START = 6,
VENDOR = 7,
VENDOR = 6,
START = 7,
}

14
biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/Error.aidl
View File

@@ -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,
}

1
biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/IFingerprint.aidl
View File

@@ -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);
}

24
biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ILockoutCallback.aidl
View File

@@ -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);
}

2
biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ISession.aidl
View File

@@ -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);

8
biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ISessionCallback.aidl
View File

@@ -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);

3
biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/SessionState.aidl
View File

@@ -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,
}

38
biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/AcquiredInfo.aidl
View File

@@ -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
}

52
biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/Error.aidl
View File

@@ -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,
}

31
biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/IFingerprint.aidl
View File

@@ -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 | <future_time> |
* | 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:
*

60
biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ILockoutCallback.aidl
View File

@@ -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);
}

286
biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl
View File

@@ -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 | <future_time> |
* | 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();
}

141
biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl
View File

@@ -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();
}

36
biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/SessionState.aidl
View File

@@ -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
}

5
biometrics/fingerprint/aidl/default/Fingerprint.cpp
View File

@@ -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<ILockoutCallback>& /*cb*/) {
return ndk::ScopedAStatus::ok();
}
ndk::ScopedAStatus Fingerprint::generateChallenge(
int32_t /*sensorId*/, int32_t /*userId*/, int32_t /*timeoutSec*/,
const std::shared_ptr<IGenerateChallengeCallback>& /*cb*/) {

3
biometrics/fingerprint/aidl/default/Fingerprint.h
View File

@@ -28,9 +28,6 @@ class Fingerprint : public BnFingerprint {
const std::shared_ptr<ISessionCallback>& cb,
std::shared_ptr<ISession>* _aidl_return) override;
ndk::ScopedAStatus setLockoutCallback(
const std::shared_ptr<ILockoutCallback>& cb) override;
ndk::ScopedAStatus generateChallenge(
int32_t sensorId, int32_t userId, int32_t timeoutSec,
const std::shared_ptr<IGenerateChallengeCallback>& cb) override;

22
biometrics/fingerprint/aidl/vts/VtsHalBiometricsFingerprintTargetTest.cpp
View File

@@ -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(