System services registered with Samgr can be accessed by other processes through IPC APIs. When a process requests to access such an API, IPC authentication is triggered to check whether the process has the required permission. If the process does not have the required permission, the access request will be denied.
When developing a system service, you can use the IPC authentication component to configure access policies for APIs of the service. When other processes access these APIs through IPC, Samgr calls APIs of the IPC authentication component to check whether the processes have the access permission.
When developing a system service, you can use the IPC authentication component to configure access policies for APIs of the service. When other services access these APIs through IPC, Samgr calls APIs of the IPC authentication component to check whether the services have the access permission.
## Available APIs<a name="section1633115419401"></a>
The following table lists the APIs provided by IPC authentication \(intended for Samgr only\).
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p134951921115511"><aname="p134951921115511"></a><aname="p134951921115511"></a>Checks whether a process has the permission to access an API of another service.</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p134951921115511"><aname="p134951921115511"></a><aname="p134951921115511"></a>Checks whether a process has the permission to access an API of another process.</p>
</td>
</tr>
</tbody>
...
...
@@ -39,15 +39,15 @@ The following table lists the APIs provided by IPC authentication \(intended for
## How to Develop<a name="section022611498210"></a>
This section uses BMS as an example to describe how to configure access policies for APIs provided by the IPC authentication component. In this example, the service registered by BMS with Samgr is **bundlems**, and the feature registered for open APIs is**BmsFeature**.
This section uses BMS as an example to describe how to configure access policies for APIs provided by the IPC authentication component. In this example, the service registered by BMS with Samgr is **bundlems**, and the feature registered for open APIs is **BmsFeature**.
1.<aname="li15901515152517"></a>On the OpenHarmony side, configure access policies in the **base/security/permission/services/permission\_lite/ipc\_auth/include/policy\_preset.h** file. On the device side, configure access policies in the **vendor/hisilicon/product_name/hals/security/permission\_lite/ipc\_auth/include/policy\_preset\_product.h** file (replace product_name with the actual product name). After that, set **POLICY\_PRODUCT** in the header files to**1**. Access policies are classified into the following three types:
1.<aname="li15901515152517"></a>On the OpenHarmony side, configure access policies in the **base/security/permission/services/permission\_lite/ipc\_auth/include/policy\_preset.h** file. On the device side, configure access policies in the **vendor/hisilicon/_product name_/hals/security/permission\_lite/ipc\_auth/include/policy\_preset\_product.h** file. After that, set **POLICY\_PRODUCT** in the header files to **1**. Access policies are classified into the following three types:
1. **RANGE**: Processes with a specified range of UIDs can access BMS APIs. **uidMin** and **uidMax** must be specified.
1. **RANGE**: Processes with a specified range of UIDs can access BMS APIs. **uidMin** and **uidMax** must be specified.
2. **FIXED**: Processes with specified UIDs can access BMS APIs. **fixedUid** must be specified, and a maximum of eight UIDs are allowed.
2. **FIXED**: Processes with specified UIDs can access BMS APIs. **fixedUid** must be specified, and a maximum of eight UIDs are allowed.
3. **BUNDLENAME**: An application with a specified **bundleName** can access BMS APIs.
3. **BUNDLENAME**: An application with a specified **bundleName** can access BMS APIs.
```
FeaturePolicy bmsFeature[] = {
...
...
@@ -59,7 +59,7 @@ This section uses BMS as an example to describe how to configure access policies
.fixedUid={2, 3, 8}
},
{
.type=RANGE, // Processes with a specified range of UIDs can access BMS APIs.
.type=RANGE, // Processes with a specified range of UIDs can access BMS APIs.
.uidMin=100,
.uidMax=__INT_MAX__,
},
...
...
@@ -82,13 +82,13 @@ This section uses BMS as an example to describe how to configure access policies
};
```
2. Add the policies configured for the features in [Step 1](#li15901515152517) to the global policy settings. You need to set the number of features.
2. Add the policies configured for the features in [Step 1](#li15901515152517) to the global policy settings. You need to set the number of features.
```
static PolicySetting g_presetPolicies[] = {
{"permissionms", pmsFeature, 1},
{"abilityms", amsFeature, 2},
{"bundlems", bmsFeature, 2}, // Add the policies configured for the two features in Step 1 to the global policy settings.
{"bundlems", bmsFeature, 2}, // Add the policies configured for the two features in [Step 1](#li15901515152517) to the global policy settings.
{"dtbschedsrv", dmsFeature, 1},
{"samgr", samgrFeature, 1},
{"appspawn", appspawnFeature, 1},
...
...
@@ -97,7 +97,7 @@ This section uses BMS as an example to describe how to configure access policies
};
```
3. Register the **BmsFeature** defined in [Step 1](#li15901515152517) with Samgr.
3. Register the **BmsFeature** defined in [Step 1](#li15901515152517) with Samgr.
```
const char BMS_SERVICE[] = "bundlems";
...
...
@@ -118,22 +118,22 @@ This section uses BMS as an example to describe how to configure access policies
```
When you register a service with Samgr, Samgr calls the **GetCommunicationStrategy** function of the IPC authentication component to obtain access policies of the service. When other processes access this service through IPC, Samgr calls the **IsCommunicationAllowed** function of the IPC authentication component to check whether the processes have the access permission.
When you register a service with Samgr, Samgr calls the **GetCommunicationStrategy** function of the IPC authentication component to obtain access policies of the service. When other services or applications access this service through IPC, Samgr calls the **IsCommunicationAllowed** function of the IPC authentication component to check whether the services or applications have the access permission.
## FAQ<a name="section15729104510271"></a>
-Service registration failure
-Registering a service with Samgr failed
**Symptom**
**Problem**
During the startup of a new service, a message is displayed indicating that the service fails to be registered with Samgr.
**Possible Causes**
**Cause**
The service UID is not configured in the IPC authentication component.
**Solutions**
**Solution**
Configure the service UID in the **base/security/permission/services/permission\_lite/ipc\_auth/src/ipc\_auth\_impl.c** file.
Configure a valid UID for the service in the **base/security/permission/services/permission\_lite/ipc\_auth/src/ipc\_auth\_impl.c** file.
@@ -13,13 +13,9 @@ The OpenHarmony security subsystem provides security capabilities that make your
Application permissions determine what system resources and capabilities an application can access. During application development, you need to declare the permissions that the application may require in the **profile.json** file. Static permissions need to be registered during application installation, while dynamic permissions usually involve sensitive information and need users' dynamic authorization.
- Inter-process communication \(IPC\) authentication
APIs are provided for processes to access system services through IPC. Access policies are configured for these APIs. When a process requests to access an API, the IPC authentication mechanism is triggered to check whether the process has the required permission. If it is found that the process does not have the required permission, the access request will be denied.
- Trusted device group management
You can create and query a group of trusted devices that use the same HUAWEI ID or a peer-to-peer group created by scanning a QR code or using OneHop. With this capability, distributed applications can perform trusted authentication between devices and request from the distributed virtual bus for secure sessions between devices.
You can create and query a group of trusted devices that use the same ID or a peer-to-peer group created by scanning a QR code or using OneHop. With this capability, distributed applications can perform trusted authentication between devices and request from the distributed virtual bus for secure sessions between devices.
@@ -33,7 +29,7 @@ Before developing an application that depends on the signature verification comp
- BMS
Bundle Manager Service \(BMS\) manages application installation, uninstallation, and data.
Bundle Manager Service \(BMS\) manages application installation, uninstallation, and data on OpenHarmony.
- Profile
...
...
@@ -41,19 +37,9 @@ Before developing an application that depends on the signature verification comp
The profile in this document refers to HarmonyAppProvision \(profile for short\). HarmonyAppProvision is in JSON format.
- Leaf certificate
A leaf certificate is used to sign a bundle or profile. It is the last certificate in a digital certificate chain.
- Debugging application
A debugging application is a HarmonyOS Ability Package \(HAP\) that is signed with a debugging certificate and profile obtained from the application market.
- Application for release
This application refers to a HAP that is signed with a distribution certificate and profile obtained from the application market, but has not been released in the application market.
A debugging application is a HAP that is signed with a debugging certificate and profile obtained from the application market.
- Released application
...
...
@@ -63,14 +49,11 @@ Before developing an application that depends on the signature verification comp
- OpenHarmony self-signed application
This application refers to a HAP that is signed with the profile of the OpenHarmony application you have compiled, and a public/private key pair and certificate of OpenHarmony.
A self-signed application is one that has been signed with the signing certificate and profile issued by OpenHarmony's open-source root CA, which is comprised of a certificate and a key.
## Limitations and Constraints<a name="section2029921310472"></a>
- Only signatures of debugging, released, and self-signed applications can be verified.
- Only signatures of debugging, released, and OpenHarmony self-signed applications can be verified.
- To verify the signature of a debugging application, the UDID of the device on which the debugging application is installed must be in the UDID list contained in the profile.
- Signatures of the applications for release cannot be verified.
- APIs provided by the signature verification component are stored in the [app\_verify\_pub.h](https://gitee.com/fork_ohos_wj/security_interfaces_innerkits_app_verify/blob/master/app_verify_pub.h) file of the **security\_interfaces\_innerkits\_app\_verify** repository and can be called only by system application developers.
- APIs for managing trusted device groups are only available for applications with the system signature permission.
## How Application Permission Management Works<a name="section193961322175011"></a>
OpenHarmony allows users to install third-party applications and controls calls made by third-party applications to sensitive permissions. When developing an application, you need to declare the sensitive permissions that the application may require in the **profile.json** file. The permissions include static and dynamic ones. Static permissions need to be registered during application installation, and dynamic permissions can be obtained only upon user authorization. Authorization modes include system settings, manual authorization by applications, and others. In addition, application signature control is used to ensure that the application installation package has been confirmed by the device vendor.
OpenHarmony allows users to install third-party applications and controls calls made by third-party applications to sensitive permissions. When developing an application, you need to declare the sensitive permissions that the application may require in the **profile.json** file. The permissions can be static or dynamic. Static permissions need to be registered during application installation, and dynamic permissions can be obtained only upon user authorization. Authorization modes include system settings, manual authorization by applications, and others. In addition, application signature control is used to ensure that the application installation package has been confirmed by the device vendor.
**Table 1** OpenHarmony permissions
...
...
@@ -215,7 +215,7 @@ This section uses the BMS as an example to describe the application permission d
HILOG_ERROR(HILOG_MODULE_APP, "BundleManager install failed due to nullptr parameters");
return false;
}
// Check whether the ohos.permission.INSTALL_BUNDLE permission has been granted.
// Check whether the ohos.permission.INSTALL_BUNDLE permission has been granted.
if (CheckPermission(0, static_cast<const char *>(PERMISSION_INSTALL_BUNDLE)) != GRANTED) {
HILOG_ERROR(HILOG_MODULE_APP, "BundleManager install failed due to permission denied");
-[Debugging and Verification](#section427316292411)
## When to Use<a name="section18502174174019"></a>
You can call the APIs provided by the signature verification component to check integrity of a debugging, released, or OpenHarmony self-signed application. You can also call APIs of the signature verification component to obtain some information in the profile, for example, **appid**. In addition, you can call APIs to check whether the UDID of a debugging application matches that of the device to ensure that the application is installed on the right device.
To ensure the integrity and trustworthiness of the applications to be installed in OpenHarmony, the applications must be signed and their signatures must be verified.
- In application development: After developing an application, you need to sign its installation package to ensure that the installation package is not tampered with when it is released on devices. To sign the application package, you can use the signature tools and the public key certificates and follow the signing certificate generation specifications provided by the application integrity verification module. For your convenience, a public key certificate and a corresponding private key are preset in OpenHarmony. You need to replace the public key certificate and private key in your commercial version of OpenHarmony.
- In application installation: The Application Framework subsystem of OpenHarmony installs applications. Upon receiving an application installation package, the Application Framework subsystem parses the signature of the installation package, and verifies the signature using the application integrity verification APIs. The application can be installed only after the verification succeeds. During the verification, the application integrity verification module uses the preset public key certificate to verify the signature.
An unsigned HAP is in **.zip** format and consists of a file block, central directory, and end of central directory \(EOCD\).
After the HAP is signed, a signature block is added between the file block and the central directory. The signature block consists of a file signature block, profile signature block, and signature header. The following figure shows the structure of a signed HAP.
**Figure 1** Structure of a signed HAP<aname="fig699855043"></a>
After the HAP is signed, a signature block is added between the file block and the central directory. The integrated signature block consists of a profile signature block, HAP signature block, and signature header. The following figure shows the structure of a signed HAP.
**Figure 1** Structure of a signed HAP<aname="fig157962397486"></a>
The signature verification process consists of three steps: HAP signature verification, signature verification for the profile signature block, and profile content verification.
The signature verification process consists of three steps: HAP signature verification, profile signature verification, and profile content verification.
**HAP signature verification**
Use the preset root certificate of the device and the certificate chain to prove that the leaf certificate is trusted. Then use the digest obtained by decrypting the public key of the leaf certificate to prove that the HAP is not tampered with.
The HAP signature block is a signed data block in PKCS7 format. The signature verification process includes PKSC7 signature verification, hash comparison, certificate chain verification, and matching between the certificate chain and the device's preset root certificate.
The process is as follows:
**Profile signature verification**
1. Use the preset root certificate of the device to verify the certificate chain in the file signature block and prove that the leaf certificate is trusted.
2. Use the public key in the leaf certificate to verify the file signature block and prove that this block is not tampered with.
3. Calculate and merge the digests of the file block, central directory, and EOCD. Merge the calculation result with the digest of the profile signature block in the signature block. Then compare the merge result with the digest of the file signature block. If they are the same, the HAP signature verification is successful.
**Signature verification for the profile signature block**
First of all, check who issued the signature of the profile signature block. If the signature was issued by the application market, the signature is trusted and does not need to be verified. Otherwise, the signature needs to be verified. Next, verify the certificate chain and then use the leaf certificate to verify the signature of the profile signature block to prove that it is not tampered with.
The profile signature block is a signed data block in PKCS7 format. The profile content is stored in **contentinfo** of the PKCS7 signature block. The signature verification process includes PKCS7 signature verification, hash comparison, certificate chain verification, and profile certificate validity verification.
**Profile content verification**
Obtain the profile and check the validity of its content. If the HAP is a debugging application, check whether the UDID of the current device is contained in the UDID list in the profile. If yes, the verification is successful. Then compare the certificate in the profile with the leaf certificate used for HAP verification \(this is not required for a released or OpenHarmony self-signed application\). If they are the same, the entire signature verification process is complete.
The signature verification module checks the validity of the profile content. If the profile is of the debugging type, the module checks whether the UDID of the current device is contained in the UDID list in the profile. If yes, the module compares the certificate in the profile with the certificate used for HAP signature verification. If they are the same, the entire verification process is complete.
## Available APIs<a name="section1633115419401"></a>
The following table lists the innerkits APIs provided by the signature verification component. These APIs are available only for system applications.
**Table 1** APIs provided by the signature verification component
**Table 1** APIs provided by the signature verification component for mini systems
To verify applications released in the application market, debugging applications signed with debugging certificates of the application market, and OpenHarmony self-signed applications, perform the following steps:
1. Construct the VerifyResult structure.
```
VerifyResult verifyResult = {0};
```
2. Call the APPVERI\_AppVerify function by specifying the file path and VerifyResult to verify the application signature.
```
int32_t ret = APPVERI_AppVerify(hapFilepath.c_str(), &verifyResult);
```
3. Check the returned result. If the verification is successful, obtain and process the data in VerifyResult.
Prepare the signature tool, system application HAP, system application profile \(\*.p7b\), signing certificate \(\*.cer\), and signing public/private key pair \(\*.jks\).
2. Place all the materials in the same directory and start the shell.
3. Run the following command in the shell to sign the application:
**-jar**: signature tool, which is **[hapsigntool](https://repo.huaweicloud.com/harmonyos/develop_tools/hapsigntoolv2.jar)**
**-mode**: local signature flag, which is fixed at **localjks**
**-privatekey**: alias of the public/private key pair, which is **OpenHarmony Software Signature**
**-inputFile**: application to be signed, which is generated through compilation
**-outputFile**: signed application
**Table 2** APIs provided by the signature verification component for standard systems
**-signAlg**: signing algorithm, which is fixed at **SHA256withECDSA**
**-keystore**: public/private key pair, which is [OpenHarmony.jks](https://gitee.com/openharmony/security_appverify/blob/master/interfaces/innerkits/appverify_lite/OpenHarmonyCer/OpenHarmony.jks) in the **OpenHarmonyCer** directory of the **security\_services\_app\_verify** repository. The default password is **123456**. You can use a tool \(such as keytool\) to change the password.
**-keystorepasswd**: password of the public/private key pair, which is **123456** by default
**-keyaliaspasswd**: password of the public/private key pair alias, which is **123456** by default
**-profile**: application profile, which is stored in the code directory
**-certpath**: signing certificate, which is [OpenHarmony.cer](https://gitee.com/openharmony/security_appverify/blob/master/interfaces/innerkits/appverify_lite/OpenHarmonyCer/OpenHarmony.cer) in the **OpenHarmonyCer** directory of the **security\_services\_app\_verify** repository.
**-profileSigned**: whether the signature block contains the profile. The value is fixed at **1**, indicating that the signature block contains the profile.
### Development Examples<a name="section174318361353"></a>
The following example describes how the application management framework component verifies the signature of an application during its installation.
<tdclass="cellrowborder"valign="top"width="62.339999999999996%"headers="mcps1.2.3.1.2 "><pid="p0384184810169"><aname="p0384184810169"></a><aname="p0384184810169"></a>Verifies application integrity and identifies the application source.</p>
1. Choose an application that can be properly installed on OpenHarmony.
2. Develop the application based on the development guidelines.
3. Use a self-developed program to verify the signature of the developed application. If the verification is successful and **appid** can be obtained, the development is successful.
To develop an OpenHarmony self-signed application, follow instructions provided in the guide of [_Configuring the OpenHarmony App Signature_](https://gitee.com/openharmony/docs/blob/master/en/application-dev/quick-start/configuring-openharmony-app-signature.md) :
<trid="row1757189172714"><tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.1 "><pid="p1726998273"><aname="p1726998273"></a><aname="p1726998273"></a>struct UsbRequest *UsbAllocRequest(const UsbInterfaceHandle *interfaceHandle, int isoPackets, int length);</p>
<trid="row14756109152719"><tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.1 "><pid="p137288914273"><aname="p137288914273"></a><aname="p137288914273"></a>struct UsbRawRequest *UsbRawAllocRequest(const UsbRawHandle *devHandle, int isoPackets, int length);</p>
USB ACM设备核心代码路径为driversperipheralusbgadgetfunctionacmcdcacm.c，其使用示例如下所示，首先根据描述符创建设备，然后获取接口，打开接口，获取Pipe信息，接收Event事件，接着进行USB通信（读写等），设备卸载时候，关闭接口，停止Event接收，删除设备。
