From aa499f141876720fd7c97473d0875ea94dd0d4d5 Mon Sep 17 00:00:00 2001 From: liuziwei Date: Sat, 4 Mar 2023 04:20:52 +0000 Subject: [PATCH] add annotation for innerapi Signed-off-by: liuziwei Change-Id: I9a350f6bcc2edcb0813d61f0728c5b6645811f02 --- frameworks/js/napi/user_auth/BUILD.gn | 6 +- interfaces/inner_api/attributes.h | 342 ++++++++++++++++-- interfaces/inner_api/co_auth_client.h | 29 ++ .../inner_api/co_auth_client_callback.h | 45 +++ interfaces/inner_api/co_auth_client_defines.h | 43 +++ interfaces/inner_api/iam_common_defines.h | 86 ++++- .../iam_executor_framework_types.h | 20 + .../iam_executor_iauth_driver_hdi.h | 20 + .../iam_executor_iauth_executor_hdi.h | 93 ++++- .../iam_executor_idriver_manager.h | 26 ++ .../iam_executor_iexecute_callback.h | 35 ++ interfaces/inner_api/user_auth_client.h | 64 ++++ .../inner_api/user_auth_client_callback.h | 48 +++ .../inner_api/user_auth_client_defines.h | 19 + interfaces/inner_api/user_idm_client.h | 99 +++++ .../inner_api/user_idm_client_callback.h | 32 ++ .../inner_api/user_idm_client_defines.h | 31 ++ 17 files changed, 1002 insertions(+), 36 deletions(-) diff --git a/frameworks/js/napi/user_auth/BUILD.gn b/frameworks/js/napi/user_auth/BUILD.gn index 60e81b692..33bcbe686 100644 --- a/frameworks/js/napi/user_auth/BUILD.gn +++ b/frameworks/js/napi/user_auth/BUILD.gn @@ -33,8 +33,9 @@ ohos_shared_library("userauth") { ] deps = [ - "//base/useriam/user_auth_framework/common:iam_utils", - "//base/useriam/user_auth_framework/frameworks/native/common:dfx", + "../../../../common:iam_utils", + "../../../native/client:userauth_client", + "../../../native/common:dfx", ] external_deps = [ @@ -42,7 +43,6 @@ ohos_shared_library("userauth") { "hiviewdfx_hilog_native:libhilog", "ipc:ipc_single", "napi:ace_napi", - "user_auth_framework:userauth_client", ] public_configs = [ ":userauth_public_config" ] diff --git a/interfaces/inner_api/attributes.h b/interfaces/inner_api/attributes.h index 5bd8ce01c..69b5c1eda 100644 --- a/interfaces/inner_api/attributes.h +++ b/interfaces/inner_api/attributes.h @@ -13,6 +13,14 @@ * limitations under the License. */ +/** + * @file attributes.h + * + * @brief Attributes enum define. + * @since 3.1 + * @version 3.2 + */ + #ifndef IAM_ATTRIBUTES_H #define IAM_ATTRIBUTES_H @@ -25,79 +33,353 @@ namespace UserIam { namespace UserAuth { class Attributes final { public: + /** + * @brief The key to set attribute. + */ enum AttributeKey : uint32_t { + /** Root tag. */ ATTR_ROOT = 100000, - ATTR_RESULT_CODE = 100001, // int32_t - ATTR_SIGNATURE = 100004, // std::vector - ATTR_IDENTIFY_MODE = 100005, // uint32_t - ATTR_TEMPLATE_ID = 100006, // uint64_t - ATTR_TEMPLATE_ID_LIST = 100007, // std::vector - ATTR_ERROR_COUNT = 100008, // int32_t - ATTR_REMAIN_TIMES = 100009, // int32_t - ATTR_FREEZING_TIME = 100010, // int32_t - ATTR_SESSION_ID = 100014, // uint64_t - ATTR_SCHEDULE_VERSION = 100016, // uint32_t - ATTR_SCHEDULE_ID = 100020, // uint64_t - ATTR_PIN_SUB_TYPE = 100021, // int32_t - ATTR_SCHEDULE_MODE = 100022, // int32_t - ATTR_PROPERTY_MODE = 100023, // uint32_t - ATTR_AUTH_TYPE = 100024, // int32_t - ATTR_CREDENTIAL_ID = 100025, // uint64_t - ATTR_CALLER_UID = 100027, // uint64_t - ATTR_RESULT = 100028, // std::vector - ATTR_CAPABILITY_LEVEL = 100029, // uint64_t - ATTR_ALGORITHM_INFO = 100030, // uint64_t - ATTR_TIME_STAMP = 100031, // uint64_t - ATTR_ROOT_SECRET = 100032, // std::vector - ATTR_AUTH_TOKEN = 100033, // std::vector + /** Result code, the value type is int32_t. */ + ATTR_RESULT_CODE = 100001, + /** Signature, the value type is std::vector. */ + ATTR_SIGNATURE = 100004, + /** Identify mode, the value type is uint32_t. */ + ATTR_IDENTIFY_MODE = 100005, + /** Template ID, the value type is uint64_t. */ + ATTR_TEMPLATE_ID = 100006, + /** Template ID list, the value type is std::vector. */ + ATTR_TEMPLATE_ID_LIST = 100007, + /** Attribute error count, the value type is int32_t. */ + ATTR_ERROR_COUNT = 100008, + /** Remain time, the value type is int32_t. */ + ATTR_REMAIN_TIMES = 100009, + /** Freezing time, the value type is int32_t. */ + ATTR_FREEZING_TIME = 100010, + /** Session ID, the value type is uint64_t. */ + ATTR_SESSION_ID = 100014, + /** Schedule version, the value type is uint32_t. */ + ATTR_SCHEDULE_VERSION = 100016, + /** Schedule ID, the value type is uint64_t. */ + ATTR_SCHEDULE_ID = 100020, + /** Pin subtype, the value type is int32_t. */ + ATTR_PIN_SUB_TYPE = 100021, + /** Schedule mode, the value type is int32_t. */ + ATTR_SCHEDULE_MODE = 100022, + /** Property mode, the value type is uint32_t. */ + ATTR_PROPERTY_MODE = 100023, + /** Authenticate type, the value type is int32_t. */ + ATTR_AUTH_TYPE = 100024, + /** Credential ID, the value type is uint64_t. */ + ATTR_CREDENTIAL_ID = 100025, + /** Caller UID, the value type is uint64_t. */ + ATTR_CALLER_UID = 100027, + /** Tag of result, the value type is std::vector. */ + ATTR_RESULT = 100028, + /** Capability level, the value type is uint64_t. */ + ATTR_CAPABILITY_LEVEL = 100029, + /** Algorithm infomation, the value type is uint64_t. */ + ATTR_ALGORITHM_INFO = 100030, + /** Timer stamp, the value type is uint64_t. */ + ATTR_TIME_STAMP = 100031, + /** Root secret, the value type is std::vector. */ + ATTR_ROOT_SECRET = 100032, + /** Auth token, the value type is std::vector. */ + ATTR_AUTH_TOKEN = 100033, - // private attrs - ATTR_USER_ID = 300000, // int32_t - ATTR_EXTRA_INFO, // std::vector - ATTR_EXECUTOR_INDEX, // uint64_t - ATTR_EXECUTOR_SENSOR_HINT, // uint32_t - ATTR_EXECUTOR_MATCHER, // uint32_t - ATTR_ACCESS_TOKEN_ID, // uint32_t + /** + * Private attrs. + * User ID, the value type is int32_t. + */ + ATTR_USER_ID = 300000, + /** Extra infomation, the value type is std::vector. */ + ATTR_EXTRA_INFO, + /** Executor ID, the value type is uint64_t. */ + ATTR_EXECUTOR_INDEX, + /** ExecutorSensorHint, the value type is uint32_t. */ + ATTR_EXECUTOR_SENSOR_HINT, + /** ExecutorMatcher, the value type is uint32_t. */ + ATTR_EXECUTOR_MATCHER, + /** Access token ID, the value type is uint32_t. */ + ATTR_ACCESS_TOKEN_ID, }; + /** + * @brief Default constructor. + */ Attributes(); + /** + * @brief Overload constructor. + * + * This constructor prohibits implicit type conversion of input parameters. + * + * @param raw The value to be passed in when defining Attribute. + */ explicit Attributes(const std::vector &raw); + /** + * @brief Overload constructor. + * + * This constructor is used to define constant Attribute type. + * + * @param other The value to be passed in when defining Attribute. + */ Attributes(const Attributes &other) = delete; + + /** + * @brief Overload operator. + * + * @param other The value to be compared. + */ Attributes &operator=(const Attributes &other) = delete; + /** + * @brief Overload constructor. + * + * @param other The value to be passed in when defining Attribute. + */ Attributes(Attributes &&other) noexcept; + + /** + * @brief Overload operator. + * + * @param other The value to be compared. + */ Attributes &operator=(Attributes &&other) noexcept; + /** + * @brief Deconstructor. + */ virtual ~Attributes(); + /** + * @brief Set bool value. + * + * @param key The attribute key. + * @param value The bool value. + * @return Return success or not(true:success; false:failed). + */ bool SetBoolValue(AttributeKey key, bool value); + + /** + * @brief Set uint64 value. + * + * @param key The attribute key. + * @param value The uint64_t value. + * @return Return success or not(true:success; false:failed). + */ bool SetUint64Value(AttributeKey key, uint64_t value); + + /** + * @brief Set uint32_t value. + * + * @param key The attribute key. + * @param value The uint32_t value. + * @return Return success or not(true:success; false:failed). + */ bool SetUint32Value(AttributeKey key, uint32_t value); + + /** + * @brief Set uint16_t value. + * + * @param key The attribute key. + * @param value The uint16_t value. + * @return Return success or not(true:success; false:failed). + */ bool SetUint16Value(AttributeKey key, uint16_t value); + + /** + * @brief Set uint8_t value. + * + * @param key The attribute key. + * @param value The uint8_t value. + * @return Return success or not(true:success; false:failed). + */ bool SetUint8Value(AttributeKey key, uint8_t value); + + /** + * @brief Set int32_t value. + * + * @param key The attribute key. + * @param value The int32_t value. + * @return Return success or not(true:success; false:failed). + */ bool SetInt32Value(AttributeKey key, int32_t value); + + /** + * @brief Set string value. + * + * @param key The attribute key. + * @param value The string. + * @return Return success or not(true:success; false:failed). + */ bool SetStringValue(AttributeKey key, const std::string &value); + + /** + * @brief Set Attributes value. + * + * @param key The attribute key. + * @param value The attributes type value. + * @return Return success or not(true:success; false:failed). + */ bool SetAttributesValue(AttributeKey key, const Attributes &value); + + /** + * @brief Set vector value. + * + * @param key The attribute key. + * @param value The vector value. + * @return Return success or not(true:success; false:failed). + */ bool SetUint64ArrayValue(AttributeKey key, const std::vector &value); + + /** + * @brief Set vector value. + * + * @param key The attribute key. + * @param value The vector value. + * @return Return success or not(true:success; false:failed). + */ bool SetUint32ArrayValue(AttributeKey key, const std::vector &value); + + /** + * @brief Set vector value. + * + * @param key The attribute key. + * @param value The vector value. + * @return Return success or not(true:success; false:failed). + */ bool SetUint16ArrayValue(AttributeKey key, const std::vector &value); + + /** + * @brief Set vector value. + * + * @param key The attribute key. + * @param value The vector value. + * @return Return success or not(true:success; false:failed). + */ bool SetUint8ArrayValue(AttributeKey key, const std::vector &value); + /** + * @brief Get bool value. + * + * @param key The attribute key. + * @param value Return bool value corresponding to key. + * @return Return success or not(true:success; false:failed). + */ bool GetBoolValue(AttributeKey key, bool &value) const; + + /** + * @brief Get uint64_t value. + * + * @param key The attribute key. + * @param value Return uint64_t value corresponding to key. + * @return Return success or not(true:success; false:failed). + */ bool GetUint64Value(AttributeKey key, uint64_t &value) const; + + /** + * @brief Get uint32_t value. + * + * @param key The attribute key. + * @param value Return uint32_t value corresponding to key. + * @return Return success or not(true:success; false:failed). + */ bool GetUint32Value(AttributeKey key, uint32_t &value) const; + + /** + * @brief Get uint16_t value. + * + * @param key The attribute key. + * @param value Return uint16_t value corresponding to key. + * @return Return success or not(true:success; false:failed). + */ bool GetUint16Value(AttributeKey key, uint16_t &value) const; + + /** + * @brief Get uint8_t value. + * + * @param key The attribute key. + * @param value Return uint8_t value corresponding to key. + * @return Return success or not(true:success; false:failed). + */ bool GetUint8Value(AttributeKey key, uint8_t &value) const; + + /** + * @brief Get int32_t value. + * + * @param key The attribute key. + * @param value Return int32_t value corresponding to key. + * @return Return success or not(true:success; false:failed). + */ bool GetInt32Value(AttributeKey key, int32_t &value) const; + + /** + * @brief Get string value. + * + * @param key The attribute key. + * @param value Return string corresponding to key. + * @return Return success or not(true:success; false:failed). + */ bool GetStringValue(AttributeKey key, std::string &value) const; + + /** + * @brief Get vector value. + * + * @param key The attribute key. + * @param value Return vector value corresponding to key. + * @return Return success or not(true:success; false:failed). + */ bool GetUint64ArrayValue(AttributeKey key, std::vector &value) const; + + /** + * @brief Get vector value. + * + * @param key The attribute key. + * @param value Return vector value corresponding to key. + * @return Return success or not(true:success; false:failed). + */ bool GetUint32ArrayValue(AttributeKey key, std::vector &value) const; + + /** + * @brief Get vector value. + * + * @param key The attribute key. + * @param value Return vector value corresponding to key. + * @return Return success or not(true:success; false:failed). + */ bool GetUint16ArrayValue(AttributeKey key, std::vector &value) const; + + /** + * @brief Get vector value. + * + * @param key The attribute key. + * @param value Return vector value corresponding to key. + * @return Return success or not(true:success; false:failed). + */ bool GetUint8ArrayValue(AttributeKey key, std::vector &value) const; + + /** + * @brief Get Attributes value. + * + * @param key The attribute key. + * @param value Return Attributes value corresponding to key. + * @return Return success or not(true:success; false:failed). + */ bool GetAttributesValue(AttributeKey key, Attributes &value) const; + + /** + * @brief Serialize the Attribute object. + * + * @return Return serialized Attribute object. + */ std::vector Serialize() const; + + /** + * @brief Get all keys of Attribute. + * + * @return Return all keys of Attribute. + */ std::vector GetKeys() const; private: diff --git a/interfaces/inner_api/co_auth_client.h b/interfaces/inner_api/co_auth_client.h index cc888e817..356405601 100644 --- a/interfaces/inner_api/co_auth_client.h +++ b/interfaces/inner_api/co_auth_client.h @@ -13,6 +13,14 @@ * limitations under the License. */ +/** + * @file co_auth_client.h + * + * @brief The definition of coAuth client. + * @since 3.1 + * @version 3.2 + */ + #ifndef CO_AUTH_CLIENT_H #define CO_AUTH_CLIENT_H @@ -24,10 +32,31 @@ namespace UserIam { namespace UserAuth { class CoAuthClient { public: + /** + * @brief Get coAuth client's instance. + * + * @return CoAuthClient's instance. + */ static CoAuthClient &GetInstance(); + + /** + * @brief Deconstructor. + */ virtual ~CoAuthClient() = default; + /** + * @brief Executor secure register into coAuth resource pool. + * + * @param info Information about executor which need to register into coAuth. + * @param callback Callback of executor register. + */ virtual void Register(const ExecutorInfo &info, const std::shared_ptr &callback) = 0; + + /** + * @brief Executor secure unregister from coAuth resource pool. + * + * @param info Information about executor which need to unregister from coAuth. + */ virtual void Unregister(const ExecutorInfo &info) = 0; }; } // namespace UserAuth diff --git a/interfaces/inner_api/co_auth_client_callback.h b/interfaces/inner_api/co_auth_client_callback.h index f594c373f..d78135a36 100644 --- a/interfaces/inner_api/co_auth_client_callback.h +++ b/interfaces/inner_api/co_auth_client_callback.h @@ -13,6 +13,14 @@ * limitations under the License. */ +/** + * @file co_auth_client_callback.h + * + * @brief Callback definitions returned by coAuth client. + * @since 3.1 + * @version 3.2 + */ + #ifndef CO_AUTH_CLIENT_CALLBACK_H #define CO_AUTH_CLIENT_CALLBACK_H @@ -24,14 +32,51 @@ namespace UserIam { namespace UserAuth { class ExecutorRegisterCallback { public: + /** + * @brief Called by the coAuth resource pool to tell the executor messenger ready. + * + * @param messenger Messenger used for execute process. + * @param publicKey Public key of the framework. + * @param templateIds Matched templateIds based on authType and executor info. + */ virtual void OnMessengerReady(const std::shared_ptr &messenger, const std::vector &publicKey, const std::vector &templateIds) = 0; + /** + * @brief Called by coAuth resource pool to tell the executor to begin. + * + * @param scheduleId Specify the current schedule. + * @param publicKey Public key of the framework. + * @param commandAttrs Properties of this operation. + * @return Return begin execute success or not(0:success; other:failed). + */ virtual int32_t OnBeginExecute(uint64_t scheduleId, const std::vector &publicKey, const Attributes &commandAttrs) = 0; + + /** + * @brief Notify the executor to end the operation. + * + * @param scheduleId Specify the current schedule. + * @param commandAttrs Properties of this operation. + * @return Return end execute success or not(0:success; other:failed). + */ virtual int32_t OnEndExecute(uint64_t scheduleId, const Attributes &commandAttrs) = 0; + /** + * @brief Called by coAuth resource pool to set executor's property. + * + * @param properties The properties need to set. + * @return Return set property success or not(0:success; other:failed). + */ virtual int32_t OnSetProperty(const Attributes &properties) = 0; + + /** + * @brief Called by coAuth resource pool to get executor's property. + * + * @param conditions The condition to get property. + * @param results The result of get property. + * @return Return get property success or not(0:success; other:failed). + */ virtual int32_t OnGetProperty(const Attributes &conditions, Attributes &results) = 0; }; } // namespace UserAuth diff --git a/interfaces/inner_api/co_auth_client_defines.h b/interfaces/inner_api/co_auth_client_defines.h index 1d75b36d6..5f3cf5dfb 100644 --- a/interfaces/inner_api/co_auth_client_defines.h +++ b/interfaces/inner_api/co_auth_client_defines.h @@ -13,6 +13,14 @@ * limitations under the License. */ +/** + * @file co_auth_client_defines.h + * + * @brief Type definitions used by coAuth client. + * @since 3.1 + * @version 3.2 + */ + #ifndef CO_AUTH_CLIENT_DEFINES_H #define CO_AUTH_CLIENT_DEFINES_H @@ -24,24 +32,59 @@ namespace OHOS { namespace UserIam { namespace UserAuth { +/** + * @brief Infomation used to describe an Executor. + */ struct ExecutorInfo { + /** Authentication type supported by executor. */ AuthType authType {0}; + /** Executor role. */ ExecutorRole executorRole {0}; + /** Unique index of executor within each authType. */ uint32_t executorSensorHint {0}; + /** Sensor or algorithm type supported by executor. */ uint32_t executorMatcher {0}; + /** Executor secure level. */ ExecutorSecureLevel esl {0}; + /** Used to verify the result issued by the authenticator. */ std::vector publicKey {}; }; class AuthMessage { public: + /** + * @brief Function of type conversion. + * + * @param msg Incoming vector type. + * @return Return shared_ptr. + */ static std::shared_ptr As(const std::vector &msg); }; class ExecutorMessenger { public: + /** + * @brief Called by the executor, send authentication data to resource pool. + * + * @param scheduleId Specify the current schedule. + * @param transNum Properties of this operation. + * @param srcRole Source executor role. + * @param dstRole Destination executor role. + * @param msg Authentication message. + * @return Return send data success or not(0:success; other:failed). + */ virtual int32_t SendData(uint64_t scheduleId, uint64_t transNum, ExecutorRole srcRole, ExecutorRole dstRole, const std::shared_ptr &msg) = 0; + + /** + * @brief Called by the executor, send finish data to resource pool. + * + * @param scheduleId Specify the current schedule. + * @param srcRole Source executor role. + * @param resultcode Authentication result code. + * @param finalResult Authentication final result. + * @return Return finish success or not(0:success; other:failed). + */ virtual int32_t Finish(uint64_t scheduleId, ExecutorRole srcRole, int32_t resultCode, const Attributes &finalResult) = 0; }; diff --git a/interfaces/inner_api/iam_common_defines.h b/interfaces/inner_api/iam_common_defines.h index a6ecc3067..a25f1a16f 100644 --- a/interfaces/inner_api/iam_common_defines.h +++ b/interfaces/inner_api/iam_common_defines.h @@ -13,85 +13,167 @@ * limitations under the License. */ +/** + * @file iam_common_defines.h + * + * @brief Some common defines in IAM. + * @since 3.1 + * @version 3.2 + */ + #ifndef IAM_COMMON_DEFINES_H #define IAM_COMMON_DEFINES_H namespace OHOS { namespace UserIam { namespace UserAuth { +/** Max length of challenge. */ constexpr size_t MAX_CHALLENG_LEN = 32; +/** + * @brief Defines authentication type. + */ enum AuthType : int32_t { + /** All authentication types. */ ALL = 0, + /** Pin authentication. */ PIN = 1, + /** Face authentication. */ FACE = 2, + /** Fingerprint authentication. */ FINGERPRINT = 4, }; +/** + * @brief Defines pin auth's subtype. + */ enum PinSubType : int32_t { + /** Digit password with fixed length of six. */ PIN_SIX = 10000, + /** Digit password with unfixed length. */ PIN_NUMBER = 10001, + /** Complex password with number and alphabet. */ PIN_MIXED = 10002, + /** Max pin. */ PIN_MAX, }; +/** + * @brief Enumerates executor roles. + */ enum ExecutorRole : int32_t { + /** Scheduler executor. */ SCHEDULER = 0, + /** The executor acts as a collector. */ COLLECTOR = 1, + /** The executor acts as a verifier. */ VERIFIER = 2, + /** The executor acts as a collector and verifier. */ ALL_IN_ONE = 3, }; +/** + * @brief Enumerates executor security levels. + */ enum ExecutorSecureLevel : int32_t { + /** Executor secure level 0. */ ESL0 = 0, + /** Executor secure level 1. */ ESL1 = 1, + /** Executor secure level 2. */ ESL2 = 2, + /** Executor secure level 3. */ ESL3 = 3, }; +/** + * @brief Authentication trust level + */ enum AuthTrustLevel : uint32_t { + /** Auth trust level 1. */ ATL1 = 10000, + /** Auth trust level 2. */ ATL2 = 20000, + /** Auth trust level 3. */ ATL3 = 30000, + /** Auth trust level 4. */ ATL4 = 40000, }; +/** + * @brief Schedule mode. + */ enum ScheduleMode : int32_t { + /** The schedule mode is enrollment. */ ENROLL = 0, + /** The schedule mode is authentication. */ AUTH = 1, + /** The schedule mode is identification. */ IDENTIFY = 2, }; +/** + * @brief Property mode. + */ enum PropertyMode : uint32_t { + /** The property mode is init algorithm. */ PROPERTY_INIT_ALGORITHM = 1, + /** The property mode is delete. */ PROPERTY_MODE_DEL = 2, + /** The property mode is get. */ PROPERTY_MODE_GET = 3, + /** The property mode is set. */ PROPERTY_MODE_SET = 4, + /** The property mode is freeze. */ PROPERTY_MODE_FREEZE = 5, + /** The property mode is unfreeze. */ PROPERTY_MODE_UNFREEZE = 6, }; +/** + * @brief The result code. + */ enum ResultCode : int32_t { + /** The result is success. */ SUCCESS = 0, + /** Compile fail. */ FAIL = 1, + /** The result is fail, because an unknown error occurred. */ GENERAL_ERROR = 2, + /** The result is fail, because the request was canceled. */ CANCELED = 3, + /** The result is fail ,because of time out. */ TIMEOUT = 4, + /** The result is fail ,because type is not support. */ TYPE_NOT_SUPPORT = 5, + /** The result is fail ,because trust level is not support. */ TRUST_LEVEL_NOT_SUPPORT = 6, + /** The result is fail, because the service was busy. */ BUSY = 7, + /** The result is fail, because parameters is invalid. */ INVALID_PARAMETERS = 8, + /** The result if fail, because the status is locked. */ LOCKED = 9, + /** The result is fail, because the user was not enrolled. */ NOT_ENROLLED = 10, + /** The result is fail, because the hardware is not supported. */ HARDWARE_NOT_SUPPORTED = 11, - SYSTEM_ERROR_CODE_BEGIN = 1000, // error code for system + /** The result is fail, because something wrong from system. */ + SYSTEM_ERROR_CODE_BEGIN = 1000, + /** The result is fail, because something wrong from ipc. */ IPC_ERROR = 1001, + /** The result is fail, because the context ID is invalid. */ INVALID_CONTEXT_ID = 1002, + /** The result is fail, because something wrong when read parcel. */ READ_PARCEL_ERROR = 1003, + /** The result is fail, because something wrong when write parcel. */ WRITE_PARCEL_ERROR = 1004, + /** The result is fail, because permission check is failed. */ CHECK_PERMISSION_FAILED = 1005, + /** The result is fail, because the hdi interface is invalid. */ INVALID_HDI_INTERFACE = 1006, - VENDOR_ERROR_CODE_BEGIN = 10000, // error code for vendor + /** The result is fail, because something wrong from vendor. */ + VENDOR_ERROR_CODE_BEGIN = 10000, }; } // namespace UserAuth } // namespace UserIam diff --git a/interfaces/inner_api/iam_executor/iam_executor_framework_types.h b/interfaces/inner_api/iam_executor/iam_executor_framework_types.h index 7538b3aea..f342582f3 100644 --- a/interfaces/inner_api/iam_executor/iam_executor_framework_types.h +++ b/interfaces/inner_api/iam_executor/iam_executor_framework_types.h @@ -13,6 +13,14 @@ * limitations under the License. */ +/** + * @file iam_executor_framework_types.h + * + * @brief Some type defines in executor framwork. + * @since 3.1 + * @version 3.2 + */ + #ifndef IAM_EXECUTOR_FRAMEWORK_TYPES_H #define IAM_EXECUTOR_FRAMEWORK_TYPES_H @@ -22,15 +30,27 @@ namespace OHOS { namespace UserIam { namespace UserAuth { +/** + * @brief Defines authentication result. + */ enum UserAuthResult : int32_t { + /** Authentication result is success. */ USERAUTH_SUCCESS = 0, + /** Authentication result is error. */ USERAUTH_ERROR = 1, }; +/** + * @brief Defines Template infomation. + */ struct TemplateInfo { + /** Executor type. */ uint32_t executorType; + /** Freezing time. */ int32_t freezingTime; + /** Remain time. */ int32_t remainTimes; + /** Extra Info. */ std::vector extraInfo; }; } // namespace UserAuth diff --git a/interfaces/inner_api/iam_executor/iam_executor_iauth_driver_hdi.h b/interfaces/inner_api/iam_executor/iam_executor_iauth_driver_hdi.h index 6173f44af..e6482ecd6 100644 --- a/interfaces/inner_api/iam_executor/iam_executor_iauth_driver_hdi.h +++ b/interfaces/inner_api/iam_executor/iam_executor_iauth_driver_hdi.h @@ -13,6 +13,14 @@ * limitations under the License. */ +/** + * @file iam_executor_iauth_driver_hdi.h + * + * @brief Hardware device interface for authenticate driver. + * @since 3.1 + * @version 3.2 + */ + #ifndef IAM_EXECUTOR_IAUTH_DRIVER_HDI_H #define IAM_EXECUTOR_IAUTH_DRIVER_HDI_H @@ -27,9 +35,21 @@ namespace UserIam { namespace UserAuth { class IAuthDriverHdi { public: + /** + * @brief Default constructor. + */ IAuthDriverHdi() = default; + + /** + * @brief Deconstructor. + */ virtual ~IAuthDriverHdi() = default; + /** + * @brief Get the list of executor. + * + * @param executorList The list of executor. + */ virtual void GetExecutorList(std::vector> &executorList) = 0; }; } // namespace UserAuth diff --git a/interfaces/inner_api/iam_executor/iam_executor_iauth_executor_hdi.h b/interfaces/inner_api/iam_executor/iam_executor_iauth_executor_hdi.h index 3b2ee113a..f4c278468 100644 --- a/interfaces/inner_api/iam_executor/iam_executor_iauth_executor_hdi.h +++ b/interfaces/inner_api/iam_executor/iam_executor_iauth_executor_hdi.h @@ -13,6 +13,14 @@ * limitations under the License. */ +/** + * @file iam_executor_iauth_executor_hdi.h + * + * @brief Hardware device interface for authenticate executor. + * @since 3.1 + * @version 3.2 + */ + #ifndef IAM_EXECUTOR_IAUTH_EXECUTOR_HDI_H #define IAM_EXECUTOR_IAUTH_EXECUTOR_HDI_H @@ -29,22 +37,105 @@ namespace UserIam { namespace UserAuth { class IAuthExecutorHdi { public: + /** + * @brief Default constructor. + */ IAuthExecutorHdi() = default; + + /** + * @brief Deconstructor. + */ virtual ~IAuthExecutorHdi() = default; + /** + * @brief Get executor infomation. + * + * @param info The executor infomation. + * @return Return the result success or error code{@link ResultCode}. + */ virtual ResultCode GetExecutorInfo(ExecutorInfo &info) = 0; + + /** + * @brief Get template infomation. + * + * @param templateId Template id. + * @param info The template infomation. + * @return Return the result success or error code{@link ResultCode}. + */ virtual ResultCode GetTemplateInfo(uint64_t templateId, UserAuth::TemplateInfo &info) = 0; + + /** + * @brief Register is finish. + * + * @param templateIdList Template ID list. + * @param frameworkPublicKey Framework publickey + * @param extraInfo Extra infomation. + * @return Return the result success or error code{@link ResultCode}. + */ virtual ResultCode OnRegisterFinish(const std::vector &templateIdList, const std::vector &frameworkPublicKey, const std::vector &extraInfo) = 0; + + /** + * @brief Begin enroll. + * + * @param scheduleId Current enroll schedule ID. + * @param tokenId Current enroll token ID. + * @param extraInfo Extra information of enroll. + * @param callbackObj Callback of enroll result. + * @return Return the result success or error code{@link ResultCode}. + */ virtual ResultCode Enroll(uint64_t scheduleId, uint32_t tokenId, const std::vector &extraInfo, const std::shared_ptr &callbackObj) = 0; + + /** + * @brief Begin authenticate. + * + * @param scheduleId Current authenticate schedule ID. + * @param tokenId Current authenticate token ID. + * @param templateIdList Template ID list. + * @param extraInfo Extra information of authenticate. + * @param callbackObj Callback of authenticate result. + * @return Return the result success or error code{@link ResultCode}. + */ virtual ResultCode Authenticate(uint64_t scheduleId, uint32_t tokenId, const std::vector &templateIdList, const std::vector &extraInfo, const std::shared_ptr &callbackObj) = 0; - virtual ResultCode Identify(uint64_t scheduleId, uint32_t tokenId, const std::vector &extraInfo, + /** + * @brief Begin identify. + * + * @param scheduleId Current identify schedule ID. + * @param tokenId Current identify token ID. + * @param extraInfo Extra information of identify. + * @param callbackObj Callback of identify result. + * @return Return the result success or error code{@link ResultCode}. + */ + virtual ResultCode Identify(uint64_t scheduleId, uint32_t tokenId, const std::vector &extraInfo, const std::shared_ptr &callbackObj) = 0; + + /** + * @brief Delete. + * + * @param templateIdList Template ID list. + * @return Return the result success or error code{@link ResultCode}. + */ virtual ResultCode Delete(const std::vector &templateIdList) = 0; + + /** + * @brief Cancel the action of executor. + * + * @param scheduleId Current working schedule ID. + * @return Return the result success or error code{@link ResultCode}. + */ virtual ResultCode Cancel(uint64_t scheduleId) = 0; + + /** + * @brief Send command. + * + * @param commandId Command ID. + * @param extraInfo Extra information of send command. + * @param callbackObj Callback of send command result. + * @return Return the result success or error code{@link ResultCode}. + */ virtual ResultCode SendCommand(PropertyMode commandId, const std::vector &extraInfo, const std::shared_ptr &callbackObj) = 0; }; diff --git a/interfaces/inner_api/iam_executor/iam_executor_idriver_manager.h b/interfaces/inner_api/iam_executor/iam_executor_idriver_manager.h index a14e0bb85..6051a5d0e 100644 --- a/interfaces/inner_api/iam_executor/iam_executor_idriver_manager.h +++ b/interfaces/inner_api/iam_executor/iam_executor_idriver_manager.h @@ -13,6 +13,14 @@ * limitations under the License. */ +/** + * @file iam_executor_idriver_manager.h + * + * @brief Driver manager of executor. + * @since 3.1 + * @version 3.2 + */ + #ifndef IAM_EXECUTOR_IDRIVER_MANAGER_H #define IAM_EXECUTOR_IDRIVER_MANAGER_H @@ -24,16 +32,34 @@ namespace OHOS { namespace UserIam { namespace UserAuth { +/** + * @brief Hardware device interface config. + */ struct HdiConfig { + /** Driver ID. */ uint16_t id; // non-zero + /** The current driver. */ std::shared_ptr driver; }; class IDriverManager { public: + /** + * @brief Default constructor. + */ IDriverManager() = default; + + /** + * @brief Deconstructor. + */ virtual ~IDriverManager() = default; + /** + * @brief Start. + * + * @param hdiName2Config Hardware device interface name and config. + * @return Return the result success or not. + */ static int32_t Start(const std::map &hdiName2Config); }; } // namespace UserAuth diff --git a/interfaces/inner_api/iam_executor/iam_executor_iexecute_callback.h b/interfaces/inner_api/iam_executor/iam_executor_iexecute_callback.h index f1730493c..4fbd86ad4 100644 --- a/interfaces/inner_api/iam_executor/iam_executor_iexecute_callback.h +++ b/interfaces/inner_api/iam_executor/iam_executor_iexecute_callback.h @@ -13,6 +13,14 @@ * limitations under the License. */ +/** + * @file iam_executor_idriver_manager.h + * + * @brief Driver manager of executor. + * @since 3.1 + * @version 3.2 + */ + #ifndef IAM_EXECUTOR_IEXECUTE_CALLBACK_H #define IAM_EXECUTOR_IEXECUTE_CALLBACK_H @@ -27,11 +35,38 @@ namespace UserAuth { class IExecuteCallback { public: using ResultCode = UserIam::UserAuth::ResultCode; + + /** + * @brief Default constructor. + */ IExecuteCallback() = default; + + /** + * @brief Deconstructor. + */ virtual ~IExecuteCallback() = default; + /** + * @brief The callback return execute result. + * + * @param result The result success or error code{@link ResultCode}. + * @param extraInfo Other related information about execute. + */ virtual void OnResult(ResultCode result, const std::vector &extraInfo) = 0; + + /** + * @brief The callback return execute result. + * + * @param result The result success or error code{@link ResultCode}. + */ virtual void OnResult(ResultCode result) = 0; + + /** + * @brief The callback return authenticate acquire information. + * + * @param acquireInfo Acquire info needed to be pass in. + * @param extraInfo Other related information about execute. + */ virtual void OnAcquireInfo(int32_t acquire, const std::vector &extraInfo) = 0; }; } // namespace UserAuth diff --git a/interfaces/inner_api/user_auth_client.h b/interfaces/inner_api/user_auth_client.h index 9a510c4b4..044a72b16 100644 --- a/interfaces/inner_api/user_auth_client.h +++ b/interfaces/inner_api/user_auth_client.h @@ -13,6 +13,14 @@ * limitations under the License. */ +/** + * @file user_auth_client.h + * + * @brief The definition of user auth client. + * @since 3.1 + * @version 3.2 + */ + #ifndef USER_AUTH_CLIENT_H #define USER_AUTH_CLIENT_H @@ -27,20 +35,76 @@ namespace UserIam { namespace UserAuth { class UserAuthClient { public: + /** + * @brief Get userAuth client's instance. + * + * @return UserAuthClient's instance. + */ static UserAuthClient &GetInstance(); + + /** + * @brief Deconstructor. + */ virtual ~UserAuthClient() = default; + /** + * @brief Get executor property. + * + * @param userId System userId, generated by account subsystem. + * @param request AuthType and AttributeKey to get property. + * @param callback Callback of get property result. + */ virtual void GetProperty(int32_t userId, const GetPropertyRequest &request, const std::shared_ptr &callback) = 0; + + /** + * @brief Set executor property. + * + * @param userId System userId, generated by account subsystem. + * @param request AuthType, propertyMode and attributes to set property. + * @param callback Callback of set property result. + */ virtual void SetProperty(int32_t userId, const SetPropertyRequest &request, const std::shared_ptr &callback) = 0; + /** + * @brief Begin user authentication according to ATL and authType. + * + * @param userId System userId, generated by account subsystem. + * @param challenge auth challenge which can prevent replay attacks. + * @param authType Auth type supported by executor. + * @param atl Auth trust level. + * @param callback Callback of user authentication result. + * @return Return context ID of authentication. + */ virtual uint64_t BeginAuthentication(int32_t userId, const std::vector &challenge, AuthType authType, AuthTrustLevel atl, const std::shared_ptr &callback) = 0; + + /** + * @brief Cancel user authentication. + * + * @param contextId Indicates the authenticate context index. + * @return Return cancelAuthentication result(0:success; other:failed). + */ virtual int32_t CancelAuthentication(uint64_t contextId) = 0; + /** + * @brief Begin user identification according to authType. + * + * @param challenge auth challenge which can prevent replay attacks. + * @param authType Auth type supported by executor. + * @param callback Callback of user identification result. + * @return Return context ID of authentication. + */ virtual uint64_t BeginIdentification(const std::vector &challenge, AuthType authType, const std::shared_ptr &callback) = 0; + + /** + * @brief Cancel user identification. + * + * @param contextId Indicates the identification context index. + * @return Return CancelIdentification result(0:success; other:failed). + */ virtual int32_t CancelIdentification(uint64_t contextId) = 0; }; } // namespace UserAuth diff --git a/interfaces/inner_api/user_auth_client_callback.h b/interfaces/inner_api/user_auth_client_callback.h index 42a6a9a4f..172246974 100644 --- a/interfaces/inner_api/user_auth_client_callback.h +++ b/interfaces/inner_api/user_auth_client_callback.h @@ -13,6 +13,14 @@ * limitations under the License. */ +/** + * @file user_auth_client_callback.h + * + * @brief Callback definitions returned by user auth client. + * @since 3.1 + * @version 3.2 + */ + #ifndef USER_AUTH_CLIENT_CALLBACK_H #define USER_AUTH_CLIENT_CALLBACK_H @@ -24,23 +32,63 @@ namespace UserIam { namespace UserAuth { class AuthenticationCallback { public: + /** + * @brief The callback return authenticate acquire information. + * + * @param module Module of current acquire info. + * @param acquireInfo Acquire info needed to be pass in. + * @param extraInfo Other related information about authentication. + */ virtual void OnAcquireInfo(int32_t module, uint32_t acquireInfo, const Attributes &extraInfo) = 0; + + /** + * @brief The callback return authenticate result. + * + * @param result The result success or error code{@link ResultCode}. + * @param extraInfo Other related information about authentication. + */ virtual void OnResult(int32_t result, const Attributes &extraInfo) = 0; }; class IdentificationCallback { public: + /** + * @brief The callback return identification acquire information. + * + * @param module Module of current acquire info. + * @param acquireInfo Acquire info needed to be pass in. + * @param extraInfo Other related information about identification. + */ virtual void OnAcquireInfo(int32_t module, uint32_t acquireInfo, const Attributes &extraInfo) = 0; + + /** + * @brief The callback return identification result. + * + * @param result The result success or error code{@link ResultCode}. + * @param extraInfo Other related information about identification. + */ virtual void OnResult(int32_t result, const Attributes &extraInfo) = 0; }; class GetPropCallback { public: + /** + * @brief The callback return get property result. + * + * @param result The result success or error code{@link ResultCode}. + * @param extraInfo Other related information about get property. + */ virtual void OnResult(int32_t result, const Attributes &extraInfo) = 0; }; class SetPropCallback { public: + /** + * @brief The callback return set property result. + * + * @param result The result success or error code{@link ResultCode}. + * @param extraInfo Other related information about set property. + */ virtual void OnResult(int32_t result, const Attributes &extraInfo) = 0; }; } // namespace UserAuth diff --git a/interfaces/inner_api/user_auth_client_defines.h b/interfaces/inner_api/user_auth_client_defines.h index a33e8eae4..9cc520f30 100644 --- a/interfaces/inner_api/user_auth_client_defines.h +++ b/interfaces/inner_api/user_auth_client_defines.h @@ -13,6 +13,14 @@ * limitations under the License. */ +/** + * @file co_auth_client_defines.h + * + * @brief Type definitions used by user auth client. + * @since 3.1 + * @version 3.2 + */ + #ifndef USER_AUTH_CLIENT_DEFINES_H #define USER_AUTH_CLIENT_DEFINES_H @@ -22,14 +30,25 @@ namespace OHOS { namespace UserIam { namespace UserAuth { +/** + * @brief Executor property needed to get. + */ struct GetPropertyRequest { + /** Auth type supported by executor. */ AuthType authType {0}; + /** The keys of attribute needed to get. */ std::vector keys {}; }; +/** + * @brief Executor property needed to set. + */ struct SetPropertyRequest { + /** Auth type supported by executor. */ AuthType authType {0}; + /** The executor's property mode. */ PropertyMode mode {0}; + /** The attributes needed to set. */ Attributes attrs {}; }; } // namespace UserAuth diff --git a/interfaces/inner_api/user_idm_client.h b/interfaces/inner_api/user_idm_client.h index 86d223557..939ce610b 100644 --- a/interfaces/inner_api/user_idm_client.h +++ b/interfaces/inner_api/user_idm_client.h @@ -13,6 +13,14 @@ * limitations under the License. */ +/** + * @file user_idm_client.h + * + * @brief The definition of idm client. + * @since 3.1 + * @version 3.2 + */ + #ifndef USER_IDM_CLIENT_H #define USER_IDM_CLIENT_H @@ -29,27 +37,118 @@ namespace UserIam { namespace UserAuth { class UserIdmClient { public: + /** + * @brief Get userIdm client's instance. + * + * @return UserIdmClient's instance. + */ static UserIdmClient &GetInstance(); + + /** + * @brief Deconstructor. + */ virtual ~UserIdmClient() = default; + /** + * @brief Open session with user identity management. + * + * User identity Management can be used only after the session is open, + * and the session is valid for ten minutes. + * @param userId System userId, generated by account subsystem. + * @return Return the challenge. + */ virtual std::vector OpenSession(int32_t userId) = 0; + + /** + * @brief Open session with user identity management. + * + * @param userId System userId, generated by account subsystem. + */ virtual void CloseSession(int32_t userId) = 0; + /** + * @brief Add user credential information. + * + * @param userId System userId, generated by account subsystem. + * @param para Include authType, pinSubType and token. + * @param callback Callback of add credential result. + */ virtual void AddCredential(int32_t userId, const CredentialParameters ¶, const std::shared_ptr &callback) = 0; + + /** + * @brief Update user credential information. + * + * @param userId System userId, generated by account subsystem. + * @param para Include authType, pinSubType and token(PIN). + * @param callback Callback of update credential result. + */ virtual void UpdateCredential(int32_t userId, const CredentialParameters ¶, const std::shared_ptr &callback) = 0; + + /** + * @brief Cancel add user credential. + * + * @param userId System userId, generated by account subsystem. + * @return Return Cancel result(0:success; other:failed). + */ virtual int32_t Cancel(int32_t userId) = 0; + /** + * @brief Delete user's credential according to credentialId. + * + * Only support to delete non-password credentials. + * + * @param userId System userId, generated by account subsystem. + * @param credentialId User credentialId. + * @param authToken PIN auth token. + * @param callback Callback of delete credential result. + */ virtual void DeleteCredential(int32_t userId, uint64_t credentialId, const std::vector &authToken, const std::shared_ptr &callback) = 0; + /** + * @brief Delete user's PIN. + * + * When deleting user's PIN, all credentials of the user will be deleted. + * + * @param userId System userId, generated by account subsystem. + * @param authToken PIN auth token. + * @param callback Callback of delete user's credential result. + */ virtual void DeleteUser(int32_t userId, const std::vector &authToken, const std::shared_ptr &callback) = 0; + + /** + * @brief Erase user. + * + * This method is used for administrators to delete user and + * delete all credentials of the user at the same time. + * + * @param userId System userId, generated by account subsystem. + * @param callback Callback of erase user result. + * @return Return erase user success or not(0:success; other:failed). + */ virtual int32_t EraseUser(int32_t userId, const std::shared_ptr &callback) = 0; + /** + * @brief get user's credential information. + * + * @param userId System userId, generated by account subsystem. + * @param authType Authtype supported by executor. + * @param callback Callback of get credentialInfo result. + * @return Return get credentialInfo success or not(0:success; other:failed). + */ virtual int32_t GetCredentialInfo(int32_t userId, AuthType authType, const std::shared_ptr &callback) = 0; + + /** + * @brief get security user information. + * + * @param userId System userId, generated by account subsystem. + * @param callback Return get security userInfo result. + * @return Return get security userInfo success or not(0:success; other:failed). + */ virtual int32_t GetSecUserInfo(int32_t userId, const std::shared_ptr &callback) = 0; }; } // namespace UserAuth diff --git a/interfaces/inner_api/user_idm_client_callback.h b/interfaces/inner_api/user_idm_client_callback.h index d851a61ec..021cfad08 100644 --- a/interfaces/inner_api/user_idm_client_callback.h +++ b/interfaces/inner_api/user_idm_client_callback.h @@ -13,6 +13,14 @@ * limitations under the License. */ +/** + * @file user_idm_client_callback.h + * + * @brief Callback definitions returned by idm client. + * @since 3.1 + * @version 3.2 + */ + #ifndef USER_IDM_CLIENT_CALLBACK_H #define USER_IDM_CLIENT_CALLBACK_H @@ -25,17 +33,41 @@ namespace UserIam { namespace UserAuth { class GetCredentialInfoCallback { public: + /** + * @brief The callback return get credential info result. + * + * @param infoList The credential info list. + */ virtual void OnCredentialInfo(const std::vector &infoList) = 0; }; class GetSecUserInfoCallback { public: + /** + * @brief The callback return get security user info result. + * + * @param info The security user info. + */ virtual void OnSecUserInfo(const SecUserInfo &info) = 0; }; class UserIdmClientCallback { public: + /** + * @brief The callback return authenticate acquire information. + * + * @param module Module of current acquire info. + * @param acquireInfo Acquire info needed to be pass in. + * @param extraInfo Other related information about authentication. + */ virtual void OnAcquireInfo(int32_t module, uint32_t acquireInfo, const Attributes &extraInfo) = 0; + + /** + * @brief The callback return set property result. + * + * @param result The result success or error code{@link ResultCode}. + * @param extraInfo Other related information about set property. + */ virtual void OnResult(int32_t result, const Attributes &extraInfo) = 0; }; } // namespace UserAuth diff --git a/interfaces/inner_api/user_idm_client_defines.h b/interfaces/inner_api/user_idm_client_defines.h index f81fd2f4a..b0e2972ae 100644 --- a/interfaces/inner_api/user_idm_client_defines.h +++ b/interfaces/inner_api/user_idm_client_defines.h @@ -13,6 +13,14 @@ * limitations under the License. */ +/** + * @file user_idm_client_defines.h + * + * @brief Type definitions used by idm client. + * @since 3.1 + * @version 3.2 + */ + #ifndef USER_IDM_CLIENT_DEFINES_H #define USER_IDM_CLIENT_DEFINES_H @@ -23,26 +31,49 @@ namespace OHOS { namespace UserIam { namespace UserAuth { +/** + * @brief User credential infomation returned. + */ struct CredentialInfo { + /* Auth type supported by executor. */ AuthType authType {0}; + /* Auth subtype of PIN. */ std::optional pinType {}; + /* User credentialId is generated by idm to associate userId and templateId. */ uint64_t credentialId {0}; + /* User templateId is generated by executor to represent user characteristics. */ uint64_t templateId {0}; }; +/** + * @brief Define credential enrollment information. + */ struct EnrolledInfo { + /** Auth type supported by executor. */ AuthType authType {0}; + /** Enrolled ID. */ uint64_t enrolledId {0}; }; +/** + * @brief Define security user information. + */ struct SecUserInfo { + /** Security user ID. */ uint64_t secureUid {0}; + /** The user credential enrollment infomation. */ std::vector enrolledInfo {}; }; +/** + * @brief Parameters needed to set about user credential information. + */ struct CredentialParameters { + /** Auth type supported by executor. */ AuthType authType {0}; + /** Auth subtype of PIN. */ std::optional pinType {}; + /** Auth token. */ std::vector token {}; }; } // namespace UserAuth