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