biometrics/face/1.0/IBiometricsFace.hal - android_hardware_interfaces - Gitiles

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

 // TODO(b/78538290): Update comments with state machine transitions when ready.
 // TODO(b/78537981): Update comments with callback interaction contract.
 // TODO(b/79496983): Update comments with status returns fully enumerated.
 /**
  * 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.
      *
      * @param userId A non-negative user identifier that must be unique and
      *     persistent for a given user.
      * @param storePath filesystem path to the template storage directory.
      */
     @callflow(next={"authenticate", "generateChallenge", "enumerate", "remove"})
     setActiveUser(int32_t userId, string storePath) generates (Status status);

     /**
      * Begins a secure transaction request, e.g. enrollment.
      *
      * Generates a unique and cryptographically secure random token used to
      * indicate the start of a secure transaction. generateChallenge() and
      * revokeChallenge() specify a pin/pattern/password cleared time window where
      * the secure transaction is allowed.
      *
      * generateChallenge() generates a challenge which must then be wrapped by the
      * gatekeeper after verifying a successful strong authentication attempt,
      * which generates a Hardware Authentication Token. The challenge prevents
      * spoofing and replay attacks and ensures that we only update a user’s face
      * template if the operation was preceded by some kind of strong credential
      * confirmation (e.g. device password).
      *
      * @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", "setFeatureDisabled"})
     generateChallenge(uint32_t challengeTimeoutSec)
         generates (OptionalUint64 result);

     /**
      * Enrolls a user's face.
      *
      * Note that this interface permits implementations where multiple faces can
      * be enrolled for a single user. However, allowing multiple faces to be
      * enrolled can be a severe security vulnerability and hence, most
      * implementations must ensure that only a single face be enrolled at a
      * given time. Multi-enrollment must only be used where there is a clear
      * necessity for a shared use case, e.g. TVs or cars.
      *
      * Note that the Hardware Authentication Token must still be valid after
      * this call, and must be explicitly invalidated by a call to
      * revokeChallenge(). This allows clients to immediately reattempt
      * enrollment (for example, if a user wasn’t satisfied with their enrollment)
      * without having to go through another strong authentication flow.
      *
      * 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 sucessful strong authentication request.
      * @param timeoutSec A timeout in seconds, after which this enrollment
      *     attempt is cancelled. Note that the client still needs to
      *     call revokeChallenge() to terminate the enrollment session.
      * @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 enrollment is complete, and the user's
      * face template no longer needs to be updated.
      *
      * @return status The status of this method call.
      */
     @callflow(next={"authenticate", "setActiveUser", "enumerate", "remove"})
     revokeChallenge() generates (Status status);

     /**
      * Requires all subsequent enroll/authenticate calls to use the feature.
      * This method does not affect enroll, which has its own feature list.
      *
      * 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.
      * 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().
      *
      * @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().
      * @return status The status of this method call.
      */
     setFeature(Feature feature, bool enabled, vec<uint8_t> hat)
         generates(Status status);

     /**
      * Retrieves the current state of the feature.
      *
      * @return enabled True if the feature is enabled, false if disabled.
      */
     getFeature(Feature feature) generates (bool enabled);

     /**
      * 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 a pending enrollment or authentication request.
      *
      * @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.
      *
      * @param hat A valid Hardware Authentication Token, generated when the
      *     user authenticates with Pin/Pattern/Pass.
      * @return true if lockout was reset, false otherwise.
      */
     resetLockout(vec<uint8_t> hat) generates (bool success);
 };
	/*
	* 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;

	// TODO(b/78538290): Update comments with state machine transitions when ready.
	// TODO(b/78537981): Update comments with callback interaction contract.
	// TODO(b/79496983): Update comments with status returns fully enumerated.
	/**
	* 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.
	*
	* @param userId A non-negative user identifier that must be unique and
	* persistent for a given user.
	* @param storePath filesystem path to the template storage directory.
	*/
	@callflow(next={"authenticate", "generateChallenge", "enumerate", "remove"})
	setActiveUser(int32_t userId, string storePath) generates (Status status);

	/**
	* Begins a secure transaction request, e.g. enrollment.
	*
	* Generates a unique and cryptographically secure random token used to
	* indicate the start of a secure transaction. generateChallenge() and
	* revokeChallenge() specify a pin/pattern/password cleared time window where
	* the secure transaction is allowed.
	*
	* generateChallenge() generates a challenge which must then be wrapped by the
	* gatekeeper after verifying a successful strong authentication attempt,
	* which generates a Hardware Authentication Token. The challenge prevents
	* spoofing and replay attacks and ensures that we only update a user’s face
	* template if the operation was preceded by some kind of strong credential
	* confirmation (e.g. device password).
	*
	* @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", "setFeatureDisabled"})
	generateChallenge(uint32_t challengeTimeoutSec)
	generates (OptionalUint64 result);

	/**
	* Enrolls a user's face.
	*
	* Note that this interface permits implementations where multiple faces can
	* be enrolled for a single user. However, allowing multiple faces to be
	* enrolled can be a severe security vulnerability and hence, most
	* implementations must ensure that only a single face be enrolled at a
	* given time. Multi-enrollment must only be used where there is a clear
	* necessity for a shared use case, e.g. TVs or cars.
	*
	* Note that the Hardware Authentication Token must still be valid after
	* this call, and must be explicitly invalidated by a call to
	* revokeChallenge(). This allows clients to immediately reattempt
	* enrollment (for example, if a user wasn’t satisfied with their enrollment)
	* without having to go through another strong authentication flow.
	*
	* 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 sucessful strong authentication request.
	* @param timeoutSec A timeout in seconds, after which this enrollment
	* attempt is cancelled. Note that the client still needs to
	* call revokeChallenge() to terminate the enrollment session.
	* @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 enrollment is complete, and the user's
	* face template no longer needs to be updated.
	*
	* @return status The status of this method call.
	*/
	@callflow(next={"authenticate", "setActiveUser", "enumerate", "remove"})
	revokeChallenge() generates (Status status);

	/**
	* Requires all subsequent enroll/authenticate calls to use the feature.
	* This method does not affect enroll, which has its own feature list.
	*
	* 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.
	* 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().
	*
	* @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().
	* @return status The status of this method call.
	*/
	setFeature(Feature feature, bool enabled, vec<uint8_t> hat)
	generates(Status status);

	/**
	* Retrieves the current state of the feature.
	*
	* @return enabled True if the feature is enabled, false if disabled.
	*/
	getFeature(Feature feature) generates (bool enabled);

	/**
	* 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 a pending enrollment or authentication request.
	*
	* @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.
	*
	* @param hat A valid Hardware Authentication Token, generated when the
	* user authenticates with Pin/Pattern/Pass.
	* @return true if lockout was reset, false otherwise.
	*/
	resetLockout(vec<uint8_t> hat) generates (bool success);
	};