xref: /drivers/interface/user_auth/v2_0/IUserAuthInterface.idl

/*
 * Copyright (c) 2024 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup HdfUserAuth
 * @{
 *
 * @brief Provides APIs for the user_auth driver.
 *
 * The user_auth driver provides a unified interface for the user_auth service to access the user_auth driver.
 * After obtaining the user_auth driver proxy, the service can call related APIs to register executors,
 * manage credentials, and complete password and biometric authentication.
 * @since 3.2
 * @version 1.0
 */

/**
 * @file IUserAuthInterface.idl
 *
 * @brief Declares the user_auth driver APIs, which can be used to register executors,
 * manage credentials, and complete password and biometric authentication.
 *
 * @since 3.2
 * @version 1.0
 */

package ohos.hdi.user_auth.v2_0;

import ohos.hdi.user_auth.v2_0.UserAuthTypes;
import ohos.hdi.user_auth.v2_0.IMessageCallback;

/**
 * @brief Declares the APIs of the user_auth driver.
 *
 * @since 3.2
 * @version 1.0
 */
interface IUserAuthInterface {
    /**
     * @brief Initializes the cache information of the user_auth driver.
     *
     * @param deviceUdid Indicates the device udid.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 3.2
     * @version 2.0
     */
    Init([in] String deviceUdid);
    /**
     * @brief Adds an authentication executor to obtain the authentication capability.
     *
     * @param info Indicates executor registration information. See {@link ExecutorRegisterInfo}.
     * @param index Indicates the executor index under the authentication framework.
     * @param publicKey Indicates the public key of the authentication framework.
     * @param templateIds Indicates template IDs enrolled by the executors.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 3.2
     * @version 1.0
     */
    AddExecutor([in] struct ExecutorRegisterInfo info, [out] unsigned long index,
        [out] unsigned char[] publicKey, [out] unsigned long[] templateIds);
    /**
     * @brief Deletes an executor.
     *
     * @param index Indicates the executor index under the authentication framework.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 3.2
     * @version 1.0
     */
    DeleteExecutor([in] unsigned long index);
    /**
     * @brief Opens a session for authentication credential management.
     *
     * @param userId Indicates the user ID.
     * @param challenge Indicates the random number, which is used to generate an authentication token.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 3.2
     * @version 1.0
     */
    OpenSession([in] int userId, [out] unsigned char[] challenge);
    /**
     * @brief Closes the authentication credential management session.
     *
     * @param userId Indicates the user ID.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 3.2
     * @version 1.0
     */
    CloseSession([in] int userId);
    /**
     * @brief Updates the enrollment result and completes the enrollment.
     *
     * @param userId Indicates the user ID.
     * @param scheduleResult Indicates the enrollment result issued by the executor.
     * @param info Indicates the enrollment result. See {@link EnrollResultInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 3.2
     * @version 1.0
     */
    UpdateEnrollmentResult([in] int userId, [in] unsigned char[] scheduleResult, [out] struct EnrollResultInfo info);
    /**
     * @brief Cancels an enrollment.
     *
     * @param userId Indicates the user ID.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 3.2
     * @version 1.0
     */
    CancelEnrollment([in] int userId);
    /**
     * @brief Deletes credential information.
     *
     * @param userId Indicates the user ID.
     * @param credentialId Indicates the credential index.
     * @param authToken Indicates the authentication token of the user password.
     * @param info Indicates the credential information to delete. See {@link CredentialInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 3.2
     * @version 1.0
     */
    DeleteCredential([in] int userId, [in] unsigned long credentialId, [in] unsigned char[] authToken,
        [out] struct CredentialInfo info);
    /**
     * @brief Obtains credential information.
     *
     * @param userId Indicates the user ID.
     * @param authType Indicates the authentication type. See {@link AuthType}.
     * @param infos Indicates credential information. See {@link CredentialInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 3.2
     * @version 2.0
     */
    GetCredential([in] int userId, [in] int authType, [out] struct CredentialInfo[] infos);
    /**
     * @brief Obtains user information.
     *
     * @param userId Indicates the user ID.
     * @param secureUid Indicates the secure user ID.
     * @param pinSubType Indicates the sub type of PIN authentication. See {@link PinSubType}.
     * @param infos Indicates enrolled information. See {@link EnrolledInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 3.2
     * @version 2.0
     */
    GetUserInfo([in] int userId, [out] unsigned long secureUid, [out] int pinSubType,
        [out] struct EnrolledInfo[] infos);
    /**
     * @brief Deletes a pin and a user from the IAM subsystem.
     *
     * @param userId Indicates the user ID.
     * @param authToken Indicates the authentication token of the user password.
     * @param deletedInfos Indicates the credential information to delete. See {@link CredentialInfo}.
     * @param rootSecret protection key for the user file key.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 3.2
     * @version 2.0
     */
    DeleteUser([in] int userId, [in] unsigned char[] authToken, [out] struct CredentialInfo[] deletedInfos,
        [out] unsigned char[] rootSecret);
    /**
     * @brief Forcibly deletes a user.
     *
     * @param userId Indicates the user ID.
     * @param deletedInfos Indicates the credential information to delete. See {@link CredentialInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 3.2
     * @version 1.0
     */
    EnforceDeleteUser([in] int userId, [out] struct CredentialInfo[] deletedInfos);
    /**
     * @brief Updates the authentication result, and evaluates the result of the authentication solution.
     *
     * @param contextId Indicates the context index.
     * @param scheduleResult Indicates the authentication result issued by the executor.
     * @param info Indicates authentication result information. See {@link AuthResultInfo}.
     * @param enrolledState EnrolledID information.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 3.2
     * @version 2.0
     */
    UpdateAuthenticationResult([in] unsigned long contextId, [in] unsigned char[] scheduleResult,
        [out] struct AuthResultInfo info, [out] EnrolledState enrolledState);
    /**
     * @brief Cancels authentication.
     *
     * @param contextId Indicates the context index.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 3.2
     * @version 1.0
     */
    CancelAuthentication([in] unsigned long contextId);
    /**
     * @brief Updates the identification result, and evaluates the result of the identification solution.
     *
     * @param contextId Indicates the context index.
     * @param scheduleResult Indicates the identification result issued by the executor.
     * @param info Indicates identification result information. See {@link IdentifyResultInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 3.2
     * @version 1.0
     */
    UpdateIdentificationResult([in] unsigned long contextId, [in] unsigned char[] scheduleResult,
        [out] struct IdentifyResultInfo info);
    /**
     * @brief Cancels identification.
     *
     * @param contextId Indicates the context index.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 3.2
     * @version 1.0
     */
    CancelIdentification([in] unsigned long contextId);
    /**
     * @brief Check whether the authentication capability is avaliable.
     *
     * @param userId Indicates the user ID.
     * @param authType Indicates the authentication type. See {@link AuthType}.
     * @param authTrustLevel Indicates the authentication trust level.
     * @param checkResult Indicates check result.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 5.0
     * @version 1.0
     */
    GetAvailableStatus([in] int userId, [in] int authType, [in] unsigned int authTrustLevel, [out] int checkResult);
    /**
     * @brief Obtains the valid authentication methods under the current authentication trust level.
     *
     * @param userId Indicates the user ID.
     * @param authTypes Indicates the authentication types to be filtered. See {@link AuthType}.
     * @param authTrustLevel Indicates the authentication trust level.
     * @param validTypes Indicates the valid authentication types. See {@link AuthType}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 3.2
     * @version 2.0
     */
    GetValidSolution([in] int userId, [in] int[] authTypes, [in] unsigned int authTrustLevel,
        [out] int[] validTypes);
    /**
     * @brief Begins authentication, and generates the authentication solution.
     *
     * @param contextId Indicates the context index.
     * @param param Indicates input parameters. See {@link AuthParam}.
     * @param scheduleInfos Indicates scheduling information. See {@link ScheduleInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 3.2
     * @version 2.0
     */
    BeginAuthentication([in] unsigned long contextId, [in] struct AuthParam param,
        [out] struct ScheduleInfo[] scheduleInfos);
    /**
     * @brief Begins the enrollment of authentication credentials.
     * If the authentication type is PIN, this method updates the existing PIN credential.
     *
     * @param userId Indicates the user ID.
     * @param authToken Indicates the authentication token of the user password.
     * @param param Indicates input parameters. See {@link EnrollParam}.
     * @param info Indicates scheduling information. See {@link ScheduleInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 3.2
     * @version 2.0
     */
    BeginEnrollment([in] unsigned char[] authToken, [in] struct EnrollParam param,
        [out] struct ScheduleInfo info);
    /**
     * @brief Begins identification, and generates the identification solution.
     *
     * @param contextId Indicates the context index.
     * @param authType Indicates the identification type. See @{AuthType}.
     * @param challenge Indicates the identification challenge.
     * @param executorSensorHint Indicates the executor sensor hint.
     * The value <b>0</b> indicates that no value is specified.
     * @param scheduleInfo Indicates scheduling information. See {@link ScheduleInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 3.2
     * @version 2.0
     */
    BeginIdentification([in] unsigned long contextId, [in] int authType, [in] unsigned char[] challenge,
        [in] unsigned int executorSensorHint, [out] struct ScheduleInfo scheduleInfo);
    /**
     * @brief Get all enrolled user information.
     *
     * @param userInfos List of all userInfo. See @{UserInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 4.0
     * @version 1.0
     */
    GetAllUserInfo([out] UserInfo[] userInfos);
    /**
     * @brief Get all credential of enrolled users.
     *
     * @param userInfos List of all users. See @{ExtUserInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 4.0
     * @version 1.0
     */
    GetAllExtUserInfo([out] ExtUserInfo[] userInfos);

