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