Fingerprint: HIDL: add legacy (2.1) interface definition. (7bceb230) · Commits · e / os / android_hardware_interfaces

Android.bp

+1 −0

Original line number	Diff line number	Diff line
		@@ -4,6 +4,7 @@ subdirs = [
		"audio/common/2.0",
		"audio/effect/2.0",
		"benchmarks/msgq/1.0",
		"biometrics/fingerprint/2.1",
		"graphics/allocator/2.0",
		"graphics/allocator/2.0/default",
		"graphics/mapper/2.0",

biometrics/fingerprint/2.1/Android.bp

0 → 100644

+54 −0

Original line number	Diff line number	Diff line
		// This file is autogenerated by hidl-gen. Do not edit manually.

		genrule {
		name: "android.hardware.biometrics.fingerprint@2.1_genc++",
		tool: "hidl-gen",
		cmd: "$tool -o $genDir -Lc++ -randroid.hardware:hardware/interfaces android.hardware.biometrics.fingerprint@2.1",
		srcs: [
		"types.hal",
		"IBiometricsFingerprint.hal",
		"IBiometricsFingerprintClientCallback.hal",
		],
		out: [
		"android/hardware/biometrics/fingerprint/2.1/types.cpp",
		"android/hardware/biometrics/fingerprint/2.1/BiometricsFingerprintAll.cpp",
		"android/hardware/biometrics/fingerprint/2.1/BiometricsFingerprintClientCallbackAll.cpp",
		],
		}

		genrule {
		name: "android.hardware.biometrics.fingerprint@2.1_genc++_headers",
		tool: "hidl-gen",
		cmd: "$tool -o $genDir -Lc++ -randroid.hardware:hardware/interfaces android.hardware.biometrics.fingerprint@2.1",
		srcs: [
		"types.hal",
		"IBiometricsFingerprint.hal",
		"IBiometricsFingerprintClientCallback.hal",
		],
		out: [
		"android/hardware/biometrics/fingerprint/2.1/types.h",
		"android/hardware/biometrics/fingerprint/2.1/IBiometricsFingerprint.h",
		"android/hardware/biometrics/fingerprint/2.1/IHwBiometricsFingerprint.h",
		"android/hardware/biometrics/fingerprint/2.1/BnBiometricsFingerprint.h",
		"android/hardware/biometrics/fingerprint/2.1/BpBiometricsFingerprint.h",
		"android/hardware/biometrics/fingerprint/2.1/BsBiometricsFingerprint.h",
		"android/hardware/biometrics/fingerprint/2.1/IBiometricsFingerprintClientCallback.h",
		"android/hardware/biometrics/fingerprint/2.1/IHwBiometricsFingerprintClientCallback.h",
		"android/hardware/biometrics/fingerprint/2.1/BnBiometricsFingerprintClientCallback.h",
		"android/hardware/biometrics/fingerprint/2.1/BpBiometricsFingerprintClientCallback.h",
		"android/hardware/biometrics/fingerprint/2.1/BsBiometricsFingerprintClientCallback.h",
		],
		}

		cc_library_shared {
		name: "android.hardware.biometrics.fingerprint@2.1",
		generated_sources: ["android.hardware.biometrics.fingerprint@2.1_genc++"],
		generated_headers: ["android.hardware.biometrics.fingerprint@2.1_genc++_headers"],
		export_generated_headers: ["android.hardware.biometrics.fingerprint@2.1_genc++_headers"],
		shared_libs: [
		"libhidl",
		"libhwbinder",
		"libutils",
		"libcutils",
		],
		}

biometrics/fingerprint/2.1/IBiometricsFingerprint.hal

0 → 100644

+157 −0

Original line number	Diff line number	Diff line
		/*
		* Copyright (C) 2016 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.fingerprint@2.1;

		interface IBiometricsFingerprint {
		/*
		* Fingerprint pre-enroll enroll request:
		* Generates a unique token to upper layers to indicate the start of
		* an enrollment transaction. pre-enroll and post-enroll specify
		* a pin/password cleared time window where enrollment is allowed.
		* Pre-enroll only generates a challenge, a full hardwareAuthToken is
		* generated by trustzone after verifying a pin/password/swipe. This is to
		* ensure adding a new fingerprint template was preceded by some kind of
		* credential confirmation (e.g. device password).
		*
		* @return 0 if function failed, a uint64_t of challenge otherwise.
		*/
		@callflow(next={"enroll", "postEnroll"})
		preEnroll() generates (uint64_t authChallenge);

		/*
		* Fingerprint enroll request:
		* Switches the HAL state machine to collect and store a new fingerprint
		* template. Switches back as soon as enroll is complete, signalled by
		* (fingerprintMsg.type == FINGERPRINT_TEMPLATE_ENROLLING &&
		* fingerprintMsg.data.enroll.samplesRemaining == 0)
		* or after timeoutSec seconds.
		* The fingerprint template must be assigned to the group gid.
		*
		* @param hat a valid Hardware Authentication Token (HAT), generated
		* as a result of a preEnroll() call.
		* @param gid a framework defined fingerprint set (group) id.
		* @param timeoutSec a timeout in seconds.
		*
		* @return isOk indicates if the request is accepted.
		* @return debugErrno is a value the framework logs in case isOk == false.
		*
		* A notify() function may be called with a more detailed error structure.
		*/
		@callflow(next={"cancel", "enroll", "postEnroll", "remove"})
		enroll(HwAuthToken hat, uint32_t gid, uint32_t timeoutSec)
		generates (bool isOk, int32_t debugErrno);

		/*
		* Finishes the enroll operation and invalidates the preEnroll() generated
		* challenge. This must be called at the end of a multi-finger enrollment
		* session to indicate that no more fingers may be added.
		*
		* @return isOk indicates if the request is accepted.
		* @return debugErrno is a value the framework logs in case isOk == false.
		*/
		@callflow(next={"authenticate", "setActiveGroup", "enumerate", "remove"})
		postEnroll() generates (bool isOk, int32_t debugErrno);

		/*
		* getAuthenticatorId:
		* Returns a token associated with the current fingerprint set. This value
		* must change whenever a new fingerprint is enrolled, thus creating a new
		* fingerprint set.
		*
		* @return getAuthenticatorIdRet current authenticator id, 0 if function
		* failed.
		*/
		@callflow(next={"authenticate"})
		getAuthenticatorId() generates (uint64_t AuthenticatorId);

		/*
		* Cancel pending enroll or authenticate, sending FINGERPRINT_ERROR_CANCELED
		* to all running clients. Switches the HAL state machine back to the idle
		* state. Unlike enrollDone() doesn't invalidate the preEnroll() challenge.
		*
		* @return isOk indicates if the request is accepted.
		* @return debugErrno is a value the framework logs in case isOk == false.
		*/
		@callflow(next={"authenticate", "enroll", "enumerate", "remove",
		"setActiveGroup"})
		cancel() generates (bool isOk, int32_t debugErrno);

		/*
		* Enumerate all the fingerprint templates found in the directory set by
		* setActiveGroup():
		* For each template found a notify() must be called with:
		* fingerprintMsg.type == FINGERPRINT_TEMPLATE_ENUMERATED
		* fingerprintMsg.data.enumerated.finger indicating a template id
		* fingerprintMsg.data.enumerated.remainingTemplates indicating how many more
		* enumeration messages to expect.
		*
		* @return isOk indicates if the request is accepted.
		* @return debugErrno is a value the framework logs in case isOk == false.
		*/
		@callflow(next={"remove", "enroll", "authenticate", "setActiveGroup"})
		enumerate() generates (bool isOk, int32_t debugErrno);

		/*
		* Fingerprint remove request:
		* Deletes fingerprint template(s).
		* Works only within the path set by setActiveGroup().
		* For each template found a notify() must be called with:
		* fingerprintMsg.type == FINGERPRINT_TEMPLATE_REMOVED
		* fingerprintMsg.data.removed.finger indicating the template id deleted
		* fingerprintMsg.data.removed.remainingTemplates indicating how many more
		* templates must be deleted by this operation.
		*
		* @param gid group id must match the last group set by setActiveGroup().
		* @param fid template id to delete or 0 to delete all templates within the
		* current group.
		*
		* @return isOk indicates if the request is accepted.
		* @return debugErrno is a value the framework logs in case isOk == false.
		*/
		@callflow(next={"enumerate", "authenticate", "cancel", "getAuthenticatorId",
		"setActiveGroup"})
		remove(uint32_t gid, uint32_t fid) generates (bool isOk, int32_t debugErrno);

		/*
		* Restricts the HAL operation to a set of fingerprints belonging to a group
		* provided. The caller must provide a path to a storage location within the
		* user's data directory.
		*
		* @param gid the fingerprint group (set) id.
		* @param storePath filesystem path to the template storage directory.
		*
		* @return isOk indicates if the request is accepted.
		* @return debugErrno is a value the framework logs in case isOk == false.
		*/
		@callflow(next={"authenticate", "preEnroll", "enumerate", "remove"})
		@entry
		setActiveGroup(uint32_t gid, string storePath)
		generates (bool isOk, int32_t debugErrno);

		/*
		* Authenticates an operation identifed by operationId
		*
		* @param operationId operation id.
		* @param gid fingerprint group id.
		*
		* @return isOk indicates if the request is accepted.
		* @return debugErrno is a value the framework logs in case isOk == false.
		*/
		@callflow(next={"cancel", "preEnroll", "remove"})
		authenticate(uint64_t operationId, uint32_t gid)
		generates (bool isOk, int32_t debugErrno);
		};

