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.IntDef; 20 import android.hardware.biometrics.BiometricPrompt.AuthenticationResultType; 21 import android.os.CancellationSignal; 22 import android.os.Parcelable; 23 24 import java.lang.annotation.Retention; 25 import java.lang.annotation.RetentionPolicy; 26 import java.util.concurrent.Executor; 27 28 /** 29 * This is the common interface that all biometric authentication classes should implement. 30 * @hide 31 */ 32 public interface BiometricAuthenticator { 33 34 /** 35 * No biometric methods or nothing has been enrolled. 36 * Move/expose these in BiometricPrompt if we ever want to allow applications to "denylist" 37 * modalities when calling authenticate(). 38 * @hide 39 */ 40 int TYPE_NONE = 0; 41 42 /** 43 * Constant representing credential (PIN, pattern, or password). 44 * @hide 45 */ 46 int TYPE_CREDENTIAL = 1 << 0; 47 48 /** 49 * Constant representing fingerprint. 50 * @hide 51 */ 52 int TYPE_FINGERPRINT = 1 << 1; 53 54 /** 55 * Constant representing iris. 56 * @hide 57 */ 58 int TYPE_IRIS = 1 << 2; 59 60 /** 61 * Constant representing face. 62 * @hide 63 */ 64 int TYPE_FACE = 1 << 3; 65 66 /** 67 * @hide 68 */ 69 int TYPE_ANY_BIOMETRIC = TYPE_FINGERPRINT | TYPE_IRIS | TYPE_FACE; 70 71 @IntDef(flag = true, value = { 72 TYPE_NONE, 73 TYPE_CREDENTIAL, 74 TYPE_FINGERPRINT, 75 TYPE_IRIS, 76 TYPE_FACE 77 }) 78 @Retention(RetentionPolicy.SOURCE) 79 @interface Modality {} 80 81 /** 82 * Container for biometric data 83 * @hide 84 */ 85 abstract class Identifier implements Parcelable { 86 private CharSequence mName; 87 private int mBiometricId; 88 private long mDeviceId; // physical device this is associated with 89 Identifier()90 public Identifier() {} 91 Identifier(CharSequence name, int biometricId, long deviceId)92 public Identifier(CharSequence name, int biometricId, long deviceId) { 93 mName = name; 94 mBiometricId = biometricId; 95 mDeviceId = deviceId; 96 } 97 98 /** 99 * Gets the human-readable name for the given biometric. 100 * @return name given to the biometric 101 */ getName()102 public CharSequence getName() { 103 return mName; 104 } 105 106 /** 107 * Gets the device-specific biometric id. Used by Settings to map a name to a specific 108 * biometric template. 109 */ getBiometricId()110 public int getBiometricId() { 111 return mBiometricId; 112 } 113 114 /** 115 * Device this biometric belongs to. 116 */ getDeviceId()117 public long getDeviceId() { 118 return mDeviceId; 119 } 120 setName(CharSequence name)121 public void setName(CharSequence name) { 122 mName = name; 123 } 124 setDeviceId(long deviceId)125 public void setDeviceId(long deviceId) { 126 mDeviceId = deviceId; 127 } 128 } 129 130 /** 131 * Container for callback data from {@link BiometricAuthenticator#authenticate( 132 * CancellationSignal, Executor, AuthenticationCallback)} and 133 * {@link BiometricAuthenticator#authenticate(CryptoObject, CancellationSignal, Executor, 134 * AuthenticationCallback)} 135 */ 136 class AuthenticationResult { 137 private Identifier mIdentifier; 138 private CryptoObject mCryptoObject; 139 private @AuthenticationResultType int mAuthenticationType; 140 private int mUserId; 141 142 /** 143 * @hide 144 */ AuthenticationResult()145 public AuthenticationResult() { } 146 147 /** 148 * Authentication result 149 * @param crypto 150 * @param authenticationType 151 * @param identifier 152 * @param userId 153 * @hide 154 */ AuthenticationResult(CryptoObject crypto, @AuthenticationResultType int authenticationType, Identifier identifier, int userId)155 public AuthenticationResult(CryptoObject crypto, 156 @AuthenticationResultType int authenticationType, Identifier identifier, 157 int userId) { 158 mCryptoObject = crypto; 159 mAuthenticationType = authenticationType; 160 mIdentifier = identifier; 161 mUserId = userId; 162 } 163 164 /** 165 * Provides the crypto object associated with this transaction. 166 * @return The crypto object provided to {@link BiometricPrompt#authenticate( 167 * BiometricPrompt.CryptoObject, CancellationSignal, Executor, 168 * BiometricPrompt.AuthenticationCallback)} 169 */ getCryptoObject()170 public CryptoObject getCryptoObject() { 171 return mCryptoObject; 172 } 173 174 /** 175 * Provides the type of authentication (e.g. device credential or biometric) that was 176 * requested from and successfully provided by the user. 177 * 178 * @return An integer value representing the authentication method used. 179 */ getAuthenticationType()180 public @AuthenticationResultType int getAuthenticationType() { 181 return mAuthenticationType; 182 } 183 184 /** 185 * Obtain the biometric identifier associated with this operation. Applications are strongly 186 * discouraged from associating specific identifiers with specific applications or 187 * operations. 188 * @hide 189 */ getId()190 public Identifier getId() { 191 return mIdentifier; 192 } 193 194 /** 195 * Obtain the userId for which this biometric was authenticated. 196 * @hide 197 */ getUserId()198 public int getUserId() { 199 return mUserId; 200 } 201 }; 202 203 /** 204 * Callback structure provided to {@link BiometricAuthenticator#authenticate(CancellationSignal, 205 * Executor, AuthenticationCallback)} or {@link BiometricAuthenticator#authenticate( 206 * CryptoObject, CancellationSignal, Executor, AuthenticationCallback)}. Users must provide 207 * an implementation of this for listening to biometric events. 208 */ 209 abstract class AuthenticationCallback { 210 /** 211 * Called when an unrecoverable error has been encountered and the operation is complete. 212 * No further actions will be made on this object. 213 * @param errorCode An integer identifying the error message 214 * @param errString A human-readable error string that can be shown on an UI 215 */ onAuthenticationError(int errorCode, CharSequence errString)216 public void onAuthenticationError(int errorCode, CharSequence errString) {} 217 218 /** 219 * Called when a recoverable error has been encountered during authentication. The help 220 * string is provided to give the user guidance for what went wrong, such as "Sensor dirty, 221 * please clean it." 222 * @param helpCode An integer identifying the error message 223 * @param helpString A human-readable string that can be shown on an UI 224 */ onAuthenticationHelp(int helpCode, CharSequence helpString)225 public void onAuthenticationHelp(int helpCode, CharSequence helpString) {} 226 227 /** 228 * Called when a biometric is valid but not recognized. 229 */ onAuthenticationFailed()230 public void onAuthenticationFailed() {} 231 232 /** 233 * Called when a biometric has been acquired, but hasn't been processed yet. 234 * @hide 235 */ onAuthenticationAcquired(int acquireInfo)236 public void onAuthenticationAcquired(int acquireInfo) {} 237 } 238 } 239