1# User IAM Subsystem ChangeLog
2
3## cl.useriam.1 API Exception Handling Method Change
4
5Certain APIs of user IAM use service logic return values to indicate error information, which does not comply with the API error code specifications of OpenHarmony. The following changes are made in API version 9 and later:
6
7An error message is returned via an exception.
8
9**Change Impacts**
10
11Applications developed based on earlier versions are not affected. If your application uses API version 9 or later, you need to adapt the change in the way for APIs to return the error information. Otherwise, service logic will be affected.
12
13**Key API/Component Changes**
14
15For adaptation to the unified API exception handling mode, certain APIs of user IAM are deprecated (original APIs in the following table) and corresponding new APIs in the following table are added. The newly added APIs support unified error code handling specifications and function the same as the original APIs.
16
17|   Module     |     Class    |     Method/Attribute/Enumeration/Constant     |    Change Type    |
18| ---------------------- | ------------------- | ------------------------- | ------------------------ |
19| ohos.userIAM.userAuth | UserAuth | constructor() | Deprecated|
20| ohos.userIAM.userAuth | UserAuth | getVersion() : number | Deprecated|
21| ohos.userIAM.userAuth | UserAuth | getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number | Deprecated|
22| ohos.userIAM.userAuth | UserAuth | auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array | Deprecated|
23| ohos.userIAM.userAuth | UserAuth | cancelAuth(contextID : Uint8Array) : number | Deprecated|
24| ohos.userIAM.userAuth | IUserAuthCallback | onResult: (result : number, extraInfo : AuthResult) => void | Deprecated|
25| ohos.userIAM.userAuth | IUserAuthCallback | onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void | Deprecated|
26| ohos.userIAM.userAuth | AuthResult | AuthResult {<br>token ?: Uint8Array; <br>remainTimes ?: number; <br>freezingTime ?: number;} | Deprecated|
27| ohos.userIAM.userAuth | Enumeration| ResultCode {<br>SUCCESS = 0, <br>FAIL = 1, <br>GENERAL_ERROR = 2, <br>CANCELED = 3, <br>TIMEOUT = 4, <br>TYPE_NOT_SUPPORT = 5, <br>TRUST_LEVEL_NOT_SUPPORT = 6, <br>BUSY = 7, <br>INVALID_PARAMETERS = 8, <br>LOCKED = 9, <br>NOT_ENROLLED = 10,} | Deprecated|
28| ohos.userIAM.userAuth | type | AuthEventKey = "result" | Added|
29| ohos.userIAM.userAuth | type | EventInfo = AuthResultInfo | Added|
30| ohos.userIAM.userAuth | AuthResultInfo | AuthResultInfo {<br>result : number; <br>token ?: Uint8Array; <br>remainAttempts ?: number; <br>lockoutDuration ?: number;} | Added|
31| ohos.userIAM.userAuth | TipInfo | TipInfo {<br>module : number; <br>tip : number;} | Added|
32| ohos.userIAM.userAuth | AuthInstance | AuthInstance {<br>on: (name: AuthEventKey, callback: AuthEvent) => void; <br>off: (name: AuthEventKey) => void; <br>start: () => void; <br>cancel: () => void;} | Added|
33| ohos.userIAM.userAuth | Enumeration| ResultCodeV9 {<br>SUCCESS = 12500000, <br>FAIL = 12500001, <br>GENERAL_ERROR = 12500002, <br>CANCELED = 12500003, <br>TIMEOUT = 12500004, <br>TYPE_NOT_SUPPORT = 12500005, <br>TRUST_LEVEL_NOT_SUPPORT = 12500006, <br>BUSY = 12500007, <br>LOCKED = 12500009, <br>NOT_ENROLLED = 12500010,} | Added|
34| ohos.userIAM.userAuth | function | getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel : AuthTrustLevel) : AuthInstance | Added|
35| ohos.userIAM.userAuth | function | getVersion() : number | Added|
36| ohos.userIAM.userAuth | function | getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : void | Added|
37| ohos.userIAM.faceAuth | FaceAuthManager | setSurfaceId(surfaceId : string) : ResultCode | Deleted|
38| ohos.userIAM.faceAuth | Enumeration| ResultCode {<br>SUCCESS = 0, <br>FAIL = 1,} | Deleted|
39| ohos.userIAM.faceAuth | FaceAuthManager | setSurfaceId(surfaceId: string) : void | Added|
40
41**Adaptation Guide**
42
43The following uses **getVersion** as an example:
44
45```js
46import userIAM_userAuth from '@ohos.userIAM.userAuth';
47
48try {
49    let version = userIAM_userAuth.getVersion();
50    console.info("auth version = " + version);
51} catch (error) {
52    console.info("get version failed, error = " + error);
53}
54```
55
56For sample code of more APIs, see the [user authentication API reference](../../../application-dev/reference/apis/js-apis-useriam-userauth.md) and [face authentication API reference](../../../application-dev/reference/apis/js-apis-useriam-faceauth.md).
57
58## cl.useriam.2 API Call Permission Change
59
60Some APIs of user IAM can only be called by system applications, and system application runtime authentication is required. The following changes are made in API version 9 and later:
61
62The service logic for checking whether an application is a system application is added for the **setSurfaceId** API of the face authentication module. Non-system applications cannot call this API.
63
64**Change Impacts**
65
66Applications developed based on earlier versions are not affected. If your application uses API version 9 or later and wants to call this API, your application must be a system application.
67
68**Key API/Component Changes**
69
70The service logic for checking whether an application is a system application is added for the **setSurfaceId** API. Error code **202** will be returned if the API is called by a non-system application.
71
72**Adaptation Guide**
73
74Modify the **UnsgnedReleasedProfileTemplate.json** file related to [app signing](https://gitee.com/openharmony/developtools_hapsigner/tree/master/dist) to change the **app-feature** field to **hos_system_app**, so that the signed application is a system application.
75