1/*
2 * Copyright (C) 2018 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.hardware.biometrics.face@1.0;
18
19import IBiometricsFaceClientCallback;
20
21/**
22 * The HAL interface for biometric face authentication.
23 */
24interface IBiometricsFace {
25
26    /**
27     * Sets the current client callback.
28     *
29     * Registers a user function that must receive notifications from the HAL.
30     * There is usually only one client (FaceService). This call must block
31     * if the HAL state machine is in busy state until the HAL leaves the
32     * busy state.
33     *
34     * All callback methods pass a deviceId to differentiate callback
35     * invocations in the case where multiple sensors exist.
36     *
37     * @param clientCallback The client defined callback to register.
38     * @return result, with its "value" parameter representing a "deviceId",
39     *     which must be unique for a given sensor.
40     */
41    @callflow(next={"setActiveUser"})
42    @entry
43    setCallback(IBiometricsFaceClientCallback clientCallback)
44        generates (OptionalUint64 result);
45
46    /**
47     * Sets the active user, which all subsequent HAL operations are applied to.
48     *
49     * HAL service implementors must ensure that operations are restricted to
50     * the given user. Clients must not call any part of this interface, except
51     * for setCallback(), without first having set an active user. The
52     * implementation is responsible for cancelling the current operation and
53     * returning to the idle state. Calling this method with the same userId
54     * should have no effect on the state machine.
55     *
56     * Note that onLockoutChanged() MUST be invoked by the implementation in
57     * response to a user change in order to update the framework with the
58     * timeout of the new user (or 0 if the user is not locked out).
59     *
60     * @param userId A non-negative user identifier that must be unique and
61     *     persistent for a given user.
62     * @param storePath absolute filesystem path to the template storage
63     *     directory. This must be the /data/vendor_de/<user>/facedata
64     *     directory specified by the SeLinux policy.
65     */
66    @callflow(next={"authenticate", "generateChallenge", "enumerate", "remove"})
67    setActiveUser(int32_t userId, string storePath) generates (Status status);
68
69    /**
70     * Begins a secure transaction request, e.g. enroll() or resetLockout().
71     *
72     * Generates a unique and cryptographically secure random token used to
73     * indicate the start of a secure transaction. generateChallenge() and
74     * revokeChallenge() specify a window where the resulting HAT that is
75     * generated in response to checking the user's PIN/pattern/password
76     * can be used to verify/perform a secure transaction.
77     *
78     * generateChallenge() generates a challenge which must then be wrapped by
79     * gatekeeper after verifying a successful strong authentication attempt,
80     * which generates a Hardware Authentication Token. The challenge prevents
81     * spoofing and replay attacks and ensures that only a transaction backed
82     * by a user authentication (PIN/pattern/password) can proceed.
83     *
84     * The implementation should be tolerant of revokeChallenge() being invoked
85     * after timeout has expired.
86     *
87     * @param challengeTimeoutSec A timeout in seconds, after which the driver
88     *     must invalidate the challenge. This is to prevent bugs or crashes in
89     *     the system from leaving a challenge enabled indefinitely.
90     * @return result, with its "value" parameter representing a "challenge": a
91     *     unique and cryptographically secure random token.
92     */
93    @callflow(next={"enroll", "revokeChallenge", "setFeature"})
94    generateChallenge(uint32_t challengeTimeoutSec)
95        generates (OptionalUint64 result);
96
97    /**
98     * Enrolls a user's face.
99     *
100     * Note that the Hardware Authentication Token must be valid for the
101     * duration of enrollment and thus should be explicitly invalidated by a
102     * call to revokeChallenge() when enrollment is complete, to reduce the
103     * window of opportunity to re-use the challenge and HAT. For example,
104     * Settings calls generateChallenge() once to allow the user to enroll one
105     * or more faces or toggle secure settings without having to re-enter the
106     * PIN/pattern/password. Once the user completes the operation, Settings
107     * invokes revokeChallenge() to close the transaction. If the HAT is expired,
108     * the implementation must invoke onError with UNABLE_TO_PROCESS.
109     *
110     * This method triggers the IBiometricsFaceClientCallback#onEnrollResult()
111     * method.
112     *
113     * @param hat A valid Hardware Authentication Token, generated as a result
114     *     of a generateChallenge() challenge being wrapped by the gatekeeper
115     *     after a successful strong authentication request.
116     * @param timeoutSec A timeout in seconds, after which this enroll
117     *     attempt is cancelled. Note that the framework can continue
118     *     enrollment by calling this again with a valid HAT. This timeout is
119     *     expected to be used to limit power usage if the device becomes idle
120     *     during enrollment. The implementation is expected to send
121     *     ERROR_TIMEOUT if this happens.
122     * @param disabledFeatures A list of features to be disabled during
123     *     enrollment. Note that all features are enabled by default.
124     * @return status The status of this method call.
125     */
126    @callflow(next={"cancel", "enroll", "revokeChallenge", "remove"})
127    enroll(vec<uint8_t> hat, uint32_t timeoutSec, vec<Feature> disabledFeatures)
128        generates (Status status);
129
130    /**
131     * Finishes the secure transaction by invalidating the challenge generated
132     * by generateChallenge().
133     *
134     * Clients must call this method once the secure transaction (e.g. enroll
135     * or setFeature) is completed. See generateChallenge().
136     *
137     * @return status The status of this method call.
138     */
139    @callflow(next={"authenticate", "setActiveUser", "enumerate", "remove"})
140    revokeChallenge() generates (Status status);
141
142    /**
143     * Changes the state of previous enrollment setting. Because this may
144     * decrease security, the user must enter their password before this method
145     * is invoked (see @param HAT). The driver must verify the HAT before
146     * changing any feature state. This method must return ILLEGAL_ARGUMENT if
147     * the HAT or faceId is invalid. This must only be invoked after
148     * setActiveUser() is called.
149     *
150     * Note: In some cases it may not be possible to change the state of this
151     * flag without re-enrolling. For example, if the user didn't provide
152     * attention during the original enrollment. This flag reflects the same
153     * persistent state as the one passed to enroll().
154     *
155     * Note: This call may block for a short amount of time (few hundred
156     * milliseconds). Clients are expected to invoke this asynchronously if it
157     * takes much longer than the above limit. Also note that the result is
158     * returned solely through Status (and not onError).
159     *
160     * @param feature The feature to be enabled or disabled.
161     * @param enabled True to enable the feature, false to disable.
162     * @param hat A valid Hardware Authentication Token, generated as a result
163     *     of getChallenge().
164     * @param faceId the ID of the enrollment returned by onEnrollResult() for
165     *     the feature to update.
166     * @return status The status of this method call.
167     */
168    setFeature(Feature feature, bool enabled, vec<uint8_t> hat, uint32_t faceId)
169        generates(Status status);
170
171    /**
172     * Retrieves the current state of the feature. If the faceId is invalid,
173     * the implementation must return ILLEGAL_ARGUMENT.
174     *
175     * @param faceId the ID of the enrollment returned by enroll().
176     * @return result with the value set to true if the feature is enabled,
177     *     false if disabled.
178     */
179    getFeature(Feature feature, uint32_t faceId) generates (OptionalBool result);
180
181    /**
182     * Returns an identifier associated with the current face set.
183     *
184     * The authenticator ID must change whenever a new face is enrolled. The
185     * authenticator ID must not be changed when a face is deleted. The
186     * authenticator ID must be an entropy-encoded random number which all
187     * current templates are tied to. The authenticator ID must be immutable
188     * outside of an active enrollment window to prevent replay attacks.
189     *
190     * @return result, with its value parameter representing an
191     *     "authenticatorId": an identifier associated to the user's current
192     *     face enrollment.
193     */
194    @callflow(next={"authenticate"})
195    getAuthenticatorId() generates (OptionalUint64 result);
196
197    /**
198     * Cancels the current enroll, authenticate, remove, or enumerate operation.
199     *
200     * @return status The status of this method call.
201     */
202    @callflow(next={"authenticate", "enroll", "enumerate", "remove",
203        "setActiveUser"})
204    cancel() generates (Status status);
205
206    /**
207     * Enumerates all face templates associated with the active user.
208     *
209     * The onEnumerate() callback method is invoked once for each face template
210     * found.
211     *
212     * @return status The status of this method call.
213     */
214    @callflow(next={"remove", "enroll", "authenticate", "setActiveUser"})
215    enumerate() generates (Status status);
216
217    /**
218     * Removes a face template or all face templates associated with the active
219     * user.
220     *
221     * This method triggers the IBiometricsFaceClientCallback#onRemoved() method.
222     *
223     * @param faceId The id correpsonding to the face to be removed; or 0 if all
224     *    faces are to be removed.
225     * @return status The status of this method call.
226     */
227    @callflow(next={"enumerate", "authenticate", "cancel", "getAuthenticatorId",
228        "setActiveUser"})
229    remove(uint32_t faceId) generates (Status status);
230
231    /**
232     * Authenticates the active user.
233     *
234     * An optional operationId can be specified as a token from the transaction
235     * being authorized. The hardware may enter a standby state during
236     * authentication, where the device is idle to conserve power while
237     * authenticating, e.g. after 3 seconds without finding a face. See
238     * IBiometricsFace#userActivity() for more info.
239     *
240     * @param operationId A non-zero operation id associated with a crypto
241     * object instance; or 0 if not being used.
242     * @return status The status of this method call.
243     */
244    @callflow(next={"cancel", "generateChallenge", "remove"})
245    authenticate(uint64_t operationId) generates (Status status);
246
247    /**
248     * A hint to the HAL to continue looking for faces.
249     *
250     * This method should only be used when the HAL is in the authenticating
251     * or standby state. Using this method when the HAL is not in one of the
252     * mentioned states must return OPERATION_NOT_SUPPORTED. Calling this
253     * method while the HAL is already authenticating may extend the duration
254     * where it's looking for a face.
255     *
256     * @return status The status of this method call.
257     */
258    userActivity() generates (Status status);
259
260    /**
261     * Reset lockout for the current user.
262     *
263     * Note: This call may block for a short amount of time (few hundred
264     * milliseconds). Clients are expected to invoke this asynchronously if it
265     * takes much longer than the above limit.
266     *
267     * @param hat A valid Hardware Authentication Token, generated when the
268     *     user authenticates with PIN/pattern/pass. When the Hardware
269     *     Authentication Token is verified, lockout must be reset and
270     *     onLockoutChanged must be called with duration 0.
271     * @return status The status of this method call.
272     */
273    resetLockout(vec<uint8_t> hat) generates (Status status);
274};
275