User IAM Subsystem ChangeLog

cl.useriam.1 API Exception Handling Change

Certain user IAM APIs 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:

An error message is returned by throwing an exception.

Change Impact

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 error information. Otherwise, service logic will be affected.

Key API/Component Changes

To implement unified exception handling, certain IAM APIs are deprecated and replaced by new APIs. The newly added APIs support unified error code handling specifications and function the same as the original APIs.

Module Class Method/Attribute/Enum/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 Enum 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 Enum 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 Enum 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 more information about the APIs, see User Authentication and Facial Authentication.

cl.useriam.2 API Invoking Permission Change

Some user IAM APIs can only be called by system applications, and system application runtime authentication is required. The following changes are made in API version 9:

Added the service logic for checking whether an application is a system application to the setSurfaceId API of the facial authentication module. Non-system applications cannot call this API.

Change Impact

Applications developed based on earlier versions are not affected.

Key API/Component Changes

The service logic for checking whether an application is a system application is added to setSurfaceId() . Error code 202 will be returned if the API is called by a non-system application.

Adaptation Guide

Change the app-feature field to hos_system_app in the UnsgnedReleasedProfileTemplate.json file in developtools_hapsigner. Then, the signed application is a system application.