1/* 2 * Copyright (c) 2021 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 { AsyncCallback } from './basic'; 17 18/** 19 * User authentication 20 * @since 6 21 * @syscap SystemCapability.UserIAM.UserAuth.Core 22 * @permission ohos.permission.ACCESS_BIOMETRIC 23 */ 24declare namespace userAuth { 25 export enum AuthenticationResult { 26 /** 27 * Indicates that the device does not support authentication. 28 * @deprecated since 8 29 */ 30 NO_SUPPORT = -1, 31 32 /** 33 * Indicates that authentication is success. 34 * @deprecated since 8 35 */ 36 SUCCESS = 0, 37 38 /** 39 * Indicates the authenticator fails to identify user. 40 * @deprecated since 8 41 */ 42 COMPARE_FAILURE = 1, 43 44 /** 45 * Indicates that authentication has been canceled. 46 * @deprecated since 8 47 */ 48 CANCELED = 2, 49 50 /** 51 * Indicates that authentication has timed out. 52 * @deprecated since 8 53 */ 54 TIMEOUT = 3, 55 56 /** 57 * Indicates a failure to open the camera. 58 * @deprecated since 8 59 */ 60 CAMERA_FAIL = 4, 61 62 /** 63 * Indicates that the authentication task is busy. Wait for a few seconds and try again. 64 * @deprecated since 8 65 */ 66 BUSY = 5, 67 68 /** 69 * Indicates incorrect parameters. 70 * @deprecated since 8 71 */ 72 INVALID_PARAMETERS = 6, 73 74 /** 75 * Indicates that the authenticator is locked. 76 * @deprecated since 8 77 */ 78 LOCKED = 7, 79 80 /** 81 * Indicates that the user has not enrolled the authenticator. 82 * @deprecated since 8 83 */ 84 NOT_ENROLLED = 8, 85 86 /** 87 * Indicates other errors. 88 * @deprecated since 8 89 */ 90 GENERAL_ERROR = 100, 91 } 92 93 /** 94 * Auth types 95 * @deprecated since 8 96 */ 97 type AuthType = "ALL" | "FACE_ONLY"; 98 99 /** 100 * Secure levels 101 * @deprecated since 8 102 */ 103 type SecureLevel = "S1" | "S2" | "S3" | "S4"; 104 105 interface Authenticator { 106 /** 107 * Execute authentication. 108 * @syscap SystemCapability.UserIAM.UserAuth.Core 109 * @param type Indicates the authentication type. 110 * @param level Indicates the security level. 111 * @return Returns authentication result, which is specified by AuthenticationResult. 112 * @deprecated since 8 113 */ 114 execute(type: AuthType, level: SecureLevel, callback: AsyncCallback<number>): void; 115 execute(type: AuthType, level: SecureLevel): Promise<number>; 116 } 117 118 /** 119 * Get Authenticator instance. 120 * @syscap SystemCapability.UserIAM.UserAuth.Core 121 * @return Returns an Authenticator. 122 * @deprecated since 8 123 */ 124 function getAuthenticator(): Authenticator; 125 126 /** 127 * User authentication. 128 * @since 8 129 * @syscap SystemCapability.UserIAM.UserAuth.Core 130 */ 131 class UserAuth { 132 /** 133 * Constructor to get the UserAuth class instance. 134 * @since 8 135 * @syscap SystemCapability.UserIAM.UserAuth.Core 136 * @return Returns the UserAuth class instance. 137 */ 138 constructor(); 139 140 /** 141 * Get version information. 142 * @since 8 143 * @syscap SystemCapability.UserIAM.UserAuth.Core 144 * @return Returns version information. 145 */ 146 getVersion() : number; 147 148 /** 149 * Check whether the authentication capability is available. 150 * @since 8 151 * @syscap SystemCapability.UserIAM.UserAuth.Core 152 * @permission ohos.permission.ACCESS_BIOMETRIC 153 * @param authType Credential type for authentication. 154 * @param authTrustLevel Trust level of authentication result. 155 * @return Returns a check result, which is specified by getAvailableStatus. 156 */ 157 getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number; 158 159 /** 160 * Executes authentication. 161 * @since 8 162 * @syscap SystemCapability.UserIAM.UserAuth.Core 163 * @permission ohos.permission.ACCESS_BIOMETRIC 164 * @param challenge pass in challenge value. 165 * @param authType type of authentication. 166 * @param authTrustLevel Trust level of authentication result. 167 * @param callback Return result and acquireinfo through callback. 168 * @return Returns ContextId for cancel. 169 */ 170 auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array; 171 172 /** 173 * Cancels authentication with ContextID. 174 * @since 8 175 * @syscap SystemCapability.UserIAM.UserAuth.Core 176 * @permission ohos.permission.ACCESS_BIOMETRIC 177 * @param contextID Cancel authentication and pass in ContextID. 178 * @return Returns a number value indicating whether Cancel authentication was successful. 179 */ 180 cancelAuth(contextID : Uint8Array) : number; 181 } 182 183 interface IUserAuthCallback { 184 /** 185 * The authentication result code is returned through the callback. 186 * @since 8 187 * @syscap SystemCapability.UserIAM.UserAuth.Core 188 * @param result authentication result code. 189 * @param extraInfo pass the specific information for different situation. 190 * If the authentication is passed, the authentication token is returned in extrainfo, 191 * If the authentication fails, the remaining authentication times are returned in extrainfo, 192 * If the authentication executor is locked, the freezing time is returned in extrainfo. 193 */ 194 onResult: (result : number, extraInfo : AuthResult) => void; 195 196 /** 197 * During an authentication, the TipsCode is returned through the callback. 198 * @since 8 199 * @syscap SystemCapability.UserIAM.UserAuth.Core 200 * @param module the executor type for authentication. 201 * @param acquire the tip code for different authentication executor. 202 * @param extraInfo reserved parameter. 203 */ 204 onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void; 205 } 206 207 /** 208 * Authentication result: authentication token, remaining authentication times, freezing time. 209 * @since 8 210 * @syscap SystemCapability.UserIAM.UserAuth.Core 211 * @param token pass the authentication result if the authentication is passed. 212 * @param remainTimes return the remaining authentication times if the authentication fails. 213 * @param freezingTime return the freezing time if the authectication executor is locked. 214 */ 215 interface AuthResult { 216 token ?: Uint8Array; 217 remainTimes ?: number; 218 freezingTime ?: number; 219 } 220 221 /** 222 * Result code. 223 * @since 8 224 * @syscap SystemCapability.UserIAM.UserAuth.Core 225 */ 226 enum ResultCode { 227 /** 228 * Indicates that the result is success or ability is supported. 229 * @since 8 230 * @syscap SystemCapability.UserIAM.UserAuth.Core 231 */ 232 SUCCESS = 0, 233 234 /** 235 * Indicates the the result is failure or ability is not supported. 236 * @since 8 237 * @syscap SystemCapability.UserIAM.UserAuth.Core 238 */ 239 FAIL = 1, 240 241 /** 242 * Indicates other errors. 243 * @since 8 244 * @syscap SystemCapability.UserIAM.UserAuth.Core 245 */ 246 GENERAL_ERROR = 2, 247 248 /** 249 * Indicates that this operation has been canceled. 250 * @since 8 251 * @syscap SystemCapability.UserIAM.UserAuth.Core 252 */ 253 CANCELED = 3, 254 255 /** 256 * Indicates that this operation has timed out. 257 * @since 8 258 * @syscap SystemCapability.UserIAM.UserAuth.Core 259 */ 260 TIMEOUT = 4, 261 262 /** 263 * Indicates that this authentication type is not supported. 264 * @since 8 265 * @syscap SystemCapability.UserIAM.UserAuth.Core 266 */ 267 TYPE_NOT_SUPPORT = 5, 268 269 /** 270 * Indicates that the authentication trust level is not supported. 271 * @since 8 272 * @syscap SystemCapability.UserIAM.UserAuth.Core 273 */ 274 TRUST_LEVEL_NOT_SUPPORT = 6, 275 276 /** 277 * Indicates that the authentication task is busy. Wait for a few seconds and try again. 278 * @since 8 279 * @syscap SystemCapability.UserIAM.UserAuth.Core 280 */ 281 BUSY = 7, 282 283 /** 284 * Indicates incorrect parameters. 285 * @since 8 286 * @syscap SystemCapability.UserIAM.UserAuth.Core 287 */ 288 INVALID_PARAMETERS = 8, 289 290 /** 291 * Indicates that the authenticator is locked. 292 * @since 8 293 * @syscap SystemCapability.UserIAM.UserAuth.Core 294 */ 295 LOCKED = 9, 296 297 /** 298 * Indicates that the user has not enrolled the authenticator. 299 * @since 8 300 * @syscap SystemCapability.UserIAM.UserAuth.Core 301 */ 302 NOT_ENROLLED = 10 303 } 304 305 /** 306 * Indicates the enumeration of prompt codes in the process of face authentication. 307 * @since 8 308 * @syscap SystemCapability.UserIAM.UserAuth.Core 309 */ 310 enum FaceTips { 311 /** 312 * Indicates that the obtained facial image is too bright due to high illumination. 313 * @since 8 314 * @syscap SystemCapability.UserIAM.UserAuth.Core 315 */ 316 FACE_AUTH_TIP_TOO_BRIGHT = 1, 317 318 /** 319 * Indicates that the obtained facial image is too dark due to low illumination. 320 * @since 8 321 * @syscap SystemCapability.UserIAM.UserAuth.Core 322 */ 323 FACE_AUTH_TIP_TOO_DARK = 2, 324 325 /** 326 * Indicates that the face is too close to the device. 327 * @since 8 328 * @syscap SystemCapability.UserIAM.UserAuth.Core 329 */ 330 FACE_AUTH_TIP_TOO_CLOSE = 3, 331 332 /** 333 * Indicates that the face is too far away from the device. 334 * @since 8 335 * @syscap SystemCapability.UserIAM.UserAuth.Core 336 */ 337 FACE_AUTH_TIP_TOO_FAR = 4, 338 339 /** 340 * Indicates that the device is too high, and that only the upper part of the face is captured. 341 * @since 8 342 * @syscap SystemCapability.UserIAM.UserAuth.Core 343 */ 344 FACE_AUTH_TIP_TOO_HIGH = 5, 345 346 /** 347 * Indicates that the device is too low, and that only the lower part of the face is captured. 348 * @since 8 349 * @syscap SystemCapability.UserIAM.UserAuth.Core 350 */ 351 FACE_AUTH_TIP_TOO_LOW = 6, 352 353 /** 354 * Indicates that the device is deviated to the right, and that only the right part of the face is captured. 355 * @since 8 356 * @syscap SystemCapability.UserIAM.UserAuth.Core 357 */ 358 FACE_AUTH_TIP_TOO_RIGHT = 7, 359 360 /** 361 * Indicates that the device is deviated to the left, and that only the left part of the face is captured. 362 * @since 8 363 * @syscap SystemCapability.UserIAM.UserAuth.Core 364 */ 365 FACE_AUTH_TIP_TOO_LEFT = 8, 366 367 /** 368 * Indicates that the face moves too fast during facial information collection. 369 * @since 8 370 * @syscap SystemCapability.UserIAM.UserAuth.Core 371 */ 372 FACE_AUTH_TIP_TOO_MUCH_MOTION = 9, 373 374 /** 375 * Indicates that the face is not facing the device. 376 * @since 8 377 * @syscap SystemCapability.UserIAM.UserAuth.Core 378 */ 379 FACE_AUTH_TIP_POOR_GAZE = 10, 380 381 /** 382 * Indicates that no face is detected. 383 * @since 8 384 * @syscap SystemCapability.UserIAM.UserAuth.Core 385 */ 386 FACE_AUTH_TIP_NOT_DETECTED = 11, 387 } 388 389 /** 390 * Indicates the enumeration of prompt codes in the process of fingerprint authentication. 391 * @since 8 392 * @syscap SystemCapability.UserIAM.UserAuth.Core 393 */ 394 enum FingerprintTips { 395 /** 396 * Indicates that the image acquired is good. 397 * @since 8 398 * @syscap SystemCapability.UserIAM.UserAuth.Core 399 */ 400 FINGERPRINT_AUTH_TIP_GOOD = 0, 401 402 /** 403 * Indicates that the fingerprint image is too noisy due to suspected or detected dirt on sensor. 404 * @since 8 405 * @syscap SystemCapability.UserIAM.UserAuth.Core 406 */ 407 FINGERPRINT_AUTH_TIP_DIRTY = 1, 408 409 /** 410 * Indicates that the fingerprint image is too noisy to process due to a detected condition. 411 * @since 8 412 * @syscap SystemCapability.UserIAM.UserAuth.Core 413 */ 414 FINGERPRINT_AUTH_TIP_INSUFFICIENT = 2, 415 416 /** 417 * Indicates that only a partial fingerprint image is detected. 418 * @since 8 419 * @syscap SystemCapability.UserIAM.UserAuth.Core 420 */ 421 FINGERPRINT_AUTH_TIP_PARTIAL = 3, 422 423 /** 424 * Indicates that the fingerprint image is incomplete due to quick motion. 425 * @since 8 426 * @syscap SystemCapability.UserIAM.UserAuth.Core 427 */ 428 FINGERPRINT_AUTH_TIP_TOO_FAST = 4, 429 430 /** 431 * Indicates that the fingerprint image is unreadable due to lack of motion. 432 * @since 8 433 * @syscap SystemCapability.UserIAM.UserAuth.Core 434 */ 435 FINGERPRINT_AUTH_TIP_TOO_SLOW = 5 436 } 437 438 /** 439 * Credential type for authentication. 440 * @since 8 441 * @syscap SystemCapability.UserIAM.UserAuth.Core 442 */ 443 enum UserAuthType { 444 /** 445 * Authentication type face. 446 * @since 8 447 * @syscap SystemCapability.UserIAM.UserAuth.Core 448 */ 449 FACE = 2, 450 451 /** 452 * Authentication type fingerprint. 453 * @since 8 454 * @syscap SystemCapability.UserIAM.UserAuth.Core 455 */ 456 FINGERPRINT = 4 457 } 458 459 /** 460 * Trust level of authentication results. 461 * @since 8 462 * @syscap SystemCapability.UserIAM.UserAuth.Core 463 */ 464 enum AuthTrustLevel { 465 /** 466 * Authentication result trusted level 1. 467 * @since 8 468 * @syscap SystemCapability.UserIAM.UserAuth.Core 469 */ 470 ATL1 = 10000, 471 472 /** 473 * Authentication result trusted level 2. 474 * @since 8 475 * @syscap SystemCapability.UserIAM.UserAuth.Core 476 */ 477 ATL2 = 20000, 478 479 /** 480 * Authentication result trusted level 3. 481 * @since 8 482 * @syscap SystemCapability.UserIAM.UserAuth.Core 483 */ 484 ATL3 = 30000, 485 486 /** 487 * Authentication result trusted level 4. 488 * @since 8 489 * @syscap SystemCapability.UserIAM.UserAuth.Core 490 */ 491 ATL4 = 40000 492 } 493} 494 495export default userAuth; 496