diff --git a/en/device-dev/driver/driver-peripherals-face_auth-des.md b/en/device-dev/driver/driver-peripherals-face_auth-des.md index 24bfeb387734b384f628919ad9ee473be6ab522f..fdf444f9cc68f7a3dd1a35e7a0fcaf4cc50dee64 100644 --- a/en/device-dev/driver/driver-peripherals-face_auth-des.md +++ b/en/device-dev/driver/driver-peripherals-face_auth-des.md @@ -39,9 +39,9 @@ The identity authentication consists of User_auth and basic authentication servi To ensure user data security and authentication result accuracy, measures must be taken to protect the integrity of the key information exchanged between User_auth and basic authentication services. Public keys must be exchanged when the executor provided by a basic authentication service interworks with User_auth. - The executor uses the User_auth public key to verify scheduling instructions. + The executor uses the User_auth public key to verify scheduling instructions. - User_auth uses the executor public key to verify the authentication result accuracy and the integrity of the information exchanged with the executor. + User_auth uses the executor public key to verify the authentication result accuracy and the integrity of the information exchanged with the executor. - Authentication credential template @@ -61,7 +61,7 @@ The identity authentication consists of User_auth and basic authentication servi - IPC - Inter-Process Communication (IPC) is a mechanism that allows processes to communicate with each other. For details, see [IPC](https://gitee.com/openharmony/communication_ipc/blob/master/README.md). + Inter-process communication (IPC) is a mechanism that allows processes to communicate with each other. For details, see [IPC](https://gitee.com/openharmony/communication_ipc/blob/master/README.md). - HDI @@ -90,7 +90,7 @@ The Face_auth driver provides basic facial authentication capabilities for the U ### Available APIs -The following table describes the C++ APIs generated from the Interface Definition Language (IDL) interface description. For details about the interface declaration, see the .idl file in **/drivers/interface/face_auth/v1_0/**. +The following table describes the C++ APIs generated from the Interface Definition Language (IDL) interface description. For details about the interface declaration, see the .idl file in **/drivers/interface/face_auth/**. **Table 1** describes the HDI APIs for face credential enrollment, authentication, recognition, and deletion. **Table 2** describes the callbacks used to return the executor operation result to the framework or return the authentication tip information to upper-layer applications. @@ -98,23 +98,29 @@ The following table describes the C++ APIs generated from the Interface Definiti | API | Description | | ----------------------------------- | ---------------------------------- | -| GetExecutorList(std::vector>& executorList) | Obtains the executor list. | +| GetExecutorList(std::vector\>& executorList) | Obtains the executor list (version V1_0).| +| GetExecutorListV1_1(std::vector\>& executorList) | Obtains the executor list (version V1_1). | | GetExecutorInfo(ExecutorInfo& info) | Obtains the executor information, including the executor type, executor role, authentication type, security level, and executor public key.| | GetTemplateInfo(uint64_t templateId, TemplateInfo& info) | Obtains information about a face image template based on the specified template ID. | -| OnRegisterFinish(const std::vector& templateIdList,
const std::vector& frameworkPublicKey, const std::vector& extraInfo) | Obtains the public key and template ID list from User_auth after the executor is registered successfully.| -| Enroll(uint64_t scheduleId, const std::vector& extraInfo,
const sptr& callbackObj) | Enrolls a face image. | -| Authenticate(uint64_t scheduleId, const std::vector& templateIdList,
const std::vector& extraInfo, const sptr& callbackObj) | Performs facial authentication. | -| Identify(uint64_t scheduleId, const std::vector& extraInfo,
const sptr& callbackObj) | Performs facial identification. | -| Delete(const std::vector& templateIdList) | Deletes a face image. | +| OnRegisterFinish(const std::vector\& templateIdList,
const std::vector\& frameworkPublicKey, const std::vector\& extraInfo) | Obtains the public key and template ID list from User_auth after the executor is registered successfully.| +| Enroll(uint64_t scheduleId, const std::vector\& extraInfo,
const sptr\& callbackObj) | Enrolls a face image template. | +| Authenticate(uint64_t scheduleId, const std::vector\& templateIdList,
const std::vector\& extraInfo, const sptr\& callbackObj) | Performs facial authentication. | +| Identify(uint64_t scheduleId, const std::vector\& extraInfo,
const sptr\& callbackObj) | Performs facial identification. | +| Delete(const std::vector\& templateIdList) | Deletes a face image template. | | Cancel(uint64_t scheduleId) | Cancels a face enrollment, authentication, or identification operation based on the **scheduleId**. | -| SendCommand(int32_t commandId, const std::vector& extraInfo,
const sptr& callbackObj) | Sends commands to the Face_auth service. | +| SendCommand(int32_t commandId, const std::vector\& extraInfo,
const sptr\& callbackObj) | Sends commands to the Face_auth service. | +| SetBufferProducer(const sptr\ &bufferProducer) | Sets the preview stream buffer.| +| GetProperty(const std::vector\& templateIdList,
const std::vector\& propertyTypes, Property& property) | Obtains executor property information.| +| SetCachedTemplates(const std::vector\ &templateIdList) | Sets a list of templates to be cached.| +| RegisterSaCommandCallback(const sptr\ &callbackObj) | Registers a callback to be invoked when an SA command is executed.| **Table 2** Callbacks | API | Description | | ------------------------------------------------------------ | ------------------------ | -| IExecutorCallback::OnResult(int32_t code, const std::vector& extraInfo) | Called to return the operation result. | -| IExecutorCallback::OnTip(int32_t code, const std::vector& extraInfo) | Called to return the interaction information about the operation process.| +| IExecutorCallback::OnResult(int32_t code, const std::vector\& extraInfo) | Called to return the operation result. | +| IExecutorCallback::OnTip(int32_t code, const std::vector\& extraInfo) | Called to return the interaction information about the operation process.| +| ISaCommandCallback::OnSaCommands(const std::vector\& commands) | Called to send the command list.| ### How to Develop @@ -122,12 +128,12 @@ The following uses the Hi3516D V300 development board as an example to demonstra ```undefined // drivers/peripheral/face_auth -├── BUILD.gn # Build script -├── bundle.json # Component description file -└── hdi_service # Face_auth driver implementation - ├── BUILD.gn # Build script - ├── include # Header files - └── src # Source files +├── BUILD.gn # Build script +├── bundle.json # Component description file +└── hdi_service # Face_auth driver implementation + ├── BUILD.gn # Build script + ├── include # Header files + └── src # Source files ├── executor_impl.cpp # Implementation of authentication and enrollment APIs ├── face_auth_interface_driver.cpp # Face_auth driver entry └── face_auth_interface_service.cpp # Implementation of the APIs for obtaining the executor list @@ -143,7 +149,7 @@ The development procedure is as follows: struct IDeviceIoService ioService; OHOS::sptr stub; }; - + // Enable the IPC service to call the response API. static int32_t FaceAuthInterfaceDriverDispatch(struct HdfDeviceIoClient *client, int cmdId, struct HdfSBuf *data, struct HdfSBuf *reply) @@ -151,11 +157,11 @@ The development procedure is as follows: IAM_LOGI("start"); auto *hdfFaceAuthInterfaceHost = CONTAINER_OF(client->device->service, struct HdfFaceAuthInterfaceHost, ioService); - + OHOS::MessageParcel *dataParcel = nullptr; OHOS::MessageParcel *replyParcel = nullptr; OHOS::MessageOption option; - + if (SbufToParcel(data, &dataParcel) != HDF_SUCCESS) { IAM_LOGE("%{public}s:invalid data sbuf object to dispatch", __func__); return HDF_ERR_INVALID_PARAM; @@ -164,10 +170,10 @@ The development procedure is as follows: IAM_LOGE("%{public}s:invalid reply sbuf object to dispatch", __func__); return HDF_ERR_INVALID_PARAM; } - + return hdfFaceAuthInterfaceHost->stub->SendRequest(cmdId, *dataParcel, *replyParcel, option); } - + // Initialize the HdfFaceAuthInterfaceDriver object. int HdfFaceAuthInterfaceDriverInit(struct HdfDeviceObject *deviceObject) { @@ -178,39 +184,39 @@ The development procedure is as follows: } return HDF_SUCCESS; } - + // Bind the service provided by the Face_auth driver to the HDF. int HdfFaceAuthInterfaceDriverBind(struct HdfDeviceObject *deviceObject) { IAM_LOGI("start"); auto *hdfFaceAuthInterfaceHost = new (std::nothrow) HdfFaceAuthInterfaceHost; if (hdfFaceAuthInterfaceHost == nullptr) { - IAM_LOGE("%{public}s: Failed to create HdfFaceAuthInterfaceHost object", __func__); + IAM_LOGE("%{public}s: failed to create HdfFaceAuthInterfaceHost object", __func__); return HDF_FAILURE; } - + hdfFaceAuthInterfaceHost->ioService.Dispatch = FaceAuthInterfaceDriverDispatch; hdfFaceAuthInterfaceHost->ioService.Open = NULL; hdfFaceAuthInterfaceHost->ioService.Release = NULL; - + auto serviceImpl = IFaceAuthInterface::Get(true); if (serviceImpl == nullptr) { - IAM_LOGE("%{public}s: Failed to implement service", __func__); + IAM_LOGE("%{public}s: failed to implement service", __func__); return HDF_FAILURE; } - + hdfFaceAuthInterfaceHost->stub = OHOS::HDI::ObjectCollector::GetInstance().GetOrNewObject(serviceImpl, IFaceAuthInterface::GetDescriptor()); if (hdfFaceAuthInterfaceHost->stub == nullptr) { IAM_LOGE("%{public}s: Failed to get stub object", __func__); return HDF_FAILURE; } - + deviceObject->service = &hdfFaceAuthInterfaceHost->ioService; IAM_LOGI("success"); return HDF_SUCCESS; } - + // Release resources of the Face_auth driver. void HdfFaceAuthInterfaceDriverRelease(struct HdfDeviceObject *deviceObject) { @@ -220,7 +226,7 @@ The development procedure is as follows: delete hdfFaceAuthInterfaceHost; IAM_LOGI("success"); } - + // Register the entry data structure object of the Face_auth driver. struct HdfDriverEntry g_faceAuthInterfaceDriverEntry = { .moduleVersion = 1, @@ -229,7 +235,7 @@ The development procedure is as follows: .Init = HdfFaceAuthInterfaceDriverInit, .Release = HdfFaceAuthInterfaceDriverRelease, }; - + // Call HDF_INIT to register the driver entry with the HDF. When loading the driver, the HDF calls the Bind() function and then the Init() function. If the Init() function fails to be called, the HDF will call Release() to release driver resources and exit the driver model. HDF_INIT(g_faceAuthInterfaceDriverEntry); ``` @@ -238,19 +244,19 @@ The development procedure is as follows: ```c++ // Executor implementation class - class ExecutorImpl : public IExecutor { + class ExecutorImpl : public V1_1::IExecutor { public: ExecutorImpl(struct ExecutorInfo executorInfo); virtual ~ExecutorImpl() {} - + private: struct ExecutorInfo executorInfo_; // Executor information }; - + static constexpr uint16_t SENSOR_ID = 123; // Executor sensor ID static constexpr uint32_t EXECUTOR_TYPE = 123; // Executor type static constexpr size_t PUBLIC_KEY_LEN = 32; //32-byte public key of the executor - + // Create an HDI service object. extern "C" IFaceAuthInterface *FaceAuthInterfaceImplGetInstance(void) { @@ -261,9 +267,9 @@ The development procedure is as follows: } return faceAuthInterfaceService; } - + // Obtain the executor list and create an executor. - int32_t GetExecutorList(std::vector>& executorList) + int32_t GetExecutorListV1_1(std::vector>& executorList) { IAM_LOGI("interface mock start"); executorList.clear(); @@ -281,13 +287,24 @@ The development procedure is as follows: IAM_LOGE("executor is nullptr"); return HDF_FAILURE; } - executorList.push_back(sptr(executor)); + executorList.push_back(sptr(executor)); IAM_LOGI("interface mock success"); return HDF_SUCCESS; } + + // Obtain the executor list. The method of V1_0 is called to invoke the method of V1_1 through parameter conversion. + int32_t GetExecutorList(std::vector> &executorList) + { + std::vector> executorListV1_1; + int32_t result = GetExecutorListV1_1(executorListV1_1); + for (auto &executor : executorListV1_1) { + executorList.push_back(executor); + } + return result; + } ``` -3. Implement the functions of the executor. For details about the code, see [executor_impl.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/face_auth/hdi_service/src/executor_impl.cpp). +3. Implement each function of the executor. For details about the code, see [executor_impl.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/face_auth/hdi_service/src/executor_impl.cpp). ```c++ // Obtain the executor information. @@ -298,7 +315,7 @@ The development procedure is as follows: IAM_LOGI("Executor information got successfully"); return HDF_SUCCESS; } - + // Obtain template information based on templateId. int32_t GetTemplateInfo(uint64_t templateId, TemplateInfo& info) { @@ -308,7 +325,7 @@ The development procedure is as follows: IAM_LOGI("Template information got successfully"); return HDF_SUCCESS; } - + // After the executor is successfully registered, obtain the public key and template ID list from User_auth and save the public key. The executor compares its template ID list with the template ID list obtained and updates its template ID list. int32_t OnRegisterFinish(const std::vector& templateIdList, const std::vector& frameworkPublicKey, const std::vector& extraInfo) @@ -317,10 +334,10 @@ The development procedure is as follows: static_cast(templateIdList); static_cast(extraInfo); static_cast(frameworkPublicKey); - IAM_LOGI("Registration finished"); + IAM_LOGI("registration finished"); return HDF_SUCCESS; } - + // Enroll a face image. int32_t Enroll(uint64_t scheduleId, const std::vector& extraInfo, const sptr& callbackObj) @@ -336,7 +353,7 @@ The development procedure is as follows: } return HDF_SUCCESS; } - + // Start facial authentication. int32_t Authenticate(uint64_t scheduleId, const std::vector& templateIdList, const std::vector& extraInfo, const sptr& callbackObj) @@ -353,7 +370,7 @@ The development procedure is as follows: } return HDF_SUCCESS; } - + // Perform facial recognition. int32_t Identify(uint64_t scheduleId, const std::vector& extraInfo, const sptr& callbackObj) @@ -369,7 +386,7 @@ The development procedure is as follows: } return HDF_SUCCESS; } - + // Delete the face image template. int32_t Delete(const std::vector& templateIdList) { @@ -378,7 +395,7 @@ The development procedure is as follows: IAM_LOGI("delete success"); return HDF_SUCCESS; } - + // Cancel the operation based on the specified scheduleId. int32_t Cancel(uint64_t scheduleId) { @@ -387,7 +404,7 @@ The development procedure is as follows: IAM_LOGI("cancel success"); return HDF_SUCCESS; } - + // Send template locking or unlocking command from the Face_auth service to the Face_auth driver. int32_t SendCommand(int32_t commandId, const std::vector& extraInfo, const sptr& callbackObj) @@ -422,8 +439,42 @@ The development procedure is as follows: } return HDF_SUCCESS; } + + // Set the preview stream buffer. + int32_t ExecutorImpl::SetBufferProducer(const sptr &bufferProducer) + { + IAM_LOGI("interface mock start set buffer producer %{public}s", + UserIam::Common::GetPointerNullStateString(bufferProducer.GetRefPtr()).c_str()); + return HDF_SUCCESS; + } + + // Obtaining executor properties. + int32_t ExecutorImpl::GetProperty( + const std::vector &templateIdList, const std::vector &propertyTypes, Property &property) + { + IAM_LOGI("interface mock start"); + property = {}; + IAM_LOGI("get property success"); + return HDF_SUCCESS; + } + + // Set a list of templates to be cached. + int32_t ExecutorImpl::SetCachedTemplates(const std::vector &templateIdList) + { + IAM_LOGI("interface mock start"); + IAM_LOGI("set cached templates success"); + return HDF_SUCCESS; + } + + // Register the callback to be invoked when the SA command is executed. + int32_t ExecutorImpl::RegisterSaCommandCallback(const sptr &callbackObj) + { + IAM_LOGI("interface mock start"); + IAM_LOGI("register sa command callback success"); + return HDF_SUCCESS; + } ``` - + 4. Modify **serviceName2Config** in the **face_auth_service.cpp** file if you need to add a driver or modify driver information. ```c++ diff --git a/en/device-dev/driver/driver-peripherals-fingerprint_auth-des.md b/en/device-dev/driver/driver-peripherals-fingerprint_auth-des.md index 4c9edd59dcd6c549cfa97b8e38daa8f8dee98ab3..1bf8ea6f38eecf3e78a749db4391baa9effedc71 100644 --- a/en/device-dev/driver/driver-peripherals-fingerprint_auth-des.md +++ b/en/device-dev/driver/driver-peripherals-fingerprint_auth-des.md @@ -39,9 +39,9 @@ The identity authentication consists of the User_auth framework and basic authen To ensure user data security and authentication result accuracy, measures must be taken to protect the integrity of the key information exchanged between User_auth and basic authentication services. Public keys must be exchanged when the executor provided by a basic authentication service interworks with User_auth. - The executor uses the User_auth public key to verify scheduling instructions. + The executor uses the User_auth public key to verify scheduling instructions. - User_auth uses the executor public key to verify the authentication result accuracy and the integrity of the information exchanged with the executor. + User_auth uses the executor public key to verify the authentication result accuracy and the integrity of the information exchanged with the executor. - Authentication credential @@ -61,7 +61,7 @@ The identity authentication consists of the User_auth framework and basic authen - IPC - Inter-Process Communication (IPC) is a mechanism that allows processes to communicate with each other. For details, see [IPC](https://gitee.com/openharmony/communication_ipc/blob/master/README.md). + Inter-process communication (IPC) is a mechanism that allows processes to communicate with each other. For details, see [IPC](https://gitee.com/openharmony/communication_ipc/blob/master/README.md). - HDI @@ -88,30 +88,36 @@ The fingerprint_auth driver provides stable basic fingerprint authentication cap ### Available APIs -The following table describes the C++ APIs generated from the Interface Definition Language (IDL) interface description. For details about the interface declaration, see the .idl file in **/drivers/interface/fingerprint_auth/v1_0/**. +The following table describes the C++ APIs generated from the Interface Definition Language (IDL) interface description. For details about the interface declaration, see the .idl file in **/drivers/interface/fingerprint_auth/**. **Table 1** describes the HDI APIs for fingerprint credential enrollment, authentication, recognition, and deletion. **Table 2** describes the callbacks used to return the executor operation result to the framework or return the authentication tip information to upper-layer applications. **Table 1** Available APIs | API | Description | | -------------------------------- | ----------------------------------- | -| GetExecutorList(std::vector>& executorList) | Obtains the executor list. | +| GetExecutorList(std::vector\>& executorList) | Obtains the executor list (version V1_0).| +| GetExecutorListV1_1(std::vector\>& executorList) | Obtains the executor list (version V1_1). | | GetExecutorInfo(ExecutorInfo& info) | Obtains the executor information, including the executor type, executor role, authentication type, security level, and executor public key.| | GetTemplateInfo(uint64_t templateId, TemplateInfo& info) | Obtains information about the template based on the specified ID. | -| OnRegisterFinish(const std::vector& templateIdList,
const std::vector& frameworkPublicKey, const std::vector& extraInfo) | Obtains the public key and template ID list from User_auth after the executor is registered successfully.| -| Enroll(uint64_t scheduleId, const std::vector& extraInfo,
const sptr& callbackObj) | Enrolls a fingerprint. | -| Authenticate(uint64_t scheduleId, const std::vector& templateIdList,
const std::vector& extraInfo, const sptr& callbackObj) | Authenticates a fingerprint. | -| Identify(uint64_t scheduleId, const std::vector& extraInfo,
const sptr& callbackObj) | Identifies a fingerprint. | -| Delete(const std::vector& templateIdList) | Deletes a fingerprint. | +| OnRegisterFinish(const std::vector\& templateIdList,
const std::vector\& frameworkPublicKey, const std::vector\& extraInfo) | Obtains the public key and template ID list from User_auth after the executor is registered successfully.| +| Enroll(uint64_t scheduleId, const std::vector\& extraInfo,
const sptr\& callbackObj) | Enrolls a fingerprint. | +| Authenticate(uint64_t scheduleId, const std::vector\& templateIdList,
const std::vector\& extraInfo, const sptr\& callbackObj) | Authenticates a fingerprint (version V1_0). | +| AuthenticateV1_1(uint64_t scheduleId, const std::vector\& templateIdList,
bool endAfterFirstFail, const std::vector\& extraInfo, const sptr\& callbackObj) | Authenticates a fingerprint (version V1_1). | +| Identify(uint64_t scheduleId, const std::vector\& extraInfo,
const sptr\& callbackObj) | Identifies a fingerprint. | +| Delete(const std::vector\& templateIdList) | Deletes a fingerprint. | | Cancel(uint64_t scheduleId) | Cancels a fingerprint enrollment, authentication, or identification operation based on the **scheduleId**. | -| SendCommand(int32_t commandId, const std::vector& extraInfo,
const sptr& callbackObj) | Sends commands to the Fingerprint_auth driver. | +| SendCommand(int32_t commandId, const std::vector\& extraInfo,
const sptr\& callbackObj) | Sends commands to the Fingerprint_auth driver. | +| GetProperty(const std::vector\& templateIdList,
const std::vector\& propertyTypes, Property& property) | Obtains executor property information.| +| SetCachedTemplates(const std::vector\ &templateIdList) | Sets a list of templates to be cached.| +| RegisterSaCommandCallback(const sptr\ &callbackObj) | Registers a callback to be invoked when an SA command is executed.| **Table 2** Callbacks | API | Description | | ------------------------------------------------------------ | ------------------------ | -| IExecutorCallback::OnResult(int32_t code, const std::vector& extraInfo) | Called to return the operation result. | -| IExecutorCallback::OnTip(int32_t code, const std::vector& extraInfo) | Called to return the interaction information about the operation process.| +| IExecutorCallback::OnResult(int32_t code, const std::vector\& extraInfo) | Called to return the operation result. | +| IExecutorCallback::OnTip(int32_t code, const std::vector\& extraInfo) | Called to return the interaction information about the operation process.| +| ISaCommandCallback::OnSaCommands(const std::vector\& commands) | Called to send the command list.| ### How to Develop @@ -119,12 +125,12 @@ The following uses the Hi3516D V300 development board as an example to demonstra ```undefined // drivers/peripheral/fingerprint_auth -├── BUILD.gn # Build script -├── bundle.json # Component description file -└── hdi_service # Fingerprint_auth driver implementation - ├── BUILD.gn # Build script - ├── include # Header files - └── src # Source files +├── BUILD.gn # Build script +├── bundle.json # Component description file +└── hdi_service # Fingerprint_auth driver implementation + ├── BUILD.gn # Build script + ├── include # Header files + └── src # Source files ├── executor_impl.cpp # Implementation of authentication and enrollment APIs ├── fingerprint_auth_interface_driver.cpp # Fingerprint_auth driver entry └── fingerprint_auth_interface_service.cpp # Implementation of the API for obtaining the executor list @@ -140,7 +146,7 @@ The development procedure is as follows: struct IDeviceIoService ioService; OHOS::sptr stub; }; - + // Enable the IPC service to call the response API. static int32_t FingerprintAuthInterfaceDriverDispatch(struct HdfDeviceIoClient *client, int cmdId, struct HdfSBuf *data, struct HdfSBuf *reply) @@ -148,11 +154,11 @@ The development procedure is as follows: IAM_LOGI("start"); auto *hdfFingerprintAuthInterfaceHost = CONTAINER_OF(client->device->service, struct HdfFingerprintAuthInterfaceHost, ioService); - + OHOS::MessageParcel *dataParcel = nullptr; OHOS::MessageParcel *replyParcel = nullptr; OHOS::MessageOption option; - + if (SbufToParcel(data, &dataParcel) != HDF_SUCCESS) { IAM_LOGE("%{public}s:invalid data sbuf object to dispatch", __func__); return HDF_ERR_INVALID_PARAM; @@ -161,10 +167,10 @@ The development procedure is as follows: IAM_LOGE("%{public}s:invalid reply sbuf object to dispatch", __func__); return HDF_ERR_INVALID_PARAM; } - + return hdfFingerprintAuthInterfaceHost->stub->SendRequest(cmdId, *dataParcel, *replyParcel, option); } - + // Initialize the HdfFingerprintAuthInterfaceDriver object. int HdfFingerprintAuthInterfaceDriverInit(struct HdfDeviceObject *deviceObject) { @@ -175,7 +181,7 @@ The development procedure is as follows: } return HDF_SUCCESS; } - + // Bind the service provided by the Fingerprint_auth driver to the HDF. int HdfFingerprintAuthInterfaceDriverBind(struct HdfDeviceObject *deviceObject) { @@ -185,29 +191,29 @@ The development procedure is as follows: IAM_LOGE("%{public}s: failed to create HdfFaceAuthInterfaceHost object", __func__); return HDF_FAILURE; } - + hdfFingerprintAuthInterfaceHost->ioService.Dispatch = FingerprintAuthInterfaceDriverDispatch; hdfFingerprintAuthInterfaceHost->ioService.Open = NULL; hdfFingerprintAuthInterfaceHost->ioService.Release = NULL; - + auto serviceImpl = IFingerprintAuthInterface::Get(true); if (serviceImpl == nullptr) { IAM_LOGE("%{public}s: failed to implement service", __func__); return HDF_FAILURE; } - + hdfFingerprintAuthInterfaceHost->stub = OHOS::HDI::ObjectCollector::GetInstance().GetOrNewObject(serviceImpl, IFaceAuthInterface::GetDescriptor()); if (hdfFingerprintAuthInterfaceHost->stub == nullptr) { IAM_LOGE("%{public}s: Failed to get stub object", __func__); return HDF_FAILURE; } - + deviceObject->service = &hdfFingerprintAuthInterfaceHost->ioService; IAM_LOGI("success"); return HDF_SUCCESS; } - + // Release the resources used by the Fingerprint_auth driver. void HdfFingerprintAuthInterfaceDriverRelease(struct HdfDeviceObject *deviceObject) { @@ -217,7 +223,7 @@ The development procedure is as follows: delete hdfFaceAuthInterfaceHost; IAM_LOGI("success"); } - + // Register the Fingerprint_auth driver entry data structure object. struct HdfDriverEntry g_fingerprintAuthInterfaceDriverEntry = { .moduleVersion = 1, @@ -226,7 +232,7 @@ The development procedure is as follows: .Init = HdfFingerprintAuthInterfaceDriverInit, .Release = HdfFingerprintAuthInterfaceDriverRelease, }; - + // Call HDF_INIT to register the driver entry with the HDF. When loading the driver, the HDF calls the Bind() function and then the Init() function. If the Init() function fails to be called, the HDF will call Release() to release driver resources and exit the driver model. HDF_INIT(g_fingerprintAuthInterfaceDriverEntry); ``` @@ -239,15 +245,15 @@ The development procedure is as follows: public: ExecutorImpl(struct ExecutorInfo executorInfo); virtual ~ExecutorImpl() {} - + private: struct ExecutorInfo executorInfo_; // Executor information }; - + static constexpr uint16_t SENSOR_ID = 123; // Executor sensor ID static constexpr uint32_t EXECUTOR_TYPE = 123; // Executor type static constexpr size_t PUBLIC_KEY_LEN = 32; //32-byte public key of the executor - + // Create an HDI service object. extern "C" IFaceAuthInterface *FingerprintAuthInterfaceImplGetInstance(void) { @@ -258,9 +264,9 @@ The development procedure is as follows: } return fingerprintAuthInterfaceService; } - + // Obtain the executor list and create an executor. - int32_t GetExecutorList(std::vector>& executorList) + int32_t GetExecutorListV1_1(std::vector>& executorList) { IAM_LOGI("interface mock start"); executorList.clear(); @@ -278,13 +284,24 @@ The development procedure is as follows: IAM_LOGE("executor is nullptr"); return HDF_FAILURE; } - executorList.push_back(sptr(executor)); + executorList.push_back(sptr(executor)); IAM_LOGI("interface mock success"); return HDF_SUCCESS; } + + // Obtain the executor list. The method of V1_0 is called to invoke the method of V1_1 through parameter conversion. + int32_t GetExecutorList(std::vector> &executorList) + { + std::vector> executorListV1_1; + int32_t result = GetExecutorListV1_1(executorListV1_1); + for (auto &executor : executorListV1_1) { + executorList.push_back(executor); + } + return result; + } ``` -3. Implement functions of the executor. For details about the code, see [executor_impl.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/fingerprint_auth/hdi_service/src/executor_impl.cpp).
The sample code is as follows: +3. Implement each function of the executor. For details about the code, see [executor_impl.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/fingerprint_auth/hdi_service/src/executor_impl.cpp).
The sample code is as follows: ```c++ // Obtain the executor information. @@ -295,7 +312,7 @@ The development procedure is as follows: IAM_LOGI("Executor information got successfully"); return HDF_SUCCESS; } - + // Obtain template information based on templateId. int32_t GetTemplateInfo(uint64_t templateId, TemplateInfo& info) { @@ -305,7 +322,7 @@ The development procedure is as follows: IAM_LOGI("Template information got successfully"); return HDF_SUCCESS; } - + // After the executor is successfully registered, obtain the public key and template ID list from User_auth and save the public key. The executor compares its template ID list with the template ID list obtained and updates its template ID list. int32_t OnRegisterFinish(const std::vector& templateIdList, const std::vector& frameworkPublicKey, const std::vector& extraInfo) @@ -317,7 +334,7 @@ The development procedure is as follows: IAM_LOGI("registration finished"); return HDF_SUCCESS; } - + // Enroll fingerprints. int32_t Enroll(uint64_t scheduleId, const std::vector& extraInfo, const sptr& callbackObj) @@ -333,16 +350,25 @@ The development procedure is as follows: } return HDF_SUCCESS; } - - // Authenticate fingerprints. - int32_t Authenticate(uint64_t scheduleId, const std::vector& templateIdList, + + // Call Authenticate() of V1_0 to invoke authenticate() of V1_1. + int32_t Authenticate(uint64_t scheduleId, const std::vector &templateIdList, + const std::vector &extraInfo, const sptr &callbackObj) + { + IAM_LOGI("interface mock start"); + return AuthenticateV1_1(scheduleId, templateIdList, true, extraInfo, callbackObj); + } + + // Call Authenticate() of V1_1 to implement fingerprint authentication. + int32_t AuthenticateV1_1(uint64_t scheduleId, const std::vector& templateIdList, bool endAfterFirstFail, const std::vector& extraInfo, const sptr& callbackObj) { IAM_LOGI("interface mock start"); static_cast(scheduleId); static_cast(templateIdList); + static_cast(endAfterFirstFail); static_cast(extraInfo); - IAM_LOGI("authenticate, result is %{public}d", ResultCode::NOT_ENROLLED); + IAM_LOGI("authenticateV1_1, result is %{public}d", ResultCode::NOT_ENROLLED); int32_t ret = callbackObj->OnResult(ResultCode::NOT_ENROLLED, {}); if (ret != ResultCode::SUCCESS) { IAM_LOGE("callback result is %{public}d", ret); @@ -350,7 +376,7 @@ The development procedure is as follows: } return HDF_SUCCESS; } - + // Identify fingerprints. int32_t Identify(uint64_t scheduleId, const std::vector& extraInfo, const sptr& callbackObj) @@ -366,7 +392,7 @@ The development procedure is as follows: } return HDF_SUCCESS; } - + // Delete fingerprints. int32_t Delete(const std::vector& templateIdList) { @@ -375,7 +401,7 @@ The development procedure is as follows: IAM_LOGI("delete success"); return HDF_SUCCESS; } - + // Cancel the operation based on the specified scheduleId. int32_t Cancel(uint64_t scheduleId) { @@ -384,7 +410,7 @@ The development procedure is as follows: IAM_LOGI("cancel success"); return HDF_SUCCESS; } - + // Send template locking or unlocking command from the Fingerprint_auth service to the Fingerprint_auth driver. int32_t SendCommand(int32_t commandId, const std::vector& extraInfo, const sptr& callbackObj) @@ -419,8 +445,34 @@ The development procedure is as follows: } return HDF_SUCCESS; } + + // Obtain executor properties. + int32_t ExecutorImpl::GetProperty( + const std::vector &templateIdList, const std::vector &propertyTypes, Property &property) + { + IAM_LOGI("interface mock start"); + property = {}; + IAM_LOGI("get property success"); + return HDF_SUCCESS; + } + + // Set a list of templates to be cached. + int32_t ExecutorImpl::SetCachedTemplates(const std::vector &templateIdList) + { + IAM_LOGI("interface mock start"); + IAM_LOGI("set cached templates success"); + return HDF_SUCCESS; + } + + // Register the callback to be invoked when the SA command is executed. + int32_t ExecutorImpl::RegisterSaCommandCallback(const sptr &callbackObj) + { + IAM_LOGI("interface mock start"); + IAM_LOGI("register sa command callback success"); + return HDF_SUCCESS; + } ``` - + 4. Modify **serviceName2Config** in the **fingerprint_auth_service.cpp** file if you need to add a driver or modify driver information. ```c++ diff --git a/en/device-dev/driver/driver-peripherals-pinauth-des.md b/en/device-dev/driver/driver-peripherals-pinauth-des.md index 455633e413003a2bc829ca9a27e2812349149dc7..d3a2c968eeb944ff3023741bca8976d12274d954 100644 --- a/en/device-dev/driver/driver-peripherals-pinauth-des.md +++ b/en/device-dev/driver/driver-peripherals-pinauth-des.md @@ -74,7 +74,6 @@ The Pin_auth driver provides basic PIN authentication capabilities for the upper ### Constraints PIN authentication must be implemented in a Trusted Execution Environment (TEE), and the confidential information, such as PINs and credentials, must be encrypted and stored in a TEE. - ## Development Guidelines ### When to Use @@ -82,30 +81,32 @@ The Pin_auth driver provides basic PIN authentication capabilities for the User_ ### Available APIs -The following table describes the C++ APIs generated from the Interface Definition Language (IDL) interface description. For details about the interface declaration, see the .idl file in **/drivers/interface/pin_auth/v1_0/**. +The following table describes the C++ APIs generated from the Interface Definition Language (IDL) interface description. For details about the interface declaration, see the .idl file in **/drivers/interface/pin_auth**. **Table 1** describes the HDI APIs for PIN credential enrollment, authentication, and deletion. **Table 2** describes the callbacks used to return the executor operation result to the framework or return the PIN entered by the user. **Table 1** Available APIs | API | Description | | ------------------------------- | ------------------------------------------- | -| GetExecutorList(std::vector>& executorList) | Obtains the executor list.| -| GetExecutorInfo(ExecutorInfo& info) | Obtains information about an executor. | +| GetExecutorList(std::vector\>& executorList) | Obtains the executor list (version V1_0).| +| GetExecutorListV1_1(std::vector\>& executorList) | Obtains the executor list (version V1_1). | | GetTemplateInfo(uint64_t templateId, TemplateInfo& info) | Obtains information about a template. | -| OnRegisterFinish(const std::vector& templateIdList,
const std::vector& frameworkPublicKey,
const std::vector& extraInfo) | Obtains the public key and template ID list from User_auth after the executor is registered successfully.| -| OnSetData(uint64_t scheduleId, uint64_t authSubType,
const std::vector &data) | Called to return the subtype of the PIN enrolled by the user and the anonymization PIN data. | -| Enroll(uint64_t scheduleId, const std::vector& extraInfo,
const sptr& callbackObj) | Enrolls a PIN. | -| Authenticate(uint64_t scheduleId, uint64_t templateId, const std::vector& extraInfo, const sptr& callbackObj) | Starts PIN authentication. | +| OnRegisterFinish(const std::vector\& templateIdList,
const std::vector\& frameworkPublicKey,
const std::vector\& extraInfo) | Obtains the public key and template ID list from User_auth after the executor is registered successfully.| +| OnSetData(uint64_t scheduleId, uint64_t authSubType,
const std::vector\ &data) | Called to return the subtype of the PIN enrolled by the user and the anonymization PIN data. | +| Enroll(uint64_t scheduleId, const std::vector\& extraInfo,
const sptr\& callbackObj) | Enrolls a PIN. | +| Authenticate(uint64_t scheduleId, uint64_t templateId, const std::vector\& extraInfo, const sptr\& callbackObj) | Starts PIN authentication. | | Delete(uint64_t templateId) | Deletes a PIN template. | | Cancel(uint64_t scheduleId) | Cancels an operation. | -| SendCommand(int32_t commandId, const std::vector& extraInfo,
const sptr& callbackObj) | Reserved. | +| SendCommand(int32_t commandId, const std::vector\& extraInfo,
const sptr\& callbackObj) | Reserved. | +| GetProperty(const std::vector\& templateIdList,
const std::vector\& propertyTypes, Property& property) | Obtains executor property information.| + **Table 2** Callbacks | API | Description | | ------------------------------------------------------------ | -------------------- | -| IExecutorCallback::OnResult(int32_t code, const std::vector& extraInfo) | Called to return the operation result.| -| IExecutorCallback::OnGetData(uint64_t scheduleId, const std::vector& salt,
uint64_t authSubType)| Called to return the PIN information obtained. | +| IExecutorCallback::OnResult(int32_t code, const std::vector\& extraInfo) | Called to return the operation result.| +| IExecutorCallback::OnGetData(uint64_t scheduleId, const std::vector\& salt,
uint64_t authSubType)| Called to return the PIN information obtained. | ### How to Develop @@ -113,21 +114,21 @@ The following uses the RK3568 platform as an example to demonstrate how to devel ```text // drivers/peripheral/pin_auth -├── BUILD.gn # Build script -├── bundle.json # Component description file -├── test # Test cases -└── hdi_service # Pin_auth driver implementation - ├── BUILD.gn # Build script - ├── adaptor # Implementation of related algorithms - ├── common # Implementation of common interfaces - ├── database # Database implementation - ├── main # Entry for implementing PIN-related functions - └── service # Entry for implementing the Pin_auth driver - ├── inc # Header files - └── src # Source files - ├── executor_impl.cpp # Implementation of authentication and enrollment APIs - ├── pin_auth_interface_driver.cpp # Pin_auth driver entry - └── pin_auth_interface_service.cpp # Implementation of the APIs for obtaining the executor list +├── BUILD.gn # Build script +├── bundle.json # Component description file +├── test # Test cases +└── hdi_service # Pin_auth driver implementation + ├── BUILD.gn # Build script + ├── adaptor # Implementation of related algorithms + ├── common # Implementation of common interfaces + ├── database # Database implementation + ├── main # Entry for implementing PIN-related functions + └── service # Entry for implementing the Pin_auth driver + ├── inc # Header files + └── src # Source files + ├── executor_impl.cpp # Implementation of authentication and enrollment APIs + ├── pin_auth_interface_driver.cpp # Pin_auth driver entry + └── pin_auth_interface_service.cpp # Implementation of the APIs for obtaining the executor list ``` The development procedure is as follows: @@ -140,18 +141,18 @@ The development procedure is as follows: struct IDeviceIoService ioService; OHOS::sptr stub; }; - + // Enable the IPC service to call the response API. static int32_t PinAuthInterfaceDriverDispatch(struct HdfDeviceIoClient *client, int cmdId, struct HdfSBuf *data, struct HdfSBuf *reply) { IAM_LOGI("start"); auto *hdfPinAuthInterfaceHost = CONTAINER_OF(client->device->service, struct HdfPinAuthInterfaceHost, ioService); - + OHOS::MessageParcel *dataParcel = nullptr; OHOS::MessageParcel *replyParcel = nullptr; OHOS::MessageOption option; - + if (SbufToParcel(data, &dataParcel) != HDF_SUCCESS) { IAM_LOGE("%{public}s:invalid data sbuf object to dispatch", __func__); return HDF_ERR_INVALID_PARAM; @@ -160,10 +161,10 @@ The development procedure is as follows: IAM_LOGE("%{public}s:invalid reply sbuf object to dispatch", __func__); return HDF_ERR_INVALID_PARAM; } - + return hdfPinAuthInterfaceHost->stub->SendRequest(cmdId, *dataParcel, *replyParcel, option); } - + // Initialize the HdfPinAuthInterfaceDriver object. static int HdfPinAuthInterfaceDriverInit(struct HdfDeviceObject *deviceObject) { @@ -177,7 +178,7 @@ The development procedure is as follows: } return HDF_SUCCESS; } - + // Bind the service provided by the Pin_auth driver to the HDF. static int HdfPinAuthInterfaceDriverBind(struct HdfDeviceObject *deviceObject) { @@ -187,29 +188,29 @@ The development procedure is as follows: IAM_LOGE("%{public}s: Failed to create HdfPinAuthInterfaceHost object", __func__); return HDF_FAILURE; } - + hdfPinAuthInterfaceHost->ioService.Dispatch = PinAuthInterfaceDriverDispatch; hdfPinAuthInterfaceHost->ioService.Open = NULL; hdfPinAuthInterfaceHost->ioService.Release = NULL; - + auto serviceImpl = IPinAuthInterface::Get(true); if (serviceImpl == nullptr) { IAM_LOGE("%{public}s: Failed to implement the service", __func__); return HDF_FAILURE; } - + hdfPinAuthInterfaceHost->stub = OHOS::HDI::ObjectCollector::GetInstance().GetOrNewObject(serviceImpl, IPinAuthInterface::GetDescriptor()); if (hdfPinAuthInterfaceHost->stub == nullptr) { IAM_LOGE("%{public}s: Failed to get stub object", __func__); return HDF_FAILURE; } - + deviceObject->service = &hdfPinAuthInterfaceHost->ioService; IAM_LOGI("success"); return HDF_SUCCESS; } - + // Release resources of the Pin_auth driver. static void HdfPinAuthInterfaceDriverRelease(struct HdfDeviceObject *deviceObject) { @@ -219,7 +220,7 @@ The development procedure is as follows: delete hdfPinAuthInterfaceHost; IAM_LOGI("success"); } - + static struct HdfDriverEntry g_pinAuthInterfaceDriverEntry = { .moduleVersion = 1, .moduleName = "pinauth_interface_service", @@ -227,18 +228,18 @@ The development procedure is as follows: .Init = HdfPinAuthInterfaceDriverInit, .Release = HdfPinAuthInterfaceDriverRelease, }; - + // Call HDF_INIT to register the driver entry with the HDF. When loading the driver, the HDF calls the Bind() function and then the Init() function. If the Init() function fails to be called, the HDF will call Release() to release driver resources and exit the driver model. HDF_INIT(g_pinauthinterfaceDriverEntry); ``` - - + + 1. Obtain the executor list. For details about the code, see [pin_auth_interface_service.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/pin_auth/hdi_service/service/src/pin_auth_interface_service.cpp). ```c++ // Executor implementation class - class ExecutorImpl : public IExecutor, public NoCopyable { + class ExecutorImpl : public V1_1::IExecutor, public NoCopyable { public: explicit ExecutorImpl(std::shared_ptr pinHdi); virtual ~ExecutorImpl() {} @@ -255,7 +256,9 @@ The development procedure is as follows: int32_t Cancel(uint64_t scheduleId) override; int32_t SendCommand(int32_t commandId, const std::vector &extraInfo, const sptr &callbackObj) override; - + int32_t GetProperty(const std::vector &templateIdList, const std::vector &propertyTypes, + Property &property) override; + private: class ScheduleMap { public: @@ -264,7 +267,7 @@ The development procedure is as follows: uint32_t GetScheduleInfo(const uint64_t scheduleId, uint32_t &commandId, sptr &callback, uint64_t &templateId, std::vector &salt); uint32_t DeleteScheduleId(const uint64_t scheduleId); - + private: struct ScheduleInfo { uint32_t commandId; @@ -272,20 +275,20 @@ The development procedure is as follows: uint64_t templateId; std::vector salt; }; - + std::mutex mutex_; std::map scheduleInfo_; }; - + private: uint32_t NewSalt(std::vector &salt); void CallError(const sptr &callbackObj, const uint32_t errorCode); std::shared_ptr pinHdi_; ScheduleMap scheduleMap_; }; - - // Obtain the executor list and create an executor (example only). - int32_t PinAuthInterfaceService::GetExecutorList(std::vector> &executorList) + + // Obtain the executor list (using the method of version V1_1) and create an executor (example only). + int32_t PinAuthInterfaceService::GetExecutorListV1_1(std::vector> &executorList) { IAM_LOGI("start"); std::shared_ptr pinHdi = @@ -303,11 +306,22 @@ The development procedure is as follows: IAM_LOGI("end"); return HDF_SUCCESS; } + + // Obtain the executor list. The method of V1_0 is called to invoke the API of V1_1 through parameter conversion. + int32_t PinAuthInterfaceService::GetExecutorList(std::vector> &executorList) + { + std::vector> executorListV1_1; + int32_t result = GetExecutorListV1_1(executorListV1_1); + for (auto &executor : executorListV1_1) { + executorList.push_back(executor); + } + return result; + } ``` - - - -1. Implement functions of the executor. For details about the code, see [executor_impl.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/pin_auth/hdi_service/service/src/executor_impl.cpp). + + + +1. Implement each function of the executor. For details about the code, see [executor_impl.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/pin_auth/hdi_service/service/src/executor_impl.cpp). ```c++ // Obtain executor information (example only). @@ -330,10 +344,10 @@ The development procedure is as follows: return result; } info.esl = static_cast(eslRet); - + return HDF_SUCCESS; } - + // Obtain template information based on templateId. int32_t ExecutorImpl::GetTemplateInfo(uint64_t templateId, TemplateInfo &info) { @@ -354,14 +368,14 @@ The development procedure is as follows: IAM_LOGE("Failed to copy subType to extraInfo."); return HDF_FAILURE; } - + info.executorType = EXECUTOR_TYPE; info.remainAttempts = infoRet.remainTimes; info.lockoutDuration = infoRet.freezingTime; - + return HDF_SUCCESS; } - + // After the executor is successfully registered, obtain the public key and template ID list from User_auth and save the public key obtained. The executor compares its template ID list with the template ID list obtained and updates its template ID list. int32_t ExecutorImpl::OnRegisterFinish(const std::vector &templateIdList, const std::vector &frameworkPublicKey, const std::vector &extraInfo) @@ -378,10 +392,10 @@ The development procedure is as follows: IAM_LOGE("Failed to verify templateData"); return result; } - + return HDF_SUCCESS; } - + // Enroll the PIN. int32_t ExecutorImpl::Enroll(uint64_t scheduleId, const std::vector &extraInfo, const sptr &callbackObj) @@ -413,10 +427,10 @@ The development procedure is as follows: } return result; } - + return HDF_SUCCESS; } - + // Implement the callback for returning data. int32_t ExecutorImpl::OnSetData(uint64_t scheduleId, uint64_t authSubType, const std::vector &data) { @@ -452,7 +466,7 @@ The development procedure is as follows: default: IAM_LOGE("Error commandId"); } - + if (callback->OnResult(result, resultTlv) != SUCCESS) { IAM_LOGE("callbackObj Pin failed"); } @@ -460,7 +474,7 @@ The development procedure is as follows: if (scheduleMap_.DeleteScheduleId(scheduleId) != HDF_SUCCESS) { IAM_LOGI("Failed to delete scheduleId"); } - + return HDF_SUCCESS; } // Perform PIN authentication. @@ -500,10 +514,10 @@ The development procedure is as follows: } return result; } - + return HDF_SUCCESS; } - + // Delete the PIN template. int32_t ExecutorImpl::Delete(uint64_t templateId) { @@ -517,10 +531,10 @@ The development procedure is as follows: IAM_LOGE("Failed to verify templateData, error code : %{public}d", result); return result; } - + return HDF_SUCCESS; } - + // Cancel the operation based on the specified scheduleId. int32_t ExecutorImpl::Cancel(uint64_t scheduleId) { @@ -531,7 +545,7 @@ The development procedure is as follows: } return HDF_SUCCESS; } - + // API reserved. int32_t ExecutorImpl::SendCommand(int32_t commandId, const std::vector &extraInfo, const sptr &callbackObj) @@ -542,8 +556,37 @@ The development procedure is as follows: static_cast(callbackObj); return HDF_SUCCESS; } + + // Obtain the executor property information. + int32_t ExecutorImpl::GetProperty( + const std::vector &templateIdList, const std::vector &propertyTypes, Property &property) + { + IAM_LOGI("start"); + if (pinHdi_ == nullptr) { + IAM_LOGE("pinHdi_ is nullptr"); + return HDF_FAILURE; + } + + if (templateIdList.size() != 1) { + IAM_LOGE("templateIdList size is not 1"); + return HDF_FAILURE; + } + + uint64_t templateId = templateIdList[0]; + OHOS::UserIam::PinAuth::PinCredentialInfo infoRet = {}; + int32_t result = pinHdi_->QueryPinInfo(templateId, infoRet); + if (result != SUCCESS) { + IAM_LOGE("Failed to get TemplateInfo, error code : %{public}d", result); + return HDF_FAILURE; + } + + property.authSubType = infoRet.subType; + property.remainAttempts = infoRet.remainTimes; + property.lockoutDuration = infoRet.freezingTime; + return HDF_SUCCESS; + } ``` - + ### Verification Verify whether PIN authentication can be successfully performed on the RK3568 platform as follows: diff --git a/en/device-dev/driver/driver-peripherals-user-auth-des.md b/en/device-dev/driver/driver-peripherals-user-auth-des.md index 160d121393b3ec6c57b0ae2981dba873b222df0b..9dde23569a6e45f84cadeead9422b8652b4a4895 100644 --- a/en/device-dev/driver/driver-peripherals-user-auth-des.md +++ b/en/device-dev/driver/driver-peripherals-user-auth-des.md @@ -71,7 +71,7 @@ The identity authentication consists of the User_auth framework and basic authen - Kit The kit provides basic APIs for third-party applications. - + - Inner API Inner API is an API provided by OpenHarmony for system applications. @@ -95,7 +95,7 @@ You can develop drivers to call Hardware Device Interface (HDI) APIs based on th **Figure 2** User_auth service and User_auth driver APIs -![image](figures/user_auth_service_and_driver_api.png "interaction between the user_auth service and driver") +![image](figures/user_auth_service_and_driver_api.png "Interaction") ### Constraints @@ -109,7 +109,7 @@ The User_auth driver provides stable user credential management, authentication ### Available APIs -The following table describes the C++ APIs generated from the Interface Definition Language (IDL) interface description. For details about the interface declaration, see the .idl file in **/drivers/interface/user_auth/v1_0/**. +The following table describes the C++ APIs generated from the Interface Definition Language (IDL) interface description. For details about the interface declaration, see the .idl file in **/drivers/interface/user_auth**. **Table 1** describes the HDI APIs for executor registration, credential enrollment and deletion, user authentication, and user identification. **Table 1** Available APIs @@ -117,38 +117,40 @@ The following table describes the C++ APIs generated from the Interface Definiti | API | Description | | --------------------------- | --------------------------- | | Init() | Initializes cached information. | -| AddExecutor(const ExecutorRegisterInfo& info, uint64_t& index, std::vector& publicKey,
std::vector& templateIds) | Adds an executor to obtain the authentication capability. | +| AddExecutor(const ExecutorRegisterInfo& info, uint64_t& index, std::vector\& publicKey,
std::vector\& templateIds) | Adds an executor to obtain the authentication capability. | | DeleteExecutor(uint64_t index) | Deletes an executor. | -| OpenSession(int32_t userId, std::vector& challenge) | Opens a session for authentication credential management. | +| OpenSession(int32_t userId, std::vector\& challenge) | Opens a session for authentication credential management. | | CloseSession(int32_t userId) | Closes a session for authentication credential management. | -| BeginEnrollment(int32_t userId, const std::vector& authToken, const EnrollParam& param,
ScheduleInfo& info) | Enrolls the user authentication credential. If a user has enrolled a PIN, the old PIN will be overwritten.| -| UpdateEnrollmentResult(int32_t userId, const std::vector& scheduleResult, uint64_t& credentialId,
CredentialInfo& oldInfo) | Updates the data to complete this enrollment. | +| BeginEnrollment(int32_t userId, const std::vector\& authToken, const EnrollParam& param,
ScheduleInfo& info) | Enrolls the user authentication credential (version V1_0). If a user has enrolled a PIN, the old PIN will be overwritten .| +| UpdateEnrollmentResult(int32_t userId, const std::vector\& scheduleResult, uint64_t& credentialId,
CredentialInfo& oldInfo) | Updates the data to complete this enrollment. | | CancelEnrollment(int32_t userId) | Cancels an enrollment operation. | -| DeleteCredential(int32_t userId, uint64_t credentialId, const std::vector& authToken,
CredentialInfo& info) | Deletes credential information based on the specified **credentialId**. | -| DeleteUser(int32_t userId, const std::vector& authToken,
std::vector& deletedInfos) | Deletes a user PIN from User_auth. | -| EnforceDeleteUser(int32_t userId, std::vector& deletedInfos) | Forcibly deletes a user. This API will be called when a user is deleted from the system. | -| GetCredential(int32_t userId, AuthType authType, std::vector& infos) | Obtains user credential information by authentication type. | -| GetSecureInfo(int32_t userId, uint64_t& secureUid, std::vector& infos) | Obtains the secure user ID and the enrolled tag ID of each authentication type. | -| BeginAuthentication(uint64_t contextId, const AuthSolution& param,
std::vector& scheduleInfos) | Starts an authentication to generate the authentication scheme and scheduling information. | -| UpdateAuthenticationResult(uint64_t contextId, const std::vector& scheduleResult,
AuthResultInfo& info) | Updates the authentication result to evaluate the authentication scheme. | +| DeleteCredential(int32_t userId, uint64_t credentialId, const std::vector\& authToken,
CredentialInfo& info) | Deletes credential information based on the specified **credentialId**. | +| DeleteUser(int32_t userId, const std::vector\& authToken,
std::vector\& deletedInfos) | Deletes a user PIN from User_auth. | +| EnforceDeleteUser(int32_t userId, std::vector\& deletedInfos) | Forcibly deletes a user. This API will be called when a user is deleted from the system. | +| GetCredential(int32_t userId, AuthType authType, std::vector\& infos) | Obtains user credential information by authentication type. | +| GetSecureInfo(int32_t userId, uint64_t& secureUid, std::vector\& infos) | Obtains the secure user ID and the enrolled tag ID of each authentication type. | +| BeginAuthentication(uint64_t contextId, const AuthSolution& param,
std::vector\& scheduleInfos) | Starts authentication and generates the authentication scheme and scheduling information (version V1_0). | +| UpdateAuthenticationResult(uint64_t contextId, const std::vector\& scheduleResult,
AuthResultInfo& info) | Updates the authentication result to evaluate the authentication scheme. | | CancelAuthentication(uint64_t contextId) | Cancels an authentication. | -| BeginIdentification(uint64_t contextId, AuthType authType, const std::vector& challenge,
uint32_t executorId, ScheduleInfo& scheduleInfo) | Starts an identification to generate the identification scheme and scheduling information. | -| UpdateIdentificationResult(uint64_t contextId, const std::vector& scheduleResult,
IdentifyResultInfo& info) | Updates the identification result to evaluate the identification scheme. | +| BeginIdentification(uint64_t contextId, AuthType authType, const std::vector\& challenge,
uint32_t executorId, ScheduleInfo& scheduleInfo) | Starts identification and generates the identification scheme and scheduling information (version V1_0). | +| UpdateIdentificationResult(uint64_t contextId, const std::vector\& scheduleResult,
IdentifyResultInfo& info) | Updates the identification result to evaluate the identification scheme. | | CancelIdentification(uint64_t contextId) | Cancels an identification. | | GetAuthTrustLevel(int32_t userId, AuthType authType, uint32_t& authTrustLevel) | Obtains the authentication trust level of the specified authentication type. | -| GetValidSolution(int32_t userId, const std::vector& authTypes, uint32_t authTrustLevel,
std::vector& validTypes) | Obtains the valid authentication scheme based on the authentication trust level for a user. | - +| GetValidSolution(int32_t userId, const std::vector\& authTypes, uint32_t authTrustLevel,
std::vector\& validTypes) | Obtains the valid authentication scheme based on the authentication trust level for a user. | +| BeginEnrollmentV1_1(int32_t userId, const std::vector\& authToken, const EnrollParam& param, ScheduleInfoV1_1& info) | Enrolls the user authentication credential (version V1_1). If a user has enrolled a PIN, the old PIN will be overwritten.| +| BeginAuthenticationV1_1(uint64_t contextId, const AuthSolution& param, std::vector\& scheduleInfos) | Starts authentication and generates the authentication scheme and scheduling information (version V1_1). | +| BeginIdentificationV1_1(uint64_t contextId, AuthType authType,
const std::vector\& challenge, uint32_t executorSensorHint, ScheduleInfoV1_1& scheduleInfo) | Starts identification and generates the identification scheme and scheduling information (version V1_1). | ### How to Develop The following uses the Hi3516D V300 development board as an example to demonstrate how to develop the User_auth driver.
The directory structure is as follows: ```undefined // drivers/peripheral/user_auth -├── BUILD.gn # Build script -├── bundle.json # Component description file -└── hdi_service # User_auth driver implementation - ├── BUILD.gn # Build script - ├── module # Implementation of functionalities +├── BUILD.gn # Build script +├── bundle.json # Component description file +└── hdi_service # User_auth driver implementation + ├── BUILD.gn # Build script + ├── module # Implementation of functionalities └── service ├── user_auth_interface_driver.cpp # User_auth driver entry └── user_auth_interface_service.cpp # Implementation of the APIs for obtaining the executor list @@ -164,17 +166,17 @@ The development procedure is as follows: struct IDeviceIoService ioService; OHOS::sptr stub; }; - + // Enable the IPC service to call the response API. static int32_t UserAuthInterfaceDriverDispatch(struct HdfDeviceIoClient *client, int cmdId, struct HdfSBuf *data, struct HdfSBuf *reply) { auto *hdfUserAuthInterfaceHost = CONTAINER_OF(client->device->service, struct HdfUserAuthInterfaceHost, ioService); - + OHOS::MessageParcel *dataParcel = nullptr; OHOS::MessageParcel *replyParcel = nullptr; OHOS::MessageOption option; - + if (SbufToParcel(data, &dataParcel) != HDF_SUCCESS) { HDF_LOGE("%{public}s:invalid data sbuf object to dispatch", __func__); return HDF_ERR_INVALID_PARAM; @@ -183,10 +185,10 @@ The development procedure is as follows: HDF_LOGE("%{public}s:invalid reply sbuf object to dispatch", __func__); return HDF_ERR_INVALID_PARAM; } - + return hdfUserAuthInterfaceHost->stub->SendRequest(cmdId, *dataParcel, *replyParcel, option); } - + // Initialize the HdfUserAuthInterfaceDriver object. int HdfUserAuthInterfaceDriverInit(struct HdfDeviceObject *deviceObject) { @@ -194,46 +196,46 @@ The development procedure is as follows: OHOS::UserIAM::Common::Init(); return HDF_SUCCESS; } - + // Bind the service provided by the User_auth driver to the HDF. int HdfUserAuthInterfaceDriverBind(struct HdfDeviceObject *deviceObject) { HDF_LOGI("HdfUserAuthInterfaceDriverBind enter"); - + auto *hdfUserAuthInterfaceHost = new (std::nothrow) HdfUserAuthInterfaceHost; if (hdfUserAuthInterfaceHost == nullptr) { - HDF_LOGE("%{public}s: Failed to create HdfUserAuthInterfaceHost object", __func__); + HDF_LOGE("%{public}s: failed to create HdfUserAuthInterfaceHost object", __func__); return HDF_FAILURE; } - + hdfUserAuthInterfaceHost->ioService.Dispatch = UserAuthInterfaceDriverDispatch; hdfUserAuthInterfaceHost->ioService.Open = NULL; hdfUserAuthInterfaceHost->ioService.Release = NULL; - + auto serviceImpl = IUserAuthInterface::Get(true); if (serviceImpl == nullptr) { - HDF_LOGE("%{public}s: Failed to obtain service", __func__); + HDF_LOGE("%{public}s: failed to implement service", __func__); return HDF_FAILURE; } - + hdfUserAuthInterfaceHost->stub = OHOS::HDI::ObjectCollector::GetInstance().GetOrNewObject(serviceImpl, IUserAuthInterface::GetDescriptor()); if (hdfUserAuthInterfaceHost->stub == nullptr) { HDF_LOGE("%{public}s: failed to get stub object", __func__); return HDF_FAILURE; } - + deviceObject->service = &hdfUserAuthInterfaceHost->ioService; return HDF_SUCCESS; } - + // Release resources of the User_auth driver. void HdfUserAuthInterfaceDriverRelease(struct HdfDeviceObject *deviceObject){ HDF_LOGI("HdfUserAuthInterfaceDriverRelease enter"); auto *hdfUserAuthInterfaceHost = CONTAINER_OF(deviceObject->service, struct HdfUserAuthInterfaceHost, ioService); delete hdfUserAuthInterfaceHost; } - + // Register the User_auth driver entry data structure object. struct HdfDriverEntry g_userAuthInterfaceDriverEntry = { .moduleVersion = 1, @@ -242,7 +244,7 @@ The development procedure is as follows: .Init = HdfUserAuthInterfaceDriverInit, .Release = HdfUserAuthInterfaceDriverRelease, }; - + // Call HDF_INIT to register the driver entry with the HDF. When loading the driver, the HDF calls the Bind() function and then the Init() function. If the Init() function fails to be called, the HDF will call Release() to release driver resources and exit the driver model. #ifndef __cplusplus extern "C" { @@ -267,14 +269,14 @@ The development procedure is as follows: GlobalUnLock(); return ret; } - + // Delete the executor. int32_t UserAuthInterfaceService::DeleteExecutor(uint64_t index) { return UnRegisterExecutor(index); } ``` - + 3. Enroll user authentication data. For details about the code, see [user_auth_interface_service.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/user_auth/hdi_service/service/user_auth_interface_service.cpp). ```c++ @@ -286,13 +288,13 @@ The development procedure is as follows: int32_t ret = OpenEditSession(userId, &challengeU64); challenge.resize(sizeof(uint64_t)); if (memcpy_s(&challenge[0], challenge.size(), &challengeU64, sizeof(uint64_t)) != EOK) { - IAM_LOGE("Failed to copy challengeU64"); + IAM_LOGE("failed to copy challengeU64"); return RESULT_BAD_COPY; } GlobalUnLock(); return ret; } - + // Close the session for authentication credential management. int32_t UserAuthInterfaceService::CloseSession(int32_t userId) { @@ -301,10 +303,10 @@ The development procedure is as follows: GlobalUnLock(); return ret; } - - // Start an authentication to generate enrollment and scheduling information. - int32_t UserAuthInterfaceService::BeginEnrollment(int32_t userId, const std::vector& authToken, - const EnrollParam& param, ScheduleInfo& info) + + // Start enrollment and generate scheduling information (V1_1). + int32_t UserAuthInterfaceService::BeginEnrollmentV1_1(int32_t userId, const std::vector& authToken, + const EnrollParam& param, ScheduleInfoV1_1& info) { IAM_LOGI("start"); GlobalLock(); @@ -342,7 +344,18 @@ The development procedure is as follows: GlobalUnLock(); return ret; } - + + // Start enrollment and generate scheduling information (V1_0 version). The method of V1_0 is called to invoke the method of V1_1 through parameter conversion. + int32_t UserAuthInterfaceService::BeginEnrollment(int32_t userId, const std::vector &authToken, + const EnrollParam ¶m, ScheduleInfo &info) + { + IAM_LOGI("start"); + ScheduleInfoV1_1 infoV1_1; + int32_t ret = BeginEnrollmentV1_1(userId, authToken, param, infoV1_1); + CopyScheduleInfoV1_1ToV1_0(infoV1_1, info); + return ret; + } + // Cancel the enrollment operation. int32_t UserAuthInterfaceService::CancelEnrollment(int32_t userId) { @@ -350,7 +363,7 @@ The development procedure is as follows: BreakOffCoauthSchedule(userId); return RESULT_SUCCESS; } - + // Update the enrolled credential information. int32_t UserAuthInterfaceService::UpdateEnrollmentResult(int32_t userId, const std::vector& scheduleResult, uint64_t& credentialId, CredentialInfo& oldInfo) @@ -405,14 +418,14 @@ The development procedure is as follows: } return userAuthInterfaceService; } - + // Start an authentication to generate the authentication scheme and scheduling information. - int32_t UserAuthInterfaceService::BeginAuthentication(uint64_t contextId, const AuthSolution& param, - std::vector& infos) + int32_t UserAuthInterfaceService::BeginAuthenticationV1_1(uint64_t contextId, const AuthSolution& param, + std::vector& infos) { IAM_LOGI("start"); if (param.challenge.size() != sizeof(uint64_t)) { - IAM_LOGE("Failed to copy the challenge"); + IAM_LOGE("Failed to copy challenge"); return RESULT_BAD_PARAM; } GlobalLock(); @@ -425,7 +438,7 @@ The development procedure is as follows: solutionIn.authTrustLevel = param.authTrustLevel; if (memcpy_s(&solutionIn.challenge, sizeof(uint64_t), ¶m.challenge[0], param.challenge.size()) != EOK) { - IAM_LOGE("Failed to copy the challenge"); + IAM_LOGE("Failed to copy challenge"); GlobalUnLock(); return RESULT_BAD_COPY; } @@ -436,7 +449,7 @@ The development procedure is as follows: return ret; } for (uint32_t i = 0; i < scheduleIdNum; i++) { - ScheduleInfo temp; + ScheduleInfoV1_1 temp; if (!CopyScheduleInfo(schedulesGet + i, &temp)) { infos.clear(); ret = RESULT_GENERAL_ERROR; @@ -448,7 +461,18 @@ The development procedure is as follows: GlobalUnLock(); return ret; } - + + // Start user authentication, generate the authentication scheme and scheduling information. The method of V1_0 is called to invoke the method of V1_1 through parameter conversion. + int32_t UserAuthInterfaceService::BeginAuthentication(uint64_t contextId, const AuthSolution ¶m, + std::vector &infos) + { + IAM_LOGI("start"); + std::vector infosV1_1; + int32_t ret = BeginAuthenticationV1_1(contextId, param, infosV1_1); + CopyScheduleInfosV1_1ToV1_0(infosV1_1, infos); + return ret; + } + // Update the authentication result to evaluate the authentication scheme. int32_t UserAuthInterfaceService::UpdateAuthenticationResult(uint64_t contextId, const std::vector& scheduleResult, AuthResultInfo& info) @@ -471,7 +495,7 @@ The development procedure is as follows: UserAuthTokenHal authTokenHal; info.result = RequestAuthResultFunc(contextId, scheduleResultBuffer, &authTokenHal); if (info.result != RESULT_SUCCESS) { - IAM_LOGE("Failed to execute the function"); + IAM_LOGE("Failed to execute func"); DestoryBuffer(scheduleResultBuffer); GlobalUnLock(); return info.result; @@ -487,7 +511,7 @@ The development procedure is as follows: GlobalUnLock(); return RESULT_SUCCESS; } - + // Cancel the authentication. int32_t UserAuthInterfaceService::CancelAuthentication(uint64_t contextId) { @@ -496,7 +520,7 @@ The development procedure is as follows: uint32_t scheduleIdNum = 0; int32_t ret = CancelContextFunc(contextId, nullptr, &scheduleIdNum); if (ret != RESULT_SUCCESS) { - IAM_LOGE("Failed to execute the function"); + IAM_LOGE("Failed to execute func"); GlobalUnLock(); return ret; }