Merge changes Ie78e42b9,Ibf2baa14 (90412944) · Commits · e / os / android_hardware_interfaces

biometrics/common/aidl/android/hardware/biometrics/common/CommonProps.aidl

+7 −10

Original line number	Diff line number	Diff line
		@@ -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

biometrics/common/aidl/android/hardware/biometrics/common/SensorStrength.aidl

+7 −8

Original line number	Diff line number	Diff line
		@@ -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).

biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/Error.aidl

+5 −5

Original line number	Diff line number	Diff line
		@@ -34,28 +34,28 @@ enum Error {
		* The implementation is unable to process the request. For example, invalid arguments were
		* supplied.
		*/
		UNABLE_TO_PROCESS,
		UNABLE_TO_PROCESS = 2,

		/**
		* The current operation took too long to complete.
		*/
		TIMEOUT,
		TIMEOUT = 3,

		/**
		* No space available to store additional enrollments.
		*/
		NO_SPACE,
		NO_SPACE = 4,

		/**
		* The operation was canceled. See common::ICancellationSignal.
		*/
		CANCELED,
		CANCELED = 5,

		/**
		* The implementation was unable to remove an enrollment.
		* See ISession#removeEnrollments.
		*/
		UNABLE_TO_REMOVE,
		UNABLE_TO_REMOVE = 6,

		/**
		* Reserved to maintain backwards compatibility. See ISessionCallback#onLockoutTimed instead.

biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/IFingerprint.aidl

+36 −47

Original line number	Diff line number	Diff line
		@@ -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/<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.
		@@ -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.

biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl

+68 −88

Original line number	Diff line number	Diff line
		@@ -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.
		*
		* 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.
		* 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.
		*
		* 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.
		* 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);
		@@ -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.
		*
		* @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.
		* 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.
		*/
		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.