User IAM Subsystem ChangeLog

cl.useriam.1 API Exception Handling Method Change

Certain 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:

An error message is returned via an exception.

Change Impacts

Applications 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.

Key API/Component Changes

For 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.

Module	Class	Method/Attribute/Enumeration/Constant	Change Type
ohos.userIAM.userAuth	UserAuth	constructor()	Deprecated
ohos.userIAM.userAuth	UserAuth	getVersion() : number	Deprecated
ohos.userIAM.userAuth	UserAuth	getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number	Deprecated
ohos.userIAM.userAuth	UserAuth	auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array	Deprecated
ohos.userIAM.userAuth	UserAuth	cancelAuth(contextID : Uint8Array) : number	Deprecated
ohos.userIAM.userAuth	IUserAuthCallback	onResult: (result : number, extraInfo : AuthResult) => void	Deprecated
ohos.userIAM.userAuth	IUserAuthCallback	onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void	Deprecated
ohos.userIAM.userAuth	AuthResult	AuthResult { token ?: Uint8Array; remainTimes ?: number; freezingTime ?: number;}	Deprecated
ohos.userIAM.userAuth	Enumeration	ResultCode { SUCCESS = 0, FAIL = 1, GENERAL_ERROR = 2, CANCELED = 3, TIMEOUT = 4, TYPE_NOT_SUPPORT = 5, TRUST_LEVEL_NOT_SUPPORT = 6, BUSY = 7, INVALID_PARAMETERS = 8, LOCKED = 9, NOT_ENROLLED = 10,}	Deprecated
ohos.userIAM.userAuth	type	AuthEventKey = "result"	Added
ohos.userIAM.userAuth	type	EventInfo = AuthResultInfo	Added
ohos.userIAM.userAuth	AuthResultInfo	AuthResultInfo { result : number; token ?: Uint8Array; remainAttempts ?: number; lockoutDuration ?: number;}	Added
ohos.userIAM.userAuth	TipInfo	TipInfo { module : number; tip : number;}	Added
ohos.userIAM.userAuth	AuthInstance	AuthInstance { on: (name: AuthEventKey, callback: AuthEvent) => void; off: (name: AuthEventKey) => void; start: () => void; cancel: () => void;}	Added
ohos.userIAM.userAuth	Enumeration	ResultCodeV9 { SUCCESS = 12500000, FAIL = 12500001, GENERAL_ERROR = 12500002, CANCELED = 12500003, TIMEOUT = 12500004, TYPE_NOT_SUPPORT = 12500005, TRUST_LEVEL_NOT_SUPPORT = 12500006, BUSY = 12500007, LOCKED = 12500009, NOT_ENROLLED = 12500010,}	Added
ohos.userIAM.userAuth	function	getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel : AuthTrustLevel) : AuthInstance	Added
ohos.userIAM.userAuth	function	getVersion() : number	Added
ohos.userIAM.userAuth	function	getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : void	Added
ohos.userIAM.faceAuth	FaceAuthManager	setSurfaceId(surfaceId : string) : ResultCode	Deleted
ohos.userIAM.faceAuth	Enumeration	ResultCode { SUCCESS = 0, FAIL = 1,}	Deleted
ohos.userIAM.faceAuth	FaceAuthManager	setSurfaceId(surfaceId: string) : void	Added

Adaptation Guide

The following uses getVersion as an example:

import userIAM_userAuth from '@ohos.userIAM.userAuth';

try {
    let version = userIAM_userAuth.getVersion();
    console.info("auth version = " + version);
} catch (error) {
    console.info("get version failed, error = " + error);
}

For sample code of more APIs, see the user authentication API reference and face authentication API reference.

cl.useriam.2 API Call Permission Change

Some 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:

The 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.

Change Impacts

Applications 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.

Key API/Component Changes

The 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.

Adaptation Guide

Modify the UnsgnedReleasedProfileTemplate.json file related to app signing to change the app-feature field to hos_system_app, so that the signed application is a system application.