Merge "Added initial HIDL interface for the biometric face HAL." (f470b928) · Commits · e / os / android_hardware_interfaces

biometrics/face/1.0/Android.bp

0 → 100644

+26 −0

Original line number	Diff line number	Diff line
		// This file is autogenerated by hidl-gen -Landroidbp.

		hidl_interface {
		name: "android.hardware.biometrics.face@1.0",
		root: "android.hardware",
		vndk: {
		enabled: true,
		},
		srcs: [
		"types.hal",
		"IBiometricsFace.hal",
		"IBiometricsFaceClientCallback.hal",
		],
		interfaces: [
		"android.hidl.base@1.0",
		],
		types: [
		"FaceAcquiredInfo",
		"FaceError",
		"OptionalUint64",
		"Status",
		"UserHandle",
		],
		gen_java: true,
		}

biometrics/face/1.0/IBiometricsFace.hal

0 → 100644

+191 −0

Original line number	Diff line number	Diff line
		/*
		* 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", "preEnroll", "enumerate", "remove"})
		setActiveUser(int32_t userId, string storePath) generates (Status status);

		/**
		* Begins a pre-enrollment request.
		*
		* Generates a unique and cryptographically secure random token used to
		* indicate the start of an enrollment transaction. preEnroll() and
		* postEnroll() specify a pin/pattern/password cleared time window where
		* enrollment is allowed.
		*
		* preEnroll() 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).
		*
		* @return result, with its "value" parameter representing a "challenge": a
		* unique and cryptographically secure random token.
		*/
		@callflow(next={"enroll", "postEnroll"})
		preEnroll() 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 postEnroll().
		* 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 preEnroll() 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 postEnroll() to terminate the enrollment session.
		* @return status The status of this method call.
		*/
		@callflow(next={"cancel", "enroll", "postEnroll", "remove"})
		enroll(vec<uint8_t> hat, uint32_t timeoutSec) generates (Status status);

		/**
		* Finishes the enrollment session and invalidates the challenge generated
		* by preEnroll().
		*
		* 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"})
		postEnroll() generates (Status status);

		/**
		* 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.
		*
		* @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", "preEnroll", "remove"})
		authenticate(uint64_t operationId) generates (Status status);
		};

biometrics/face/1.0/IBiometricsFaceClientCallback.hal

0 → 100644

+116 −0

Original line number	Diff line number	Diff line
		/*
		* 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;

		/**
		* This callback interface is used by clients to recieve updates from the face
		* HAL.
		*/
		interface IBiometricsFaceClientCallback {

		/**
		* A callback invoked when one enrollment step has been completed.
		*
		* @param deviceId A unique id associated with the HAL implementation
		* service that processed this enrollment step.
		* @param faceId The id of the face template being enrolled.
		* @param userId The active user id for the template being enrolled.
		* @param remaining The number of remaining steps before enrolllment is
		* complete or 0 if enrollment has completed successfully.
		*/
		oneway onEnrollResult(uint64_t deviceId, uint32_t faceId, int32_t userId,
		uint32_t remaining);

		/**
		* A callback invoked when a face has been successfully authenticated.
		*
		* @param deviceId A unique id associated with the HAL implementation
		* service that processed this autentication attempt.
		* @param faceId The id of the face template that passed the authentication
		* challenge.
		* @param userId The active user id for the authenticated face.
		* @param token The hardware authentication token associated with this
		* authenticate operation.
		*/
		oneway onAuthenticated(uint64_t deviceId, uint32_t faceId, int32_t userId,
		vec<uint8_t> token);

		/**
		* A callback invoked when a face is acquired.
		*
		* If a non-critical, recoverable error occurs during an enrollment or
		* authentication attempt, the HAL implementation must invoke this callback
		* to allow clients to inform the user that some actionable change must be
		* made.
		*
		* @param deviceId A unique id associated with the HAL implementation
		* service that acquired a face.
		* @param userId The id of the active user associated with the attempted
		* face acquisition.
		* @param acquiredInfo A message about the quality of the acquired image.
		* @param vendorCode An optional vendor-specific message. This is only valid
		* when acquiredInfo == FaceAcquiredInfo.VENDOR. This message is opaque
		* to the framework, and vendors must provide code to handle it. For
		* example this can be used to guide enrollment in Settings or provide
		* a message during authentication that is vendor-specific. The vendor
		* is expected to provide help strings to cover all known values.
		*/
		oneway onAcquired(uint64_t deviceId, int32_t userId,
		FaceAcquiredInfo acquiredInfo, int32_t vendorCode);

		/**
		* A callback invoked when an error has occured.
		*
		* @param deviceId A unique id associated with the HAL implementation
		* service where this error occured.
		* @param userId The id of the active user when the error occured, or
		* UserHandle::NONE if an active user had not been set yet.
		* @param error A message about the error that occurred.
		* @param vendorCode An optional, vendor-speicifc error message. Only valid
		* when error == FaceError.VENDOR. This message is opaque to the
		* framework, and vendors must provide code to handle it. For example,
		* this scan be used to show the user an error message specific to the
		* device. The vendor is expected to provide error strings to cover
		* all known values.
		*/
		oneway onError(uint64_t deviceId, int32_t userId, FaceError error,
		int32_t vendorCode);

		/**
		* A callback invoked when a face template has been removed.
		*
		* @param deviceId A unique id associated with the HAL implementation
		* service that processed this removal.
		* @param faceId The id of the face template that was removed.
		* @param userId The active user id for the removed face template.
		* @param remaining The number of face templates remaining after this
		* removal, or 0 if there are no more.
		*/
		oneway onRemoved(uint64_t deviceId, uint32_t faceId, int32_t userId,
		uint32_t remaining);

		/**
		* A callback invoked to enumerate all current face templates.
		*
		* @param deviceId A unique id associated with the HAL implementation
		* service that processed this enumeration.
		* @param faceIds A list of ids of all currently enrolled face templates.
		* @param userId The active user id for the enumerated face template.
		*/
		oneway onEnumerate(uint64_t deviceId, vec<uint32_t> faceIds,
		int32_t userId);
		};