biometrics/fingerprint/2.1/IBiometricsFingerprintClientCallback.hal

0 → 100644

+27 −0

Original line number	Diff line number	Diff line
		/*
		* Copyright (C) 2016 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.fingerprint@2.1;

		interface IBiometricsFingerprintClientCallback {
		/* This function is the response chanel for all messages
		* coming from the fingerprint HAL to the framework
		*
		* @param msg a union of message structures identified by
		* FingerprintMsg.type
		*/
		oneway notify(FingerprintMsg msg);
		};

biometrics/fingerprint/2.1/types.hal

0 → 100644

+148 −0

Original line number	Diff line number	Diff line
		/*
		* Copyright (C) 2016 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.fingerprint@2.1;

		/*
		* Fingerprint errors are meant to tell the framework to terminate the current
		* operation and ask for the user to correct the situation. These will almost
		* always result in messaging and user interaction to correct the problem.
		*
		* For example, ERROR_CANCELED should follow any acquisition message that
		* results in a situation where the current operation can't continue without
		* user interaction. For example, if the sensor is dirty during enrollment and
		* no further enrollment progress can be made, send ACQUIRED_IMAGER_DIRTY
		* followed by ERROR_CANCELED.
		*/
		enum FingerprintError : int32_t {
		/* The hardware has an error that can't be resolved. */
		ERROR_HW_UNAVAILABLE = 1,
		/* Bad data; operation can't continue */
		ERROR_UNABLE_TO_PROCESS = 2,
		/* The operation has timed out waiting for user input. */
		ERROR_TIMEOUT = 3,
		/* No space available to store a template */
		ERROR_NO_SPACE = 4,
		/* The current operation has been canceled */
		ERROR_CANCELED = 5,
		/* Unable to remove a template */
		ERROR_UNABLE_TO_REMOVE = 6,
		};

		/*
		* Fingerprint acquisition info is meant as feedback for the current operation.
		* Anything but ACQUIRED_GOOD must be shown to the user as feedback on how to
		* take action on the current operation. For example, ACQUIRED_IMAGER_DIRTY may
		* be used to tell the user to clean the sensor if it is detected to be dirty.
		* If this causes the current operation to fail, an additional ERROR_CANCELED
		* must be sent to stop the operation in progress (e.g. enrollment).
		* In general, these messages will result in a "Try again" message.
		*/
		enum FingerprintAcquiredInfo : int32_t {
		ACQUIRED_GOOD = 0,
		/* sensor needs more data, i.e. longer swipe. */
		ACQUIRED_PARTIAL = 1,
		/* image doesn't contain enough detail for recognition*/
		ACQUIRED_INSUFFICIENT = 2,
		/* sensor needs to be cleaned */
		ACQUIRED_IMAGER_DIRTY = 3,
		/* mostly swipe-type sensors; not enough data collected */
		ACQUIRED_TOO_SLOW = 4,
		/* vendor-specific acquisition messages start here */
		ACQUIRED_TOO_FAST = 5,
		ACQUIRED_VENDOR_BASE = 1000,
		};

		/* TODO import from keymaster HIDL when available */
		enum HwAuthenticatorType : uint32_t {
		HW_AUTH_NONE = 0,
		HW_AUTH_PASSWORD = 1,
		HW_AUTH_FINGERPRINT = 2,
		HW_AUTH_ANY = 0xffffffff,
		};

		/* TODO import from keymaster HIDL when available */
		struct HwAuthToken {
		uint8_t version;
		uint64_t challenge;
		uint64_t userId;
		uint64_t authenticatorId;
		uint32_t authenticatorType;
		uint64_t timestamp;
		uint8_t[32] hmac;
		};

		struct FingerprintFingerId {
		/* Group ID */
		uint32_t gid;
		/* Fingerprint template ID */
		uint32_t fid;
		};

		struct FingerprintEnroll {
		/* Template ID */
		FingerprintFingerId finger;
		/* samplesRemaining goes from N (no data collected, but N scans needed)
		* to 0 (no more data is needed to build a template). */
		uint32_t samplesRemaining;
		/* Vendor specific message. Used for user guidance */
		uint64_t msg;
		};

		struct FingerprintIterator {
		/* Template ID */
		FingerprintFingerId finger;
		/* How many templates remain to iterate through */
		uint32_t remainingTemplates;
		};

		typedef FingerprintIterator FingerprintEnumerated;
		typedef FingerprintIterator FingerprintRemoved;

		struct FingerprintAcquired {
		/* information about the image */
		FingerprintAcquiredInfo acquiredInfo;
		};

		struct FingerprintAuthenticated {
		/* Matched template ID */
		FingerprintFingerId finger;
		/* Authentication result from the keymaster */
		HwAuthToken hat;
		};

		/* Run time type identification for the notify() call payload. */
		enum FingerprintMsgType : int32_t {
		ERROR = -1,
		ACQUIRED = 1,
		TEMPLATE_ENROLLING = 3,
		TEMPLATE_REMOVED = 4,
		AUTHENTICATED = 5,
		TEMPLATE_ENUMERATING = 6,
		};

		struct FingerprintMsg {
		/* Selects the payload below */
		FingerprintMsgType type;
		union data {
		FingerprintError error;
		FingerprintEnroll enroll;
		FingerprintEnumerated enumerated;
		FingerprintRemoved removed;
		FingerprintAcquired acquired;
		FingerprintAuthenticated authenticated;
		};
		};