/*
 * Copyright (C) 2018 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.hardware.biometrics.face@1.0;

import IBiometricsFaceClientCallback;

/**
 * The HAL interface for biometric face authentication.
 */
interface IBiometricsFace {

    /**
     * Sets the current client callback.
     *
     * Registers a user function that must receive notifications from the HAL.
     * There is usually only one client (FaceService). This call must block
     * if the HAL state machine is in busy state until the HAL leaves the
     * busy state.
     *
     * All callback methods pass a deviceId to differentiate callback
     * invocations in the case where multiple sensors exist.
     *
     * @param clientCallback The client defined callback to register.
     * @return result, with its "value" parameter representing a "deviceId",
     *     which must be unique for a given sensor.
     */
    @callflow(next={"setActiveUser"})
    @entry
    setCallback(IBiometricsFaceClientCallback clientCallback)
        generates (OptionalUint64 result);

    /**
     * Sets the active user, which all subsequent HAL operations are applied to.
     *
     * HAL service implementors must ensure that operations are restricted to
     * the given user. Clients must not call any part of this interface, except
     * for setCallback(), without first having set an active user. The
     * implementation is responsible for cancelling the current operation and
     * returning to the idle state. Calling this method with the same userId
     * should have no effect on the state machine.
     *
     * Note that onLockoutChanged() MUST be invoked by the implementation in
     * response to a user change in order to update the framework with the
     * timeout of the new user (or 0 if the user is not locked out).
     *
     * @param userId A non-negative user identifier that must be unique and
     *     persistent for a given user.
     * @param storePath absolute filesystem path to the template storage
     *     directory. This must be the /data/vendor_de/<user>/facedata
     *     directory specified by the SeLinux policy.
     */
    @callflow(next={"authenticate", "generateChallenge", "enumerate", "remove"})
    setActiveUser(int32_t userId, string storePath) generates (Status status);

    /**
     * Begins a secure transaction request, e.g. enroll() or resetLockout().
     *
     * Generates a unique and cryptographically secure random token used to
     * indicate the start of a secure transaction. generateChallenge() and
     * revokeChallenge() specify a window where the resulting HAT that is
     * generated in response to checking the user's PIN/pattern/password
     * can be used to verify/perform a secure transaction.
     *
     * generateChallenge() generates a challenge which must then be wrapped by
     * gatekeeper after verifying a successful strong authentication attempt,
     * which generates a Hardware Authentication Token. The challenge prevents
     * spoofing and replay attacks and ensures that only a transaction backed
     * by a user authentication (PIN/pattern/password) can proceed.
     *
     * The implementation should be tolerant of revokeChallenge() being invoked
     * after timeout has expired.
     *
     * @param challengeTimeoutSec A timeout in seconds, after which the driver
     *     must invalidate the challenge. This is to prevent bugs or crashes in
     *     the system from leaving a challenge enabled indefinitely.
     * @return result, with its "value" parameter representing a "challenge": a
     *     unique and cryptographically secure random token.
     */
    @callflow(next={"enroll", "revokeChallenge", "setFeature"})
    generateChallenge(uint32_t challengeTimeoutSec)
        generates (OptionalUint64 result);

    /**
     * Enrolls a user's face.
     *
     * Note that the Hardware Authentication Token must be valid for the
     * duration of enrollment and thus should be explicitly invalidated by a
     * call to revokeChallenge() when enrollment is complete, to reduce the
     * window of opportunity to re-use the challenge and HAT. For example,
     * Settings calls generateChallenge() once to allow the user to enroll one
     * or more faces or toggle secure settings without having to re-enter the
     * PIN/pattern/password. Once the user completes the operation, Settings
     * invokes revokeChallenge() to close the transaction. If the HAT is expired,
     * the implementation must invoke onError with UNABLE_TO_PROCESS.
     *
     * This method triggers the IBiometricsFaceClientCallback#onEnrollResult()
     * method.
     *
     * @param hat A valid Hardware Authentication Token, generated as a result
     *     of a generateChallenge() challenge being wrapped by the gatekeeper
     *     after a successful strong authentication request.
     * @param timeoutSec A timeout in seconds, after which this enroll
     *     attempt is cancelled. Note that the framework can continue
     *     enrollment by calling this again with a valid HAT. This timeout is
     *     expected to be used to limit power usage if the device becomes idle
     *     during enrollment. The implementation is expected to send
     *     ERROR_TIMEOUT if this happens.
     * @param disabledFeatures A list of features to be disabled during
     *     enrollment. Note that all features are enabled by default.
     * @return status The status of this method call.
     */
    @callflow(next={"cancel", "enroll", "revokeChallenge", "remove"})
    enroll(vec<uint8_t> hat, uint32_t timeoutSec, vec<Feature> disabledFeatures)
        generates (Status status);

    /**
     * Finishes the secure transaction by invalidating the challenge generated
     * by generateChallenge().
     *
     * Clients must call this method once the secure transaction (e.g. enroll
     * or setFeature) is completed. See generateChallenge().
     *
     * @return status The status of this method call.
     */
    @callflow(next={"authenticate", "setActiveUser", "enumerate", "remove"})
    revokeChallenge() generates (Status status);

