Remove SessionState from IFingerprint

package android.hardware.biometrics.fingerprint;

@VintfStability

interface ISession {

  void generateChallenge(in int cookie);

  void revokeChallenge(in int cookie, in long challenge);

  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 operationId);

  android.hardware.biometrics.common.ICancellationSignal detectInteraction(in int cookie);

  void enumerateEnrollments(in int cookie);

  void removeEnrollments(in int cookie, in int[] enrollmentIds);

  void getAuthenticatorId(in int cookie);

  void invalidateAuthenticatorId(in int cookie);

  void resetLockout(in int cookie, in android.hardware.keymaster.HardwareAuthToken hat);

  void close(in int cookie);

  void generateChallenge();

  void revokeChallenge(in long challenge);

  android.hardware.biometrics.common.ICancellationSignal enroll(in android.hardware.keymaster.HardwareAuthToken hat);

  android.hardware.biometrics.common.ICancellationSignal authenticate(in long operationId);

  android.hardware.biometrics.common.ICancellationSignal detectInteraction();

  void enumerateEnrollments();

  void removeEnrollments(in int[] enrollmentIds);

  void getAuthenticatorId();

  void invalidateAuthenticatorId();

  void resetLockout(in android.hardware.keymaster.HardwareAuthToken hat);

  void close();

  void onPointerDown(in int pointerId, in int x, in int y, in float minor, in float major);

  void onPointerUp(in int pointerId);

  void onUiReady();

package android.hardware.biometrics.fingerprint;

@VintfStability

interface ISessionCallback {

  void onStateChanged(in int cookie, in android.hardware.biometrics.fingerprint.SessionState state);

  void onChallengeGenerated(in long challenge);

  void onChallengeRevoked(in long challenge);

  void onAcquired(in android.hardware.biometrics.fingerprint.AcquiredInfo info, in int vendorCode);

/*

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

 */

///////////////////////////////////////////////////////////////////////////////

// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE.                          //

///////////////////////////////////////////////////////////////////////////////

// This file is a snapshot of an AIDL file. Do not edit it manually. There are

// two cases:

// 1). this is a frozen version file - do not edit this in any case.

// 2). this is a 'current' file. If you make a backwards compatible change to

//     the interface (from the latest frozen version), the build system will

//     prompt you to update this file with `m <name>-update-api`.

//

// You must not make a backward incompatible change to any AIDL file 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;

@Backing(type="byte") @VintfStability

enum SessionState {

  IDLING = 0,

  CLOSED = 1,

  GENERATING_CHALLENGE = 2,

  REVOKING_CHALLENGE = 3,

  ENROLLING = 4,

  AUTHENTICATING = 5,

  DETECTING_INTERACTION = 6,

  ENUMERATING_ENROLLMENTS = 7,

  REMOVING_ENROLLMENTS = 8,

  GETTING_AUTHENTICATOR_ID = 9,

  INVALIDATING_AUTHENTICATOR_ID = 10,

  RESETTING_LOCKOUT = 11,

}

    /**

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

     *

     * Calling this method while there is an active session is considered an error. If the

     * framework is in a bad state and for some reason cannot close its session, it should use

     * the reset method below.

     *

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

     * Creates a instance of ISession which can be used by the framework to perform operations

     * such as ISession#enroll, ISession#authenticate, etc. for the given sensorId and userId.

     *

     * Calling this method while there is an active session is considered an error. If the framework

     * wants to create a new session when it already has an active session, it must first cancel the

     * current operation if it's cancellable, or wait until it completes. Then, the framework must

     * explicitly close the session with ISession#close. Once the framework receives

     * ISessionCallback#onSessionClosed, a new session can be created.

     *

     * 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

/**

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

 *   1) Non-interrupting operations. These operations are handled by the HAL in FIFO order.

 *   1a) Cancellable operations. These are usually the operations that can execute for several

 *       minutes. To allow for cancellation, they return an instance of ICancellationSignal that

 *       lets the framework cancel them by calling ICancellationSignal#cancel. If such an operation

 *       is cancelled, it must notify the framework by calling ISessionCallback#onError with

 *       Error::CANCELED.

 *   1b) Non-cancellable operations. Such operations cannot be cancelled once started.

 *   2) Interrupting operations. These operations may be invoked by the framework immediately,

 *      regardless of whether another operation is executing. For example, on devices with sensors

 *      of FingerprintSensorType::UNDER_DISPLAY_*, ISession#onFingerDown may be invoked while the

 *      HAL is executing ISession#enroll, ISession#authenticate or ISession#detectInteraction.

 *

 * The lifecycle of a non-interrupting operation ends when one of its terminal callbacks is called.

 * For example, ISession#authenticate is considered completed when either of the following callbacks

 * is called: ISessionCallback#onError or ISessionCallback#onAuthenticationSucceeded.

 *

 * The lifecycle of an interrupting operation ends when it returns. Interrupting operations do not

 * have callbacks.

 *

 * ISession only supports execution of one non-interrupting operation at a time, regardless of

 * whether it's cancellable. The framework must wait for a corresponding callback indicating the end of

 * the current non-interrupting operation before a new non-interrupting operation can be started.

 */

@VintfStability

interface ISession {

