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