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

Reformat biometric interface documentation to 100 cols

Browse Source 
Bug: 168843220
Test: Builds
Change-Id: Ibf2baa14f8c8bd47250dd964eab68307e3885b4c
This commit is contained in:
Kevin Chyn
2020-09-23 14:29:26 -07:00
parent ef79d661ba
commit 3388eebde5
5 changed files with 124 additions and 163 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
biometrics/common/aidl/android/hardware/biometrics/common/CommonProps.aidl
View File

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

15
biometrics/common/aidl/android/hardware/biometrics/common/SensorStrength.aidl
View File

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

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

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

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

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

26
biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/SensorProps.aidl
View File

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