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

/*
 * Copyright (c) 2023 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 4.1
 */

/**
 * @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 4.1
 */

package ohos.hdi.user_auth.v1_2;

import ohos.hdi.user_auth.v1_2.UserAuthTypes;

/**
 * @brief Declares the APIs of the user_auth driver.
 *
 * @since 4.1
 * @version 1.2
 */
interface IUserAuthInterface {
    /**
     * @brief Initializes the cache information of the user_auth driver.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    Init();
    /**
     * @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.
     */
    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.
     */
    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.
     */
    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.
     */
    CloseSession([in] int userId);
    /**
     * @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.
     *
     * @deprecated
     */
    BeginEnrollment([in] int userId, [in] unsigned char[] authToken, [in] struct EnrollParam param, 
        [out] struct ScheduleInfo info);
    /**
     * @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.
     */
    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.
     */
    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.
     */
    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.
     */
    GetCredential([in] int userId, [in] enum AuthType 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.
     */
    GetUserInfo([in] int userId, [out] unsigned long secureUid, [out] enum PinSubType 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}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    DeleteUser([in] int userId, [in] unsigned char[] authToken, [out] struct CredentialInfo[] deletedInfos);
    /**
     * @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.
     */
    EnforceDeleteUser([in] int userId, [out] struct CredentialInfo[] deletedInfos);
    /**
     * @brief Begins authentication, and generates the authentication solution.
     *
     * @param contextId Indicates the context index.
     * @param param Indicates input parameters. See {@link AuthSolution}.
     * @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.
     *
     * @deprecated
     */
    BeginAuthentication([in] unsigned long contextId, [in] struct AuthSolution param,
        [out] struct ScheduleInfo[] scheduleInfos);
    /**
     * @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}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    UpdateAuthenticationResult([in] unsigned long contextId, [in] unsigned char[] scheduleResult,
        [out] struct AuthResultInfo info);
    /**
     * @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.
     */
    CancelAuthentication([in] unsigned long contextId);
    /**
     * @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.
     *
     * @deprecated
     */
    BeginIdentification([in] unsigned long contextId, [in] enum AuthType authType, [in] unsigned char[] challenge,
        [in] unsigned int executorSensorHint, [out] struct ScheduleInfo scheduleInfo);
    /**
     * @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.
     */
    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.
     */
    CancelIdentification([in] unsigned long contextId);
    /**
     * @brief Obtains the trust level of the current authentication type.
     *
     * @param userId Indicates the user ID.
     * @param authType Indicates the authentication type. See {@link AuthType}.
     * @param authTrustLevel Indicates the authentication trust level.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    GetAuthTrustLevel([in] int userId, [in] enum AuthType authType, [out] unsigned int authTrustLevel);
    /**
     * @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.
     */
    GetValidSolution([in] int userId, [in] enum AuthType[] authTypes, [in] unsigned int authTrustLevel,
        [out] enum AuthType[] validTypes);
    /**
     * @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 ScheduleInfoV1_1}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @deprecated
     */
    BeginEnrollmentV1_1([in] int userId, [in] unsigned char[] authToken, [in] struct EnrollParam param, 
        [out] struct ScheduleInfoV1_1 info);
    /**
     * @brief Begins authentication, and generates the authentication solution.
     *
     * @param contextId Indicates the context index.
     * @param param Indicates input parameters. See {@link AuthSolution}.
     * @param scheduleInfos Indicates scheduling information. See {@link ScheduleInfoV1_1}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     *
     * @deprecated
     */
    BeginAuthenticationV1_1([in] unsigned long contextId, [in] struct AuthSolution param,
        [out] struct ScheduleInfoV1_1[] scheduleInfos);
    /**
     * @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 ScheduleInfoV1_1}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    BeginIdentificationV1_1([in] unsigned long contextId, [in] enum AuthType authType, [in] unsigned char[] challenge,
        [in] unsigned int executorSensorHint, [out] struct ScheduleInfoV1_1 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.
     */
    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.
     */
    GetAllExtUserInfo([out] ExtUserInfo[] userInfos);
    /**
     * @brief Begins authentication, and generates the authentication solution.
     *
     * @param contextId Indicates the context index.
     * @param param Indicates input parameters. See {@link AuthSolutionV1_2}.
     * @param scheduleInfos Indicates scheduling information. See {@link ScheduleInfoV1_1}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    BeginAuthenticationV1_2([in] unsigned long contextId, [in] struct AuthSolutionV1_2 param,
        [out] struct ScheduleInfoV1_1[] 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 EnrollParamV1_2}.
     * @param info Indicates scheduling information. See {@link ScheduleInfoV1_1}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    BeginEnrollmentV1_2([in] int userId, [in] unsigned char[] authToken, [in] struct EnrollParamV1_2 param, 
        [out] struct ScheduleInfoV1_1 info);
}
/** @} */