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