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 package android.hardware.face;
17 
18 import android.hardware.biometrics.AuthenticationStateListener;
19 import android.hardware.biometrics.IBiometricSensorReceiver;
20 import android.hardware.biometrics.IBiometricServiceLockoutResetCallback;
21 import android.hardware.biometrics.IBiometricStateListener;
22 import android.hardware.biometrics.IInvalidationCallback;
23 import android.hardware.biometrics.ITestSession;
24 import android.hardware.biometrics.ITestSessionCallback;
25 import android.hardware.face.IFaceAuthenticatorsRegisteredCallback;
26 import android.hardware.face.IFaceServiceReceiver;
27 import android.hardware.face.Face;
28 import android.hardware.face.FaceAuthenticateOptions;
29 import android.hardware.face.FaceEnrollOptions;
30 import android.hardware.face.FaceSensorPropertiesInternal;
31 import android.hardware.face.FaceSensorConfigurations;
32 import android.view.Surface;
33 
34 /**
35  * Communication channel from client to the face service. These methods are all require the
36  * MANAGE_BIOMETRIC signature permission.
37  * @hide
38  */
39 interface IFaceService {
40 
41     // Creates a test session with the specified sensorId
42     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
createTestSession(int sensorId, ITestSessionCallback callback, String opPackageName)43     ITestSession createTestSession(int sensorId, ITestSessionCallback callback, String opPackageName);
44 
45     // Requests a proto dump of the specified sensor
46     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
dumpSensorServiceStateProto(int sensorId, boolean clearSchedulerBuffer)47     byte[] dumpSensorServiceStateProto(int sensorId, boolean clearSchedulerBuffer);
48 
49     // Retrieve static sensor properties for all face sensors
50     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
getSensorPropertiesInternal(String opPackageName)51     List<FaceSensorPropertiesInternal> getSensorPropertiesInternal(String opPackageName);
52 
53     // Retrieve static sensor properties for the specified sensor
54     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
getSensorProperties(int sensorId, String opPackageName)55     FaceSensorPropertiesInternal getSensorProperties(int sensorId, String opPackageName);
56 
57     // Authenticate with a face. A requestId is returned that can be used to cancel this operation.
58     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
authenticate(IBinder token, long operationId, IFaceServiceReceiver receiver, in FaceAuthenticateOptions options)59     long authenticate(IBinder token, long operationId, IFaceServiceReceiver receiver,
60             in FaceAuthenticateOptions options);
61 
62     // Uses the face hardware to detect for the presence of a face, without giving details
63     // about accept/reject/lockout. A requestId is returned that can be used to cancel this
64     // operation.
65     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
detectFace(IBinder token, IFaceServiceReceiver receiver, in FaceAuthenticateOptions options)66     long detectFace(IBinder token, IFaceServiceReceiver receiver, in FaceAuthenticateOptions options);
67 
68     // This method prepares the service to start authenticating, but doesn't start authentication.
69     // This is protected by the MANAGE_BIOMETRIC signatuer permission. This method should only be
70     // called from BiometricService. The additional uid, pid, userId arguments should be determined
71     // by BiometricService. To start authentication after the clients are ready, use
72     // startPreparedClient().
73     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
prepareForAuthentication(boolean requireConfirmation, IBinder token, long operationId, IBiometricSensorReceiver sensorReceiver, in FaceAuthenticateOptions options, long requestId, int cookie, boolean allowBackgroundAuthentication)74     void prepareForAuthentication(boolean requireConfirmation, IBinder token,
75             long operationId, IBiometricSensorReceiver sensorReceiver,
76             in FaceAuthenticateOptions options, long requestId, int cookie,
77             boolean allowBackgroundAuthentication);
78 
79     // Starts authentication with the previously prepared client.
80     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
startPreparedClient(int sensorId, int cookie)81     void startPreparedClient(int sensorId, int cookie);
82 
83     // Cancel authentication for the given requestId.
84     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
cancelAuthentication(IBinder token, String opPackageName, long requestId)85     void cancelAuthentication(IBinder token, String opPackageName, long requestId);
86 
87     // Cancel face detection for the given requestId.
88     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
cancelFaceDetect(IBinder token, String opPackageName, long requestId)89     void cancelFaceDetect(IBinder token, String opPackageName, long requestId);
90 
91     // Same as above, with extra arguments.
92     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
cancelAuthenticationFromService(int sensorId, IBinder token, String opPackageName, long requestId)93     void cancelAuthenticationFromService(int sensorId, IBinder token, String opPackageName, long requestId);
94 
95     // Start face enrollment
96     @EnforcePermission("MANAGE_BIOMETRIC")
enroll(int userId, IBinder token, in byte [] hardwareAuthToken, IFaceServiceReceiver receiver, String opPackageName, in int [] disabledFeatures, in Surface previewSurface, boolean debugConsent, in FaceEnrollOptions options)97     long enroll(int userId, IBinder token, in byte [] hardwareAuthToken, IFaceServiceReceiver receiver,
98             String opPackageName, in int [] disabledFeatures,
99             in Surface previewSurface, boolean debugConsent, in FaceEnrollOptions options);
100 
101     // Start remote face enrollment
102     @EnforcePermission("MANAGE_BIOMETRIC")
enrollRemotely(int userId, IBinder token, in byte [] hardwareAuthToken, IFaceServiceReceiver receiver, String opPackageName, in int [] disabledFeatures)103     long enrollRemotely(int userId, IBinder token, in byte [] hardwareAuthToken, IFaceServiceReceiver receiver,
104             String opPackageName, in int [] disabledFeatures);
105 
106     // Cancel enrollment in progress
107     @EnforcePermission("MANAGE_BIOMETRIC")
cancelEnrollment(IBinder token, long requestId)108     void cancelEnrollment(IBinder token, long requestId);
109 
110     // Removes the specified face enrollment for the specified userId.
111     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
remove(IBinder token, int faceId, int userId, IFaceServiceReceiver receiver, String opPackageName)112     void remove(IBinder token, int faceId, int userId, IFaceServiceReceiver receiver,
113             String opPackageName);
114 
115     // Removes all face enrollments for the specified userId.
116     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
removeAll(IBinder token, int userId, IFaceServiceReceiver receiver, String opPackageName)117     void removeAll(IBinder token, int userId, IFaceServiceReceiver receiver, String opPackageName);
118 
119     // Get the enrolled face for user.
120     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
getEnrolledFaces(int sensorId, int userId, String opPackageName)121     List<Face> getEnrolledFaces(int sensorId, int userId, String opPackageName);
122 
123     // Determine if HAL is loaded and ready
124     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
isHardwareDetected(int sensorId, String opPackageName)125     boolean isHardwareDetected(int sensorId, String opPackageName);
126 
127     // Get a pre-enrollment authentication token
128     @EnforcePermission("MANAGE_BIOMETRIC")
generateChallenge(IBinder token, int sensorId, int userId, IFaceServiceReceiver receiver, String opPackageName)129     void generateChallenge(IBinder token, int sensorId, int userId, IFaceServiceReceiver receiver, String opPackageName);
130 
131     // Finish an enrollment sequence and invalidate the authentication token
132     @EnforcePermission("MANAGE_BIOMETRIC")
revokeChallenge(IBinder token, int sensorId, int userId, String opPackageName, long challenge)133     void revokeChallenge(IBinder token, int sensorId, int userId, String opPackageName, long challenge);
134 
135     // Determine if a user has at least one enrolled face
136     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
hasEnrolledFaces(int sensorId, int userId, String opPackageName)137     boolean hasEnrolledFaces(int sensorId, int userId, String opPackageName);
138 
139     // Return the LockoutTracker status for the specified user
140     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
getLockoutModeForUser(int sensorId, int userId)141     int getLockoutModeForUser(int sensorId, int userId);
142 
143     // Requests for the specified sensor+userId's authenticatorId to be invalidated
144     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
invalidateAuthenticatorId(int sensorId, int userId, IInvalidationCallback callback)145     void invalidateAuthenticatorId(int sensorId, int userId, IInvalidationCallback callback);
146 
147     // Gets the authenticator ID for face
148     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
getAuthenticatorId(int sensorId, int callingUserId)149     long getAuthenticatorId(int sensorId, int callingUserId);
150 
151     // Reset the lockout when user authenticates with strong auth (e.g. PIN, pattern or password)
152     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
resetLockout(IBinder token, int sensorId, int userId, in byte [] hardwareAuthToken, String opPackageName)153     void resetLockout(IBinder token, int sensorId, int userId, in byte [] hardwareAuthToken, String opPackageName);
154 
155     // Add a callback which gets notified when the face lockout period expired.
156     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
addLockoutResetCallback(IBiometricServiceLockoutResetCallback callback, String opPackageName)157     void addLockoutResetCallback(IBiometricServiceLockoutResetCallback callback, String opPackageName);
158 
159     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
setFeature(IBinder token, int userId, int feature, boolean enabled, in byte [] hardwareAuthToken, IFaceServiceReceiver receiver, String opPackageName)160     void setFeature(IBinder token, int userId, int feature, boolean enabled,
161             in byte [] hardwareAuthToken, IFaceServiceReceiver receiver, String opPackageName);
162 
163     @EnforcePermission("MANAGE_BIOMETRIC")
getFeature(IBinder token, int userId, int feature, IFaceServiceReceiver receiver, String opPackageName)164     void getFeature(IBinder token, int userId, int feature, IFaceServiceReceiver receiver,
165             String opPackageName);
166 
167     //Register all available face sensors.
168     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
registerAuthenticators(in FaceSensorConfigurations faceSensorConfigurations)169     void registerAuthenticators(in FaceSensorConfigurations faceSensorConfigurations);
170 
171     // Adds a callback which gets called when the service registers all of the face
172     // authenticators. The callback is automatically removed after it's invoked.
addAuthenticatorsRegisteredCallback(IFaceAuthenticatorsRegisteredCallback callback)173     void addAuthenticatorsRegisteredCallback(IFaceAuthenticatorsRegisteredCallback callback);
174 
175     // Registers AuthenticationStateListener.
176     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
registerAuthenticationStateListener(AuthenticationStateListener listener)177     void registerAuthenticationStateListener(AuthenticationStateListener listener);
178 
179     // Unregisters AuthenticationStateListener.
180     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
unregisterAuthenticationStateListener(AuthenticationStateListener listener)181     void unregisterAuthenticationStateListener(AuthenticationStateListener listener);
182 
183     // Registers BiometricStateListener.
registerBiometricStateListener(IBiometricStateListener listener)184     void registerBiometricStateListener(IBiometricStateListener listener);
185 
186     // Internal operation used to clear face biometric scheduler.
187     // Ensures that the scheduler is not stuck.
188     @EnforcePermission("USE_BIOMETRIC_INTERNAL")
scheduleWatchdog()189     oneway void scheduleWatchdog();
190 }
191