Add setter/getter for requireAttention
Also renames pre/postEnroll to get/revokeChallenge
Bug: 110597778
Test: builds
Change-Id: I5547504b27e0f6d304f016e02be91aa15e548e5f
diff --git a/biometrics/face/1.0/Android.bp b/biometrics/face/1.0/Android.bp
index 61bf247..45dbad9 100644
--- a/biometrics/face/1.0/Android.bp
+++ b/biometrics/face/1.0/Android.bp
@@ -17,6 +17,7 @@
types: [
"FaceAcquiredInfo",
"FaceError",
+ "OptionalBool",
"OptionalUint64",
"Status",
"UserHandle",
diff --git a/biometrics/face/1.0/IBiometricsFace.hal b/biometrics/face/1.0/IBiometricsFace.hal
index 3c3b0c2..f39eaeb 100644
--- a/biometrics/face/1.0/IBiometricsFace.hal
+++ b/biometrics/face/1.0/IBiometricsFace.hal
@@ -60,18 +60,18 @@
* persistent for a given user.
* @param storePath filesystem path to the template storage directory.
*/
- @callflow(next={"authenticate", "preEnroll", "enumerate", "remove"})
+ @callflow(next={"authenticate", "generateChallenge", "enumerate", "remove"})
setActiveUser(int32_t userId, string storePath) generates (Status status);
/**
- * Begins a pre-enrollment request.
+ * Begins a secure transaction request, e.g. enrollment.
*
* 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.
+ * indicate the start of a secure transaction. generateChallenge() and
+ * revokeChallenge() specify a pin/pattern/password cleared time window where
+ * the secure transaction is allowed.
*
- * preEnroll() generates a challenge which must then be wrapped by the
+ * 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
@@ -81,8 +81,8 @@
* @return result, with its "value" parameter representing a "challenge": a
* unique and cryptographically secure random token.
*/
- @callflow(next={"enroll", "postEnroll"})
- preEnroll() generates (OptionalUint64 result);
+ @callflow(next={"enroll", "revokeChallenge", "setRequireAttention"})
+ generateChallenge() generates (OptionalUint64 result);
/**
* Enrolls a user's face.
@@ -95,20 +95,20 @@
* 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 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 preEnroll() challenge being wrapped by the gatekeeper after a
- * sucessful strong authentication request.
+ * 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 postEnroll() to terminate the enrollment session.
+ * call revokeChallenge() to terminate the enrollment session.
* @param requireAttention When set to true, requires user attention (e.g.
* eyes open and looking at the device) for enrollment to complete, as
* well as subsequent authentication. This is expected to be enabled by
@@ -120,13 +120,13 @@
* to look at the device.
* @return status The status of this method call.
*/
- @callflow(next={"cancel", "enroll", "postEnroll", "remove"})
+ @callflow(next={"cancel", "enroll", "revokeChallenge", "remove"})
enroll(vec<uint8_t> hat, uint32_t timeoutSec, bool requireAttention)
generates (Status status);
/**
- * Finishes the enrollment session and invalidates the challenge generated
- * by preEnroll().
+ * 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.
@@ -134,7 +134,38 @@
* @return status The status of this method call.
*/
@callflow(next={"authenticate", "setActiveUser", "enumerate", "remove"})
- postEnroll() generates (Status status);
+ revokeChallenge() generates (Status status);
+
+ /**
+ * Requires that all subsequent authenticate calls to first have the
+ * user's attention. This method does not affect enroll, which has its
+ * own requireAttention parameter.
+ *
+ * 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 the requireAttention 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 requireAttention When set to true, requires user attention for
+ * authentication to succeed.
+ * @param hat A valid Hardware Authentication Token, generated as a result
+ * of getChallenge().
+ * @return status The status of this method call.
+ */
+ setRequireAttention(bool requireAttention, vec<uint8_t> hat)
+ generates(Status status);
+
+ /**
+ * Retrieves the current requireAttention state.
+ *
+ * @return result, with its value parameter representing the current
+ * requireAttention state.
+ */
+ getRequireAttention(vec<uint8_t> hat) generates (OptionalBool result);
/**
* Returns an identifier associated with the current face set.
@@ -196,6 +227,6 @@
* object instance; or 0 if not being used.
* @return status The status of this method call.
*/
- @callflow(next={"cancel", "preEnroll", "remove"})
+ @callflow(next={"cancel", "generateChallenge", "remove"})
authenticate(uint64_t operationId) generates (Status status);
};
diff --git a/biometrics/face/1.0/types.hal b/biometrics/face/1.0/types.hal
index 08af919..92cb70d 100644
--- a/biometrics/face/1.0/types.hal
+++ b/biometrics/face/1.0/types.hal
@@ -48,7 +48,13 @@
/**
* The HAL has encountered an internal error and cannot complete the request.
*/
- INTERNAL_ERROR = 3
+ INTERNAL_ERROR = 3,
+
+ /**
+ * The operation could not be completed because there are no enrolled
+ * templates.
+ */
+ NOT_ENROLLED = 4
};
/**
@@ -253,3 +259,19 @@
*/
uint64_t value;
};
+
+/**
+ * Result structure with an addition bool field. See documentation in
+ * getRequireAttention() for usage of the value.
+ */
+struct OptionalBool {
+ /**
+ * The return status.
+ */
+ Status status;
+
+ /**
+ * This value is only meaningful if status is OK.
+ */
+ bool value;
+};
\ No newline at end of file