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      * Container for biometric data
34      * @hide
35      */
36     abstract class BiometricIdentifier implements Parcelable {}
37 
38     /**
39      * Container for callback data from {@link BiometricAuthenticator#authenticate(
40      * CancellationSignal, Executor, AuthenticationCallback)} and
41      * {@link BiometricAuthenticator#authenticate(CryptoObject, CancellationSignal, Executor,
42      * AuthenticationCallback)}
43      */
44     class AuthenticationResult {
45         private BiometricIdentifier mIdentifier;
46         private CryptoObject mCryptoObject;
47         private int mUserId;
48 
49         /**
50          * @hide
51          */
AuthenticationResult()52         public AuthenticationResult() { }
53 
54         /**
55          * Authentication result
56          * @param crypto
57          * @param identifier
58          * @param userId
59          * @hide
60          */
AuthenticationResult(CryptoObject crypto, BiometricIdentifier identifier, int userId)61         public AuthenticationResult(CryptoObject crypto, BiometricIdentifier identifier,
62                 int userId) {
63             mCryptoObject = crypto;
64             mIdentifier = identifier;
65             mUserId = userId;
66         }
67 
68         /**
69          * Obtain the crypto object associated with this transaction
70          * @return crypto object provided to {@link BiometricAuthenticator#authenticate(
71          * CryptoObject, CancellationSignal, Executor, AuthenticationCallback)}
72          */
getCryptoObject()73         public CryptoObject getCryptoObject() {
74             return mCryptoObject;
75         }
76 
77         /**
78          * Obtain the biometric identifier associated with this operation. Applications are strongly
79          * discouraged from associating specific identifiers with specific applications or
80          * operations.
81          * @hide
82          */
getId()83         public BiometricIdentifier getId() {
84             return mIdentifier;
85         }
86 
87         /**
88          * Obtain the userId for which this biometric was authenticated.
89          * @hide
90          */
getUserId()91         public int getUserId() {
92             return mUserId;
93         }
94     };
95 
96     /**
97      * Callback structure provided to {@link BiometricAuthenticator#authenticate(CancellationSignal,
98      * Executor, AuthenticationCallback)} or {@link BiometricAuthenticator#authenticate(
99      * CryptoObject, CancellationSignal, Executor, AuthenticationCallback)}. Users must provide
100      * an implementation of this for listening to biometric events.
101      */
102     abstract class AuthenticationCallback {
103         /**
104          * Called when an unrecoverable error has been encountered and the operation is complete.
105          * No further actions will be made on this object.
106          * @param errorCode An integer identifying the error message
107          * @param errString A human-readable error string that can be shown on an UI
108          */
onAuthenticationError(int errorCode, CharSequence errString)109         public void onAuthenticationError(int errorCode, CharSequence errString) {}
110 
111         /**
112          * Called when a recoverable error has been encountered during authentication. The help
113          * string is provided to give the user guidance for what went wrong, such as "Sensor dirty,
114          * please clean it."
115          * @param helpCode An integer identifying the error message
116          * @param helpString A human-readable string that can be shown on an UI
117          */
onAuthenticationHelp(int helpCode, CharSequence helpString)118         public void onAuthenticationHelp(int helpCode, CharSequence helpString) {}
119 
120         /**
121          * Called when a biometric is recognized.
122          * @param result An object containing authentication-related data
123          */
onAuthenticationSucceeded(AuthenticationResult result)124         public void onAuthenticationSucceeded(AuthenticationResult result) {}
125 
126         /**
127          * Called when a biometric is valid but not recognized.
128          */
onAuthenticationFailed()129         public void onAuthenticationFailed() {}
130 
131         /**
132          * Called when a biometric has been acquired, but hasn't been processed yet.
133          * @hide
134          */
onAuthenticationAcquired(int acquireInfo)135         public void onAuthenticationAcquired(int acquireInfo) {}
136     };
137 
138     /**
139      * This call warms up the hardware and starts scanning for valid biometrics. It terminates
140      * when {@link AuthenticationCallback#onAuthenticationError(int,
141      * CharSequence)} is called or when {@link AuthenticationCallback#onAuthenticationSucceeded(
142      * AuthenticationResult)} is called, at which point the crypto object becomes invalid. This
143      * operation can be canceled by using the provided cancel object. The application wil receive
144      * authentication errors through {@link AuthenticationCallback}. Calling
145      * {@link BiometricAuthenticator#authenticate(CryptoObject, CancellationSignal, Executor,
146      * AuthenticationCallback)} while an existing authentication attempt is occurring will stop
147      * the previous client and start a new authentication. The interrupted client will receive a
148      * cancelled notification through {@link AuthenticationCallback#onAuthenticationError(int,
149      * CharSequence)}.
150      *
151      * @throws IllegalArgumentException If any of the arguments are null
152      *
153      * @param crypto Object associated with the call
154      * @param cancel An object that can be used to cancel authentication
155      * @param executor An executor to handle callback events
156      * @param callback An object to receive authentication events
157      */
authenticate(@onNull CryptoObject crypto, @NonNull CancellationSignal cancel, @NonNull @CallbackExecutor Executor executor, @NonNull AuthenticationCallback callback)158     void authenticate(@NonNull CryptoObject crypto,
159             @NonNull CancellationSignal cancel,
160             @NonNull @CallbackExecutor Executor executor,
161             @NonNull AuthenticationCallback callback);
162 
163     /**
164      * This call warms up the hardware and starts scanning for valid biometrics. It terminates
165      * when {@link AuthenticationCallback#onAuthenticationError(int,
166      * CharSequence)} is called or when {@link AuthenticationCallback#onAuthenticationSucceeded(
167      * AuthenticationResult)} is called. This operation can be canceled by using the provided cancel
168      * object. The application wil receive authentication errors through
169      * {@link AuthenticationCallback}. Calling {@link BiometricAuthenticator#authenticate(
170      * CryptoObject, CancellationSignal, Executor, AuthenticationCallback)} while an existing
171      * authentication attempt is occurring will stop the previous client and start a new
172      * authentication. The interrupted client will receive a cancelled notification through
173      * {@link AuthenticationCallback#onAuthenticationError(int, CharSequence)}.
174      *
175      * @throws IllegalArgumentException If any of the arguments are null
176      *
177      * @param cancel An object that can be used to cancel authentication
178      * @param executor An executor to handle callback events
179      * @param callback An object to receive authentication events
180      */
authenticate(@onNull CancellationSignal cancel, @NonNull @CallbackExecutor Executor executor, @NonNull AuthenticationCallback callback)181     void authenticate(@NonNull CancellationSignal cancel,
182             @NonNull @CallbackExecutor Executor executor,
183             @NonNull AuthenticationCallback callback);
184 }
185