     * | 0        | 10     | <Time4>    | <Random4> |

     * ----------------------------------------------

     *

     * @param cookie A unique number identifying this operation

     */

    void generateChallenge(in int cookie);

    void generateChallenge();

    /**

     * revokeChallenge:

     * parameters is requested, the implementation must still notify the framework using the

     * provided callback.

     *

     * @param cookie A unique number identifying this operation

     * @param challenge Challenge that should be revoked.

     */

    void revokeChallenge(in int cookie, in long challenge);

    void revokeChallenge(in long challenge);

    /**

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

     * framework via ISessionCallback#onError with the applicable enrollment-specific error.

     *

     * 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

     * 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 enroll(in HardwareAuthToken hat);

    /**

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

     * the framework via ISessionCallback#onError with the applicable authentication-specific error.

     *

     * During authentication, the implementation may notify the framework via

     * ISessionCallback#onAcquired with messages that may be used to guide the user. This callback

     * 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

     *                    setUserAuthenticationParameters in KeyGenParameterSpec.Builder and

     *                    KeyProtection.Builder.

     */

    ICancellationSignal authenticate(in int cookie, in long operationId);

    ICancellationSignal authenticate(in long operationId);

    /**

     * detectInteraction:

     * if SensorProps#supportsDetectInteraction is true. If invoked on implementations that do not

     * support this functionality, the HAL must respond with ISession#onError(UNABLE_TO_PROCESS, 0).

     *

     * 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 framework via ISessionCallback#onError with the applicable error.

     *

     * 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

     * 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);

    ICancellationSignal detectInteraction();

    /*

     * 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);

    void enumerateEnrollments();

    /**

     * 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);

    void removeEnrollments(in int[] enrollmentIds);

    /**

     * getAuthenticatorId:

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

     */

    void getAuthenticatorId(in int cookie);

    void getAuthenticatorId();

    /**

     * invalidateAuthenticatorId:

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

     */

    void invalidateAuthenticatorId(in int cookie);

    void invalidateAuthenticatorId();

    /**

     * resetLockout:

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

     * Error::UNABLE_TO_PROCESS and return to the idling state.

     *

     * Upon successful verification, the HAL must clear the lockout counter and notify the framework

     * via ISessionCallback#onLockoutCleared.

     * 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);

    void resetLockout(in HardwareAuthToken hat);

    /*

     * Close this session and allow the HAL to release the resources associated with this session.

     *

     * A session can only be closed when it's in SessionState::IDLING. Closing a session will

     * result in a ISessionCallback#onStateChanged call with SessionState::CLOSED.

     * A session can only be closed when the HAL is idling, i.e. not performing any of the

     * non-interruptable operations. If the HAL is busy performing a cancellable operation, the

     * operation must be explicitly cancelled with a call to ICancellationSignal#cancel before

     * the session can be closed.

     *

     * If a session is unresponsive or stuck in a state other than SessionState::CLOSED,

     * IFingerprint#reset could be used as a last resort to terminate the session and recover the

     * HAL from a bad state.

     * After a session is closed, the HAL must notify the framework by calling

     * ISessionCallback#onSessionClosed.

     *

     * All sessions must be explicitly closed. Calling IFingerprint#createSession while there is an

     * active session is considered an error.

     *

     * @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 close(in int cookie);

    void close();

    /**

     * Methods for notifying the under-display fingerprint sensor about external events.

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

     * HAL of display touches. This method can be invoked when the HAL is performing any one of:

     * ISession#authenticate, ISession#enroll, ISession#detectInteraction.

     *

     * Note that the framework will only invoke this method if the event occurred on the display on

     * which this sensor is located.