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