diff --git a/en/device_api/hdi/face_auth/FaceAuthTypes.idl b/en/device_api/hdi/face_auth/FaceAuthTypes.idl new file mode 100644 index 0000000000000000000000000000000000000000..b945c81f9b9fcb5180b3da51835612885fdaef98 --- /dev/null +++ b/en/device_api/hdi/face_auth/FaceAuthTypes.idl @@ -0,0 +1,138 @@ +/* + * Copyright (c) 2022 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 HdfFaceAuth + * @{ + * + * @brief Provides APIs for the face auth driver. + * + * The face auth driver provides a unified interface for the face auth service to access the face auth driver. + * After obtaining the face auth driver proxy, the service can call related APIs to obtain executors. + * After obtaining the face auth executors, the service can call related APIs to get executor info, get + * template info, enroll template, authenticate template, delete template, etc. + * + * @since 3.2 + */ + +/** + * @file FaceAuthTypes.idl + * + * @brief Defines face auth driver enumeration and data structure, including AuthType, ExecutorRole, ExecutorSecureLevel, + * CommandId, FaceTipsCode, ExecutorInfo and TemplateInfo. + * + * @since 3.2 + */ + +package ohos.hdi.face_auth.v1_0; + +/** + * Enumerates credential type for authentication. + * + * @since 3.2 + * @version 1.0 + */ +enum AuthType : int { + PIN = 1, /**< Indicates authentication type is PIN. */ + FACE = 2, /**< Indicates authentication type is face. */ + FINGERPRINT = 3, /**< Indicates authentication type is fingerprint. */ +}; + +/** + * Enumerates executor role. + * + * @since 3.2 + * @version 1.0 + */ +enum ExecutorRole : int { + COLLECTOR = 1, /**< Indicates executor role is collector. */ + VERIFIER = 2, /**< Indicates executor role is verifier. */ + ALL_IN_ONE = 3, /**< Indicates executor role is combination of collector and verifier, cannot be used as collector or verifier. */ +}; + +/** + * Enumerates executor secure level. + * + * @since 3.2 + * @version 1.0 + */ +enum ExecutorSecureLevel : int { + ESL0 = 0, /**< Indicates executor secure level is ESL0. */ + ESL1 = 1, /**< Indicates executor secure level is ESL1. */ + ESL2 = 2, /**< Indicates executor secure level is ESL2. */ + ESL3 = 3, /**< Indicates executor secure level is ESL3. */ +}; + +/** + * Enumerates command id. + * + * @since 3.2 + * @version 1.0 + */ +enum CommandId : int { + LOCK_TEMPLATE = 1, /**< Indicates lock template command id. */ + UNLOCK_TEMPLATE = 2, /**< Indicates unlock template command id. */ + VENDOR_COMMAND_BEGIN = 10000 /**< Vendor may add custom command id after this. */ +}; + +/** + * Enumerates prompt codes. + * + * @since 3.2 + * @version 1.0 + */ +enum FaceTipsCode : int { + FACE_AUTH_TIP_TOO_BRIGHT = 1, /**< Indicates that the obtained facial image is too bright due to high illumination. */ + FACE_AUTH_TIP_TOO_DARK = 2, /**< Indicates that the obtained facial image is too dark due to low illumination. */ + FACE_AUTH_TIP_TOO_CLOSE = 3, /**< Indicates that the face is too close to the device. */ + FACE_AUTH_TIP_TOO_FAR = 4, /**< Indicates that the face is too far away from the device. */ + FACE_AUTH_TIP_TOO_HIGH = 5, /**< Indicates that the device is too high, and that only the upper part of the face is captured. */ + FACE_AUTH_TIP_TOO_LOW = 6, /**< Indicates that the device is too low, and that only the lower part of the face is captured. */ + FACE_AUTH_TIP_TOO_RIGHT = 7, /**< Indicates that the device is deviated to the right, and that only the right part of the face is captured. */ + FACE_AUTH_TIP_TOO_LEFT = 8, /**< Indicates that the device is deviated to the left, and that only the left part of the face is captured. */ + FACE_AUTH_TIP_TOO_MUCH_MOTION = 9, /**< Indicates that the face moves too much during facial information collection. */ + FACE_AUTH_TIP_POOR_GAZE = 10, /**< Indicates the user is not gazing at the device. */ + FACE_AUTH_TIP_NOT_DETECTED = 11, /**< Indicates that no face is detected. */ + VENDOR_FACE_AUTH_TIP_BEGIN = 10000 /**< Vendor may add custom face auth tip after this. */ +}; + +/** + * Indicates the executor info. + * + * @since 3.2 + * @version 1.0 + */ +struct ExecutorInfo { + unsigned short sensorId; /**< Indicates sensor id. Sensor id must be unique in driver. */ + unsigned int executorType; /**< Indicates executor type. */ + enum ExecutorRole executorRole; /**< Indicates executor role, see @{ExecutorRole}. */ + enum AuthType authType; /**< Indicates auth type, see @{AuthType}. */ + enum ExecutorSecureLevel esl; /**< Indicates executor secure level, see @{ExecutorSecureLevel}. */ + unsigned char[] publicKey; /**< Indicates publicKey. */ + unsigned char[] extraInfo; /**< Indicates extra info. */ +}; + +/** + * Indicates the template info. + * + * @since 3.2 + * @version 1.0 + */ +struct TemplateInfo { + unsigned int executorType; /**< Indicates executor type. */ + int freezingTime; /**< Indicates freezing time in seconds. */ + int remainTimes; /**< Indicates remain times before a lockout. */ + unsigned char[] extraInfo; /**< Indicates extra info. */ +}; \ No newline at end of file diff --git a/en/device_api/hdi/face_auth/IExecutor.idl b/en/device_api/hdi/face_auth/IExecutor.idl new file mode 100644 index 0000000000000000000000000000000000000000..2164de737adbeb4c8f8bb398cd95212e33757f38 --- /dev/null +++ b/en/device_api/hdi/face_auth/IExecutor.idl @@ -0,0 +1,145 @@ +/* + * Copyright (c) 2022 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 HdfFaceAuth + * @{ + * + * @brief Provides APIs for the face auth driver. + * + * The face auth driver provides a unified interface for the face auth service to access the face auth driver. + * After obtaining the face auth driver proxy, the service can call related APIs to obtain executors. + * After obtaining the face auth executors, the service can call related APIs to get executor info, get + * template info, enroll template, authenticate template, delete template, etc. + * + * @since 3.2 + */ + +/** + * @file IExecutor.idl + * + * @brief Defines the APIs of executor. These APIs can be used to get executor info, get + * template info, enroll template, authenticate template, delete template, etc. + * + * @since 3.2 + */ + +package ohos.hdi.face_auth.v1_0; + +import ohos.hdi.face_auth.v1_0.FaceAuthTypes; +import ohos.hdi.face_auth.v1_0.IExecutorCallback; + +/** + * @brief Defines the APIs of executor. These APIs can be used to get executor info, get + * template info, enroll template, authenticate template, delete template, etc. + * + * @since 3.2 + * @version 1.0 + */ +interface IExecutor { + /** + * @brief Get executor info. + * + * @param executorInfo Indicates executor info, see {@link ExecutorInfo}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + GetExecutorInfo([out] struct ExecutorInfo executorInfo); + /** + * @brief Get template info. + * + * @param templateId Indicates template id. + * @param templateInfo Indicates template info, see {@link TemplateInfo}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + GetTemplateInfo([in] unsigned long templateId, [out] struct TemplateInfo templateInfo); + /** + * @brief Send parameters to driver when executor register finish. + * + * @param templateIdList Indicates templates previously registered to userauth framework. + * @param frameworkPublicKey Indicates framework public key. + * @param extraInfo Indicates extra info send to executor. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + OnRegisterFinish([in] unsigned long[] templateIdList, [in] unsigned char[] frameworkPublicKey, [in] unsigned char[] extraInfo); + /** + * @brief Enroll template. + * + * @param scheduleId Indicates schedule id of enroll. + * @param extraInfo Indicates extra info of enroll. + * @param callbackObj Indicates enroll callback object, see {@link IExecutorCallback}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + Enroll([in] unsigned long scheduleId, [in] unsigned char[] extraInfo, [in] IExecutorCallback callbackObj); + /** + * @brief Authenticate template. + * + * @param scheduleId Indicates schedule id of authenticate. + * @param templateIdList Indicates the templates to authenticate. + * @param extraInfo Indicates extra info of authenticate. + * @param callbackObj Indicates authenticate callback object, see {@link IExecutorCallback}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + Authenticate([in] unsigned long scheduleId, [in] unsigned long[] templateIdList, [in] unsigned char[] extraInfo, [in] IExecutorCallback callbackObj); + /** + * @brief Identify template. + * + * @param scheduleId Indicates schedule id of identify. + * @param extraInfo Indicates extra info of identify. + * @param callbackObj Indicates identify callback object, see {@link IExecutorCallback}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + Identify([in] unsigned long scheduleId, [in] unsigned char[] extraInfo, [in] IExecutorCallback callbackObj); + /** + * @brief Delete templates. + * + * @param templateIdList Indicates the templates to delete. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + Delete([in] unsigned long[] templateIdList); + /** + * @brief Cancel enroll, authenticate or identify operation. + * + * @param scheduleId Indicates schedule id of operation to cancel. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + Cancel([in] unsigned long scheduleId); + /** + * @brief Send command to driver. + * + * @param commandId Indicates command id. For details, see {@link CommandId}. + * @param extraInfo Indicates extra info of command. + * @param callbackObj Indicates command callback object, see {@link IExecutorCallback}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + SendCommand([in] int commandId, [in] unsigned char[] extraInfo, [in] IExecutorCallback callbackObj); +} \ No newline at end of file diff --git a/en/device_api/hdi/face_auth/IExecutorCallback.idl b/en/device_api/hdi/face_auth/IExecutorCallback.idl new file mode 100644 index 0000000000000000000000000000000000000000..a1b52091d2bef0f5c3c119e0f17745d5c79412f6 --- /dev/null +++ b/en/device_api/hdi/face_auth/IExecutorCallback.idl @@ -0,0 +1,69 @@ +/* + * Copyright (c) 2022 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 HdfFaceAuth + * @{ + * + * @brief Provides APIs for the face auth driver. + * + * The face auth driver provides a unified interface for the face auth service to access the face auth driver. + * After obtaining the face auth driver proxy, the service can call related APIs to obtain executors. + * After obtaining the face auth executors, the service can call related APIs to get executor info, get + * template info, enroll template, authenticate template, delete template, etc. + * + * @since 3.2 + */ + +/** + * @file IExecutorCallback.idl + * + * @brief Defines the callback for async API. These callback can be used to report operation result or info + * of async API. + * + * @since 3.2 + */ + +package ohos.hdi.face_auth.v1_0; + +/** + * @brief Defines the callback for async API. This callback needs to be registered when + * executor user calls an async function. For details, see {@link IExecutor}. + * + * @since 3.2 + * @version 1.0 + */ +[callback] interface IExecutorCallback { + /** + * @brief Defines the function for reporting operation result. + * + * @param result Indicates result code. + * @param extraInfo Indicates extra info to report. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + OnResult([in] int result, [in] unsigned char[] extraInfo); + /** + * @brief defines the function for reporting info in process. + * + * @param acquire Indicates acquire info code, see {@link FaceTipsCode}. + * @param extraInfo Indicates extra info to report. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + OnAcquireInfo([in] int acquire, [in] unsigned char[] extraInfo); +} \ No newline at end of file diff --git a/en/device_api/hdi/face_auth/IFaceAuthInterface.idl b/en/device_api/hdi/face_auth/IFaceAuthInterface.idl new file mode 100644 index 0000000000000000000000000000000000000000..ae6a926db61060571af31d01f902da6416a15178 --- /dev/null +++ b/en/device_api/hdi/face_auth/IFaceAuthInterface.idl @@ -0,0 +1,59 @@ +/* + * Copyright (c) 2022 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 HdfFaceAuth + * @{ + * + * @brief Provides APIs for the face auth driver. + * + * The face auth driver provides a unified interface for the face auth service to access the face auth driver. + * After obtaining the face auth driver proxy, the service can call related APIs to obtain executors. + * After obtaining the face auth executors, the service can call related APIs to get executor info, get + * template info, enroll template, authenticate template, delete template, etc. + * + * @since 3.2 + */ + +/** + * @file IFaceAuthInterface.idl + * + * @brief Defines the get executor list API of the face auth driver. This API can be used to get executor list + * of driver. + * + * @since 3.2 + */ + +package ohos.hdi.face_auth.v1_0; + +import ohos.hdi.face_auth.v1_0.IExecutor; + +/** + * @brief Defines the get executor list API of the face auth driver. + * + * @since 3.2 + * @version 1.0 + */ +interface IFaceAuthInterface { + /** + * @brief Obtains executor list of driver. + * + * @param executorList Indicates executor list of driver. For details, see {@link IExecutor}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + GetExecutorList([out] IExecutor[] executorList); +} \ No newline at end of file diff --git a/en/device_api/hdi/pin_auth/IExecutor.idl b/en/device_api/hdi/pin_auth/IExecutor.idl new file mode 100644 index 0000000000000000000000000000000000000000..244e6b64dab688d54667ff998b44adc36207fc1d --- /dev/null +++ b/en/device_api/hdi/pin_auth/IExecutor.idl @@ -0,0 +1,146 @@ +/* + * Copyright (c) 2022 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 HdfPinAuth + * @{ + * + * @brief Provides APIs for the pin auth driver. + * + * The pin auth driver provides a unified interface for the pin auth service to access the pin auth driver. + * After obtaining the pin auth driver proxy, the service can call related APIs to obtain executors. + * After obtaining the pin auth executors, the service can call related APIs to get executor info, get + * template info, enroll template, authenticate template, delete template, etc. + * + * @since 3.2 + */ + +/** + * @file IExecutor.idl + * + * @brief Defines the APIs of executor. These APIs can be used to get executor info, get + * template info, enroll template, authenticate template, delete template, etc. + * + * @since 3.2 + */ + +package ohos.hdi.pin_auth.v1_0; + +import ohos.hdi.pin_auth.v1_0.PinAuthTypes; +import ohos.hdi.pin_auth.v1_0.IExecutorCallback; + +/** + * @brief Defines the APIs of executor. These APIs can be used to get executor info, get + * template info, enroll template, authenticate template, delete template, etc. + * + * @since 3.2 + * @version 1.0 + */ + +interface IExecutor { + /** + * @brief Get executor info. + * + * @param executorInfo Indicates executor info, see {@link ExecutorInfo}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + GetExecutorInfo([out] struct ExecutorInfo executorInfo); + /** + * @brief Get template info. + * + * @param templateId Indicates template id. + * @param templateInfo Indicates template info, see {@link TemplateInfo}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + GetTemplateInfo([in] unsigned long templateId, [out] struct TemplateInfo templateInfo); + /** + * @brief Send parameters to driver when executor register finish. + * + * @param templateIdList Indicates templates previously registered to userauth framework. + * @param frameworkPublicKey Indicates framework public key. + * @param extraInfo Indicates extra info send to executor. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + OnRegisterFinish([in] unsigned long[] templateIdList, [in] unsigned char[] frameworkPublicKey, [in] unsigned char[] extraInfo); + /** + * @brief Send parameters to driver when executor register finish. + * + * @param scheduleId Indicates schedule id of enroll. + * @param authSubType . + * @param data . + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + OnSetData([in] unsigned long scheduleId, [in] unsigned long authSubType, [in] unsigned char[] data); + /** + * @brief Enroll template. + * + * @param scheduleId Indicates schedule id of enroll. + * @param extraInfo Indicates extra info of enroll. + * @param callbackObj Indicates enroll callback object, see {@link IExecutorCallback}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + Enroll([in] unsigned long scheduleId, [in] unsigned char[] extraInfo, [in] IExecutorCallback callbackObj); + /** + * @brief Authenticate template. + * + * @param scheduleId Indicates schedule id of authenticate. + * @param templateId Indicates the template to authenticate. + * @param extraInfo Indicates extra info of authenticate. + * @param callbackObj Indicates authenticate callback object, see {@link IExecutorCallback}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + Authenticate([in] unsigned long scheduleId, [in] unsigned long templateId, [in] unsigned char[] extraInfo, [in] IExecutorCallback callbackObj); + /** + * @brief Delete templates. + * + * @param templateId Indicates the template to delete. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + Delete([in] unsigned long templateId); + /** + * @brief Cancel enroll, authenticate or identify operation. + * + * @param scheduleId Indicates schedule id of operation to cancel. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + Cancel([in] unsigned long scheduleId); + /** + * @brief Send command to driver. + * + * @param commandId Indicates command id. For details, see {@link CommandId}. + * @param extraInfo Indicates extra info of command. + * @param callbackObj Indicates command callback object, see {@link IExecutorCallback}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + SendCommand([in] int commandId, [in] unsigned char[] extraInfo, [in] IExecutorCallback callbackObj); +} diff --git a/en/device_api/hdi/pin_auth/IExecutorCallback.idl b/en/device_api/hdi/pin_auth/IExecutorCallback.idl new file mode 100644 index 0000000000000000000000000000000000000000..8dc4922f2612aa13f8112655297fbc144164adaf --- /dev/null +++ b/en/device_api/hdi/pin_auth/IExecutorCallback.idl @@ -0,0 +1,69 @@ +/* + * Copyright (c) 2022 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 HdfPinAuth + * @{ + * + * @brief Provides APIs for the pin auth driver. + * + * The pin auth driver provides a unified interface for the pin auth service to access the pin auth driver. + * After obtaining the pin auth driver proxy, the service can call related APIs to obtain executors. + * After obtaining the pin auth executors, the service can call related APIs to get executor info, get + * template info, enroll template, authenticate template, delete template, etc. + * + * @since 3.2 + */ + +/** + * @file IExecutorCallback.idl + * + * @brief Defines the callback for async API. These callback can be used to report operation result or info + * of async API. + * + * @since 3.2 + */ + +package ohos.hdi.pin_auth.v1_0; + +/** + * @brief Defines the callback for async API. This callback needs to be registered when + * executor user calls an async function. For details, see {@link IExecutor}. + * + * @since 3.2 + * @version 1.0 + */ +[callback] interface IExecutorCallback { + /** + * @brief Defines the function for reporting operation result. + * + * @param result Indicates result code. + * @param extraInfo Indicates extra info to report. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + OnResult([in] int result, [in] unsigned char[] extraInfo); + /** + * @brief defines the function for reporting info in process. + * + * @param salt Indicates acquire info code, see {@link FaceTipsCode}. + * @param authSubType Indicates extra info to report. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + OnGetData([in] unsigned long scheduleId, [in] unsigned char[] salt, [in] unsigned long authSubType); +} \ No newline at end of file diff --git a/en/device_api/hdi/pin_auth/IPinAuthInterface.idl b/en/device_api/hdi/pin_auth/IPinAuthInterface.idl new file mode 100644 index 0000000000000000000000000000000000000000..1c21f6fa6f6f11c7769da256dffdef5cc40ecebd --- /dev/null +++ b/en/device_api/hdi/pin_auth/IPinAuthInterface.idl @@ -0,0 +1,59 @@ +/* + * Copyright (c) 2022 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 HdfPinAuth + * @{ + * + * @brief Provides APIs for the pin auth driver. + * + * The pin auth driver provides a unified interface for the pin auth service to access the pin auth driver. + * After obtaining the pin auth driver proxy, the service can call related APIs to obtain executors. + * After obtaining the pin auth executors, the service can call related APIs to get executor info, get + * template info, enroll template, authenticate template, delete template, etc. + * + * @since 3.2 + */ + +/** + * @file IPinAuthInterface.idl + * + * @brief Defines the get executor list API of the pin auth driver. This API can be used to get executor list + * of driver. + * + * @since 3.2 + */ + +package ohos.hdi.pin_auth.v1_0; + +import ohos.hdi.pin_auth.v1_0.IExecutor; + +/** + * @brief Defines the get executor list API of the pin auth driver. + * + * @since 3.2 + * @version 1.0 + */ +interface IPinAuthInterface { + /** + * @brief Obtains executor list of driver. + * + * @param executorList Indicates executor list of driver. For details, see {@link IExecutor}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + GetExecutorList([out] IExecutor[] executorList); +} \ No newline at end of file diff --git a/en/device_api/hdi/pin_auth/PinAuthTypes.idl b/en/device_api/hdi/pin_auth/PinAuthTypes.idl new file mode 100644 index 0000000000000000000000000000000000000000..3f89572e39239e7a5632fbd6be546c2689a36eec --- /dev/null +++ b/en/device_api/hdi/pin_auth/PinAuthTypes.idl @@ -0,0 +1,115 @@ +/* + * Copyright (c) 2022 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 HdfPinAuth + * @{ + * + * @brief Provides APIs for the pin auth driver. + * + * The pin auth driver provides a unified interface for the pin auth service to access the pin auth driver. + * After obtaining the pin auth driver proxy, the service can call related APIs to obtain executors. + * After obtaining the pin auth executors, the service can call related APIs to get executor info, get + * template info, enroll template, authenticate template, delete template, etc. + * + * @since 3.2 + */ + +/** + * @fiPinTypes.idl + * + * @brief Defines pin auth driver enumeration and data structure, including AuthType, ExecutorRole, ExecutorSecureLevel, + * CommandId, ResultCode, ExecutorInfo and TemplateInfo. + * + * @since 3.2 + */ +package ohos.hdi.pin_auth.v1_0; + +/** + * Enumerates credential type for authentication. + * + * @since 3.2 + * @version 1.0 + */ +enum AuthType : int { + PIN = 1, /**< Indicates authentication type is PIN. */ + FACE = 2, /**< Indicates authentication type is face. */ + FINGERPRINT = 3, /**< Indicates authentication type is fingerprint. */ +}; + +/** + * Enumerates executor role. + * + * @since 3.2 + * @version 1.0 + */ +enum ExecutorRole : int { + COLLECTOR = 1, /**< Indicates executor role is collector. */ + VERIFIER = 2, /**< Indicates executor role is verifier. */ + ALL_IN_ONE = 3, /**< Indicates executor role is combination of collector and verifier, cannot be used as collector or verifier. */ +}; + +/** + * Enumerates executor secure level. + * + * @since 3.2 + * @version 1.0 + */ +enum ExecutorSecureLevel : int { + ESL0 = 0, /**< Indicates executor secure level is ESL0. */ + ESL1 = 1, /**< Indicates executor secure level is ESL1. */ + ESL2 = 2, /**< Indicates executor secure level is ESL2. */ + ESL3 = 3, /**< Indicates executor secure level is ESL3. */ +}; + +/** + * Enumerates command id. + * + * @since 3.2 + * @version 1.0 + */ +enum CommandId : int { + DEFAULT = 0, /**< Default parameters. */ +}; + + +/** + * Indicates the executor info. + * + * @since 3.2 + * @version 1.0 + */ +struct ExecutorInfo { + unsigned short sensorId; /**< Indicates sensor id. Sensor id must be unique in driver. */ + unsigned int executorType; /**< Indicates executor type. */ + enum ExecutorRole executorRole; /**< Indicates executor role, see @{ExecutorRole}. */ + enum AuthType authType; /**< Indicates auth type, see @{AuthType}. */ + enum ExecutorSecureLevel esl; /**< Indicates executor secure level, see @{ExecutorSecureLevel}. */ + unsigned char[] publicKey; /**< Indicates publicKey. */ + unsigned char[] extraInfo; /**< Indicates extra info. */ +}; + +/** + * Indicates the template info. + * + * @since 3.2 + * @version 1.0 + */ +struct TemplateInfo { + unsigned int executorType; /**< Indicates executor type. */ + int freezingTime; /**< Indicates freezing time in seconds. */ + int remainTimes; /**< Indicates remain times before a lockout. */ + unsigned char[] extraInfo; /**< Indicates extra info. */ +}; \ No newline at end of file diff --git a/en/device_api/hdi/user_auth/IUserAuthInterface.idl b/en/device_api/hdi/user_auth/IUserAuthInterface.idl new file mode 100644 index 0000000000000000000000000000000000000000..f13a2e6ec91d34f6246749ea45c9338b0146cde0 --- /dev/null +++ b/en/device_api/hdi/user_auth/IUserAuthInterface.idl @@ -0,0 +1,279 @@ +/* + * Copyright (c) 2022 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 pin auth service to access the user auth driver. + * After obtaining the pin auth driver proxy, the service can call related APIs to register executor, + * manage credentials, and complete password and biometric authentication. + * @since 3.2 + */ + +/** + * @file IUserAuthInterface.idl + * + * @brief Declare the APIs of userauth driver. These APIs can be used to register executor, + * manage credentials, and complete password and biometric authentication. + * + * @since 3.2 + */ + +package ohos.hdi.user_auth.v1_0; + +import ohos.hdi.user_auth.v1_0.UserAuthTypes; + +/** + * @brief Declare the APIs of userauth driver. + * + * @since 3.2 + * @version 1.0 + */ +interface IUserAuthInterface { + /** + * @brief Initialize cache information of user auth driver. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + Init(); + /** + * @brief Add an authentication executor to obtain this authentication capability. + * + * @param info Indicates executor registration information, see {@link ExecutorRegisterInfo}. + * @param index Indicates executor index under the authentication frameworks. + * @param publicKey Indicates public key of authentication frameworks. + * @param templateIds Indicates templateIds enrolled by executor. + * + * @return Returns 0 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 Delete executor. + * + * @param index Indicates executor index under the authentication frameworks. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + DeleteExecutor([in] unsigned long index); + /** + * @brief Open authentication credential management session. + * + * @param userId Indicates user id. + * @param challenge Indicates random number, used to generate authentication token. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + OpenSession([in] int userId, [out] unsigned char[] challenge); + /** + * @brief Close authentication credential management session. + * + * @param userId Indicates user id. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + CloseSession([in] int userId); + /** + * @brief Begin the enrollment of authentication credential. + * When the authentication type is pin and the current user has enrolled PIN credential, + * the pin credential will be updated. + * + * @param userId Indicates user id. + * @param authToken Indicates user password authentication token. + * @param param Indicates input parameters, see {@link EnrollParam}. + * @param info Indicates scheduling information, see {@link ScheduleInfo}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + BeginEnrollment([in] int userId, [in] unsigned char[] authToken, [in] struct EnrollParam param, + [out] struct ScheduleInfo info); + /** + * @brief Update the enrollment result and complete this enrollment. + * + * @param userId Indicates user id. + * @param scheduleResult Indicates enrollment result issued by executor. + * @param credentialId Indicates credential id. + * @param oldInfo Indicates old credential information, see {@link CredentialInfo}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + UpdateEnrollmentResult([in] int userId, [in] unsigned char[] scheduleResult, [out] unsigned long credentialId, + [out] struct CredentialInfo oldInfo); + /** + * @brief Cancel enrollment. + * + * @param userId Indicates user id. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + CancelEnrollment([in] int userId); + /** + * @brief Delete credential information. + * + * @param userId Indicates user id. + * @param credentialId Indicates credential id. + * @param authToken Indicates user password authentication token. + * @param info Indicates deleted credential information, see {@link CredentialInfo}. + * + * @return Returns 0 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 Query credential information. + * + * @param userId Indicates Indicates user id. + * @param authType Indicates authentication type, see {@link AuthType}. + * @param infos Indicates credential information, see {@link CredentialInfo}. + * + * @return Returns 0 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 Query secure information. + * + * @param userId Indicates user id. + * @param secureUid Indicates secure user id, see {@link AuthType}. + * @param infos Indicates enrolled Info, see {@link EnrolledInfo}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + GetSecureInfo([in] int userId, [out] unsigned long secureUid, [out] struct EnrolledInfo[] infos); + /** + * @brief Delete pin, delete user in Iam subsystem. + * + * @param userId Indicates user id. + * @param authToken Indicates Indicates user password authentication token. + * @param deletedInfos Indicates deleted credential information, see {@link CredentialInfo}. + * + * @return Returns 0 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 delete user. + * + * @param userId Indicates user id. + * @param deletedInfos Indicates deleted credential information, see {@link CredentialInfo}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + EnforceDeleteUser([in] int userId, [out] struct CredentialInfo[] deletedInfos); + /** + * @brief Begin authentication, and generate authentication scheme. + * + * @param contextId Indicates context id. + * @param param Indicates input parameters, see {@link AuthSolution}. + * @param scheduleInfos Indicates scheduling information, see {@link ScheduleInfo}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + BeginAuthentication([in] unsigned long contextId, [in] struct AuthSolution param, + [out] struct ScheduleInfo[] scheduleInfos); + /** + * @brief Update authentication result, and evaluate the results of this authentication scheme. + * + * @param contextId Indicates context id. + * @param scheduleResult Indicates authentication result issued by executor. + * @param info Indicates authentication result information, see {@link AuthResultInfo}. + * + * @return Returns 0 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 Cancel authentication. + * + * @param contextId Indicates context id. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + CancelAuthentication([in] unsigned long contextId); + /** + * @brief Begin identification, and generate identification scheme. + * + * @param contextId Indicates context id. + * @param authType Indicates identification type, see @{AuthType}. + * @param scheduleInfo Indicates scheduling information, see {@link ScheduleInfo}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + BeginIdentification([in] unsigned long contextId, [in] enum AuthType authType, [in] byte[] challenge, + [in] unsigned int executorId, [out] struct ScheduleInfo scheduleInfo); + /** + * @brief Update identification result, and evaluate the results of this identification scheme. + * + * @param contextId Indicates context id. + * @param scheduleResult Indicates identification result issued by executor. + * @param info Indicates identification result information, see {@link IdentifyResultInfo}. + * + * @return Returns 0 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 Cancel identification. + * + * @param contextId Indicates context id. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value if the operation fails. + */ + CancelIdentification([in] unsigned long contextId); + /** + * @brief Get the authentication trust level of the current authentication type. + * + * @param userId Indicates user id. + * @param authType Indicates authentication type, see {@link AuthType}. + * @param authTrustLevel Indicates authentication trust level. + * + * @return Returns 0 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 Get the valid authentication methods under the current authentication trust level. + * + * @param userId Indicates user id. + * @param authTypes Indicates authentication type of the to be filtered, see {@link AuthType}. + * @param authTrustLevel Indicates authentication trust level. + * @param validTypes Indicates valid authentication type, see {@link AuthType}. + * + * @return Returns 0 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); +} diff --git a/en/device_api/hdi/user_auth/UserAuthTypes.idl b/en/device_api/hdi/user_auth/UserAuthTypes.idl new file mode 100644 index 0000000000000000000000000000000000000000..9671107c26ac7b23e6bd0c6a7f02a276b1babd6a --- /dev/null +++ b/en/device_api/hdi/user_auth/UserAuthTypes.idl @@ -0,0 +1,137 @@ +/* + * Copyright (c) 2022 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. + + * + * @since 3.2 + */ + + package ohos.hdi.user_auth.v1_0; + + /** + * Enumerates credential type for authentication. + * + * @since 3.2 + * @version 1.0 + */ +enum AuthType : int { + ALL = 0, /**< Indicates authentication type is ALL. */ + PIN = 1, /**< Indicates authentication type is PIN. */ + FACE = 2, /**< Indicates authentication type is face. */ + FINGERPRINT = 3, /**< Indicates authentication type is fingerprint. */ +}; + +/** + * Enumerates executor role. + * + * @since 3.2 + * @version 1.0 + */ +enum ExecutorRole : int { + COLLECTOR = 1, /**< Indicates executor role is collector. */ + VERIFIER = 2, /**< Indicates executor role is verifier. */ + ALL_IN_ONE = 3, /**< Indicates executor role is collector and verifier. */ +}; + +/** + * Enumerates executor secure level. + * + * @since 3.2 + * @version 1.0 + */ +enum ExecutorSecureLevel : int { + ESL0 = 0, /**< Indicates executor secure level is ESL0. */ + ESL1 = 1, /**< Indicates executor secure level is ESL1. */ + ESL2 = 2, /**< Indicates executor secure level is ESL2. */ + ESL3 = 3, /**< Indicates executor secure level is ESL3. */ +}; + +struct ExecutorRegisterInfo { + enum AuthType authType; /**< Indicates authentication type, see @{AuthType}. */ + enum ExecutorRole executorRole; /**< Indicates executor role, see @{ExecutorRole}. */ + unsigned int executorId; /**< Indicates executor id under the same authentication type. */ + unsigned int executorType; /**< Indicates executor type. */ + enum ExecutorSecureLevel esl; /**< Indicates executor secure level, see @{ExecutorSecureLevel}. */ + unsigned char[] publicKey; /**< Indicates publicKey. */ +}; + +struct ExecutorInfo { + unsigned long index; /**< Indicates executor index under the authentication frameworks. */ + struct ExecutorRegisterInfo info; /**< Indicates executor registration information, see @{ExecutorRegisterInfo}. */ +}; + +struct ScheduleInfo { + unsigned long scheduleId; /**< Indicates schedule id of authentication. */ + unsigned long[] templateIds; /**< Indicates the templates to authenticate. */ + enum AuthType authType; /**< Indicates authentication type, see @{AuthType}. */ + unsigned int executorType; /**< Indicates executor type. */ + unsigned int scheduleMode; /**< Indicates authentication or identification. */ + struct ExecutorInfo[] executors; /**< Indicates executor info of identification, see @{ExecutorInfo}. */ +}; + +struct AuthSolution { + int userId; /**< Indicates user id. */ + unsigned int authTrustLevel; /**< Indicates authentication trust level of authentication. */ + enum AuthType authType; /**< Indicates authentication type, see @{AuthType}. */ + unsigned int executorId; /**< Indicates executor index under the same authentication type. */ + unsigned char[] challenge; /**< Indicates challenge of authentication. */ +}; + +struct ExecutorSendMsg { + unsigned int index; /**< Indicates executor index under the authentication frameworks. */ + unsigned char[] msg; /**< Indicates executor msg to send. */ +}; + +struct AuthResultInfo { + unsigned int result; /**< Indicates result. */ + int freezingTime; /**< Indicates freezing time in seconds. */ + int remainTimes; /**< Indicates freezing time in seconds. */ + struct ExecutorSendMsg[] msgs; /**< Indicates executor msgs, see @{ExecutorSendMsg}. */ + unsigned char[] token; /**< Indicates authentication token. */ +}; + +struct IdentifyResultInfo { + int result; /**< Indicates result. */ + int userId; /**< Indicates user id. */ + unsigned char[] token; /**< Indicates identification token. */ +}; + +struct EnrollParam { + enum AuthType authType; /**< Indicates authentication type, see @{AuthType}. */ + unsigned int executorType; /**< Indicates executor type. */ + unsigned int executorId; /**< Indicates executor id under the same authentication type. */ +}; + +struct CredentialInfo { + unsigned long credentialId; /**< Indicates credential Id. */ + unsigned long index; /**< Indicates executor index under the authentication frameworks. */ + unsigned long templateId; /**< Indicates template Id. */ + enum AuthType authType; /**< Indicates authentication type, see @{AuthType}. */ + unsigned int executorType; /**< Indicates executor type. */ + unsigned int executorId; /**< Indicates executor id under the same authentication type. */ + unsigned char[] extraInfo; /**< Indicates extra info. */ +}; + +struct EnrolledInfo { + unsigned long enrolledId; /**< Indicates enrolled id. */ + enum AuthType authType; /**< Indicates authentication type, see @{AuthType}. */ +}; \ No newline at end of file