biometrics/face/1.0/types.hal

0 → 100644

+255 −0

Original line number	Diff line number	Diff line
		/*
		* 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;

		/*
		* In the event setActiveUser is not called, all error messages will return
		* this userId.
		*/
		enum UserHandle : int32_t {
		NONE = -1
		};

		/**
		* Status codes returned directly by the HIDL method calls upon critical errors
		* where the callback cannot be invoked. Most errors should sent through the
		* onError callback using one of the FaceErrors below.
		*/
		enum Status : uint32_t {
		/**
		* The method was invoked successfully.
		*/
		OK = 0,

		/**
		* One of the arguments to the method call is invalid.
		*/
		ILLEGAL_ARGUMENT = 1,

		/**
		* This face HAL does not support this operation.
		*/
		OPERATION_NOT_SUPPORTED = 2,

		/**
		* The HAL has encountered an internal error and cannot complete the request.
		*/
		INTERNAL_ERROR = 3
		};

		/**
		* Face errors represent events that can't be immediately recovered by user
		* intervention. These are returned in the onError callback.
		*
		* Upon receiving a face error, clients must terminate the current operation and
		* notify the user where possible.
		*/
		enum FaceError : int32_t {

		/**
		* A hardware error has occured that cannot be resolved. Try again later.
		*/
		HW_UNAVAILABLE = 1,

		/**
		* The current enroll or authenticate operation could not be completed;
		* the sensor was unable to process the current image.
		*/
		UNABLE_TO_PROCESS = 2,

		/**
		* The current operation took too long to complete. This is intended to
		* prevent programs from blocking the face HAL indefinitely. The timeout is
		* framework and sensor-specific, but is generally on the order of 30
		* seconds.
		*/
		TIMEOUT = 3,

		/**
		* The current operation could not be completed because there is not enough
		* storage space remaining to do so.
		*/
		NO_SPACE = 4,

		/**
		* The current operation has been cancelled. This may happen if a new
		* request (authenticate, remove) is initiated while an on-going operation
		* is in progress, or if cancel() was called.
		*/
		CANCELED = 5,

		/**
		* The current remove operation could not be completed; the face template
		* provided could not be removed.
		*/
		UNABLE_TO_REMOVE = 6,

		/**
		* Face authentication is locked out due to too many unsuccessful attempts.
		*/
		LOCKOUT = 7,

		/**
		* Used to enable a vendor-specific error message.
		*/
		VENDOR = 8,
		};

		/**
		* Face acquisition information provides feedback for the current enrollment
		* or authentication operation.
		*
		* This information indicates that the user can take immediate action to resolve
		* an issue, and clients must ensure that this information is surfaced to the
		* user.
		*/
		enum FaceAcquiredInfo : int32_t {

		/**
		* The face acquired was good; no further user interaction is necessary.
		*/
		GOOD = 0,

		/**
		* The face data acquired was too noisy or did not have sufficient detail.
		* This is a catch-all for all acquisition errors not captured by the other
		* constants.
		*/
		INSUFFICIENT = 1,

		/**
		* Because there was too much ambient light, the captured face data was too
		* bright. It's reasonable to return this after multiple
		* FaceAcquiredInfo.INSUFFICIENT.
		*
		* The user is expected to take action to retry the operation in better
		* lighting conditions when this is returned.
		*/
		TOO_BRIGHT = 2,

		/**
		* Because there was not enough illumination, the captured face data was too
		* dark. It's reasonable to return this after multiple
		* FaceAcquiredInfo.INSUFFICIENT.
		*
		* The user is expected to take action to retry the operation in better
		* lighting conditions when this is returned.
		*/
		TOO_DARK = 3,

		/**
		* The detected face is too close to the sensor, and the image cannot be
		* processed.
		*
		* The user is expected to be informed to move further from the sensor when
		* this is returned.
		*/
		TOO_CLOSE = 4,

		/**
		* The detected face is too small, as the user might be too far away from
		* the sensor.
		*
		* The user is expected to be informed to move closer to the sensor when
		* this is returned.
		*/
		TOO_FAR = 5,

		/**
		* Only the upper part of the face was detected. The sensor's field of view
		* is too high.
		*
		* The user should be informed to move up with respect to the sensor when
		* this is returned.
		*/
		FACE_TOO_HIGH = 6,

		/**
		* Only the lower part of the face was detected. The sensor's field of view
		* is too low.
		*
		* The user should be informed to move down with respect to the sensor when
		* this is returned.
		*/
		FACE_TOO_LOW = 7,

		/**
		* Only the right part of the face was detected. The sensor's field of view
		* is too far right.
		*
		* The user should be informed to move to the right with respect to the
		* sensor when this is returned.
		*/
		FACE_TOO_RIGHT = 8,

		/**
		* Only the left part of the face was detected. The sensor's field of view
		* is too far left.
		*
		* The user should be informed to move to the left with respect to the
		* sensor when this is returned.
		*/
		FACE_TOO_LEFT = 9,

		/**
		* The user's face was directed away from the sensor. The user should be
		* informed to face the sensor when this is returned.
		*/
		POOR_GAZE = 10,

		/**
		* No face was detected within the sensor's field of view.
		*
		* The user should be informed to point the sensor to a face when this is
		* returned.
		*/
		NOT_DETECTED = 11,

		/**
		* Too much motion was detected.
		*
		* The user should be informed to keep their face steady relative to the
		* sensor.
		*/
		TOO_MUCH_MOTION = 12,

		/**
		* The sensor needs to be recalibrated.
		*/
		RECALIBRATE = 13,

		/**
		* Used to enable a vendor-specific acquisition message.
		*/
		VENDOR = 14
		};

		/**
		* Result structure with an additional uint64_t field. See documentation in
		* setCallback(), preEnroll(), and getAuthenticatorId() for usage of the value.
		*/
		struct OptionalUint64 {
		/**
		* The return status.
		*/
		Status status;

		/**
		* This value is only meaningful if status is OK.
		*/
		uint64_t value;
		};