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.hardware.biometrics.BiometricManager.Authenticators; 22 import android.hardware.face.FaceManager; 23 24 import java.lang.annotation.Retention; 25 import java.lang.annotation.RetentionPolicy; 26 27 /** 28 * Interface containing all of the face-specific constants. 29 * 30 * NOTE: The error messages must be consistent between BiometricConstants, Biometric*Constants, 31 * and the frameworks/support/biometric/.../BiometricConstants files. 32 * 33 * @hide 34 */ 35 public interface BiometricFaceConstants { 36 // 37 // Accessibility constants 38 // 39 /** 40 * Require the user to look at the device during enrollment and 41 * authentication. Note this is to accommodate people who have limited 42 * vision. 43 */ 44 int FEATURE_REQUIRE_ATTENTION = 1; 45 /** 46 * Require a diverse set of poses during enrollment. Note this is to 47 * accommodate people with limited mobility. 48 */ 49 int FEATURE_REQUIRE_REQUIRE_DIVERSITY = 2; 50 51 // 52 // Error messages from face authentication hardware during initialization, enrollment, 53 // authentication or removal. Must agree with the list in HAL h file 54 // 55 56 @IntDef({FACE_ERROR_HW_UNAVAILABLE, 57 FACE_ERROR_UNABLE_TO_PROCESS, 58 FACE_ERROR_TIMEOUT, 59 FACE_ERROR_NO_SPACE, 60 FACE_ERROR_CANCELED, 61 FACE_ERROR_UNABLE_TO_REMOVE, 62 FACE_ERROR_LOCKOUT, 63 FACE_ERROR_VENDOR, 64 FACE_ERROR_LOCKOUT_PERMANENT, 65 FACE_ERROR_USER_CANCELED, 66 FACE_ERROR_NOT_ENROLLED, 67 FACE_ERROR_HW_NOT_PRESENT, 68 FACE_ERROR_NEGATIVE_BUTTON, 69 BIOMETRIC_ERROR_NO_DEVICE_CREDENTIAL, 70 BIOMETRIC_ERROR_SECURITY_UPDATE_REQUIRED, 71 BIOMETRIC_ERROR_RE_ENROLL, 72 FACE_ERROR_UNKNOWN, 73 BIOMETRIC_ERROR_POWER_PRESSED, 74 }) 75 @Retention(RetentionPolicy.SOURCE) 76 @interface FaceError {} 77 78 /** 79 * The hardware is unavailable. Try again later. 80 */ 81 int FACE_ERROR_HW_UNAVAILABLE = 1; 82 83 /** 84 * Error state returned when the sensor was unable to process the current image. 85 */ 86 int FACE_ERROR_UNABLE_TO_PROCESS = 2; 87 88 /** 89 * Error state returned when the current request has been running too long. This is intended to 90 * prevent programs from waiting for the face authentication sensor indefinitely. The timeout is 91 * platform and sensor-specific, but is generally on the order of 30 seconds. 92 */ 93 int FACE_ERROR_TIMEOUT = 3; 94 95 /** 96 * Error state returned for operations like enrollment; the operation cannot be completed 97 * because there's not enough storage remaining to complete the operation. 98 */ 99 int FACE_ERROR_NO_SPACE = 4; 100 101 /** 102 * The operation was canceled because the face authentication sensor is unavailable. For 103 * example, this may happen when the user is switched, the device is locked or another pending 104 * operation prevents or disables it. 105 */ 106 int FACE_ERROR_CANCELED = 5; 107 108 /** 109 * The {@link FaceManager#remove} call failed. Typically this will happen when the 110 * provided face id was incorrect. 111 */ 112 int FACE_ERROR_UNABLE_TO_REMOVE = 6; 113 114 /** 115 * The operation was canceled because the API is locked out due to too many attempts. 116 * This occurs after 5 failed attempts, and lasts for 30 seconds. 117 */ 118 int FACE_ERROR_LOCKOUT = 7; 119 120 /** 121 * Hardware vendors may extend this list if there are conditions that do not fall under one of 122 * the above categories. Vendors are responsible for providing error strings for these errors. 123 * These messages are typically reserved for internal operations such as enrollment, but may be 124 * used to express vendor errors not covered by the ones in HAL h file. Applications are 125 * expected to show the error message string if they happen, but are advised not to rely on the 126 * message id since they will be device and vendor-specific 127 */ 128 int FACE_ERROR_VENDOR = 8; 129 130 /** 131 * The operation was canceled because FACE_ERROR_LOCKOUT occurred too many times. 132 * Face authentication is disabled until the user unlocks with strong authentication 133 * (PIN/Pattern/Password) 134 */ 135 int FACE_ERROR_LOCKOUT_PERMANENT = 9; 136 137 /** 138 * The user canceled the operation. Upon receiving this, applications should use alternate 139 * authentication (e.g. a password). The application should also provide the means to return 140 * to face authentication, such as a "use face authentication" button. 141 */ 142 int FACE_ERROR_USER_CANCELED = 10; 143 144 /** 145 * The user does not have a face enrolled. 146 */ 147 int FACE_ERROR_NOT_ENROLLED = 11; 148 149 /** 150 * The device does not have a face sensor. This message will propagate if the calling app 151 * ignores the result from PackageManager.hasFeature(FEATURE_FACE) and calls 152 * this API anyway. Apps should always check for the feature before calling this API. 153 */ 154 int FACE_ERROR_HW_NOT_PRESENT = 12; 155 156 /** 157 * The user pressed the negative button. This is a placeholder that is currently only used 158 * by the support library. 159 */ 160 int FACE_ERROR_NEGATIVE_BUTTON = 13; 161 162 /** 163 * The device does not have pin, pattern, or password set up. See 164 * {@link BiometricPrompt.Builder#setDeviceCredentialAllowed(boolean)} and 165 * {@link KeyguardManager#isDeviceSecure()} 166 */ 167 int BIOMETRIC_ERROR_NO_DEVICE_CREDENTIAL = 14; 168 169 /** 170 * A security vulnerability has been discovered and the sensor is unavailable until a 171 * security update has addressed this issue. This error can be received if for example, 172 * authentication was requested with {@link Authenticators#BIOMETRIC_STRONG}, but the 173 * sensor's strength can currently only meet {@link Authenticators#BIOMETRIC_WEAK}. 174 */ 175 int BIOMETRIC_ERROR_SECURITY_UPDATE_REQUIRED = 15; 176 177 /** 178 * Authentication cannot proceed because re-enrollment is required. 179 */ 180 int BIOMETRIC_ERROR_RE_ENROLL = 16; 181 182 /** 183 * Unknown error received from the HAL. 184 */ 185 int FACE_ERROR_UNKNOWN = 17; 186 187 /** 188 * A power press stopped this biometric operation. 189 * @hide 190 */ 191 int BIOMETRIC_ERROR_POWER_PRESSED = 19; 192 193 /** 194 * Vendor codes received from the HAL start at 0. Codes that the framework exposes to keyguard 195 * append this value for some reason. We should probably remove this and just send the actual 196 * vendor code. 197 */ 198 int FACE_ERROR_VENDOR_BASE = 1000; 199 200 // 201 // Image acquisition messages. These will not be sent to the user, since they conflict with 202 // existing constants. These must agree with face@1.0/types.hal. 203 // 204 205 @IntDef({FACE_ACQUIRED_GOOD, 206 FACE_ACQUIRED_INSUFFICIENT, 207 FACE_ACQUIRED_TOO_BRIGHT, 208 FACE_ACQUIRED_TOO_DARK, 209 FACE_ACQUIRED_TOO_CLOSE, 210 FACE_ACQUIRED_TOO_FAR, 211 FACE_ACQUIRED_TOO_HIGH, 212 FACE_ACQUIRED_TOO_LOW, 213 FACE_ACQUIRED_TOO_RIGHT, 214 FACE_ACQUIRED_TOO_LEFT, 215 FACE_ACQUIRED_POOR_GAZE, 216 FACE_ACQUIRED_NOT_DETECTED, 217 FACE_ACQUIRED_TOO_MUCH_MOTION, 218 FACE_ACQUIRED_RECALIBRATE, 219 FACE_ACQUIRED_TOO_DIFFERENT, 220 FACE_ACQUIRED_TOO_SIMILAR, 221 FACE_ACQUIRED_PAN_TOO_EXTREME, 222 FACE_ACQUIRED_TILT_TOO_EXTREME, 223 FACE_ACQUIRED_ROLL_TOO_EXTREME, 224 FACE_ACQUIRED_FACE_OBSCURED, 225 FACE_ACQUIRED_START, 226 FACE_ACQUIRED_SENSOR_DIRTY, 227 FACE_ACQUIRED_VENDOR, 228 FACE_ACQUIRED_UNKNOWN, 229 FACE_ACQUIRED_FIRST_FRAME_RECEIVED, 230 FACE_ACQUIRED_DARK_GLASSES_DETECTED, 231 FACE_ACQUIRED_MOUTH_COVERING_DETECTED}) 232 @Retention(RetentionPolicy.SOURCE) 233 @interface FaceAcquired {} 234 235 /** 236 * The image acquired was good. 237 */ 238 int FACE_ACQUIRED_GOOD = 0; 239 240 /** 241 * The face image was not good enough to process due to a detected condition. 242 * (See {@link #FACE_ACQUIRED_TOO_BRIGHT or @link #FACE_ACQUIRED_TOO_DARK}). 243 */ 244 int FACE_ACQUIRED_INSUFFICIENT = 1; 245 246 /** 247 * The face image was too bright due to too much ambient light. 248 * For example, it's reasonable to return this after multiple 249 * {@link #FACE_ACQUIRED_INSUFFICIENT} 250 * The user is expected to take action to retry in better lighting conditions 251 * when this is returned. 252 */ 253 int FACE_ACQUIRED_TOO_BRIGHT = 2; 254 255 /** 256 * The face image was too dark due to illumination light obscured. 257 * For example, it's reasonable to return this after multiple 258 * {@link #FACE_ACQUIRED_INSUFFICIENT} 259 * The user is expected to take action to retry in better lighting conditions 260 * when this is returned. 261 */ 262 int FACE_ACQUIRED_TOO_DARK = 3; 263 264 /** 265 * The detected face is too close to the sensor, and the image can't be processed. 266 * The user should be informed to move farther from the sensor when this is returned. 267 */ 268 int FACE_ACQUIRED_TOO_CLOSE = 4; 269 270 /** 271 * The detected face is too small, as the user might be too far from the sensor. 272 * The user should be informed to move closer to the sensor when this is returned. 273 */ 274 int FACE_ACQUIRED_TOO_FAR = 5; 275 276 /** 277 * Only the upper part of the face was detected. The sensor field of view is too high. 278 * The user should be informed to move up with respect to the sensor when this is returned. 279 */ 280 int FACE_ACQUIRED_TOO_HIGH = 6; 281 282 /** 283 * Only the lower part of the face was detected. The sensor field of view is too low. 284 * The user should be informed to move down with respect to the sensor when this is returned. 285 */ 286 int FACE_ACQUIRED_TOO_LOW = 7; 287 288 /** 289 * Only the right part of the face was detected. The sensor field of view is too far right. 290 * The user should be informed to move to the right with respect to the sensor 291 * when this is returned. 292 */ 293 int FACE_ACQUIRED_TOO_RIGHT = 8; 294 295 /** 296 * Only the left part of the face was detected. The sensor field of view is too far left. 297 * The user should be informed to move to the left with respect to the sensor 298 * when this is returned. 299 */ 300 int FACE_ACQUIRED_TOO_LEFT = 9; 301 302 /** 303 * The user's eyes have strayed away from the sensor. If this message is sent, the user should 304 * be informed to look at the device. If the user can't be found in the frame, one of the other 305 * acquisition messages should be sent, e.g. FACE_ACQUIRED_NOT_DETECTED. 306 */ 307 int FACE_ACQUIRED_POOR_GAZE = 10; 308 309 /** 310 * No face was detected in front of the sensor. 311 * The user should be informed to point the sensor to a face when this is returned. 312 */ 313 int FACE_ACQUIRED_NOT_DETECTED = 11; 314 315 /** 316 * Too much motion was detected. 317 * The user should be informed to keep their face steady relative to the 318 * sensor. 319 */ 320 int FACE_ACQUIRED_TOO_MUCH_MOTION = 12; 321 322 /** 323 * The sensor needs to be re-calibrated. This is an unexpected condition, and should only be 324 * sent if a serious, uncorrectable, and unrecoverable calibration issue is detected which 325 * requires user intervention, e.g. re-enrolling. The expected response to this message is to 326 * direct the user to re-enroll. 327 */ 328 int FACE_ACQUIRED_RECALIBRATE = 13; 329 330 /** 331 * The face is too different from a previous acquisition. This condition 332 * only applies to enrollment. This can happen if the user passes the 333 * device to someone else in the middle of enrollment. 334 */ 335 int FACE_ACQUIRED_TOO_DIFFERENT = 14; 336 337 /** 338 * The face is too similar to a previous acquisition. This condition only 339 * applies to enrollment. The user should change their pose. 340 */ 341 int FACE_ACQUIRED_TOO_SIMILAR = 15; 342 343 /** 344 * The magnitude of the pan angle of the user’s face with respect to the sensor’s 345 * capture plane is too high. 346 * 347 * The pan angle is defined as the angle swept out by the user’s face turning 348 * their neck left and right. The pan angle would be zero if the user faced the 349 * camera directly. 350 * 351 * The user should be informed to look more directly at the camera. 352 */ 353 int FACE_ACQUIRED_PAN_TOO_EXTREME = 16; 354 355 /** 356 * The magnitude of the tilt angle of the user’s face with respect to the sensor’s 357 * capture plane is too high. 358 * 359 * The tilt angle is defined as the angle swept out by the user’s face looking up 360 * and down. The tilt angle would be zero if the user faced the camera directly. 361 * 362 * The user should be informed to look more directly at the camera. 363 */ 364 int FACE_ACQUIRED_TILT_TOO_EXTREME = 17; 365 366 /** 367 * The magnitude of the roll angle of the user’s face with respect to the sensor’s 368 * capture plane is too high. 369 * 370 * The roll angle is defined as the angle swept out by the user’s face tilting their head 371 * towards their shoulders to the left and right. The roll angle would be zero if the user's 372 * head is vertically aligned with the camera. 373 * 374 * The user should be informed to look more directly at the camera. 375 */ 376 int FACE_ACQUIRED_ROLL_TOO_EXTREME = 18; 377 378 /** 379 * The user’s face has been obscured by some object. 380 * 381 * The user should be informed to remove any objects from the line of sight from 382 * the sensor to the user’s face. 383 */ 384 int FACE_ACQUIRED_FACE_OBSCURED = 19; 385 386 /** 387 * This message represents the earliest message sent at the beginning of the authentication 388 * pipeline. It is expected to be used to measure latency. For example, in a camera-based 389 * authentication system it's expected to be sent prior to camera initialization. Note this 390 * should be sent whenever authentication is restarted (see IBiometricsFace#userActivity). 391 * The framework will measure latency based on the time between the last START message and the 392 * onAuthenticated callback. 393 */ 394 int FACE_ACQUIRED_START = 20; 395 396 /** 397 * The sensor is dirty. The user should be informed to clean the sensor. 398 */ 399 int FACE_ACQUIRED_SENSOR_DIRTY = 21; 400 401 /** 402 * Hardware vendors may extend this list if there are conditions that do not fall under one of 403 * the above categories. Vendors are responsible for providing error strings for these errors. 404 */ 405 int FACE_ACQUIRED_VENDOR = 22; 406 407 /** 408 * Unknown acquired code received from the HAL. 409 */ 410 int FACE_ACQUIRED_UNKNOWN = 23; 411 412 /** 413 * The first frame from the camera has been received. 414 */ 415 int FACE_ACQUIRED_FIRST_FRAME_RECEIVED = 24; 416 417 /** 418 * Dark glasses detected. This can be useful for providing relevant feedback to the user and 419 * enabling an alternative authentication logic if the implementation supports it. 420 */ 421 int FACE_ACQUIRED_DARK_GLASSES_DETECTED = 25; 422 423 /** 424 * A face mask or face covering detected. This can be useful for providing relevant feedback to 425 * the user and enabling an alternative authentication logic if the implementation supports it. 426 */ 427 int FACE_ACQUIRED_MOUTH_COVERING_DETECTED = 26; 428 429 /** 430 * Vendor codes received from the HAL start at 0. Codes that the framework exposes to keyguard 431 * append this value for some reason. We should probably remove this and just send the actual 432 * vendor code. 433 */ 434 int FACE_ACQUIRED_VENDOR_BASE = 1000; 435 } 436