biometrics/face/1.0/IBiometricsFace.hal - platform/hardware/interfaces - Git at Google

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