Add authenticatorId changes to Fingerprint aidl
Also adds a top-level README for the biometric package
Bug: 159667191
Bug: 168541000
Test: make -j56 android.hardware.biometrics.fingerprint-update-api
Test: make -j56 VtsHalBiometricsFingerprintTargetTest
Change-Id: I3dba8e7ee16700865662c1a00b75576d2513f930
diff --git a/biometrics/README.md b/biometrics/README.md
new file mode 100644
index 0000000..8ae1ad6
--- /dev/null
+++ b/biometrics/README.md
@@ -0,0 +1,12 @@
+## Biometric HALs ##
+---
+
+## Overview: ##
+
+The interfaces within the biometrics.* HAL tree are used by the Android Biometric Services
+(e.g. FingerprintService, FaceService) to discover and operate biometric sensors on the device.
+
+More details and versioning information can be found within each particular HAL.
+
+More complete information about the Android Biometric HALs and subsystem can be found at
+[source.android.com](https://source.android.com/security/biometric).
\ No newline at end of file
diff --git a/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/IFingerprint.aidl b/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/IFingerprint.aidl
index a376acf..85d1f57 100644
--- a/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/IFingerprint.aidl
+++ b/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/IFingerprint.aidl
@@ -21,6 +21,6 @@
android.hardware.biometrics.fingerprint.SensorProps[] getSensorProps();
android.hardware.biometrics.fingerprint.ISession createSession(in int sensorId, in int userId, in android.hardware.biometrics.fingerprint.ISessionCallback cb);
void setResetLockoutCallback(in android.hardware.biometrics.fingerprint.IResetLockoutCallback cb);
- void generateChallenge(in int sensorId, in int userId, in long keystoreOperationId, in int timeoutSec, in android.hardware.biometrics.fingerprint.IGenerateChallengeCallback cb);
+ void generateChallenge(in int sensorId, in int userId, in int timeoutSec, in android.hardware.biometrics.fingerprint.IGenerateChallengeCallback cb);
void revokeChallenge(in int sensorId, in int userId, in android.hardware.biometrics.fingerprint.IRevokeChallengeCallback cb);
}
diff --git a/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ISession.aidl b/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ISession.aidl
index 4b71527..d92ca4f 100644
--- a/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ISession.aidl
+++ b/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ISession.aidl
@@ -24,6 +24,7 @@
void enumerateEnrollments(in int cookie);
void removeEnrollments(in int cookie, in int[] enrollmentIds);
void getAuthenticatorId(in int cookie);
+ void invalidateAuthenticatorId(in int cookie, in android.hardware.keymaster.HardwareAuthToken hat);
void resetLockout(in int cookie, in android.hardware.keymaster.HardwareAuthToken hat);
void onPointerDown(in int pointerId, in int x, in int y, in float minor, in float major);
void onPointerUp(in int pointerId);
diff --git a/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ISessionCallback.aidl b/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ISessionCallback.aidl
index f50554b..6140447 100644
--- a/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ISessionCallback.aidl
+++ b/biometrics/fingerprint/aidl/aidl_api/android.hardware.biometrics.fingerprint/current/android/hardware/biometrics/fingerprint/ISessionCallback.aidl
@@ -26,4 +26,6 @@
void onInteractionDetected();
void onEnrollmentsEnumerated(in int[] enrollmentIds);
void onEnrollmentsRemoved(in int[] enrollmentIds);
+ void onAuthenticatorIdRetrieved(in long authenticatorId);
+ void onAuthenticatorIdInvalidated();
}
diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/IFingerprint.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/IFingerprint.aidl
index 9aafeab..4709778 100644
--- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/IFingerprint.aidl
+++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/IFingerprint.aidl
@@ -31,7 +31,7 @@
void setResetLockoutCallback(in IResetLockoutCallback cb);
- void generateChallenge(in int sensorId, in int userId, in long keystoreOperationId, in int timeoutSec, in IGenerateChallengeCallback cb);
+ void generateChallenge(in int sensorId, in int userId, in int timeoutSec, in IGenerateChallengeCallback cb);
void revokeChallenge(in int sensorId, in int userId, in IRevokeChallengeCallback cb);
}
diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl
index 78da7ae..55ea385 100644
--- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl
+++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl
@@ -35,8 +35,76 @@
void removeEnrollments(in int cookie, in int[] enrollmentIds);
+ /**
+ * getAuthenticatorId:
+ *
+ * MUST return 0 via ISessionCallback#onAuthenticatorIdRetrieved for
+ * sensors that are configured as SensorStrength::WEAK or
+ * SensorStrength::CONVENIENCE.
+ *
+ * The following only applies to sensors that are configured as
+ * SensorStrength::STRONG.
+ *
+ * The authenticatorId is used during key generation and key import to to
+ * associate a key (in KeyStore / KeyMaster) with the current set of
+ * enrolled fingerprints. For example, the following public Android APIs
+ * allow for keys to be invalidated when the user adds a new enrollment
+ * after the key was created:
+ * KeyGenParameterSpec.Builder.setInvalidatedByBiometricEnrollment and
+ * KeyProtection.Builder.setInvalidatedByBiometricEnrollment.
+ *
+ * In addition, upon successful fingerprint authentication, the signed HAT
+ * that is returned to the framework via ISessionCallback#onAuthenticated
+ * must contain this identifier in the authenticatorId field.
+ *
+ * Returns an entropy-encoded random identifier associated with the current
+ * set of enrollments via ISessionCallback#onAuthenticatorIdRetrieved. The
+ * authenticatorId
+ * 1) MUST change whenever a new fingerprint is enrolled
+ * 2) MUST return 0 if no fingerprints are enrolled
+ * 3) MUST not change if a fingerprint is deleted.
+ * 4) MUST be an entropy-encoded random number
+ *
+ * @param cookie An identifier used to track subsystem operations related
+ * to this call path. The framework will guarantee that it is
+ * unique per ISession.
+ */
void getAuthenticatorId(in int cookie);
+ /**
+ * invalidateAuthenticatorId:
+ *
+ * This method only applies to sensors that are configured as
+ * SensorStrength::STRONG. If invoked erroneously by the framework for
+ * sensor of other strengths, the HAL should immediately invoke
+ * ISessionCallback#onAuthenticatorIdInvalidated.
+ *
+ * The following only applies to sensors that are configured as
+ * SensorStrength::STRONG.
+ *
+ * When invoked by the framework, the HAL implementation must perform the
+ * following sequence of events:
+ * 1) Verify the authenticity and integrity of the provided HAT
+ * 2) Update the authenticatorId with a new entropy-encoded random number
+ * 3) Persist the new authenticatorId to non-ephemeral storage
+ * 4) Notify the framework that the above is completed, via
+ * ISessionCallback#onAuthenticatorInvalidated
+ *
+ * A practical use case of invalidation would be when the user adds a new
+ * enrollment to a sensor managed by a different HAL instance. The
+ * public android.security.keystore APIs bind keys to "all biometrics"
+ * rather than "fingerprint-only" or "face-only" (see #getAuthenticatorId
+ * for more details). As such, the framework would coordinate invalidation
+ * across multiple biometric HALs as necessary.
+ *
+ * @param cookie An identifier used to track subsystem operations related
+ * to this call path. The framework will guarantee that it is
+ * unique per ISession.
+ * @param hat HardwareAuthToken that must be validated before proceeding
+ * with this operation.
+ */
+ void invalidateAuthenticatorId(in int cookie, in HardwareAuthToken hat);
+
void resetLockout(in int cookie, in HardwareAuthToken hat);
diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl
index 655f030..c608d65 100644
--- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl
+++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl
@@ -38,4 +38,14 @@
void onEnrollmentsEnumerated(in int[] enrollmentIds);
void onEnrollmentsRemoved(in int[] enrollmentIds);
+
+ /**
+ * A callback invoked when ISession#getAuthenticatorId is invoked.
+ */
+ void onAuthenticatorIdRetrieved(in long authenticatorId);
+
+ /**
+ * A callback invoked when ISession#invalidateAuthenticatorId has completed.
+ */
+ void onAuthenticatorIdInvalidated();
}
diff --git a/biometrics/fingerprint/aidl/default/Fingerprint.cpp b/biometrics/fingerprint/aidl/default/Fingerprint.cpp
index 6eb6237..b5d3949 100644
--- a/biometrics/fingerprint/aidl/default/Fingerprint.cpp
+++ b/biometrics/fingerprint/aidl/default/Fingerprint.cpp
@@ -48,8 +48,8 @@
}
ndk::ScopedAStatus Fingerprint::generateChallenge(
- int32_t /*sensorId*/, int32_t /*userId*/, int64_t /*keystoreOperationId*/,
- int32_t /*timeoutSec*/, const std::shared_ptr<IGenerateChallengeCallback>& /*cb*/) {
+ int32_t /*sensorId*/, int32_t /*userId*/, int32_t /*timeoutSec*/,
+ const std::shared_ptr<IGenerateChallengeCallback>& /*cb*/) {
return ndk::ScopedAStatus::ok();
}
diff --git a/biometrics/fingerprint/aidl/default/Fingerprint.h b/biometrics/fingerprint/aidl/default/Fingerprint.h
index 9f04893..b5b09c0 100644
--- a/biometrics/fingerprint/aidl/default/Fingerprint.h
+++ b/biometrics/fingerprint/aidl/default/Fingerprint.h
@@ -32,7 +32,7 @@
const std::shared_ptr<IResetLockoutCallback>& cb) override;
ndk::ScopedAStatus generateChallenge(
- int32_t sensorId, int32_t userId, int64_t keystoreOperationId, int32_t timeoutSec,
+ int32_t sensorId, int32_t userId, int32_t timeoutSec,
const std::shared_ptr<IGenerateChallengeCallback>& cb) override;
ndk::ScopedAStatus revokeChallenge(
diff --git a/biometrics/fingerprint/aidl/default/Session.cpp b/biometrics/fingerprint/aidl/default/Session.cpp
index 5eb3134..a3dd75e 100644
--- a/biometrics/fingerprint/aidl/default/Session.cpp
+++ b/biometrics/fingerprint/aidl/default/Session.cpp
@@ -59,6 +59,11 @@
return ndk::ScopedAStatus::ok();
}
+ndk::ScopedAStatus Session::invalidateAuthenticatorId(int32_t /*cookie*/,
+ const keymaster::HardwareAuthToken& /*hat*/) {
+ return ndk::ScopedAStatus::ok();
+}
+
ndk::ScopedAStatus Session::resetLockout(int32_t /*cookie*/,
const keymaster::HardwareAuthToken& /*hat*/) {
return ndk::ScopedAStatus::ok();
diff --git a/biometrics/fingerprint/aidl/default/Session.h b/biometrics/fingerprint/aidl/default/Session.h
index 69950fb..781e95a 100644
--- a/biometrics/fingerprint/aidl/default/Session.h
+++ b/biometrics/fingerprint/aidl/default/Session.h
@@ -43,6 +43,9 @@
ndk::ScopedAStatus getAuthenticatorId(int32_t cookie) override;
+ ndk::ScopedAStatus invalidateAuthenticatorId(int32_t cookie,
+ const keymaster::HardwareAuthToken& hat) override;
+
ndk::ScopedAStatus resetLockout(int32_t cookie,
const keymaster::HardwareAuthToken& hat) override;
diff --git a/biometrics/fingerprint/aidl/vts/VtsHalBiometricsFingerprintTargetTest.cpp b/biometrics/fingerprint/aidl/vts/VtsHalBiometricsFingerprintTargetTest.cpp
index 88980bf..1a39ad4 100644
--- a/biometrics/fingerprint/aidl/vts/VtsHalBiometricsFingerprintTargetTest.cpp
+++ b/biometrics/fingerprint/aidl/vts/VtsHalBiometricsFingerprintTargetTest.cpp
@@ -82,6 +82,14 @@
return ndk::ScopedAStatus::ok();
}
+ ndk::ScopedAStatus onAuthenticatorIdRetrieved(int64_t /*authenticatorId*/) override {
+ return ndk::ScopedAStatus::ok();
+ }
+
+ ndk::ScopedAStatus onAuthenticatorIdInvalidated() override {
+ return ndk::ScopedAStatus::ok();
+ }
+
private:
std::promise<SessionCallbackInvocation> invocation_promise_;
};