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 static android.Manifest.permission.TEST_BIOMETRIC; 20 import static android.Manifest.permission.USE_BIOMETRIC; 21 import static android.Manifest.permission.USE_BIOMETRIC_INTERNAL; 22 import static android.Manifest.permission.WRITE_DEVICE_CONFIG; 23 24 import static com.android.internal.util.FrameworkStatsLog.AUTH_DEPRECATED_APIUSED__DEPRECATED_API__API_BIOMETRIC_MANAGER_CAN_AUTHENTICATE; 25 26 import android.annotation.ElapsedRealtimeLong; 27 import android.annotation.FlaggedApi; 28 import android.annotation.IntDef; 29 import android.annotation.NonNull; 30 import android.annotation.Nullable; 31 import android.annotation.RequiresPermission; 32 import android.annotation.SystemApi; 33 import android.annotation.SystemService; 34 import android.annotation.TestApi; 35 import android.app.KeyguardManager; 36 import android.content.Context; 37 import android.os.IBinder; 38 import android.os.RemoteException; 39 import android.os.UserHandle; 40 import android.security.keystore.KeyProperties; 41 import android.util.Slog; 42 43 import com.android.internal.util.FrameworkStatsLog; 44 45 import java.lang.annotation.Retention; 46 import java.lang.annotation.RetentionPolicy; 47 import java.util.ArrayList; 48 import java.util.List; 49 50 /** 51 * A class that contains biometric utilities. For authentication, see {@link BiometricPrompt}. 52 */ 53 @SystemService(Context.BIOMETRIC_SERVICE) 54 public class BiometricManager { 55 56 private static final String TAG = "BiometricManager"; 57 58 /** 59 * No error detected. 60 */ 61 public static final int BIOMETRIC_SUCCESS = 62 BiometricConstants.BIOMETRIC_SUCCESS; 63 64 /** 65 * The hardware is unavailable. Try again later. 66 */ 67 public static final int BIOMETRIC_ERROR_HW_UNAVAILABLE = 68 BiometricConstants.BIOMETRIC_ERROR_HW_UNAVAILABLE; 69 70 /** 71 * The user does not have any biometrics enrolled. 72 */ 73 public static final int BIOMETRIC_ERROR_NONE_ENROLLED = 74 BiometricConstants.BIOMETRIC_ERROR_NO_BIOMETRICS; 75 76 /** 77 * There is no biometric hardware. 78 */ 79 public static final int BIOMETRIC_ERROR_NO_HARDWARE = 80 BiometricConstants.BIOMETRIC_ERROR_HW_NOT_PRESENT; 81 82 /** 83 * A security vulnerability has been discovered and the sensor is unavailable until a 84 * security update has addressed this issue. This error can be received if for example, 85 * authentication was requested with {@link Authenticators#BIOMETRIC_STRONG}, but the 86 * sensor's strength can currently only meet {@link Authenticators#BIOMETRIC_WEAK}. 87 */ 88 public static final int BIOMETRIC_ERROR_SECURITY_UPDATE_REQUIRED = 89 BiometricConstants.BIOMETRIC_ERROR_SECURITY_UPDATE_REQUIRED; 90 91 /** 92 * Returned from {@link BiometricManager#getLastAuthenticationTime(int)} when no matching 93 * successful authentication has been performed since boot. 94 */ 95 @FlaggedApi(Flags.FLAG_LAST_AUTHENTICATION_TIME) 96 public static final long BIOMETRIC_NO_AUTHENTICATION = 97 BiometricConstants.BIOMETRIC_NO_AUTHENTICATION; 98 99 private static final int GET_LAST_AUTH_TIME_ALLOWED_AUTHENTICATORS = 100 Authenticators.DEVICE_CREDENTIAL | Authenticators.BIOMETRIC_STRONG; 101 102 /** 103 * Enroll reason extra that can be used by settings to understand where this request came 104 * from. 105 * @hide 106 */ 107 public static final String EXTRA_ENROLL_REASON = "enroll_reason"; 108 109 /** 110 * @hide 111 */ 112 @IntDef({BIOMETRIC_SUCCESS, 113 BIOMETRIC_ERROR_HW_UNAVAILABLE, 114 BIOMETRIC_ERROR_NONE_ENROLLED, 115 BIOMETRIC_ERROR_NO_HARDWARE, 116 BIOMETRIC_ERROR_SECURITY_UPDATE_REQUIRED}) 117 @Retention(RetentionPolicy.SOURCE) 118 public @interface BiometricError {} 119 120 /** 121 * Types of authenticators, defined at a level of granularity supported by 122 * {@link BiometricManager} and {@link BiometricPrompt}. 123 * 124 * <p>Types may combined via bitwise OR into a single integer representing multiple 125 * authenticators (e.g. <code>DEVICE_CREDENTIAL | BIOMETRIC_WEAK</code>). 126 * 127 * @see #canAuthenticate(int) 128 * @see BiometricPrompt.Builder#setAllowedAuthenticators(int) 129 */ 130 public interface Authenticators { 131 /** 132 * An {@link IntDef} representing valid combinations of authenticator types. 133 * @hide 134 */ 135 @IntDef(flag = true, value = { 136 BIOMETRIC_STRONG, 137 BIOMETRIC_WEAK, 138 BIOMETRIC_CONVENIENCE, 139 DEVICE_CREDENTIAL, 140 }) 141 @Retention(RetentionPolicy.SOURCE) 142 @interface Types {} 143 144 /** 145 * Empty set with no authenticators specified. 146 * 147 * <p>This constant is intended for use by {@link android.provider.DeviceConfig} to adjust 148 * the reported strength of a biometric sensor. It is not a valid parameter for any of the 149 * public {@link android.hardware.biometrics} APIs. 150 * 151 * @hide 152 */ 153 @SystemApi 154 @RequiresPermission(WRITE_DEVICE_CONFIG) 155 int EMPTY_SET = 0x0000; 156 157 /** 158 * Placeholder for the theoretical strongest biometric security tier. 159 * @hide 160 */ 161 int BIOMETRIC_MAX_STRENGTH = 0x0001; 162 163 /** 164 * Any biometric (e.g. fingerprint, iris, or face) on the device that meets or exceeds the 165 * requirements for <strong>Class 3</strong> (formerly <strong>Strong</strong>), as defined 166 * by the Android CDD. 167 * 168 * <p>This corresponds to {@link KeyProperties#AUTH_BIOMETRIC_STRONG} during key generation. 169 * 170 * @see android.security.keystore.KeyGenParameterSpec.Builder 171 */ 172 int BIOMETRIC_STRONG = 0x000F; 173 174 /** 175 * Any biometric (e.g. fingerprint, iris, or face) on the device that meets or exceeds the 176 * requirements for <strong>Class 2</strong> (formerly <strong>Weak</strong>), as defined by 177 * the Android CDD. 178 * 179 * <p>Note that this is a superset of {@link #BIOMETRIC_STRONG} and is defined such that 180 * {@code BIOMETRIC_STRONG | BIOMETRIC_WEAK == BIOMETRIC_WEAK}. 181 */ 182 int BIOMETRIC_WEAK = 0x00FF; 183 184 /** 185 * Any biometric (e.g. fingerprint, iris, or face) on the device that meets or exceeds the 186 * requirements for <strong>Class 1</strong> (formerly <strong>Convenience</strong>), as 187 * defined by the Android CDD. 188 * 189 * <p>This constant is intended for use by {@link android.provider.DeviceConfig} to adjust 190 * the reported strength of a biometric sensor. It is not a valid parameter for any of the 191 * public {@link android.hardware.biometrics} APIs. 192 * 193 * @hide 194 */ 195 @SystemApi 196 @RequiresPermission(WRITE_DEVICE_CONFIG) 197 int BIOMETRIC_CONVENIENCE = 0x0FFF; 198 199 /** 200 * Placeholder for the theoretical weakest biometric security tier. 201 * @hide 202 */ 203 int BIOMETRIC_MIN_STRENGTH = 0x7FFF; 204 205 /** 206 * The non-biometric credential used to secure the device (i.e., PIN, pattern, or password). 207 * This should typically only be used in combination with a biometric auth type, such as 208 * {@link #BIOMETRIC_WEAK}. 209 * 210 * <p>This corresponds to {@link KeyProperties#AUTH_DEVICE_CREDENTIAL} during key 211 * generation. 212 * 213 * @see android.security.keystore.KeyGenParameterSpec.Builder 214 */ 215 int DEVICE_CREDENTIAL = 1 << 15; 216 217 } 218 219 /** 220 * @hide 221 * returns a string representation of an authenticator type. 222 */ authenticatorToStr(@uthenticators.Types int authenticatorType)223 @NonNull public static String authenticatorToStr(@Authenticators.Types int authenticatorType) { 224 switch(authenticatorType) { 225 case Authenticators.BIOMETRIC_STRONG: 226 return "BIOMETRIC_STRONG"; 227 case Authenticators.BIOMETRIC_WEAK: 228 return "BIOMETRIC_WEAK"; 229 case Authenticators.BIOMETRIC_CONVENIENCE: 230 return "BIOMETRIC_CONVENIENCE"; 231 case Authenticators.DEVICE_CREDENTIAL: 232 return "DEVICE_CREDENTIAL"; 233 default: 234 return "Unknown authenticator type: " + authenticatorType; 235 } 236 } 237 238 /** 239 * Provides localized strings for an application that uses {@link BiometricPrompt} to 240 * authenticate the user. 241 */ 242 public static class Strings { 243 @NonNull private final Context mContext; 244 @NonNull private final IAuthService mService; 245 @Authenticators.Types int mAuthenticators; 246 Strings(@onNull Context context, @NonNull IAuthService service, @Authenticators.Types int authenticators)247 private Strings(@NonNull Context context, @NonNull IAuthService service, 248 @Authenticators.Types int authenticators) { 249 mContext = context; 250 mService = service; 251 mAuthenticators = authenticators; 252 } 253 254 /** 255 * Provides a localized string that can be used as the label for a button that invokes 256 * {@link BiometricPrompt}. 257 * 258 * <p>When possible, this method should use the given authenticator requirements to more 259 * precisely specify the authentication type that will be used. For example, if 260 * <strong>Class 3</strong> biometric authentication is requested on a device with a 261 * <strong>Class 3</strong> fingerprint sensor and a <strong>Class 2</strong> face sensor, 262 * the returned string should indicate that fingerprint authentication will be used. 263 * 264 * <p>This method should also try to specify which authentication method(s) will be used in 265 * practice when multiple authenticators meet the given requirements. For example, if 266 * biometric authentication is requested on a device with both face and fingerprint sensors 267 * but the user has selected face as their preferred method, the returned string should 268 * indicate that face authentication will be used. 269 * 270 * <p>This method may return {@code null} if none of the requested authenticator types are 271 * available, but this should <em>not</em> be relied upon for checking the status of 272 * authenticators. Instead, use {@link #canAuthenticate(int)}. 273 * 274 * @return The label for a button that invokes {@link BiometricPrompt} for authentication. 275 */ 276 @RequiresPermission(USE_BIOMETRIC) 277 @Nullable getButtonLabel()278 public CharSequence getButtonLabel() { 279 final int userId = mContext.getUserId(); 280 final String opPackageName = mContext.getOpPackageName(); 281 try { 282 return mService.getButtonLabel(userId, opPackageName, mAuthenticators); 283 } catch (RemoteException e) { 284 throw e.rethrowFromSystemServer(); 285 } 286 } 287 288 /** 289 * Provides a localized string that can be shown while the user is authenticating with 290 * {@link BiometricPrompt}. 291 * 292 * <p>When possible, this method should use the given authenticator requirements to more 293 * precisely specify the authentication type that will be used. For example, if 294 * <strong>Class 3</strong> biometric authentication is requested on a device with a 295 * <strong>Class 3</strong> fingerprint sensor and a <strong>Class 2</strong> face sensor, 296 * the returned string should indicate that fingerprint authentication will be used. 297 * 298 * <p>This method should also try to specify which authentication method(s) will be used in 299 * practice when multiple authenticators meet the given requirements. For example, if 300 * biometric authentication is requested on a device with both face and fingerprint sensors 301 * but the user has selected face as their preferred method, the returned string should 302 * indicate that face authentication will be used. 303 * 304 * <p>This method may return {@code null} if none of the requested authenticator types are 305 * available, but this should <em>not</em> be relied upon for checking the status of 306 * authenticators. Instead, use {@link #canAuthenticate(int)}. 307 * 308 * @return The label for a button that invokes {@link BiometricPrompt} for authentication. 309 */ 310 @RequiresPermission(USE_BIOMETRIC) 311 @Nullable getPromptMessage()312 public CharSequence getPromptMessage() { 313 final int userId = mContext.getUserId(); 314 final String opPackageName = mContext.getOpPackageName(); 315 try { 316 return mService.getPromptMessage(userId, opPackageName, mAuthenticators); 317 } catch (RemoteException e) { 318 throw e.rethrowFromSystemServer(); 319 } 320 } 321 322 /** 323 * Provides a localized string that can be shown as the title for an app setting that 324 * enables authentication with {@link BiometricPrompt}. 325 * 326 * <p>When possible, this method should use the given authenticator requirements to more 327 * precisely specify the authentication type that will be used. For example, if 328 * <strong>Class 3</strong> biometric authentication is requested on a device with a 329 * <strong>Class 3</strong> fingerprint sensor and a <strong>Class 2</strong> face sensor, 330 * the returned string should indicate that fingerprint authentication will be used. 331 * 332 * <p>This method should <em>not</em> try to specify which authentication method(s) will be 333 * used in practice when multiple authenticators meet the given requirements. For example, 334 * if biometric authentication is requested on a device with both face and fingerprint 335 * sensors, the returned string should indicate that either face or fingerprint 336 * authentication may be used, regardless of whether the user has enrolled or selected 337 * either as their preferred method. 338 * 339 * <p>This method may return {@code null} if none of the requested authenticator types are 340 * supported by the system, but this should <em>not</em> be relied upon for checking the 341 * status of authenticators. Instead, use {@link #canAuthenticate(int)} or 342 * {@link android.content.pm.PackageManager#hasSystemFeature(String)}. 343 * 344 * @return The label for a button that invokes {@link BiometricPrompt} for authentication. 345 */ 346 @RequiresPermission(USE_BIOMETRIC) 347 @Nullable getSettingName()348 public CharSequence getSettingName() { 349 final int userId = mContext.getUserId(); 350 final String opPackageName = mContext.getOpPackageName(); 351 try { 352 return mService.getSettingName(userId, opPackageName, mAuthenticators); 353 } catch (RemoteException e) { 354 throw e.rethrowFromSystemServer(); 355 } 356 } 357 } 358 359 @NonNull private final Context mContext; 360 @NonNull private final IAuthService mService; 361 362 /** 363 * @hide 364 * @param context 365 * @param service 366 */ BiometricManager(@onNull Context context, @NonNull IAuthService service)367 public BiometricManager(@NonNull Context context, @NonNull IAuthService service) { 368 mContext = context; 369 mService = service; 370 } 371 372 /** 373 * @return A list of {@link SensorProperties} 374 * @hide 375 */ 376 @TestApi 377 @NonNull 378 @RequiresPermission(TEST_BIOMETRIC) getSensorProperties()379 public List<SensorProperties> getSensorProperties() { 380 try { 381 final List<SensorPropertiesInternal> internalProperties = 382 mService.getSensorProperties(mContext.getOpPackageName()); 383 final List<SensorProperties> properties = new ArrayList<>(); 384 for (SensorPropertiesInternal internalProp : internalProperties) { 385 properties.add(SensorProperties.from(internalProp)); 386 } 387 return properties; 388 } catch (RemoteException e) { 389 throw e.rethrowFromSystemServer(); 390 } 391 } 392 393 /** 394 * Retrieves a test session for BiometricManager/BiometricPrompt. 395 * @hide 396 */ 397 @TestApi 398 @NonNull 399 @RequiresPermission(TEST_BIOMETRIC) createTestSession(int sensorId)400 public BiometricTestSession createTestSession(int sensorId) { 401 try { 402 return new BiometricTestSession(mContext, sensorId, 403 (context, sensorId1, callback) -> mService 404 .createTestSession(sensorId1, callback, context.getOpPackageName())); 405 } catch (RemoteException e) { 406 throw e.rethrowFromSystemServer(); 407 } 408 } 409 410 /** 411 * Retrieves the package where BiometricPrompt's UI is implemented. 412 * @hide 413 */ 414 @TestApi 415 @NonNull 416 @RequiresPermission(TEST_BIOMETRIC) getUiPackage()417 public String getUiPackage() { 418 try { 419 return mService.getUiPackage(); 420 } catch (RemoteException e) { 421 throw e.rethrowFromSystemServer(); 422 } 423 } 424 425 /** 426 * Determine if biometrics can be used. In other words, determine if 427 * {@link BiometricPrompt} can be expected to be shown (hardware available, templates enrolled, 428 * user-enabled). This is the equivalent of {@link #canAuthenticate(int)} with 429 * {@link Authenticators#BIOMETRIC_WEAK} 430 * 431 * @return {@link #BIOMETRIC_ERROR_NONE_ENROLLED} if the user does not have any strong 432 * biometrics enrolled, or {@link #BIOMETRIC_ERROR_HW_UNAVAILABLE} if none are currently 433 * supported/enabled. Returns {@link #BIOMETRIC_SUCCESS} if a strong biometric can currently 434 * be used (enrolled and available). 435 * 436 * @deprecated See {@link #canAuthenticate(int)}. 437 */ 438 @Deprecated 439 @RequiresPermission(USE_BIOMETRIC) 440 @BiometricError canAuthenticate()441 public int canAuthenticate() { 442 @BiometricError final int result = canAuthenticate(mContext.getUserId(), 443 Authenticators.BIOMETRIC_WEAK); 444 445 FrameworkStatsLog.write(FrameworkStatsLog.AUTH_MANAGER_CAN_AUTHENTICATE_INVOKED, 446 false /* isAllowedAuthenticatorsSet */, Authenticators.EMPTY_SET, result); 447 FrameworkStatsLog.write(FrameworkStatsLog.AUTH_DEPRECATED_API_USED, 448 AUTH_DEPRECATED_APIUSED__DEPRECATED_API__API_BIOMETRIC_MANAGER_CAN_AUTHENTICATE, 449 mContext.getApplicationInfo().uid, 450 mContext.getApplicationInfo().targetSdkVersion); 451 452 return result; 453 } 454 455 /** 456 * Determine if any of the provided authenticators can be used. In other words, determine if 457 * {@link BiometricPrompt} can be expected to be shown (hardware available, templates enrolled, 458 * user-enabled). 459 * 460 * For biometric authenticators, determine if the device can currently authenticate with at 461 * least the requested strength. For example, invoking this API with 462 * {@link Authenticators#BIOMETRIC_WEAK} on a device that currently only has 463 * {@link Authenticators#BIOMETRIC_STRONG} enrolled will return {@link #BIOMETRIC_SUCCESS}. 464 * 465 * Invoking this API with {@link Authenticators#DEVICE_CREDENTIAL} can be used to determine 466 * if the user has a PIN/Pattern/Password set up. 467 * 468 * @param authenticators bit field consisting of constants defined in {@link Authenticators}. 469 * If multiple authenticators are queried, a logical OR will be applied. 470 * For example, if {@link Authenticators#DEVICE_CREDENTIAL} | 471 * {@link Authenticators#BIOMETRIC_STRONG} is queried and only 472 * {@link Authenticators#DEVICE_CREDENTIAL} is set up, this API will 473 * return {@link #BIOMETRIC_SUCCESS} 474 * 475 * @return {@link #BIOMETRIC_ERROR_NONE_ENROLLED} if the user does not have any of the 476 * requested authenticators enrolled, or {@link #BIOMETRIC_ERROR_HW_UNAVAILABLE} if none are 477 * currently supported/enabled. Returns {@link #BIOMETRIC_SUCCESS} if one of the requested 478 * authenticators can currently be used (enrolled and available). 479 */ 480 @RequiresPermission(USE_BIOMETRIC) 481 @BiometricError canAuthenticate(@uthenticators.Types int authenticators)482 public int canAuthenticate(@Authenticators.Types int authenticators) { 483 @BiometricError final int result = canAuthenticate(mContext.getUserId(), authenticators); 484 485 FrameworkStatsLog.write(FrameworkStatsLog.AUTH_MANAGER_CAN_AUTHENTICATE_INVOKED, 486 true /* isAllowedAuthenticatorsSet */, authenticators, result); 487 488 return result; 489 } 490 491 /** 492 * @hide 493 */ 494 @RequiresPermission(USE_BIOMETRIC_INTERNAL) 495 @BiometricError canAuthenticate(int userId, @Authenticators.Types int authenticators)496 public int canAuthenticate(int userId, @Authenticators.Types int authenticators) { 497 if (mService != null) { 498 try { 499 final String opPackageName = mContext.getOpPackageName(); 500 return mService.canAuthenticate(opPackageName, userId, authenticators); 501 } catch (RemoteException e) { 502 throw e.rethrowFromSystemServer(); 503 } 504 } else { 505 Slog.w(TAG, "canAuthenticate(): Service not connected"); 506 return BIOMETRIC_ERROR_HW_UNAVAILABLE; 507 } 508 } 509 510 /** 511 * Produces an instance of the {@link Strings} class, which provides localized strings for an 512 * application, given a set of allowed authenticator types. 513 * 514 * @param authenticators A bit field representing the types of {@link Authenticators} that may 515 * be used for authentication. 516 * @return A {@link Strings} collection for the given allowed authenticator types. 517 */ 518 @RequiresPermission(USE_BIOMETRIC) 519 @NonNull getStrings(@uthenticators.Types int authenticators)520 public Strings getStrings(@Authenticators.Types int authenticators) { 521 return new Strings(mContext, mService, authenticators); 522 } 523 524 /** 525 * @hide 526 * @param userId 527 * @return 528 */ 529 @RequiresPermission(USE_BIOMETRIC_INTERNAL) hasEnrolledBiometrics(int userId)530 public boolean hasEnrolledBiometrics(int userId) { 531 if (mService != null) { 532 try { 533 return mService.hasEnrolledBiometrics(userId, mContext.getOpPackageName()); 534 } catch (RemoteException e) { 535 Slog.w(TAG, "Remote exception in hasEnrolledBiometrics(): " + e); 536 return false; 537 } 538 } else { 539 return false; 540 } 541 } 542 543 /** 544 * Listens for changes to biometric eligibility on keyguard from user settings. 545 * @param callback 546 * @hide 547 */ 548 @RequiresPermission(USE_BIOMETRIC_INTERNAL) registerEnabledOnKeyguardCallback(IBiometricEnabledOnKeyguardCallback callback)549 public void registerEnabledOnKeyguardCallback(IBiometricEnabledOnKeyguardCallback callback) { 550 if (mService != null) { 551 try { 552 mService.registerEnabledOnKeyguardCallback(callback); 553 } catch (RemoteException e) { 554 throw e.rethrowFromSystemServer(); 555 } 556 } else { 557 Slog.w(TAG, "registerEnabledOnKeyguardCallback(): Service not connected"); 558 } 559 } 560 561 /** 562 * Registers listener for changes to biometric authentication state. 563 * Only sends callbacks for events that occur after the callback has been registered. 564 * @param listener Listener for changes to biometric authentication state 565 * @hide 566 */ 567 @RequiresPermission(USE_BIOMETRIC_INTERNAL) registerAuthenticationStateListener(AuthenticationStateListener listener)568 public void registerAuthenticationStateListener(AuthenticationStateListener listener) { 569 if (mService != null) { 570 try { 571 mService.registerAuthenticationStateListener(listener); 572 } catch (RemoteException e) { 573 throw e.rethrowFromSystemServer(); 574 } 575 } else { 576 Slog.w(TAG, "registerAuthenticationStateListener(): Service not connected"); 577 } 578 } 579 580 /** 581 * Unregisters listener for changes to biometric authentication state. 582 * @param listener Listener for changes to biometric authentication state 583 * @hide 584 */ 585 @RequiresPermission(USE_BIOMETRIC_INTERNAL) unregisterAuthenticationStateListener(AuthenticationStateListener listener)586 public void unregisterAuthenticationStateListener(AuthenticationStateListener listener) { 587 if (mService != null) { 588 try { 589 mService.unregisterAuthenticationStateListener(listener); 590 } catch (RemoteException e) { 591 throw e.rethrowFromSystemServer(); 592 } 593 } else { 594 Slog.w(TAG, "unregisterAuthenticationStateListener(): Service not connected"); 595 } 596 } 597 598 599 /** 600 * Requests all {@link Authenticators.Types#BIOMETRIC_STRONG} sensors to have their 601 * authenticatorId invalidated for the specified user. This happens when enrollments have been 602 * added on devices with multiple biometric sensors. 603 * 604 * @param userId userId that the authenticatorId should be invalidated for 605 * @param fromSensorId sensor that triggered the invalidation request 606 * @hide 607 */ 608 @RequiresPermission(USE_BIOMETRIC_INTERNAL) invalidateAuthenticatorIds(int userId, int fromSensorId, @NonNull IInvalidationCallback callback)609 public void invalidateAuthenticatorIds(int userId, int fromSensorId, 610 @NonNull IInvalidationCallback callback) { 611 if (mService != null) { 612 try { 613 mService.invalidateAuthenticatorIds(userId, fromSensorId, callback); 614 } catch (RemoteException e) { 615 throw e.rethrowFromSystemServer(); 616 } 617 } 618 } 619 620 /** 621 * Get a list of AuthenticatorIDs for biometric authenticators which have 1) enrolled templates, 622 * and 2) meet the requirements for integrating with Keystore. The AuthenticatorIDs are known 623 * in Keystore land as SIDs, and are used during key generation. 624 * @hide 625 */ getAuthenticatorIds()626 public long[] getAuthenticatorIds() { 627 return getAuthenticatorIds(UserHandle.myUserId()); 628 } 629 630 /** 631 * Get a list of AuthenticatorIDs for biometric authenticators which have 1) enrolled templates, 632 * and 2) meet the requirements for integrating with Keystore. The AuthenticatorIDs are known 633 * in Keystore land as SIDs, and are used during key generation. 634 * 635 * @param userId Android user ID for user to look up. 636 * 637 * @hide 638 */ getAuthenticatorIds(int userId)639 public long[] getAuthenticatorIds(int userId) { 640 if (mService != null) { 641 try { 642 return mService.getAuthenticatorIds(userId); 643 } catch (RemoteException e) { 644 throw e.rethrowFromSystemServer(); 645 } 646 } else { 647 Slog.w(TAG, "getAuthenticatorIds(): Service not connected"); 648 return new long[0]; 649 } 650 } 651 652 /** 653 * Requests all other biometric sensors to resetLockout. Note that this is a "time bound" 654 * See the {@link android.hardware.biometrics.fingerprint.ISession#resetLockout(int, 655 * HardwareAuthToken)} and {@link android.hardware.biometrics.face.ISession#resetLockout(int, 656 * HardwareAuthToken)} documentation for complete details. 657 * 658 * @param token A binder from the caller, for the service to linkToDeath 659 * @param opPackageName Caller's package name 660 * @param fromSensorId The originating sensor that just authenticated. Note that this MUST 661 * be a sensor that meets {@link Authenticators#BIOMETRIC_STRONG} strength. 662 * The strength will also be enforced on the BiometricService side. 663 * @param userId The user that authentication succeeded for, and also the user that resetLockout 664 * should be applied to. 665 * @param hardwareAuthToken A valid HAT generated upon successful biometric authentication. Note 666 * that it is not necessary for the HAT to contain a challenge. 667 * @hide 668 */ 669 @RequiresPermission(USE_BIOMETRIC_INTERNAL) resetLockoutTimeBound(IBinder token, String opPackageName, int fromSensorId, int userId, byte[] hardwareAuthToken)670 public void resetLockoutTimeBound(IBinder token, String opPackageName, int fromSensorId, 671 int userId, byte[] hardwareAuthToken) { 672 if (mService != null) { 673 try { 674 mService.resetLockoutTimeBound(token, opPackageName, fromSensorId, userId, 675 hardwareAuthToken); 676 } catch (RemoteException e) { 677 throw e.rethrowFromSystemServer(); 678 } 679 } 680 } 681 682 /** 683 * Notifies AuthService that keyguard has been dismissed for the given userId. 684 * 685 * @param userId 686 * @param hardwareAuthToken 687 * @hide 688 */ 689 @RequiresPermission(USE_BIOMETRIC_INTERNAL) resetLockout(int userId, byte[] hardwareAuthToken)690 public void resetLockout(int userId, byte[] hardwareAuthToken) { 691 if (mService != null) { 692 try { 693 mService.resetLockout(userId, hardwareAuthToken); 694 } catch (RemoteException e) { 695 throw e.rethrowFromSystemServer(); 696 } 697 } 698 699 } 700 701 /** 702 * Gets the last time the user successfully authenticated using one of the given authenticators. 703 * The returned value is time in 704 * {@link android.os.SystemClock#elapsedRealtime SystemClock.elapsedRealtime()} (time since 705 * boot, including sleep). 706 * <p> 707 * {@link BiometricManager#BIOMETRIC_NO_AUTHENTICATION} is returned in the case where there 708 * has been no successful authentication using any of the given authenticators since boot. 709 * <p> 710 * Currently, only {@link Authenticators#DEVICE_CREDENTIAL} and 711 * {@link Authenticators#BIOMETRIC_STRONG} are accepted. {@link IllegalArgumentException} will 712 * be thrown if {@code authenticators} contains other authenticator types. 713 * <p> 714 * Note that this may return successful authentication times even if the device is currently 715 * locked. You may use {@link KeyguardManager#isDeviceLocked()} to determine if the device 716 * is unlocked or not. Additionally, this method may return valid times for an authentication 717 * method that is no longer available. For instance, if the user unlocked the device with a 718 * {@link Authenticators#BIOMETRIC_STRONG} authenticator but then deleted that authenticator 719 * (e.g., fingerprint data), this method will still return the time of that unlock for 720 * {@link Authenticators#BIOMETRIC_STRONG} if it is the most recent successful event. The caveat 721 * is that {@link BiometricManager#BIOMETRIC_NO_AUTHENTICATION} will be returned if the device 722 * no longer has a secure lock screen at all, even if there were successful authentications 723 * performed before the lock screen was made insecure. 724 * 725 * @param authenticators bit field consisting of constants defined in {@link Authenticators}. 726 * @return the time of last authentication or 727 * {@link BiometricManager#BIOMETRIC_NO_AUTHENTICATION} 728 * @throws IllegalArgumentException if {@code authenticators} contains values other than 729 * {@link Authenticators#DEVICE_CREDENTIAL} and {@link Authenticators#BIOMETRIC_STRONG} or is 730 * 0. 731 */ 732 @RequiresPermission(USE_BIOMETRIC) 733 @ElapsedRealtimeLong 734 @FlaggedApi(Flags.FLAG_LAST_AUTHENTICATION_TIME) getLastAuthenticationTime( @iometricManager.Authenticators.Types int authenticators)735 public long getLastAuthenticationTime( 736 @BiometricManager.Authenticators.Types int authenticators) { 737 if (authenticators == 0 738 || (GET_LAST_AUTH_TIME_ALLOWED_AUTHENTICATORS & authenticators) != authenticators) { 739 throw new IllegalArgumentException( 740 "Only BIOMETRIC_STRONG and DEVICE_CREDENTIAL authenticators may be used."); 741 } 742 743 if (mService != null) { 744 try { 745 return mService.getLastAuthenticationTime(UserHandle.myUserId(), authenticators); 746 } catch (RemoteException e) { 747 throw e.rethrowFromSystemServer(); 748 } 749 } else { 750 return BIOMETRIC_NO_AUTHENTICATION; 751 } 752 } 753 } 754 755