diff --git a/biometrics/common/aidl/android/hardware/biometrics/common/CommonProps.aidl b/biometrics/common/aidl/android/hardware/biometrics/common/CommonProps.aidl index 8304c953cc..9c3fd58090 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 @@ import android.hardware.biometrics.common.SensorStrength; @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 7460279728..790691cbfc 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 @@ package android.hardware.biometrics.common; @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/android/hardware/biometrics/fingerprint/IFingerprint.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/IFingerprint.aidl index 0c8ebc534b..4b907b46b5 100644 --- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/IFingerprint.aidl +++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/IFingerprint.aidl @@ -27,41 +27,34 @@ interface IFingerprint { /** * 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//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//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. @@ -74,33 +67,29 @@ interface IFingerprint { /** * 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 * @@ -124,9 +113,9 @@ interface IFingerprint { /** * 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/ISession.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl index d0f546a41f..644e214c42 100644 --- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl +++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl @@ -51,41 +51,35 @@ interface ISession { * * 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. + * 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. + * 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. + * 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. + * 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. + * 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 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); @@ -212,79 +206,66 @@ interface ISession { /** * 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 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: + * 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 client must 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. If this - * check fails, the HAL must invoke ISessionCallback#onError with - * Error::UNABLE_TO_PROCESS and return to + * 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. - * 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 client must 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); @@ -329,9 +310,8 @@ interface ISession { * 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 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); @@ -352,12 +332,12 @@ interface ISession { * 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 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. + * 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. diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/SensorProps.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/SensorProps.aidl index fc3b44d608..ab70a5801c 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 @@ parcelable SensorProps { 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 @@ parcelable SensorProps { 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; }