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