    /**
     * Changes the state of previous enrollment setting. Because this may
     * decrease security, the user must enter their password before this method
     * is invoked (see @param HAT). The driver must verify the HAT before
     * changing any feature state. This method must return ILLEGAL_ARGUMENT if
     * the HAT or faceId is invalid. This must only be invoked after
     * setActiveUser() is called.
     *
     * Note: In some cases it may not be possible to change the state of this
     * flag without re-enrolling. For example, if the user didn't provide
     * attention during the original enrollment. This flag reflects the same
     * persistent state as the one passed to enroll().
     *
     * Note: This call may block for a short amount of time (few hundred
     * milliseconds). Clients are expected to invoke this asynchronously if it
     * takes much longer than the above limit. Also note that the result is
     * returned solely through Status (and not onError).
     *
     * @param feature The feature to be enabled or disabled.
     * @param enabled True to enable the feature, false to disable.
     * @param hat A valid Hardware Authentication Token, generated as a result
     *     of getChallenge().
     * @param faceId the ID of the enrollment returned by onEnrollResult() for
     *     the feature to update.
     * @return status The status of this method call.
     */
    setFeature(Feature feature, bool enabled, vec<uint8_t> hat, uint32_t faceId)
        generates(Status status);

    /**
     * Retrieves the current state of the feature. If the faceId is invalid,
     * the implementation must return ILLEGAL_ARGUMENT.
     *
     * @param faceId the ID of the enrollment returned by enroll().
     * @return result with the value set to true if the feature is enabled,
     *     false if disabled.
     */
    getFeature(Feature feature, uint32_t faceId) generates (OptionalBool result);

    /**
     * Returns an identifier associated with the current face set.
     *
     * The authenticator ID must change whenever a new face is enrolled. The
     * authenticator ID must not be changed when a face is deleted. The
     * authenticator ID must be an entropy-encoded random number which all
     * current templates are tied to. The authenticator ID must be immutable
     * outside of an active enrollment window to prevent replay attacks.
     *
     * @return result, with its value parameter representing an
     *     "authenticatorId": an identifier associated to the user's current
     *     face enrollment.
     */
    @callflow(next={"authenticate"})
    getAuthenticatorId() generates (OptionalUint64 result);

    /**
     * Cancels the current enroll, authenticate, remove, or enumerate operation.
     *
     * @return status The status of this method call.
     */
    @callflow(next={"authenticate", "enroll", "enumerate", "remove",
        "setActiveUser"})
    cancel() generates (Status status);

    /**
     * Enumerates all face templates associated with the active user.
     *
     * The onEnumerate() callback method is invoked once for each face template
     * found.
     *
     * @return status The status of this method call.
     */
    @callflow(next={"remove", "enroll", "authenticate", "setActiveUser"})
    enumerate() generates (Status status);

    /**
     * Removes a face template or all face templates associated with the active
     * user.
     *
     * This method triggers the IBiometricsFaceClientCallback#onRemoved() method.
     *
     * @param faceId The id correpsonding to the face to be removed; or 0 if all
     *    faces are to be removed.
     * @return status The status of this method call.
     */
    @callflow(next={"enumerate", "authenticate", "cancel", "getAuthenticatorId",
        "setActiveUser"})
    remove(uint32_t faceId) generates (Status status);

    /**
     * Authenticates the active user.
     *
     * An optional operationId can be specified as a token from the transaction
     * being authorized. The hardware may enter a standby state during
     * authentication, where the device is idle to conserve power while
     * authenticating, e.g. after 3 seconds without finding a face. See
     * IBiometricsFace#userActivity() for more info.
     *
     * @param operationId A non-zero operation id associated with a crypto
     * object instance; or 0 if not being used.
     * @return status The status of this method call.
     */
    @callflow(next={"cancel", "generateChallenge", "remove"})
    authenticate(uint64_t operationId) generates (Status status);

    /**
     * A hint to the HAL to continue looking for faces.
     *
     * This method should only be used when the HAL is in the authenticating
     * or standby state. Using this method when the HAL is not in one of the
     * mentioned states must return OPERATION_NOT_SUPPORTED. Calling this
     * method while the HAL is already authenticating may extend the duration
     * where it's looking for a face.
     *
     * @return status The status of this method call.
     */
    userActivity() generates (Status status);

    /**
     * Reset lockout for the current user.
     *
     * Note: This call may block for a short amount of time (few hundred
     * milliseconds). Clients are expected to invoke this asynchronously if it
     * takes much longer than the above limit.
     *
     * @param hat A valid Hardware Authentication Token, generated when the
     *     user authenticates with PIN/pattern/pass. When the Hardware
     *     Authentication Token is verified, lockout must be reset and
     *     onLockoutChanged must be called with duration 0.
     * @return status The status of this method call.
     */
    resetLockout(vec<uint8_t> hat) generates (Status status);
};