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