Merge "Add explanation to VHAL_HEARTBEAT property"
diff --git a/automotive/vehicle/2.0/default/impl/vhal_v2_0/DefaultConfig.h b/automotive/vehicle/2.0/default/impl/vhal_v2_0/DefaultConfig.h
index 72df256..e3b559e 100644
--- a/automotive/vehicle/2.0/default/impl/vhal_v2_0/DefaultConfig.h
+++ b/automotive/vehicle/2.0/default/impl/vhal_v2_0/DefaultConfig.h
@@ -499,6 +499,18 @@
},
.initialValue = {.int32Values = {0, 0, 0}}},
+ {.config =
+ {
+ .prop = toInt(VehicleProperty::HW_CUSTOM_INPUT),
+ .access = VehiclePropertyAccess::READ,
+ .changeMode = VehiclePropertyChangeMode::ON_CHANGE,
+ .configArray = {0, 0, 0, 3, 0, 0, 0, 0, 0},
+ },
+ .initialValue =
+ {
+ .int32Values = {0, 0, 0},
+ }},
+
{.config = {.prop = toInt(VehicleProperty::HVAC_POWER_ON),
.access = VehiclePropertyAccess::READ_WRITE,
.changeMode = VehiclePropertyChangeMode::ON_CHANGE,
diff --git a/automotive/vehicle/2.0/types.hal b/automotive/vehicle/2.0/types.hal
index d8a6838..11fe70e 100644
--- a/automotive/vehicle/2.0/types.hal
+++ b/automotive/vehicle/2.0/types.hal
@@ -1480,6 +1480,33 @@
| VehiclePropertyType:INT32_VEC
| VehicleArea:GLOBAL),
+ /**
+ * Defines a custom OEM partner input event.
+ *
+ * This input event must be used by OEM partners who wish to propagate events not supported
+ * by Android. It is composed by an array of int32 values only.
+ *
+ * The Android properties are:
+ *
+ * int32Values[0] : Input code identifying the function representing this event. Valid event
+ * types are defined by CustomInputType.CUSTOM_EVENT_F1 up to
+ * CustomInputType.CUSTOM_EVENT_F10. They represent the custom event to be
+ * defined by OEM partners.
+ * int32Values[1] : target display type defined in VehicleDisplay. Events not tied to specific
+ * display must be sent to VehicleDisplay#MAIN.
+ * int32Values[2] : repeat counter, if 0 then event is not repeated. Values 1 or above means
+ * how many times this event repeated.
+ *
+ * @change_mode VehiclePropertyChangeMode:ON_CHANGE
+ * @data_enum CustomInputType
+ * @access VehiclePropertyAccess:READ
+ */
+ HW_CUSTOM_INPUT = (
+ 0X0A30
+ | VehiclePropertyGroup:SYSTEM
+ | VehiclePropertyType:INT32_VEC
+ | VehicleArea:GLOBAL),
+
/***************************************************************************
* Most Car Cabin properties have both a POSition and MOVE parameter. These
* are used to control the various movements for seats, doors, and windows
@@ -4859,3 +4886,26 @@
*/
MEMORY_OVERUSE = 3,
};
+
+/**
+ * Input code values for HW_CUSTOM_INPUT.
+ */
+enum CustomInputType : int32_t {
+ /**
+ * Ten functions representing the custom input code to be defined and implemented by OEM
+ * partners.
+ *
+ * OEMs need to formally contact Android team if more than 10 functions are required.
+ */
+ CUSTOM_EVENT_F1 = 1001,
+ CUSTOM_EVENT_F2 = 1002,
+ CUSTOM_EVENT_F3 = 1003,
+ CUSTOM_EVENT_F4 = 1004,
+ CUSTOM_EVENT_F5 = 1005,
+ CUSTOM_EVENT_F6 = 1006,
+ CUSTOM_EVENT_F7 = 1007,
+ CUSTOM_EVENT_F8 = 1008,
+ CUSTOM_EVENT_F9 = 1009,
+ CUSTOM_EVENT_F10 = 1010,
+};
+
diff --git a/biometrics/common/aidl/android/hardware/biometrics/common/CommonProps.aidl b/biometrics/common/aidl/android/hardware/biometrics/common/CommonProps.aidl
index 8304c95..9c3fd58 100644
--- a/biometrics/common/aidl/android/hardware/biometrics/common/CommonProps.aidl
+++ b/biometrics/common/aidl/android/hardware/biometrics/common/CommonProps.aidl
@@ -22,29 +22,26 @@
@VintfStability
parcelable CommonProps {
/**
- * A statically configured unique ID that identifies a single biometric
- * sensor. IDs must start at zero and increment by one for each unique
- * sensor. Note that ID allocations are shared between all biometric
- * modalities (e.g. fingerprint, face, iris), and a single ID must never
+ * A statically configured unique ID that identifies a single biometric sensor. IDs must start
+ * at zero and increment by one for each unique sensor. Note that ID allocations are shared
+ * between all biometric modalities (e.g. fingerprint, face, iris), and a single ID must never
* be claimed by more than a single sensor.
*/
int sensorId;
/**
- * A statically configured strength for this sensor. See the SensorStrength
- * interface for more information.
+ * A statically configured strength for this sensor. See the SensorStrength interface for more
+ * information.
*/
SensorStrength sensorStrength;
/**
- * The maximum number of enrollments that a single user can have.
- * Statically configured.
+ * The maximum number of enrollments that a single user can have. Statically configured.
*/
int maxEnrollmentsPerUser;
/**
- * A list of hardware information for subsystems that pertain to this
- * biometric sensor.
+ * A list of hardware information for subsystems that pertain to this biometric sensor.
*/
HardwareInfo[] hardwareInfo;
}
\ No newline at end of file
diff --git a/biometrics/common/aidl/android/hardware/biometrics/common/SensorStrength.aidl b/biometrics/common/aidl/android/hardware/biometrics/common/SensorStrength.aidl
index 7460279..790691c 100644
--- a/biometrics/common/aidl/android/hardware/biometrics/common/SensorStrength.aidl
+++ b/biometrics/common/aidl/android/hardware/biometrics/common/SensorStrength.aidl
@@ -20,22 +20,21 @@
@Backing(type="byte")
enum SensorStrength {
/**
- * A sensor that meets the requirements for Class 1 biometrics as defined
- * in the CDD. This does not correspond to a public BiometricManager.Authenticators
- * constant. Sensors of this strength are not available to applications ia the
- * public API surface.
+ * A sensor that meets the requirements for Class 1 biometrics as defined in the CDD. This does
+ * not correspond to a public BiometricManager.Authenticators constant. Sensors of this strength
+ * are not available to applications via the public API surface.
*/
CONVENIENCE,
/**
- * A sensor that meets the requirements for Class 2 biometrics as defined
- * in the CDD. Corresponds to BiometricManager.Authenticators.BIOMETRIC_WEAK.
+ * A sensor that meets the requirements for Class 2 biometrics as defined in the CDD.
+ * Corresponds to BiometricManager.Authenticators.BIOMETRIC_WEAK.
*/
WEAK,
/**
- * A sensor that meets the requirements for Class 3 biometrics as defined
- * in the CDD. Corresponds to BiometricManager.Authenticators.BIOMETRIC_STRONG.
+ * A sensor that meets the requirements for Class 3 biometrics as defined in the CDD.
+ * Corresponds to BiometricManager.Authenticators.BIOMETRIC_STRONG.
*
* Notably, this is the only strength that allows generation/verification of
* HardwareAuthToken(s).
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 329a35d..df30dca 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 @@
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 0298c12..6bd71b2 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 9cbf343..6ca6d16 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 @@
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 88aabbf..0000000
--- 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 06c8623..c1f66e3 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 @@
@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 6140447..74ec077 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 @@
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 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/AcquiredInfo.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/AcquiredInfo.aidl
index 8cb7833..adb1c78 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 @@
@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 cc79de7..4fe7f5f 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 @@
@VintfStability
@Backing(type="byte")
enum Error {
- HW_UNAVAILABLE,
- UNABLE_TO_PROCESS,
- TIMEOUT,
- NO_SPACE,
- CANCELED,
- UNABLE_TO_REMOVE,
- LOCKOUT,
- LOCKOUT_PERMANENT,
- VENDOR
+ /**
+ * 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 = 2,
+
+ /**
+ * The current operation took too long to complete.
+ */
+ TIMEOUT = 3,
+
+ /**
+ * No space available to store additional enrollments.
+ */
+ NO_SPACE = 4,
+
+ /**
+ * The operation was canceled. See common::ICancellationSignal.
+ */
+ CANCELED = 5,
+
+ /**
+ * The implementation was unable to remove an enrollment.
+ * See ISession#removeEnrollments.
+ */
+ UNABLE_TO_REMOVE = 6,
+
+ /**
+ * 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 57319b2..4b907b4 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;
@@ -28,41 +27,34 @@
/**
* getSensorProps:
*
- * @return A list of properties for all sensors that an instance of the
- * HAL supports.
+ * @return A list of properties for all sensors that an instance of the HAL supports.
*/
SensorProps[] getSensorProps();
/**
* createSession:
*
- * Creates a session which can then be used by the framework to perform
- * operations such as enroll, authenticate, etc for the given sensorId
- * and userId.
+ * Creates a session which can then be used by the framework to perform operations such as
+ * enroll, authenticate, etc for the given sensorId and userId.
*
- * A physical sensor identified by sensorId typically supports only a
- * single in-flight session at a time. As such, if a session is currently
- * in a state other than SessionState::IDLING, the HAL MUST finish or
- * cancel the current operation and return to SessionState::IDLING before
- * the new session is created. For example:
- * 1) If a session for sensorId=0, userId=0
- * is currently in a cancellable state (see ICancellationSignal) such
- * as SessionState::AUTHENTICATING and the framework requests a new
- * session for sensorId=0, userId=10, the HAL must end the current
- * session with Error::CANCELED, invoke
- * ISessionCallback#onStateChanged with SessionState::IDLING, and
+ * A physical sensor identified by sensorId typically supports only a single in-flight session
+ * at a time. As such, if a session is currently in a state other than SessionState::IDLING, the
+ * HAL MUST finish or cancel the current operation and return to SessionState::IDLING before the
+ * new session is created. For example:
+ * 1) If a session for sensorId=0, userId=0 is currently in a cancellable state (see
+ * ICancellationSignal) such as SessionState::AUTHENTICATING and the framework requests a
+ * new session for sensorId=0, userId=10, the HAL must end the current session with
+ * Error::CANCELED, invoke ISessionCallback#onStateChanged with SessionState::IDLING, and
* then return a new session for sensorId=0, userId=10.
- * 2) If a session for sensorId=0, userId=0 is currently in a
- * non-cancellable state such as SessionState::REMOVING_ENROLLMENTS,
- * and the framework requests a new session for sensorId=0, userId=10,
- * the HAL must finish the current operation before invoking
- * ISessionCallback#onStateChanged with SessionState::IDLING, and
- * return a new session for sensorId=0, userId=10.
+ * 2) If a session for sensorId=0, userId=0 is currently in a non-cancellable state such as
+ * SessionState::REMOVING_ENROLLMENTS, and the framework requests a new session for
+ * sensorId=0, userId=10, the HAL must finish the current operation before invoking
+ * ISessionCallback#onStateChanged with SessionState::IDLING, and return a new session for
+ * sensorId=0, userId=10.
*
- * Implementations must store user-specific state or metadata in
- * /data/vendor_de/<user>/fpdata as specified by the SeLinux policy. This
- * directory is created/removed by vold (see vold_prepare_subdirs.cpp).
- * Implementations may store additional user-specific data, such as
+ * Implementations must store user-specific state or metadata in /data/vendor_de/<user>/fpdata
+ * as specified by the SeLinux policy. This directory is created/removed by vold (see
+ * vold_prepare_subdirs.cpp). Implementations may store additional user-specific data, such as
* embeddings or templates in StrongBox.
*
* @param sensorId The sensor with which this session is being created.
@@ -73,65 +65,31 @@
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:
*
- * Begins a secure transaction request. Note that the challenge by itself
- * is not useful. It only becomes useful when wrapped in a verifiable
- * message such as a HardwareAuthToken.
+ * Begins a secure transaction request. Note that the challenge by itself is not useful. It only
+ * becomes useful when wrapped in a verifiable message such as a HardwareAuthToken.
*
* Canonical example:
* 1) User requests an operation, such as fingerprint enrollment.
- * 2) Fingerprint enrollment cannot happen until the user confirms
- * their lockscreen credential (PIN/Pattern/Password).
- * 3) However, the biometric subsystem does not want just "any"
- * proof of credential confirmation. It needs proof that the
- * user explicitly authenticated credential in order to allow
- * addition of biometric enrollments.
+ * 2) Fingerprint enrollment cannot happen until the user confirms their lockscreen credential
+ * (PIN/Pattern/Password).
+ * 3) However, the biometric subsystem does not want just "any" proof of credential
+ * confirmation. It needs proof that the user explicitly authenticated credential in order
+ * to allow addition of biometric enrollments.
* To secure this path, the following path is taken:
* 1) Upon user requesting fingerprint enroll, the framework requests
* IFingerprint#generateChallenge
- * 2) Framework sends the challenge to the credential subsystem, and upon
- * credential confirmation, a HAT is created, containing the challenge
- * in the "challenge" field.
+ * 2) Framework sends the challenge to the credential subsystem, and upon credential
+ * confirmation, a HAT is created, containing the challenge in the "challenge" field.
* 3) Framework sends the HAT to the HAL, e.g. ISession#enroll.
* 4) Implementation verifies the authenticity and integrity of the HAT.
- * 5) Implementation now has confidence that the user entered their
- * credential to allow biometric enrollment.
+ * 5) Implementation now has confidence that the user entered their credential to allow
+ * biometric enrollment.
*
- * Note that the interface allows multiple in-flight challenges. For
- * example, invoking generateChallenge(0, 0, timeoutSec, cb) twice
- * does not invalidate the first challenge. The challenge is invalidated
- * only when:
+ * Note that the interface allows multiple in-flight challenges. For example, invoking
+ * generateChallenge(0, 0, timeoutSec, cb) twice does not invalidate the first challenge. The
+ * challenge is invalidated only when:
* 1) The provided timeout expires, or
* 2) IFingerprint#revokeChallenge is invoked
*
@@ -155,9 +113,9 @@
/**
* revokeChallenge:
*
- * Revokes a challenge that was previously generated. Note that if an
- * invalid combination of parameters is requested, the implementation
- * must still notify the framework using the provided callback.
+ * Revokes a challenge that was previously generated. Note that if an invalid combination of
+ * parameters is requested, the implementation must still notify the framework using the
+ * provided callback.
*
* @param sensorId Sensor that the revocation should apply to.
* @param userId User that the revocation should apply to.
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 4b31a38..0000000
--- 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 e2d23a6..644e214 100644
--- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl
+++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl
@@ -19,125 +19,355 @@
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);
/**
* getAuthenticatorId:
*
- * MUST return 0 via ISessionCallback#onAuthenticatorIdRetrieved for
- * sensors that are configured as SensorStrength::WEAK or
- * SensorStrength::CONVENIENCE.
+ * MUST return 0 via ISessionCallback#onAuthenticatorIdRetrieved for sensors that are configured
+ * as SensorStrength::WEAK or SensorStrength::CONVENIENCE.
*
- * The following only applies to sensors that are configured as
- * SensorStrength::STRONG.
+ * 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
- * allow for keys to be invalidated when the user adds a new enrollment
- * after the key was created:
+ * 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
* KeyProtection.Builder.setInvalidatedByBiometricEnrollment.
*
- * In addition, upon successful fingerprint authentication, the signed HAT
- * that is returned to the framework via ISessionCallback#onAuthenticated
- * must contain this identifier in the authenticatorId field.
+ * In addition, upon successful fingerprint authentication, the signed HAT that is returned to
+ * the framework via ISessionCallback#onAuthenticated must contain this identifier in the
+ * authenticatorId field.
*
- * Returns an entropy-encoded random identifier associated with the current
- * set of enrollments via ISessionCallback#onAuthenticatorIdRetrieved. The
- * authenticatorId
+ * Returns an entropy-encoded random identifier associated with the current set of enrollments
+ * via ISessionCallback#onAuthenticatorIdRetrieved. The authenticatorId
* 1) MUST change whenever a new fingerprint is enrolled
* 2) MUST return 0 if no fingerprints are enrolled
* 3) MUST not change if a fingerprint is deleted.
* 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
- * unique per ISession.
+ * @param cookie An identifier used to track subsystem operations related to this call path. The
+ * client must guarantee that it is unique per ISession.
*/
void getAuthenticatorId(in int cookie);
/**
* invalidateAuthenticatorId:
*
- * This method only applies to sensors that are configured as
- * SensorStrength::STRONG. If invoked erroneously by the framework for
- * sensor of other strengths, the HAL should immediately invoke
+ * This method only applies to sensors that are configured as SensorStrength::STRONG. If invoked
+ * by the framework for sensor of other strengths, the HAL should immediately invoke
* ISessionCallback#onAuthenticatorIdInvalidated.
*
- * The following only applies to sensors that are configured as
- * SensorStrength::STRONG.
+ * The following only applies to sensors that are configured as SensorStrength::STRONG.
*
- * When invoked by the framework, the implementation must perform the
- * following sequence of events:
- * 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).
+ * When invoked by the framework, the implementation must perform the following sequence of
+ * events:
+ * 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). 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
* ISessionCallback#onAuthenticatorInvalidated
*
- * A practical use case of invalidation would be when the user adds a new
- * enrollment to a sensor managed by a different HAL instance. The
- * public android.security.keystore APIs bind keys to "all biometrics"
- * rather than "fingerprint-only" or "face-only" (see #getAuthenticatorId
- * for more details). As such, the framework would coordinate invalidation
- * across multiple biometric HALs as necessary.
+ * A practical use case of invalidation would be when the user adds a new enrollment to a sensor
+ * managed by a different HAL instance. The public android.security.keystore APIs bind keys to
+ * "all biometrics" rather than "fingerprint-only" or "face-only" (see #getAuthenticatorId
+ * for more details). As such, the framework would coordinate invalidation 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
- * unique per ISession.
- * @param hat HardwareAuthToken that must be validated before proceeding
- * with this operation.
+ * @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 HardwareAuthToken that must be validated before proceeding with this operation.
*/
void invalidateAuthenticatorId(in int cookie, in HardwareAuthToken hat);
/**
* 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 |
+ * ------------------------------------------------------------------
*
- * @param cookie An identifier used to track subsystem operations related
- * to this call path. The framework will guarantee that it is
- * unique per ISession.
+ * 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
+ * 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 c608d65..74792d8 100644
--- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl
+++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl
@@ -23,29 +23,168 @@
@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. The vendorCode must be used to
+ * index into the configuration
+ * com.android.internal.R.array.fingerprint_acquired_vendor that's installed
+ * on the vendor partition.
+ */
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. The vendorCode must be used to index
+ * into the configuration
+ * com.android.internal.R.fingerprint_error_vendor that's installed on the
+ * vendor partition.
+ */
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/SensorProps.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/SensorProps.aidl
index fc3b44d..ab70a58 100644
--- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/SensorProps.aidl
+++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/SensorProps.aidl
@@ -27,8 +27,7 @@
CommonProps commonProps;
/**
- * A statically configured sensor type representing this fingerprint
- * sensor.
+ * A statically configured sensor type representing this fingerprint sensor.
*/
FingerprintSensorType sensorType;
@@ -39,32 +38,29 @@
boolean supportsNavigationGestures;
/**
- * The location of the center of the sensor if applicable. For example,
- * sensors of FingerprintSensorType::UNDER_DISPLAY_* would report this
- * value as the distance in pixels, measured from the left edge of the
- * screen.
+ * The location of the center of the sensor if applicable. For example, sensors of
+ * FingerprintSensorType::UNDER_DISPLAY_* would report this value as the distance in pixels,
+ * measured from the left edge of the screen.
*/
int sensorLocationX;
/**
- * The location of the center of the sensor if applicable. For example,
- * sensors of FingerprintSensorType::UNDER_DISPLAY_* would report this
- * value as the distance in pixels, measured from the top edge of the
- * screen.
+ * The location of the center of the sensor if applicable. For example, sensors of
+ * FingerprintSensorType::UNDER_DISPLAY_* would report this value as the distance in pixels,
+ * measured from the top edge of the screen.
*/
int sensorLocationY;
/**
* The radius of the sensor if applicable. For example, sensors of
- * FingerprintSensorType::UNDER_DISPLAY_* would report this value as
- * the radius of the sensor, in pixels.
+ * FingerprintSensorType::UNDER_DISPLAY_* would report this value as the radius of the sensor,
+ * in pixels.
*/
int sensorRadius;
/**
- * For sensors of FingerprintSensorType::UNDER_DISPLAY_*, this must
- * correspond to the android.hardware.DisplayManager#getDisplay Android
- * API.
+ * For sensors of FingerprintSensorType::UNDER_DISPLAY_*, this must correspond to the
+ * android.hardware.DisplayManager#getDisplay Android API.
*/
int displayId;
}
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/default/Fingerprint.cpp b/biometrics/fingerprint/aidl/default/Fingerprint.cpp
index b3bd4e7..b907bf1 100644
--- a/biometrics/fingerprint/aidl/default/Fingerprint.cpp
+++ b/biometrics/fingerprint/aidl/default/Fingerprint.cpp
@@ -61,11 +61,6 @@
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*/) {
diff --git a/biometrics/fingerprint/aidl/default/Fingerprint.h b/biometrics/fingerprint/aidl/default/Fingerprint.h
index 463d07d..59cdd44 100644
--- a/biometrics/fingerprint/aidl/default/Fingerprint.h
+++ b/biometrics/fingerprint/aidl/default/Fingerprint.h
@@ -28,9 +28,6 @@
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;
diff --git a/biometrics/fingerprint/aidl/vts/VtsHalBiometricsFingerprintTargetTest.cpp b/biometrics/fingerprint/aidl/vts/VtsHalBiometricsFingerprintTargetTest.cpp
index 9590d68..496badc 100644
--- a/biometrics/fingerprint/aidl/vts/VtsHalBiometricsFingerprintTargetTest.cpp
+++ b/biometrics/fingerprint/aidl/vts/VtsHalBiometricsFingerprintTargetTest.cpp
@@ -60,16 +60,32 @@
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(
diff --git a/health/2.1/vts/functional/VtsHalHealthV2_1TargetTest.cpp b/health/2.1/vts/functional/VtsHalHealthV2_1TargetTest.cpp
index 43e6cdc..d0b0d60 100644
--- a/health/2.1/vts/functional/VtsHalHealthV2_1TargetTest.cpp
+++ b/health/2.1/vts/functional/VtsHalHealthV2_1TargetTest.cpp
@@ -233,7 +233,7 @@
ASSERT_EQ(Result::SUCCESS, result);
EXPECT_TRUE(IsEnum(value.batteryCapacityLevel)) << " BatteryCapacityLevel";
- EXPECT_GE(value.batteryChargeTimeToFullNowSeconds, 0);
+ EXPECT_GE(value.batteryChargeTimeToFullNowSeconds, -1);
EXPECT_GE(value.batteryFullChargeDesignCapacityUah, 0)
<< "batteryFullChargeDesignCapacityUah should not be negative";