Minor API changes and additional documentation for IFingerprint
1) Removes vendorCode from onEnrollmentProgress. This is already
being sent in ISessionCallback#onAcquired
2) Adds missing SessionState::INVALIDATING_AUTHENTICATOR_ID state
Test: make -j56 android.hardware.biometrics.fingerprint-update-api
Test: make -j56 VtsHalBiometricsFingerprintTargetTest
Test: make -j56
Change-Id: I246153339b336c029c9f156868127456aecf1a04
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 114a2d1..cbac890 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,7 +21,7 @@
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 onEnrollmentProgress(in int enrollmentId, int remaining);
void onAuthenticationSucceeded(in int enrollmentId, in android.hardware.keymaster.HardwareAuthToken hat);
void onAuthenticationFailed();
void onInteractionDetected();
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 38ca1e0..97f1a1e 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 @@
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/Error.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/Error.aidl
index cc79de7..da5ee18 100644
--- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/Error.aidl
+++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/Error.aidl
@@ -19,14 +19,55 @@
@VintfStability
@Backing(type="byte")
enum Error {
+ /**
+ * A hardware error has occurred that cannot be resolved. For example, I2C failure or a broken
+ * sensor.
+ */
HW_UNAVAILABLE,
+
+ /**
+ * 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,
+
+ /**
+ * 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 the Android CDD for
+ * the full set of lockout and rate-limiting requirements.
+ */
LOCKOUT,
+
+ /**
+ * Authenticatio nis disabled until the user unlocks with their device credential
+ * (PIN/Pattern/Password). See ISession#resetLockout.
+ */
LOCKOUT_PERMANENT,
- VENDOR
+
+ /**
+ * Used to enable vendor-specific error messages.
+ */
+ VENDOR,
}
diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl
index 2d2dcaf..5fa56e0 100644
--- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl
+++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl
@@ -19,12 +19,75 @@
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, user) 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);
/**
@@ -39,7 +102,8 @@
* 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).
+ * 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
@@ -66,7 +130,7 @@
* HardwareAuthToken MUST be null.
*
* @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 operationId For sensors configured as SensorStrength::STRONG,
* this must be used ONLY upon successful authentication
@@ -99,9 +163,10 @@
* 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
@@ -120,7 +185,7 @@
* 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);
@@ -138,9 +203,15 @@
*
* 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
@@ -154,7 +225,7 @@
* 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.
@@ -169,15 +240,15 @@
* 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).
+ * 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).
- *
- * If verification was uncessful, the HAL must notify the framework via
- * ILockoutCallback#onLockoutChanged(sensorId, userId, remaining_time).
+ * Upon successful verification, the HAL must clear the lockout counter
+ * and notify the framework via ILockoutCallback#onLockoutChanged(sensorId, userId, 0).
*
* @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.
*/
diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl
index d494965..7130520 100644
--- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl
+++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl
@@ -29,7 +29,14 @@
void onError(in Error error, in int vendorCode);
- void onEnrollmentProgress(in int enrollmentId, int remaining, int vendorCode);
+ /**
+ * Used to notify the framework of enrollment progress. Enrollment completes when remaining==0,
+ *
+ * @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);
/**
* Used to notify the framework upon successful authentication. Note that the authentication
diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/SessionState.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/SessionState.aidl
index 3b4ba18..405b011 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 @@
@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/vts/VtsHalBiometricsFingerprintTargetTest.cpp b/biometrics/fingerprint/aidl/vts/VtsHalBiometricsFingerprintTargetTest.cpp
index 4651f25..3011786 100644
--- a/biometrics/fingerprint/aidl/vts/VtsHalBiometricsFingerprintTargetTest.cpp
+++ b/biometrics/fingerprint/aidl/vts/VtsHalBiometricsFingerprintTargetTest.cpp
@@ -60,8 +60,8 @@
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();
}