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 
17 package android.hardware.biometrics;
18 
19 import android.annotation.CallbackExecutor;
20 import android.annotation.NonNull;
21 import android.os.CancellationSignal;
22 import android.os.Parcelable;
23 
24 import java.util.concurrent.Executor;
25 
26 /**
27  * This is the common interface that all biometric authentication classes should implement.
28  * @hide
29  */
30 public interface BiometricAuthenticator {
31 
32     /**
33      * No biometric methods or nothing has been enrolled.
34      * Move/expose these in BiometricPrompt if we ever want to allow applications to "blacklist"
35      * modalities when calling authenticate().
36      * @hide
37      */
38     int TYPE_NONE = 0;
39     /**
40      * Constant representing fingerprint.
41      * @hide
42      */
43     int TYPE_FINGERPRINT = 1 << 0;
44 
45     /**
46      * Constant representing iris.
47      * @hide
48      */
49     int TYPE_IRIS = 1 << 1;
50 
51     /**
52      * Constant representing face.
53      * @hide
54      */
55     int TYPE_FACE = 1 << 2;
56 
57     /**
58      * Container for biometric data
59      * @hide
60      */
61     abstract class Identifier implements Parcelable {
62         private CharSequence mName;
63         private int mBiometricId;
64         private long mDeviceId; // physical device this is associated with
65 
Identifier()66         public Identifier() {}
67 
Identifier(CharSequence name, int biometricId, long deviceId)68         public Identifier(CharSequence name, int biometricId, long deviceId) {
69             mName = name;
70             mBiometricId = biometricId;
71             mDeviceId = deviceId;
72         }
73 
74         /**
75          * Gets the human-readable name for the given biometric.
76          * @return name given to the biometric
77          */
getName()78         public CharSequence getName() {
79             return mName;
80         }
81 
82         /**
83          * Gets the device-specific biometric id.  Used by Settings to map a name to a specific
84          * biometric template.
85          */
getBiometricId()86         public int getBiometricId() {
87             return mBiometricId;
88         }
89 
90         /**
91          * Device this biometric belongs to.
92          */
getDeviceId()93         public long getDeviceId() {
94             return mDeviceId;
95         }
96 
setName(CharSequence name)97         public void setName(CharSequence name) {
98             mName = name;
99         }
100 
setDeviceId(long deviceId)101         public void setDeviceId(long deviceId) {
102             mDeviceId = deviceId;
103         }
104     }
105 
106     /**
107      * Container for callback data from {@link BiometricAuthenticator#authenticate(
108      * CancellationSignal, Executor, AuthenticationCallback)} and
109      * {@link BiometricAuthenticator#authenticate(CryptoObject, CancellationSignal, Executor,
110      * AuthenticationCallback)}
111      */
112     class AuthenticationResult {
113         private Identifier mIdentifier;
114         private CryptoObject mCryptoObject;
115         private int mUserId;
116 
117         /**
118          * @hide
119          */
AuthenticationResult()120         public AuthenticationResult() { }
121 
122         /**
123          * Authentication result
124          * @param crypto
125          * @param identifier
126          * @param userId
127          * @hide
128          */
AuthenticationResult(CryptoObject crypto, Identifier identifier, int userId)129         public AuthenticationResult(CryptoObject crypto, Identifier identifier,
130                 int userId) {
131             mCryptoObject = crypto;
132             mIdentifier = identifier;
133             mUserId = userId;
134         }
135 
136         /**
137          * Obtain the crypto object associated with this transaction
138          * @return crypto object provided to {@link BiometricAuthenticator#authenticate(
139          * CryptoObject, CancellationSignal, Executor, AuthenticationCallback)}
140          */
getCryptoObject()141         public CryptoObject getCryptoObject() {
142             return mCryptoObject;
143         }
144 
145         /**
146          * Obtain the biometric identifier associated with this operation. Applications are strongly
147          * discouraged from associating specific identifiers with specific applications or
148          * operations.
149          * @hide
150          */
getId()151         public Identifier getId() {
152             return mIdentifier;
153         }
154 
155         /**
156          * Obtain the userId for which this biometric was authenticated.
157          * @hide
158          */
getUserId()159         public int getUserId() {
160             return mUserId;
161         }
162     };
163 
164     /**
165      * Callback structure provided to {@link BiometricAuthenticator#authenticate(CancellationSignal,
166      * Executor, AuthenticationCallback)} or {@link BiometricAuthenticator#authenticate(
167      * CryptoObject, CancellationSignal, Executor, AuthenticationCallback)}. Users must provide
168      * an implementation of this for listening to biometric events.
169      */
170     abstract class AuthenticationCallback {
171         /**
172          * Called when an unrecoverable error has been encountered and the operation is complete.
173          * No further actions will be made on this object.
174          * @param errorCode An integer identifying the error message
175          * @param errString A human-readable error string that can be shown on an UI
176          */
onAuthenticationError(int errorCode, CharSequence errString)177         public void onAuthenticationError(int errorCode, CharSequence errString) {}
178 
179         /**
180          * Called when a recoverable error has been encountered during authentication. The help
181          * string is provided to give the user guidance for what went wrong, such as "Sensor dirty,
182          * please clean it."
183          * @param helpCode An integer identifying the error message
184          * @param helpString A human-readable string that can be shown on an UI
185          */
onAuthenticationHelp(int helpCode, CharSequence helpString)186         public void onAuthenticationHelp(int helpCode, CharSequence helpString) {}
187 
188         /**
189          * Called when a biometric is valid but not recognized.
190          */
onAuthenticationFailed()191         public void onAuthenticationFailed() {}
192 
193         /**
194          * Called when a biometric has been acquired, but hasn't been processed yet.
195          * @hide
196          */
onAuthenticationAcquired(int acquireInfo)197         public void onAuthenticationAcquired(int acquireInfo) {}
198     };
199 
200     /**
201      * @return true if the biometric hardware is detected.
202      */
isHardwareDetected()203     default boolean isHardwareDetected() {
204         throw new UnsupportedOperationException("Stub!");
205     }
206 
207     /**
208      * @return true if the user has enrolled templates for this biometric.
209      */
hasEnrolledTemplates()210     default boolean hasEnrolledTemplates() {
211         throw new UnsupportedOperationException("Stub!");
212     }
213 
214     /**
215      * @return true if the user has enrolled templates for this biometric.
216      */
hasEnrolledTemplates(int userId)217     default boolean hasEnrolledTemplates(int userId) {
218         throw new UnsupportedOperationException("Stub!");
219     }
220 
221     /**
222      * Sets the active user. This is meant to be used to select the current profile
223      * to allow separate templates for work profile.
224      */
setActiveUser(int userId)225     default void setActiveUser(int userId) {
226         throw new UnsupportedOperationException("Stub!");
227     }
228 
229     /**
230      * This call warms up the hardware and starts scanning for valid biometrics. It terminates
231      * when {@link AuthenticationCallback#onAuthenticationError(int,
232      * CharSequence)} is called or when {@link AuthenticationCallback#onAuthenticationSucceeded(
233      * AuthenticationResult)} is called, at which point the crypto object becomes invalid. This
234      * operation can be canceled by using the provided cancel object. The application wil receive
235      * authentication errors through {@link AuthenticationCallback}. Calling
236      * {@link BiometricAuthenticator#authenticate(CryptoObject, CancellationSignal, Executor,
237      * AuthenticationCallback)} while an existing authentication attempt is occurring will stop
238      * the previous client and start a new authentication. The interrupted client will receive a
239      * cancelled notification through {@link AuthenticationCallback#onAuthenticationError(int,
240      * CharSequence)}.
241      *
242      * @throws IllegalArgumentException If any of the arguments are null
243      *
244      * @param crypto Object associated with the call
245      * @param cancel An object that can be used to cancel authentication
246      * @param executor An executor to handle callback events
247      * @param callback An object to receive authentication events
248      */
authenticate(@onNull CryptoObject crypto, @NonNull CancellationSignal cancel, @NonNull @CallbackExecutor Executor executor, @NonNull AuthenticationCallback callback)249     default void authenticate(@NonNull CryptoObject crypto,
250             @NonNull CancellationSignal cancel,
251             @NonNull @CallbackExecutor Executor executor,
252             @NonNull AuthenticationCallback callback) {
253         throw new UnsupportedOperationException("Stub!");
254     }
255 
256     /**
257      * This call warms up the hardware and starts scanning for valid biometrics. It terminates
258      * when {@link AuthenticationCallback#onAuthenticationError(int,
259      * CharSequence)} is called or when {@link AuthenticationCallback#onAuthenticationSucceeded(
260      * AuthenticationResult)} is called. This operation can be canceled by using the provided cancel
261      * object. The application wil receive authentication errors through
262      * {@link AuthenticationCallback}. Calling {@link BiometricAuthenticator#authenticate(
263      * CryptoObject, CancellationSignal, Executor, AuthenticationCallback)} while an existing
264      * authentication attempt is occurring will stop the previous client and start a new
265      * authentication. The interrupted client will receive a cancelled notification through
266      * {@link AuthenticationCallback#onAuthenticationError(int, CharSequence)}.
267      *
268      * @throws IllegalArgumentException If any of the arguments are null
269      *
270      * @param cancel An object that can be used to cancel authentication
271      * @param executor An executor to handle callback events
272      * @param callback An object to receive authentication events
273      */
authenticate(@onNull CancellationSignal cancel, @NonNull @CallbackExecutor Executor executor, @NonNull AuthenticationCallback callback)274     default void authenticate(@NonNull CancellationSignal cancel,
275             @NonNull @CallbackExecutor Executor executor,
276             @NonNull AuthenticationCallback callback) {
277         throw new UnsupportedOperationException("Stub!");
278     }
279 }
280