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.app.KeyguardManager; 21 import android.compat.annotation.UnsupportedAppUsage; 22 import android.hardware.biometrics.BiometricManager.Authenticators; 23 import android.hardware.fingerprint.FingerprintManager; 24 import android.os.Build; 25 26 import java.lang.annotation.Retention; 27 import java.lang.annotation.RetentionPolicy; 28 29 /** 30 * Interface containing all of the fingerprint-specific constants. 31 * 32 * NOTE: The error messages must be consistent between BiometricConstants, Biometric*Constants, 33 * and the frameworks/support/biometric/.../BiometricConstants files. 34 * 35 * @hide 36 */ 37 public interface BiometricFingerprintConstants { 38 // 39 // Error messages from fingerprint hardware during initilization, enrollment, authentication or 40 // removal. Must agree with the list in fingerprint.h 41 // 42 43 /** 44 * @hide 45 */ 46 @IntDef({FINGERPRINT_ERROR_HW_UNAVAILABLE, 47 FINGERPRINT_ERROR_UNABLE_TO_PROCESS, 48 FINGERPRINT_ERROR_TIMEOUT, 49 FINGERPRINT_ERROR_NO_SPACE, 50 FINGERPRINT_ERROR_CANCELED, 51 FINGERPRINT_ERROR_UNABLE_TO_REMOVE, 52 FINGERPRINT_ERROR_LOCKOUT, 53 FINGERPRINT_ERROR_VENDOR, 54 FINGERPRINT_ERROR_LOCKOUT_PERMANENT, 55 FINGERPRINT_ERROR_USER_CANCELED, 56 FINGERPRINT_ERROR_NO_FINGERPRINTS, 57 FINGERPRINT_ERROR_HW_NOT_PRESENT, 58 FINGERPRINT_ERROR_NEGATIVE_BUTTON, 59 BIOMETRIC_ERROR_NO_DEVICE_CREDENTIAL, 60 BIOMETRIC_ERROR_SECURITY_UPDATE_REQUIRED, 61 BIOMETRIC_ERROR_RE_ENROLL, 62 BIOMETRIC_ERROR_SECURITY_UPDATE_REQUIRED, 63 FINGERPRINT_ERROR_UNKNOWN, 64 FINGERPRINT_ERROR_BAD_CALIBRATION, 65 BIOMETRIC_ERROR_POWER_PRESSED}) 66 @Retention(RetentionPolicy.SOURCE) 67 @interface FingerprintError {} 68 69 /** 70 * The hardware is unavailable. Try again later. 71 */ 72 int FINGERPRINT_ERROR_HW_UNAVAILABLE = 1; 73 74 /** 75 * Error state returned when the sensor was unable to process the current image. 76 */ 77 int FINGERPRINT_ERROR_UNABLE_TO_PROCESS = 2; 78 79 /** 80 * Error state returned when the current request has been running too long. This is intended to 81 * prevent programs from waiting for the fingerprint sensor indefinitely. The timeout is 82 * platform and sensor-specific, but is generally on the order of 30 seconds. 83 */ 84 int FINGERPRINT_ERROR_TIMEOUT = 3; 85 86 /** 87 * Error state returned for operations like enrollment; the operation cannot be completed 88 * because there's not enough storage remaining to complete the operation. 89 */ 90 int FINGERPRINT_ERROR_NO_SPACE = 4; 91 92 /** 93 * The operation was canceled because the fingerprint sensor is unavailable. For example, 94 * this may happen when the user is switched, the device is locked or another pending operation 95 * prevents or disables it. 96 */ 97 int FINGERPRINT_ERROR_CANCELED = 5; 98 99 /** 100 * The {@link FingerprintManager#remove} call failed. Typically this will happen when the 101 * provided fingerprint id was incorrect. 102 * 103 * @hide 104 */ 105 int FINGERPRINT_ERROR_UNABLE_TO_REMOVE = 6; 106 107 /** 108 * The operation was canceled because the API is locked out due to too many attempts. 109 * This occurs after 5 failed attempts, and lasts for 30 seconds. 110 */ 111 int FINGERPRINT_ERROR_LOCKOUT = 7; 112 113 /** 114 * Hardware vendors may extend this list if there are conditions that do not fall under one of 115 * the above categories. Vendors are responsible for providing error strings for these errors. 116 * These messages are typically reserved for internal operations such as enrollment, but may be 117 * used to express vendor errors not covered by the ones in fingerprint.h. Applications are 118 * expected to show the error message string if they happen, but are advised not to rely on the 119 * message id since they will be device and vendor-specific 120 */ 121 int FINGERPRINT_ERROR_VENDOR = 8; 122 123 /** 124 * The operation was canceled because FINGERPRINT_ERROR_LOCKOUT occurred too many times. 125 * Fingerprint authentication is disabled until the user unlocks with strong authentication 126 * (PIN/Pattern/Password) 127 */ 128 int FINGERPRINT_ERROR_LOCKOUT_PERMANENT = 9; 129 130 /** 131 * The user canceled the operation. Upon receiving this, applications should use alternate 132 * authentication (e.g. a password). The application should also provide the means to return 133 * to fingerprint authentication, such as a "use fingerprint" button. 134 */ 135 int FINGERPRINT_ERROR_USER_CANCELED = 10; 136 137 /** 138 * The user does not have any fingerprints enrolled. 139 */ 140 int FINGERPRINT_ERROR_NO_FINGERPRINTS = 11; 141 142 /** 143 * The device does not have a fingerprint sensor. 144 */ 145 int FINGERPRINT_ERROR_HW_NOT_PRESENT = 12; 146 147 /** 148 * The user pressed the negative button. This is a placeholder that is currently only used 149 * by the support library. 150 * 151 * @hide 152 */ 153 int FINGERPRINT_ERROR_NEGATIVE_BUTTON = 13; 154 155 /** 156 * The device does not have pin, pattern, or password set up. See 157 * {@link BiometricPrompt.Builder#setDeviceCredentialAllowed(boolean)} and 158 * {@link KeyguardManager#isDeviceSecure()} 159 * 160 * @hide 161 */ 162 int BIOMETRIC_ERROR_NO_DEVICE_CREDENTIAL = 14; 163 164 /** 165 * A security vulnerability has been discovered and the sensor is unavailable until a 166 * security update has addressed this issue. This error can be received if for example, 167 * authentication was requested with {@link Authenticators#BIOMETRIC_STRONG}, but the 168 * sensor's strength can currently only meet {@link Authenticators#BIOMETRIC_WEAK}. 169 * @hide 170 */ 171 int BIOMETRIC_ERROR_SECURITY_UPDATE_REQUIRED = 15; 172 173 /** 174 * Authentication cannot proceed because re-enrollment is required. 175 * @hide 176 */ 177 int BIOMETRIC_ERROR_RE_ENROLL = 16; 178 179 /** 180 * Unknown error received from the HAL. 181 * @hide 182 */ 183 int FINGERPRINT_ERROR_UNKNOWN = 17; 184 185 /** 186 * Error indicating that the fingerprint sensor has bad calibration. 187 * @hide 188 */ 189 int FINGERPRINT_ERROR_BAD_CALIBRATION = 18; 190 191 /** 192 * A power press stopped this biometric operation. 193 * @hide 194 */ 195 int BIOMETRIC_ERROR_POWER_PRESSED = 19; 196 197 /** 198 * @hide 199 */ 200 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 201 int FINGERPRINT_ERROR_VENDOR_BASE = 1000; 202 203 // 204 // Image acquisition messages. Must agree with those in fingerprint.h 205 // 206 207 /** 208 * @hide 209 */ 210 @IntDef({FINGERPRINT_ACQUIRED_GOOD, 211 FINGERPRINT_ACQUIRED_PARTIAL, 212 FINGERPRINT_ACQUIRED_INSUFFICIENT, 213 FINGERPRINT_ACQUIRED_IMAGER_DIRTY, 214 FINGERPRINT_ACQUIRED_TOO_SLOW, 215 FINGERPRINT_ACQUIRED_TOO_FAST, 216 FINGERPRINT_ACQUIRED_VENDOR, 217 FINGERPRINT_ACQUIRED_START, 218 FINGERPRINT_ACQUIRED_UNKNOWN, 219 FINGERPRINT_ACQUIRED_IMMOBILE, 220 FINGERPRINT_ACQUIRED_TOO_BRIGHT, 221 FINGERPRINT_ACQUIRED_POWER_PRESSED}) 222 @Retention(RetentionPolicy.SOURCE) 223 @interface FingerprintAcquired {} 224 225 /** 226 * The image acquired was good. 227 */ 228 int FINGERPRINT_ACQUIRED_GOOD = 0; 229 230 /** 231 * Only a partial fingerprint image was detected. During enrollment, the user should be 232 * informed on what needs to happen to resolve this problem, e.g. "press firmly on sensor." 233 */ 234 int FINGERPRINT_ACQUIRED_PARTIAL = 1; 235 236 /** 237 * The fingerprint image was too noisy to process due to a detected condition (i.e. dry skin) or 238 * a possibly dirty sensor (See {@link #FINGERPRINT_ACQUIRED_IMAGER_DIRTY}). 239 */ 240 int FINGERPRINT_ACQUIRED_INSUFFICIENT = 2; 241 242 /** 243 * The fingerprint image was too noisy due to suspected or detected dirt on the sensor. 244 * For example, it's reasonable return this after multiple 245 * {@link #FINGERPRINT_ACQUIRED_INSUFFICIENT} or actual detection of dirt on the sensor 246 * (stuck pixels, swaths, etc.). The user is expected to take action to clean the sensor 247 * when this is returned. 248 */ 249 int FINGERPRINT_ACQUIRED_IMAGER_DIRTY = 3; 250 251 /** 252 * The fingerprint image was unreadable due to lack of motion. This is most appropriate for 253 * linear array sensors that require a swipe motion. 254 */ 255 int FINGERPRINT_ACQUIRED_TOO_SLOW = 4; 256 257 /** 258 * The fingerprint image was incomplete due to quick motion. While mostly appropriate for 259 * linear array sensors, this could also happen if the finger was moved during acquisition. 260 * The user should be asked to move the finger slower (linear) or leave the finger on the sensor 261 * longer. 262 */ 263 int FINGERPRINT_ACQUIRED_TOO_FAST = 5; 264 265 /** 266 * Hardware vendors may extend this list if there are conditions that do not fall under one of 267 * the above categories. Vendors are responsible for providing error strings for these errors. 268 * 269 * @hide 270 */ 271 int FINGERPRINT_ACQUIRED_VENDOR = 6; 272 273 /** 274 * This message represents the earliest message sent at the beginning of the authentication 275 * pipeline. It is expected to be used to measure latency. Note this should be sent whenever 276 * authentication is restarted. 277 * The framework will measure latency based on the time between the last START message and the 278 * onAuthenticated callback. 279 * 280 * @hide 281 */ 282 int FINGERPRINT_ACQUIRED_START = 7; 283 284 /** 285 * Unknown acquired code received from the HAL. 286 * @hide 287 */ 288 int FINGERPRINT_ACQUIRED_UNKNOWN = 8; 289 290 /** 291 * This message may be sent during enrollment if the same area of the finger has already 292 * been captured during this enrollment session. In general, enrolling multiple areas of the 293 * same finger can help against false rejections. 294 * @hide 295 */ 296 int FINGERPRINT_ACQUIRED_IMMOBILE = 9; 297 298 /** 299 * For sensors that require illumination, such as optical under-display fingerprint sensors, 300 * the image was too bright to be used for matching. 301 * @hide 302 */ 303 int FINGERPRINT_ACQUIRED_TOO_BRIGHT = 10; 304 305 /** 306 * For sensors that have the power button co-located with their sensor, this event will 307 * be sent during enrollment. 308 * @hide 309 */ 310 int FINGERPRINT_ACQUIRED_POWER_PRESSED = 11; 311 312 /** 313 * @hide 314 */ 315 int FINGERPRINT_ACQUIRED_VENDOR_BASE = 1000; 316 317 /** 318 * Whether the FingerprintAcquired message is a signal to disable the UDFPS display mode. 319 * We want to disable the UDFPS mode as soon as possible to conserve power and provide better 320 * UX. For example, prolonged high-brightness illumination of optical sensors can be unpleasant 321 * to the user, can cause long term display burn-in, and can drain the battery faster. 322 */ shouldDisableUdfpsDisplayMode(@ingerprintAcquired int acquiredInfo)323 static boolean shouldDisableUdfpsDisplayMode(@FingerprintAcquired int acquiredInfo) { 324 switch (acquiredInfo) { 325 case FINGERPRINT_ACQUIRED_START: 326 // Keep the UDFPS mode because the authentication just began. 327 return false; 328 case FINGERPRINT_ACQUIRED_GOOD: 329 case FINGERPRINT_ACQUIRED_PARTIAL: 330 case FINGERPRINT_ACQUIRED_INSUFFICIENT: 331 case FINGERPRINT_ACQUIRED_IMAGER_DIRTY: 332 case FINGERPRINT_ACQUIRED_TOO_SLOW: 333 case FINGERPRINT_ACQUIRED_TOO_FAST: 334 case FINGERPRINT_ACQUIRED_IMMOBILE: 335 case FINGERPRINT_ACQUIRED_TOO_BRIGHT: 336 case FINGERPRINT_ACQUIRED_VENDOR: 337 // Disable the UDFPS mode because the image capture has finished. The overlay 338 // can be hidden later, once the authentication result arrives. 339 return true; 340 case FINGERPRINT_ACQUIRED_UNKNOWN: 341 default: 342 // Keep the UDFPS mode in case of an unknown message. 343 return false; 344 } 345 } 346 } 347