    /**
     * @brief Querying EnrolledId information.
     *
     * @param userId Indicates the user ID.
     * @param authType Indicates the identification type. See @{AuthType}.
     * @param enrolledState Enrolled state.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 5.0
     * @version 1.0
     */
    GetEnrolledState([in] int userId, [in] int authType, [out] struct EnrolledState enrolledState);

    /**
     * @brief Check if unlock result can be reused and return token.
     *
     * @param info Request information of reused unLock result. See {@link ReuseUnlockParam}.
     * @param reuseInfo Reuse unlock info. See {@link ReuseUnlockInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 5.0
     * @version 1.0
     */
    CheckReuseUnlockResult([in] struct ReuseUnlockParam reuseParam, [out] ReuseUnlockInfo reuseInfo);
    /**
     * @brief Send message.
     *
     * @param scheduleId Indicates the schedule ID of the message.
     * @param srcRole is the role of source. See {@link ExecutorRole}.
     * @param msg is the message content.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 5.0
     * @version 1.0
     */
    SendMessage([in] unsigned long scheduleId, [in] int srcRole, [in] unsigned char[] msg);
    /**
     * @brief Register message callback.
     *
     * @param messageCallback Indicates the message callback. See {@link IMessageCallback}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 5.0
     * @version 1.0
     */
    RegisterMessageCallback([in] IMessageCallback messageCallback);
    /**
     * @brief Prepare remote auth.
     *
     * @param remoteUdid Indicates the remote device udid.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 5.0
     * @version 1.0
     */
    PrepareRemoteAuth([in] String remoteUdid);
    /**
     * @brief Get local schedule from message.
     *
     * @param remoteUdid Indicates the remote device udid.
     * @param message is message received.
     * @param scheduleInfo is schedule info. See {@link ScheduleInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 5.0
     * @version 1.0
     */
    GetLocalScheduleFromMessage([in] String remoteUdid, [in] unsigned char[] message, [out] ScheduleInfo scheduleInfo);
    /**
     * @brief Get signed executor info.
     *
     * @param authTypes Indicates the auth types. See @{AuthType}.
     * @param executorRole Indicates the role of executor. See {@link ExecutorRole}.
     * @param remoteUdid Indicates the remote device udid.
     * @param signedExecutorInfo Indicates the signed executor info.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 5.0
     * @version 1.0
     */
    GetSignedExecutorInfo([in] int[] authTypes, [in] int executorRole, [in] String remoteUdid,
        [out] unsigned char[] signedExecutorInfo);
    /**
     * @brief Get auth result from message.
     *
     * @param remoteUdid Indicates the remote device udid.
     * @param message is message received.
     * @param authResultInfo Indicates authentication result information. See {@link AuthResultInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @since 5.0
     * @version 1.0
     */
     GetAuthResultFromMessage([in] String remoteUdid, [in] unsigned char[] message, [out] struct AuthResultInfo authResultInfo);
    /**
     * @brief Set global config param.
     *
     * @param param The value of global config parameter. See @{GlobalConfigParam}.
     * @return Return set result(0:success; other:failed).
     *
     * @since 5.0
     * @version 1.0
     */
    SetGlobalConfigParam([in] GlobalConfigParam param);
}
/** @} */