1/* 2 * Copyright (c) 2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16import type { AsyncCallback } from './@ohos.base'; 17 18/** 19 * User authentication 20 * 21 * @namespace userAuth 22 * @syscap SystemCapability.UserIAM.UserAuth.Core 23 * @since 6 24 */ 25declare namespace userAuth { 26 /** 27 * Enum for authentication result. 28 * 29 * @enum { number } 30 * @syscap SystemCapability.UserIAM.UserAuth.Core 31 * @since 6 32 * @deprecated since 8 33 * @useinstead ohos.userIAM.userAuth.ResultCode 34 */ 35 export enum AuthenticationResult { 36 /** 37 * Indicates that the device does not support authentication. 38 * 39 * @syscap SystemCapability.UserIAM.UserAuth.Core 40 * @since 6 41 * @deprecated since 8 42 */ 43 NO_SUPPORT = -1, 44 45 /** 46 * Indicates that authentication is success. 47 * 48 * @syscap SystemCapability.UserIAM.UserAuth.Core 49 * @since 6 50 * @deprecated since 8 51 */ 52 SUCCESS = 0, 53 54 /** 55 * Indicates the authenticator fails to identify user. 56 * 57 * @syscap SystemCapability.UserIAM.UserAuth.Core 58 * @since 6 59 * @deprecated since 8 60 */ 61 COMPARE_FAILURE = 1, 62 63 /** 64 * Indicates that authentication has been canceled. 65 * 66 * @syscap SystemCapability.UserIAM.UserAuth.Core 67 * @since 6 68 * @deprecated since 8 69 */ 70 CANCELED = 2, 71 72 /** 73 * Indicates that authentication has timed out. 74 * 75 * @syscap SystemCapability.UserIAM.UserAuth.Core 76 * @since 6 77 * @deprecated since 8 78 */ 79 TIMEOUT = 3, 80 81 /** 82 * Indicates a failure to open the camera. 83 * 84 * @syscap SystemCapability.UserIAM.UserAuth.Core 85 * @since 6 86 * @deprecated since 8 87 */ 88 CAMERA_FAIL = 4, 89 90 /** 91 * Indicates that the authentication task is busy. Wait for a few seconds and try again. 92 * 93 * @syscap SystemCapability.UserIAM.UserAuth.Core 94 * @since 6 95 * @deprecated since 8 96 */ 97 BUSY = 5, 98 99 /** 100 * Indicates incorrect parameters. 101 * 102 * @syscap SystemCapability.UserIAM.UserAuth.Core 103 * @since 6 104 * @deprecated since 8 105 */ 106 INVALID_PARAMETERS = 6, 107 108 /** 109 * Indicates that the authenticator is locked. 110 * 111 * @syscap SystemCapability.UserIAM.UserAuth.Core 112 * @since 6 113 * @deprecated since 8 114 */ 115 LOCKED = 7, 116 117 /** 118 * Indicates that the user has not enrolled the authenticator. 119 * 120 * @syscap SystemCapability.UserIAM.UserAuth.Core 121 * @since 6 122 * @deprecated since 8 123 */ 124 NOT_ENROLLED = 8, 125 126 /** 127 * Indicates other errors. 128 * 129 * @syscap SystemCapability.UserIAM.UserAuth.Core 130 * @since 6 131 * @deprecated since 8 132 */ 133 GENERAL_ERROR = 100 134 } 135 136 /** 137 * Auth types 138 * 139 * @syscap SystemCapability.UserIAM.UserAuth.Core 140 * @since 6 141 * @deprecated since 8 142 */ 143 type AuthType = 'ALL' | 'FACE_ONLY'; 144 145 /** 146 * Secure levels 147 * 148 * @syscap SystemCapability.UserIAM.UserAuth.Core 149 * @since 6 150 * @deprecated since 8 151 */ 152 type SecureLevel = 'S1' | 'S2' | 'S3' | 'S4'; 153 154 /** 155 * Used to initiate authentication. 156 * 157 * @interface Authenticator 158 * @syscap SystemCapability.UserIAM.UserAuth.Core 159 * @since 6 160 * @deprecated since 8 161 */ 162 interface Authenticator { 163 /** 164 * Execute authentication. 165 * 166 * @permission ohos.permission.ACCESS_BIOMETRIC 167 * @param { AuthType } type - Indicates the authentication type. 168 * @param { SecureLevel } level - Indicates the security level. 169 * @param { AsyncCallback<number> } callback - Async callback of execute. 170 * @syscap SystemCapability.UserIAM.UserAuth.Core 171 * @since 6 172 * @deprecated since 8 173 */ 174 execute(type: AuthType, level: SecureLevel, callback: AsyncCallback<number>): void; 175 176 /** 177 * Execute authentication. 178 * 179 * @permission ohos.permission.ACCESS_BIOMETRIC 180 * @param { AuthType } type - Indicates the authentication type. 181 * @param { SecureLevel } level - Indicates the security level. 182 * @returns { Promise<number> } 183 * @syscap SystemCapability.UserIAM.UserAuth.Core 184 * @since 6 185 * @deprecated since 8 186 */ 187 execute(type: AuthType, level: SecureLevel): Promise<number>; 188 } 189 190 /** 191 * Get Authenticator instance. 192 * 193 * @returns { Authenticator } Returns an Authenticator. 194 * @syscap SystemCapability.UserIAM.UserAuth.Core 195 * @since 6 196 * @deprecated since 8 197 */ 198 function getAuthenticator(): Authenticator; 199 200 /** 201 * User authentication. 202 * 203 * @syscap SystemCapability.UserIAM.UserAuth.Core 204 * @since 8 205 * @deprecated since 9 206 * @useinstead ohos.userIAM.userAuth.AuthInstance 207 */ 208 class UserAuth { 209 /** 210 * Constructor to get the UserAuth class instance. 211 * 212 * @syscap SystemCapability.UserIAM.UserAuth.Core 213 * @since 8 214 * @deprecated since 9 215 * @useinstead ohos.userIAM.userAuth.getAuthInstance 216 */ 217 constructor(); 218 219 /** 220 * Get version information. 221 * 222 * @permission ohos.permission.ACCESS_BIOMETRIC 223 * @returns { number } Returns version information. 224 * @syscap SystemCapability.UserIAM.UserAuth.Core 225 * @since 8 226 * @deprecated since 9 227 * @useinstead ohos.userIAM.userAuth.getVersion 228 */ 229 getVersion(): number; 230 231 /** 232 * Check whether the authentication capability is available. 233 * 234 * @permission ohos.permission.ACCESS_BIOMETRIC 235 * @param { UserAuthType } authType - Credential type for authentication. 236 * @param { AuthTrustLevel } authTrustLevel - Trust level of authentication result. 237 * @returns { number } Returns a check result, which is specified by getAvailableStatus, the value of number is related to the ResultCode enum, **201** is 238 * check permission failed. 239 * @syscap SystemCapability.UserIAM.UserAuth.Core 240 * @since 8 241 * @deprecated since 9 242 * @useinstead ohos.userIAM.userAuth.getAvailableStatus 243 */ 244 getAvailableStatus(authType: UserAuthType, authTrustLevel: AuthTrustLevel): number; 245 246 /** 247 * Executes authentication. 248 * 249 * @permission ohos.permission.ACCESS_BIOMETRIC 250 * @param { Uint8Array } challenge - Pass in challenge value. 251 * @param { UserAuthType } authType - Type of authentication. 252 * @param { AuthTrustLevel } authTrustLevel - Trust level of authentication result. 253 * @param { IUserAuthCallback } callback - Return result and acquireInfo through callback, the value of result code is related to the ResultCode enum, 254 * **201** is check permission failed. 255 * @returns { Uint8Array } Returns ContextId for cancel. 256 * @syscap SystemCapability.UserIAM.UserAuth.Core 257 * @since 8 258 * @deprecated since 9 259 * @useinstead ohos.userIAM.userAuth.AuthInstance.start 260 */ 261 auth( 262 challenge: Uint8Array, 263 authType: UserAuthType, 264 authTrustLevel: AuthTrustLevel, 265 callback: IUserAuthCallback 266 ): Uint8Array; 267 268 /** 269 * Cancel authentication with ContextID. 270 * 271 * @permission ohos.permission.ACCESS_BIOMETRIC 272 * @param { Uint8Array } contextID - Cancel authentication and pass in ContextID. 273 * @returns { number } Returns a number value indicating whether Cancel authentication was successful, the value of number is related to the ResultCode 274 * enum, **201** is check permission failed. 275 * @syscap SystemCapability.UserIAM.UserAuth.Core 276 * @since 8 277 * @deprecated since 9 278 * @useinstead ohos.userIAM.userAuth.AuthInstance.cancel 279 */ 280 cancelAuth(contextID: Uint8Array): number; 281 } 282 283 /** 284 * Asynchronous callback of authentication operation. 285 * 286 * @interface IUserAuthCallback 287 * @syscap SystemCapability.UserIAM.UserAuth.Core 288 * @since 8 289 * @deprecated since 9 290 * @useinstead ohos.userIAM.userAuth.AuthEvent 291 */ 292 interface IUserAuthCallback { 293 /** 294 * The authentication result code is returned through the callback. 295 * If the authentication is passed, the authentication token is returned in extraInfo, 296 * If the authentication fails, the remaining authentication times are returned in extraInfo, 297 * If the authentication executor is locked, the freezing time is returned in extraInfo. 298 * 299 * @syscap SystemCapability.UserIAM.UserAuth.Core 300 * @since 8 301 * @deprecated since 9 302 * @useinstead ohos.userIAM.userAuth.AuthEvent.callback 303 */ 304 onResult: (result: number, extraInfo: AuthResult) => void; 305 306 /** 307 * During an authentication, the TipsCode is returned through the callback. 308 * 309 * @syscap SystemCapability.UserIAM.UserAuth.Core 310 * @since 8 311 * @deprecated since 9 312 * @useinstead ohos.userIAM.userAuth.AuthEvent.callback 313 */ 314 onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; 315 } 316 317 /** 318 * Authentication result: authentication token, remaining authentication times, freezing time. 319 * 320 * @typedef AuthResult 321 * @syscap SystemCapability.UserIAM.UserAuth.Core 322 * @since 8 323 * @deprecated since 9 324 * @useinstead ohos.userIAM.userAuth.AuthResultInfo 325 */ 326 interface AuthResult { 327 /** 328 * The authentication result if the authentication is passed. 329 * 330 * @type { ?Uint8Array } 331 * @syscap SystemCapability.UserIAM.UserAuth.Core 332 * @since 8 333 * @deprecated since 9 334 */ 335 token?: Uint8Array; 336 337 /** 338 * The remaining authentication times if the authentication fails. 339 * 340 * @type { ?number } 341 * @syscap SystemCapability.UserIAM.UserAuth.Core 342 * @since 8 343 * @deprecated since 9 344 */ 345 remainTimes?: number; 346 347 /** 348 * The freezing time if the authentication executor is locked. 349 * 350 * @type { ?number } 351 * @syscap SystemCapability.UserIAM.UserAuth.Core 352 * @since 8 353 * @deprecated since 9 354 */ 355 freezingTime?: number; 356 } 357 358 /** 359 * Enum for operation result. 360 * 361 * @enum { number } 362 * @syscap SystemCapability.UserIAM.UserAuth.Core 363 * @since 8 364 * @deprecated since 9 365 * @useinstead ohos.userIAM.userAuth.UserAuthResultCode 366 */ 367 enum ResultCode { 368 /** 369 * Indicates that the result is success or ability is supported. 370 * 371 * @syscap SystemCapability.UserIAM.UserAuth.Core 372 * @since 8 373 * @deprecated since 9 374 */ 375 SUCCESS = 0, 376 377 /** 378 * Indicates that authentication failed. 379 * 380 * @syscap SystemCapability.UserIAM.UserAuth.Core 381 * @since 8 382 * @deprecated since 9 383 */ 384 FAIL = 1, 385 386 /** 387 * Indicates other errors. 388 * 389 * @syscap SystemCapability.UserIAM.UserAuth.Core 390 * @since 8 391 * @deprecated since 9 392 */ 393 GENERAL_ERROR = 2, 394 395 /** 396 * Indicates that this operation has been canceled. 397 * 398 * @syscap SystemCapability.UserIAM.UserAuth.Core 399 * @since 8 400 * @deprecated since 9 401 */ 402 CANCELED = 3, 403 404 /** 405 * Indicates that this operation has timed out. 406 * 407 * @syscap SystemCapability.UserIAM.UserAuth.Core 408 * @since 8 409 * @deprecated since 9 410 */ 411 TIMEOUT = 4, 412 413 /** 414 * Indicates that this authentication type is not supported. 415 * 416 * @syscap SystemCapability.UserIAM.UserAuth.Core 417 * @since 8 418 * @deprecated since 9 419 */ 420 TYPE_NOT_SUPPORT = 5, 421 422 /** 423 * Indicates that the authentication trust level is not supported. 424 * 425 * @syscap SystemCapability.UserIAM.UserAuth.Core 426 * @since 8 427 * @deprecated since 9 428 */ 429 TRUST_LEVEL_NOT_SUPPORT = 6, 430 431 /** 432 * Indicates that the authentication task is busy. Wait for a few seconds and try again. 433 * 434 * @syscap SystemCapability.UserIAM.UserAuth.Core 435 * @since 8 436 * @deprecated since 9 437 */ 438 BUSY = 7, 439 440 /** 441 * Indicates incorrect parameters. 442 * 443 * @syscap SystemCapability.UserIAM.UserAuth.Core 444 * @since 8 445 * @deprecated since 9 446 */ 447 INVALID_PARAMETERS = 8, 448 449 /** 450 * Indicates that the authenticator is locked. 451 * 452 * @syscap SystemCapability.UserIAM.UserAuth.Core 453 * @since 8 454 * @deprecated since 9 455 */ 456 LOCKED = 9, 457 458 /** 459 * Indicates that the user has not enrolled the authenticator. 460 * 461 * @syscap SystemCapability.UserIAM.UserAuth.Core 462 * @since 8 463 * @deprecated since 9 464 */ 465 NOT_ENROLLED = 10 466 } 467 468 /** 469 * The enumeration of prompt codes in the process of face authentication. 470 * 471 * @enum { number } 472 * @syscap SystemCapability.UserIAM.UserAuth.Core 473 * @since 8 474 */ 475 enum FaceTips { 476 /** 477 * Indicates that the obtained facial image is too bright due to high illumination. 478 * 479 * @syscap SystemCapability.UserIAM.UserAuth.Core 480 * @since 8 481 */ 482 FACE_AUTH_TIP_TOO_BRIGHT = 1, 483 484 /** 485 * Indicates that the obtained facial image is too dark due to low illumination. 486 * 487 * @syscap SystemCapability.UserIAM.UserAuth.Core 488 * @since 8 489 */ 490 FACE_AUTH_TIP_TOO_DARK = 2, 491 492 /** 493 * Indicates that the face is too close to the device. 494 * 495 * @syscap SystemCapability.UserIAM.UserAuth.Core 496 * @since 8 497 */ 498 FACE_AUTH_TIP_TOO_CLOSE = 3, 499 500 /** 501 * Indicates that the face is too far away from the device. 502 * 503 * @syscap SystemCapability.UserIAM.UserAuth.Core 504 * @since 8 505 */ 506 FACE_AUTH_TIP_TOO_FAR = 4, 507 508 /** 509 * Indicates that the device is too high, and that only the upper part of the face is captured. 510 * 511 * @syscap SystemCapability.UserIAM.UserAuth.Core 512 * @since 8 513 */ 514 FACE_AUTH_TIP_TOO_HIGH = 5, 515 516 /** 517 * Indicates that the device is too low, and that only the lower part of the face is captured. 518 * 519 * @syscap SystemCapability.UserIAM.UserAuth.Core 520 * @since 8 521 */ 522 FACE_AUTH_TIP_TOO_LOW = 6, 523 524 /** 525 * Indicates that the device is deviated to the right, and that only the right part of the face is captured. 526 * 527 * @syscap SystemCapability.UserIAM.UserAuth.Core 528 * @since 8 529 */ 530 FACE_AUTH_TIP_TOO_RIGHT = 7, 531 532 /** 533 * Indicates that the device is deviated to the left, and that only the left part of the face is captured. 534 * 535 * @syscap SystemCapability.UserIAM.UserAuth.Core 536 * @since 8 537 */ 538 FACE_AUTH_TIP_TOO_LEFT = 8, 539 540 /** 541 * Indicates that the face moves too fast during facial information collection. 542 * 543 * @syscap SystemCapability.UserIAM.UserAuth.Core 544 * @since 8 545 */ 546 FACE_AUTH_TIP_TOO_MUCH_MOTION = 9, 547 548 /** 549 * Indicates that the face is not facing the device. 550 * 551 * @syscap SystemCapability.UserIAM.UserAuth.Core 552 * @since 8 553 */ 554 FACE_AUTH_TIP_POOR_GAZE = 10, 555 556 /** 557 * Indicates that no face is detected. 558 * 559 * @syscap SystemCapability.UserIAM.UserAuth.Core 560 * @since 8 561 */ 562 FACE_AUTH_TIP_NOT_DETECTED = 11 563 } 564 565 /** 566 * The enumeration of prompt codes in the process of fingerprint authentication. 567 * 568 * @enum { number } 569 * @syscap SystemCapability.UserIAM.UserAuth.Core 570 * @since 8 571 */ 572 enum FingerprintTips { 573 /** 574 * Indicates that the image acquired is good. 575 * 576 * @syscap SystemCapability.UserIAM.UserAuth.Core 577 * @since 8 578 */ 579 FINGERPRINT_AUTH_TIP_GOOD = 0, 580 581 /** 582 * Indicates that the fingerprint image is too noisy due to suspected or detected dirt on sensor. 583 * 584 * @syscap SystemCapability.UserIAM.UserAuth.Core 585 * @since 8 586 */ 587 FINGERPRINT_AUTH_TIP_DIRTY = 1, 588 589 /** 590 * Indicates that the fingerprint image is too noisy to process due to a detected condition. 591 * 592 * @syscap SystemCapability.UserIAM.UserAuth.Core 593 * @since 8 594 */ 595 FINGERPRINT_AUTH_TIP_INSUFFICIENT = 2, 596 597 /** 598 * Indicates that only a partial fingerprint image is detected. 599 * 600 * @syscap SystemCapability.UserIAM.UserAuth.Core 601 * @since 8 602 */ 603 FINGERPRINT_AUTH_TIP_PARTIAL = 3, 604 605 /** 606 * Indicates that the fingerprint image is incomplete due to quick motion. 607 * 608 * @syscap SystemCapability.UserIAM.UserAuth.Core 609 * @since 8 610 */ 611 FINGERPRINT_AUTH_TIP_TOO_FAST = 4, 612 613 /** 614 * Indicates that the fingerprint image is unreadable due to lack of motion. 615 * 616 * @syscap SystemCapability.UserIAM.UserAuth.Core 617 * @since 8 618 */ 619 FINGERPRINT_AUTH_TIP_TOO_SLOW = 5 620 } 621 622 /** 623 * Credential type for authentication. 624 * 625 * @enum { number } 626 * @syscap SystemCapability.UserIAM.UserAuth.Core 627 * @since 8 628 */ 629 enum UserAuthType { 630 /** 631 * Authentication type pin. 632 * 633 * @syscap SystemCapability.UserIAM.UserAuth.Core 634 * @since 10 635 */ 636 PIN = 1, 637 638 /** 639 * Authentication type face. 640 * 641 * @syscap SystemCapability.UserIAM.UserAuth.Core 642 * @since 8 643 */ 644 FACE = 2, 645 646 /** 647 * Authentication type fingerprint. 648 * 649 * @syscap SystemCapability.UserIAM.UserAuth.Core 650 * @since 8 651 */ 652 FINGERPRINT = 4 653 } 654 655 /** 656 * Trust level of authentication results. 657 * 658 * @enum { number } 659 * @syscap SystemCapability.UserIAM.UserAuth.Core 660 * @since 8 661 */ 662 enum AuthTrustLevel { 663 /** 664 * Authentication result trusted level 1. 665 * 666 * @syscap SystemCapability.UserIAM.UserAuth.Core 667 * @since 8 668 */ 669 ATL1 = 10000, 670 671 /** 672 * Authentication result trusted level 2. 673 * 674 * @syscap SystemCapability.UserIAM.UserAuth.Core 675 * @since 8 676 */ 677 ATL2 = 20000, 678 679 /** 680 * Authentication result trusted level 3. 681 * 682 * @syscap SystemCapability.UserIAM.UserAuth.Core 683 * @since 8 684 */ 685 ATL3 = 30000, 686 687 /** 688 * Authentication result trusted level 4. 689 * 690 * @syscap SystemCapability.UserIAM.UserAuth.Core 691 * @since 8 692 */ 693 ATL4 = 40000 694 } 695 696 /** 697 * Authentication events. 698 * 699 * @syscap SystemCapability.UserIAM.UserAuth.Core 700 * @since 9 701 */ 702 type AuthEventKey = 'result' | 'tip'; 703 704 /** 705 * Return information of Authentication events. 706 * 707 * @syscap SystemCapability.UserIAM.UserAuth.Core 708 * @since 9 709 */ 710 type EventInfo = AuthResultInfo | TipInfo; 711 712 /** 713 * Asynchronous callback of authentication event. 714 * 715 * @interface AuthEvent 716 * @syscap SystemCapability.UserIAM.UserAuth.Core 717 * @since 9 718 */ 719 interface AuthEvent { 720 /** 721 * The authentication event callback. 722 * 723 * @param { EventInfo } result - Event info. 724 * @syscap SystemCapability.UserIAM.UserAuth.Core 725 * @since 9 726 */ 727 callback(result: EventInfo): void; 728 } 729 730 /** 731 * Authentication result information. 732 * 733 * @typedef AuthResultInfo 734 * @syscap SystemCapability.UserIAM.UserAuth.Core 735 * @since 9 736 */ 737 interface AuthResultInfo { 738 /** 739 * The authentication result. 740 * 741 * @type { number } 742 * @syscap SystemCapability.UserIAM.UserAuth.Core 743 * @since 9 744 */ 745 result: number; 746 747 /** 748 * The authentication token if the authentication is passed. 749 * 750 * @type { ?Uint8Array } 751 * @syscap SystemCapability.UserIAM.UserAuth.Core 752 * @since 9 753 */ 754 token?: Uint8Array; 755 756 /** 757 * The remaining authentication attempts if the authentication fails. 758 * 759 * @type { ?number } 760 * @syscap SystemCapability.UserIAM.UserAuth.Core 761 * @since 9 762 */ 763 remainAttempts?: number; 764 765 /** 766 * The lockout duration if the authentication executor is locked. 767 * 768 * @type { ?number } 769 * @syscap SystemCapability.UserIAM.UserAuth.Core 770 * @since 9 771 */ 772 lockoutDuration?: number; 773 } 774 775 /** 776 * Authentication tip info. 777 * 778 * @typedef TipInfo 779 * @syscap SystemCapability.UserIAM.UserAuth.Core 780 * @since 9 781 */ 782 interface TipInfo { 783 /** 784 * The authentication module of sending tip information. 785 * 786 * @type { number } 787 * @syscap SystemCapability.UserIAM.UserAuth.Core 788 * @since 9 789 */ 790 module: number; 791 792 /** 793 * Tip information, used to prompt the business to perform some operations. 794 * 795 * @type { number } 796 * @syscap SystemCapability.UserIAM.UserAuth.Core 797 * @since 9 798 */ 799 tip: number; 800 } 801 802 /** 803 * Authentication instance, used to initiate a complete authentication. 804 * 805 * @interface AuthInstance 806 * @syscap SystemCapability.UserIAM.UserAuth.Core 807 * @since 9 808 * @deprecated since 10 809 * @useinstead ohos.userIAM.userAuth.UserAuthInstance 810 */ 811 interface AuthInstance { 812 /** 813 * Turn on authentication event listening. 814 * 815 * @throws { BusinessError } 401 - Incorrect parameters. 816 * @throws { BusinessError } 12500002 - General operation error. 817 * @syscap SystemCapability.UserIAM.UserAuth.Core 818 * @since 9 819 * @deprecated since 10 820 */ 821 on: (name: AuthEventKey, callback: AuthEvent) => void; 822 823 /** 824 * Turn off authentication event listening. 825 * 826 * @throws { BusinessError } 401 - Incorrect parameters. 827 * @throws { BusinessError } 12500002 - General operation error. 828 * @syscap SystemCapability.UserIAM.UserAuth.Core 829 * @since 9 830 * @deprecated since 10 831 */ 832 off: (name: AuthEventKey) => void; 833 834 /** 835 * Start this authentication, an instance can only perform authentication once. 836 * 837 * @permission ohos.permission.ACCESS_BIOMETRIC 838 * @throws { BusinessError } 201 - Permission verification failed. 839 * @throws { BusinessError } 401 - Incorrect parameters. 840 * @throws { BusinessError } 12500001 - Authentication failed. 841 * @throws { BusinessError } 12500002 - General operation error. 842 * @throws { BusinessError } 12500003 - The operation is canceled. 843 * @throws { BusinessError } 12500004 - The operation is time-out. 844 * @throws { BusinessError } 12500005 - The authentication type is not supported. 845 * @throws { BusinessError } 12500006 - The authentication trust level is not supported. 846 * @throws { BusinessError } 12500007 - The authentication task is busy. 847 * @throws { BusinessError } 12500009 - The authenticator is locked. 848 * @throws { BusinessError } 12500010 - The type of credential has not been enrolled. 849 * @syscap SystemCapability.UserIAM.UserAuth.Core 850 * @since 9 851 * @deprecated since 10 852 */ 853 start: () => void; 854 855 /** 856 * Cancel this authentication. 857 * 858 * @permission ohos.permission.ACCESS_BIOMETRIC 859 * @throws { BusinessError } 201 - Permission verification failed. 860 * @throws { BusinessError } 401 - Incorrect parameters. 861 * @throws { BusinessError } 12500002 - General operation error. 862 * @syscap SystemCapability.UserIAM.UserAuth.Core 863 * @since 9 864 * @deprecated since 10 865 */ 866 cancel: () => void; 867 } 868 869 /** 870 * Check whether the authentication capability is available. 871 * 872 * @permission ohos.permission.ACCESS_BIOMETRIC 873 * @param { UserAuthType } authType - Credential type for authentication. 874 * @param { AuthTrustLevel } authTrustLevel - Trust level of authentication result. 875 * @throws { BusinessError } 201 - Permission verification failed. 876 * @throws { BusinessError } 401 - Incorrect parameters. 877 * @throws { BusinessError } 12500002 - General operation error. 878 * @throws { BusinessError } 12500005 - The authentication type is not supported. 879 * @throws { BusinessError } 12500006 - The authentication trust level is not supported. 880 * @throws { BusinessError } 12500010 - The type of credential has not been enrolled. 881 * @syscap SystemCapability.UserIAM.UserAuth.Core 882 * @since 9 883 */ 884 function getAvailableStatus(authType: UserAuthType, authTrustLevel: AuthTrustLevel): void; 885 886 /** 887 * Get Authentication instance. 888 * 889 * @param { Uint8Array } challenge - Pass in challenge value. 890 * @param { UserAuthType } authType - Credential type for authentication. 891 * @param { AuthTrustLevel } authTrustLevel - Trust level of authentication result. 892 * @returns { AuthInstance } Returns an authentication instance. 893 * @throws { BusinessError } 401 - Incorrect parameters. 894 * @throws { BusinessError } 12500002 - General operation error. 895 * @throws { BusinessError } 12500005 - The authentication type is not supported. 896 * @throws { BusinessError } 12500006 - The authentication trust level is not supported. 897 * @syscap SystemCapability.UserIAM.UserAuth.Core 898 * @since 9 899 * @deprecated since 10 900 * @useinstead ohos.userIAM.userAuth.getUserAuthInstance 901 */ 902 function getAuthInstance(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel): AuthInstance; 903 904 /** 905 * Window mode type for user authentication widget. 906 * 907 * @enum { number } 908 * @syscap SystemCapability.UserIAM.UserAuth.Core 909 * @systemapi Hide this for inner system use. 910 * @since 10 911 */ 912 enum WindowModeType { 913 /** 914 * Window mode type is dialog box. 915 * 916 * @syscap SystemCapability.UserIAM.UserAuth.Core 917 * @systemapi Hide this for inner system use. 918 * @since 10 919 */ 920 DIALOG_BOX = 1, 921 922 /** 923 * Window mode type is full screen. 924 * 925 * @syscap SystemCapability.UserIAM.UserAuth.Core 926 * @systemapi Hide this for inner system use. 927 * @since 10 928 */ 929 FULLSCREEN = 2 930 } 931 932 /** 933 * Auth parameter. 934 * 935 * @typedef AuthParam 936 * @syscap SystemCapability.UserIAM.UserAuth.Core 937 * @since 10 938 */ 939 interface AuthParam { 940 /** 941 * Pass in challenge value. 942 * 943 * @type { Uint8Array } 944 * @syscap SystemCapability.UserIAM.UserAuth.Core 945 * @since 10 946 */ 947 challenge: Uint8Array; 948 949 /** 950 * Credential type for authentication. 951 * 952 * @type { UserAuthType[] } 953 * @syscap SystemCapability.UserIAM.UserAuth.Core 954 * @since 10 955 */ 956 authType: UserAuthType[]; 957 958 /** 959 * Trust level of authentication result. 960 * 961 * @type { AuthTrustLevel } 962 * @syscap SystemCapability.UserIAM.UserAuth.Core 963 * @since 10 964 */ 965 authTrustLevel: AuthTrustLevel; 966 } 967 968 /** 969 * Auth widget parameter. 970 * 971 * @typedef WidgetParam 972 * @syscap SystemCapability.UserIAM.UserAuth.Core 973 * @since 10 974 */ 975 interface WidgetParam { 976 /** 977 * Title of widget. 978 * 979 * @type { string } 980 * @syscap SystemCapability.UserIAM.UserAuth.Core 981 * @since 10 982 */ 983 title: string; 984 985 /** 986 * The description text of navigation button. 987 * 988 * @type { ?string } 989 * @syscap SystemCapability.UserIAM.UserAuth.Core 990 * @since 10 991 */ 992 navigationButtonText?: string; 993 994 /** 995 * Display type of widget. 996 * 997 * @type { ?WindowModeType } 998 * @default WindowModeType.DIALOG_BOX 999 * @syscap SystemCapability.UserIAM.UserAuth.Core 1000 * @systemapi Hide this for inner system use. 1001 * @since 10 1002 */ 1003 windowMode?: WindowModeType; 1004 } 1005 1006 /** 1007 * Authentication result: authentication token, credential type for authentication succeed. 1008 * 1009 * @typedef UserAuthResult 1010 * @syscap SystemCapability.UserIAM.UserAuth.Core 1011 * @since 10 1012 */ 1013 interface UserAuthResult { 1014 /** 1015 * The authentication result. 1016 * 1017 * @type { number } 1018 * @syscap SystemCapability.UserIAM.UserAuth.Core 1019 * @since 10 1020 */ 1021 result: number; 1022 1023 /** 1024 * The authentication result if the authentication is passed. 1025 * 1026 * @type { ?Uint8Array } 1027 * @syscap SystemCapability.UserIAM.UserAuth.Core 1028 * @since 10 1029 */ 1030 token?: Uint8Array; 1031 1032 /** 1033 * Credential type for authentication succeed. 1034 * 1035 * @type { ?UserAuthType } 1036 * @syscap SystemCapability.UserIAM.UserAuth.Core 1037 * @since 10 1038 */ 1039 authType?: UserAuthType; 1040 } 1041 1042 /** 1043 * Asynchronous callback of authentication operation. 1044 * 1045 * @interface IAuthCallback 1046 * @syscap SystemCapability.UserIAM.UserAuth.Core 1047 * @since 10 1048 */ 1049 interface IAuthCallback { 1050 /** 1051 * The authentication result code is returned through the callback. 1052 * If the authentication is passed, the authentication token is returned in extraInfo. 1053 * 1054 * @param { UserAuthResult } result - Authentication result information. 1055 * @syscap SystemCapability.UserIAM.UserAuth.Core 1056 * @since 10 1057 */ 1058 onResult(result: UserAuthResult): void; 1059 } 1060 1061 /** 1062 * User authentication instance, used to initiate a complete authentication. 1063 * 1064 * @interface UserAuthInstance 1065 * @syscap SystemCapability.UserIAM.UserAuth.Core 1066 * @since 10 1067 */ 1068 interface UserAuthInstance { 1069 /** 1070 * Turn on widget authentication result event listening. 1071 * 1072 * @param { 'result' } type - Indicates the type of event. 1073 * @param { IAuthCallback } callback - Indicates the listener. 1074 * @throws { BusinessError } 401 - Incorrect parameters. 1075 * @throws { BusinessError } 12500002 - General operation error. 1076 * @syscap SystemCapability.UserIAM.UserAuth.Core 1077 * @since 10 1078 */ 1079 on(type: 'result', callback: IAuthCallback): void; 1080 1081 /** 1082 * Turn off widget authentication result event listening. 1083 * 1084 * @param { 'result' } type - Indicates the type of event. 1085 * @param { IAuthCallback } callback - Indicates the listener. 1086 * @throws { BusinessError } 401 - Incorrect parameters. 1087 * @throws { BusinessError } 12500002 - General operation error. 1088 * @syscap SystemCapability.UserIAM.UserAuth.Core 1089 * @since 10 1090 */ 1091 off(type: 'result', callback?: IAuthCallback): void; 1092 1093 /** 1094 * Start this authentication, an instance can only perform authentication once. 1095 * 1096 * @permission ohos.permission.ACCESS_BIOMETRIC 1097 * @throws { BusinessError } 201 - Permission verification failed. 1098 * @throws { BusinessError } 401 - Incorrect parameters. 1099 * @throws { BusinessError } 12500001 - Authentication failed. 1100 * @throws { BusinessError } 12500002 - General operation error. 1101 * @throws { BusinessError } 12500003 - The operation is canceled. 1102 * @throws { BusinessError } 12500004 - The operation is time-out. 1103 * @throws { BusinessError } 12500005 - The authentication type is not supported. 1104 * @throws { BusinessError } 12500006 - The authentication trust level is not supported. 1105 * @throws { BusinessError } 12500007 - The authentication task is busy. 1106 * @throws { BusinessError } 12500009 - The authenticator is locked. 1107 * @throws { BusinessError } 12500010 - The type of credential has not been enrolled. 1108 * @throws { BusinessError } 12500011 - The authentication is canceled from widget's navigation button. 1109 * @syscap SystemCapability.UserIAM.UserAuth.Core 1110 * @since 10 1111 */ 1112 start(): void; 1113 1114 /** 1115 * Cancel this authentication. 1116 * 1117 * @permission ohos.permission.ACCESS_BIOMETRIC 1118 * @throws { BusinessError } 201 - Permission verification failed. 1119 * @throws { BusinessError } 401 - Incorrect parameters. 1120 * @throws { BusinessError } 12500002 - General operation error. 1121 * @syscap SystemCapability.UserIAM.UserAuth.Core 1122 * @since 10 1123 */ 1124 cancel(): void; 1125 } 1126 1127 /** 1128 * Get user authentication instance with widget. 1129 * 1130 * @param { AuthParam } authParam - Auth parameter. 1131 * @param { WidgetParam } widgetParam - Widget parameter. 1132 * @returns { UserAuthInstance } Returns an authentication instance with widget. 1133 * @throws { BusinessError } 401 - Incorrect parameters. 1134 * @throws { BusinessError } 12500002 - General operation error. 1135 * @throws { BusinessError } 12500005 - The authentication type is not supported. 1136 * @throws { BusinessError } 12500006 - The authentication trust level is not supported. 1137 * @syscap SystemCapability.UserIAM.UserAuth.Core 1138 * @since 10 1139 */ 1140 function getUserAuthInstance(authParam: AuthParam, widgetParam: WidgetParam): UserAuthInstance; 1141 1142 /** 1143 * Notice type for user authentication. 1144 * 1145 * @enum { number } 1146 * @syscap SystemCapability.UserIAM.UserAuth.Core 1147 * @systemapi Hide this for inner system use. 1148 * @since 10 1149 */ 1150 enum NoticeType { 1151 /** 1152 * Notice from widget. 1153 * 1154 * @syscap SystemCapability.UserIAM.UserAuth.Core 1155 * @systemapi Hide this for inner system use. 1156 * @since 10 1157 */ 1158 WIDGET_NOTICE = 1 1159 } 1160 1161 /** 1162 * Send notice to user authentication. 1163 * 1164 * @permission ohos.permission.SUPPORT_USER_AUTH 1165 * @param { NoticeType } noticeType - Notice type for user authentication. 1166 * @param { string } eventData - The event data from widget. 1167 * @throws { BusinessError } 201 - Permission verification failed. 1168 * @throws { BusinessError } 202 - The caller is not a system application. 1169 * @throws { BusinessError } 401 - Incorrect parameters. 1170 * @throws { BusinessError } 12500002 - General operation error. 1171 * @syscap SystemCapability.UserIAM.UserAuth.Core 1172 * @systemapi Hide this for inner system use. 1173 * @since 10 1174 */ 1175 function sendNotice(noticeType: NoticeType, eventData: string): void; 1176 1177 /** 1178 * Enum for operation result. 1179 * 1180 * @enum { number } 1181 * @syscap SystemCapability.UserIAM.UserAuth.Core 1182 * @since 9 1183 */ 1184 enum UserAuthResultCode { 1185 /** 1186 * Indicates that the result is success or ability is supported. 1187 * 1188 * @syscap SystemCapability.UserIAM.UserAuth.Core 1189 * @since 9 1190 */ 1191 SUCCESS = 12500000, 1192 1193 /** 1194 * Indicates that the authentication result is failed. 1195 * 1196 * @syscap SystemCapability.UserIAM.UserAuth.Core 1197 * @since 9 1198 */ 1199 FAIL = 12500001, 1200 1201 /** 1202 * Indicates other errors. 1203 * 1204 * @syscap SystemCapability.UserIAM.UserAuth.Core 1205 * @since 9 1206 */ 1207 GENERAL_ERROR = 12500002, 1208 1209 /** 1210 * Indicates that this operation is canceled. 1211 * 1212 * @syscap SystemCapability.UserIAM.UserAuth.Core 1213 * @since 9 1214 */ 1215 CANCELED = 12500003, 1216 1217 /** 1218 * Indicates that this operation is time-out. 1219 * 1220 * @syscap SystemCapability.UserIAM.UserAuth.Core 1221 * @since 9 1222 */ 1223 TIMEOUT = 12500004, 1224 1225 /** 1226 * Indicates that this authentication type is not supported. 1227 * 1228 * @syscap SystemCapability.UserIAM.UserAuth.Core 1229 * @since 9 1230 */ 1231 TYPE_NOT_SUPPORT = 12500005, 1232 1233 /** 1234 * Indicates that the authentication trust level is not supported. 1235 * 1236 * @syscap SystemCapability.UserIAM.UserAuth.Core 1237 * @since 9 1238 */ 1239 TRUST_LEVEL_NOT_SUPPORT = 12500006, 1240 1241 /** 1242 * Indicates that the authentication task is busy. Wait for a few seconds and try again. 1243 * 1244 * @syscap SystemCapability.UserIAM.UserAuth.Core 1245 * @since 9 1246 */ 1247 BUSY = 12500007, 1248 1249 /** 1250 * Indicates that the authenticator is locked. 1251 * 1252 * @syscap SystemCapability.UserIAM.UserAuth.Core 1253 * @since 9 1254 */ 1255 LOCKED = 12500009, 1256 1257 /** 1258 * Indicates that the user has not enrolled the authenticator. 1259 * 1260 * @syscap SystemCapability.UserIAM.UserAuth.Core 1261 * @since 9 1262 */ 1263 NOT_ENROLLED = 12500010, 1264 1265 /** 1266 * Indicates that this operation is canceled from widget's navigation button. 1267 * 1268 * @syscap SystemCapability.UserIAM.UserAuth.Core 1269 * @since 10 1270 */ 1271 CANCELED_FROM_WIDGET = 12500011 1272 } 1273 1274 /** 1275 * User authentication widget's manager, used to manage widget's client. 1276 * 1277 * @interface UserAuthWidgetMgr 1278 * @syscap SystemCapability.UserIAM.UserAuth.Core 1279 * @systemapi Hide this for inner system use. 1280 * @since 10 1281 */ 1282 interface UserAuthWidgetMgr { 1283 /** 1284 * Turn on authentication widget command event listening. 1285 * 1286 * @param { 'command' } type - Indicates the type of event. 1287 * @param { IAuthWidgetCallback } callback - Indicates the listener. 1288 * @throws { BusinessError } 401 - Incorrect parameters. 1289 * @throws { BusinessError } 12500002 - General operation error. 1290 * @syscap SystemCapability.UserIAM.UserAuth.Core 1291 * @systemapi Hide this for inner system use. 1292 * @since 10 1293 */ 1294 on(type: 'command', callback: IAuthWidgetCallback): void; 1295 1296 /** 1297 * Turn off authentication widget command event listening. 1298 * 1299 * @param { 'command' } type - Indicates the type of event. 1300 * @param { IAuthWidgetCallback } callback - Indicates the listener. 1301 * @throws { BusinessError } 401 - Incorrect parameters. 1302 * @throws { BusinessError } 12500002 - General operation error. 1303 * @syscap SystemCapability.UserIAM.UserAuth.Core 1304 * @systemapi Hide this for inner system use. 1305 * @since 10 1306 */ 1307 off(type: 'command', callback?: IAuthWidgetCallback): void; 1308 } 1309 1310 /** 1311 * Get authentication instance with widget. 1312 * 1313 * @permission ohos.permission.SUPPORT_USER_AUTH 1314 * @param { number } version - The version of widget. 1315 * @returns { UserAuthWidgetMgr } Returns an authentication manager. 1316 * @throws { BusinessError } 201 - Permission verification failed. 1317 * @throws { BusinessError } 202 - The caller is not a system application. 1318 * @throws { BusinessError } 401 - Incorrect parameters. 1319 * @throws { BusinessError } 12500002 - General operation error. 1320 * @syscap SystemCapability.UserIAM.UserAuth.Core 1321 * @systemapi Hide this for inner system use. 1322 * @since 10 1323 */ 1324 function getUserAuthWidgetMgr(version: number): UserAuthWidgetMgr; 1325 1326 /** 1327 * Asynchronous callback of authentication widget operation. 1328 * 1329 * @interface IAuthWidgetCallback 1330 * @syscap SystemCapability.UserIAM.UserAuth.Core 1331 * @systemapi Hide this for inner system use. 1332 * @since 10 1333 */ 1334 interface IAuthWidgetCallback { 1335 /** 1336 * The command data for authentication with widget is sent through the callback. 1337 * 1338 * @param { string } cmdData - The command data for authentication with widget. 1339 * @syscap SystemCapability.UserIAM.UserAuth.Core 1340 * @systemapi Hide this for inner system use. 1341 * @since 10 1342 */ 1343 sendCommand(cmdData: string): void; 1344 } 1345} 1346 1347export default userAuth; 1348