HarmonyOS Next Permission Application Advanced: Secrets of Restricted Open Permissions and ACL Application

This article aims to deeply explore the technical details of the Huawei HarmonyOS Next system (as of API12 currently) in developing a multilingual e-commerce platform, and is summarized based on actual development practices. It mainly serves as a technical sharing and communication vehicle, and inevitably has omissions and errors. Colleagues are welcome to put forward valuable opinions and questions so that we can make progress together. This is original content, and any form of reproduction must indicate the source and the original author.
In the permission management system of the HarmonyOS Next system, in addition to the conventional system authorization and user authorization, the restricted open permissions and ACL (Access Control List) application provide developers with a higher-level permission acquisition path in specific scenarios. Reasonable use of these two methods can meet some special functional requirements while ensuring the security and stability of the system. Today, let's explore these two important permission application mechanisms in depth.

1. Restricted Open Permissions: Permission Acquisition in Special Scenarios

(1) Concept of Restricted Open Permissions

Restricted open permissions refer to those permissions that are usually not open to third-party applications, but under certain special scenarios, after strict review, applications can be allowed to apply for them. These permissions involve some sensitive functions of the system or important user data, so they need to be managed carefully to prevent permission abuse. It can be imagined as a "high-level confidential area" in the system, and only applications that meet specific conditions can obtain permission to enter.

(2) Common Restricted Open Permissions and Special Scenarios

1. Permission to Read Audio Files (ohos.permission.READ_AUDIO)     - Special Scenario: When an application needs to clone, back up, or synchronize audio files, it may need to apply for this permission. For example, a music editing application may need to read user audio files for editing and processing, or a music playback application may need to read local audio files for playlist management.     - Alternative Solution: In other non-special scenarios, priority should be given to using "AudioPicker" to access user audio files. This way can access audio files without applying for restricted permissions, reducing the difficulty and risk of permission acquisition.
2. Permission to Modify Audio Files (ohos.permission.WRITE_AUDIO)     - Special Scenario: Similar to the permission to read audio files, when an application involves cloning, backing up, or synchronizing audio files and needs to modify the audio files, it can apply for this permission. For example, an audio format conversion application needs to modify the encoding format of audio files.     - Alternative Solution: Use "AudioPicker" to save user audio files to avoid directly applying for modification permissions and reduce potential risks to the system.
3. Permission to Read the Clipboard (ohos.permission.READ_PASTEBOARD)     - Special Scenario: Applications on 2-in-1 devices can usually apply for this permission. In addition, bank applications that need to read the bank card number in the clipboard to automatically generate a card, applications that need to read a specific format password in the clipboard to automatically open the corresponding page in the application, and document editing applications can also apply for it. For example, a bank application can read the card number information in the clipboard to facilitate users to quickly input the bank card number.     - Alternative Solution: For most applications, it is recommended to use the "paste control" to read clipboard data. This way does not require applying for restricted permissions and provides a convenient user experience. ### (3) Application Process of Restricted Open Permissions
4. Preparations before Review Before applying for restricted open permissions, developers must carefully examine whether the application truly meets the relevant special scenario requirements. This requires in-depth analysis of the application's functions and business logic to ensure the necessity and rationality of the application. At the same time, priority should be given to exploring whether there are other alternative solutions, such as using relevant components or controls provided by the system to achieve the same function, to avoid unnecessary permission applications.
5. AGC Application and Review     - Submitting Application Materials: If it is determined that restricted open permissions need to be applied for, developers need to provide detailed application materials to the application market (AppGallery Connect, abbreviated as AGC). These materials include the application's usage scenario description, function description, reasons for applying for permissions, etc., and must ensure that the information is accurate, complete, and true. For example, if applying for the permission to read audio files, it is necessary to explain in detail the specific operation process and user value in the process of audio cloning, backup, or synchronization.     - Review Process and Precautions: AGC will conduct a strict review of the application's usage scenario based on the submitted materials. During the review process, the focus will be on evaluating whether the applied permissions are closely related to the actual functions of the application and whether they comply with the usage specifications of restricted open permissions. Developers should pay close attention to the review results and supplement or correct the application materials in a timely manner if necessary. ### (4) Table of Restricted Open Permission Application Scenarios and Alternative Solutions | Permission Name | Applicable Special Scenarios | Alternative Solutions | |---|---|---| | ohos.permission.READ_AUDIO | Application needs to clone, back up, or synchronize audio files | Use "AudioPicker" to access user audio files | | ohos.permission.WRITE_AUDIO | Application needs to clone, back up, or synchronize audio files | Use "AudioPicker" to save user audio files | | ohos.permission.READ_PASTEBOARD | Bank applications read the bank card number in the clipboard to automatically generate a card, applications read a specific format password in the clipboard to automatically open the corresponding page in the application, document editing applications, etc. | Use the "paste control" to read clipboard data | ## 2. ACL Application: Breaking through Permission Level Restrictions ### (1) The Role of ACL Application The ACL application provides a special way for low-level applications to obtain high-level permissions. In the HarmonyOS Next system, the permission level is closely related to the APL (Ability Privilege Level) level of the application. In principle, low APL level applications cannot apply for higher-level permissions. However, through the ACL application mechanism, under specific conditions, applications can cross the permission level restriction and access higher-level system resources. It is like building a temporary "permission bridge" for applications with special needs, enabling them to obtain the required permissions under the premise of security and controllability. ### (2) ACL Application Process
6. Applying for the Profile File on the AGC Side     - Importance and Purpose: The Profile file plays a crucial role in the ACL application process, and it is used for subsequent application signature information configuration. When applying for the Profile file on the AGC side, developers must clearly apply to use the corresponding restricted permissions. This step is like the application process for the application to obtain a "passport", and only by indicating the required permissions in the application can the subsequent operations proceed smoothly.     - Application Steps and Precautions: When applying for the Profile file, developers need to fill in accurate application information and permission usage scenario descriptions according to the requirements of AGC. Ensure that the provided information is consistent with the actual application functions and permission requirements, otherwise the application may be rejected. For example, if an application needs to apply for the permission to access system hardware information through ACL, it should explain in detail how the application will use the hardware information and the value to the user when applying for the Profile file.
7. Declaring Permissions in the Code Project     - Configuration File Declaration: After completing the Profile file application on the AGC side, developers need to declare the required permissions in the configuration file of the code project. Similar to the ordinary permission declaration, it is declared in the "requestPermissions" tag of the "module.json5" configuration file. For example:

{
"module": {
"requestPermissions":[
{
"name": "ohos.permission.SOME_ADVANCED_PERMISSION",
"reason": "$string:reason_for_advanced_permission",
"usedScene": {
"abilities": [
"MainAbility"
],
"when":"inuse"
}
}
]
}
}

Among them, "name" is the name of the advanced permission to be applied for, "reason" needs to explain in detail the reason for applying for the permission, following the copywriting specifications for permission usage reasons, and "usedScene" specifies the scene where the permission is used.
    - User Authorization Related (if any): If the applied advanced permission belongs to the user_grant type, it is also necessary to follow the user authorization process, request permission from the user through a pop-up window when the application is running, and handle the user's authorization result. This ensures that even the advanced permissions obtained through ACL application also follow the principles of user's right to know and right to choose.

(3) Example Code: Using ACL to Apply for the Permission to Read Audio Files

The following is an example code for using ACL to apply for the permission to read audio files (ohos.permission.READ_AUDIO):

import { abilityAccessCtrl, bundleManager, Permissions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
// Define the restricted open permission to be applied for (here, taking the permission to read audio files as an example)
const advancedPermission: Permissions = 'ohos.permission.READ_AUDIO';
// Check whether the application has currently been granted this advanced permission
async function checkAdvancedPermissionGrant(): Promise<abilityAccessCtrl.GrantStatus> {
let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let grantStatus: abilityAccessCtrl.GrantStatus = abilityAccessCtrl.GrantStatus.PERMISSION_DENIED;
// Get the accessTokenID of the application program
let tokenId: number = 0;
try {
let bundleInfo: bundleManager.BundleInfo = await bundleManager.getBundleInfoForSelf(bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION);
let appInfo: bundleManager.ApplicationInfo = bundleInfo.appInfo;
tokenId = appInfo.accessTokenID;
} catch (error) {
const err: BusinessError = error as BusinessError;
console.error(`Failed to get bundle info for self. Code is ${err.code}, message is ${err.message}`);
}
// Check whether the application has been granted the advanced permission
try {
grantStatus = await atManager.checkAccessToken(tokenId, advancedPermission);
} catch (error) {
const err: BusinessError = error as BusinessError;
console.error(`Failed to check access token for advanced permission. Code is ${err.code}, message is ${err.message}`);
}
return grantStatus;
}
// The main function for applying for advanced permissions
async function requestAdvancedPermission(): Promise<void> {
let grantStatus: abilityAccessCtrl.GrantStatus = await checkAdvancedPermissionGrant();
if (grantStatus === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
// The advanced permission has been obtained, and the operation of reading audio files can be performed
console.log('The permission to read audio files has been successfully obtained, and relevant operations can be performed.');
// Add the specific code logic for reading audio files here
} else {
// Apply for advanced permissions
reqAdvancedPermissionFromUser();
}
}
// Use the API to dynamically request user authorization (if the permission is of the user_grant type)
function reqAdvancedPermissionFromUser(): void {
let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
atManager.requestPermissionsFromUser(globalThis.context as common.UIAbilityContext, [advancedPermission]).then((data) => {
let grantStatus: Array<number> = data.authResults;
let length: number = grantStatus.length;
for (let i = 0; i < length; i++) {
if (grantStatus[i] === 0) {
// The user has authorized, and the target operation can be accessed to perform the operation of reading audio files
console.log('The user has authorized the permission to read audio files, and relevant operations can be performed.');
// Add the specific code logic for reading audio files here
} else {
// The user has refused to authorize, prompt the user that authorization is required to access the relevant function, and guide the user to open the corresponding permission in the system settings
console.log('The user has refused to authorize the permission to read audio files. Please go to the system settings to manually grant the permission.');
return;
}
}
// The authorization is successful
}).catch((err: BusinessError) => {
console.error(`Failed to request advanced permission from user. Code is ${err.code}, message is ${err.message}`);
});
}
// Call the requestAdvancedPermission() function to start the permission application process when the application is started or when the advanced permission is needed
requestAdvancedPermission();

In the above example code, the permission to read audio files (ohos.permission.READ_AUDIO) is first defined. Then, the "checkAdvancedPermissionGrant()" function is used to check whether the application has currently obtained the permission. If the permission has not been obtained, the "reqAdvancedPermissionFromUser()" function is called to request authorization from the user (if the permission belongs to the user_grant type). According to the user's authorization result, the application will output the corresponding prompt information in the console, and after the authorization is successful, the operation related to reading audio files can be performed.
In conclusion, the restricted open permissions and ACL application provide a way for HarmonyOS Next application development to obtain high-level permissions in special scenarios. We must strictly follow the application process and specifications in the use process, fully consider user privacy and system security, and ensure the reasonable use of permissions. Through the reasonable use of these permission application mechanisms, developers can create more powerful and high-quality applications for users and contribute to the security and stability of the HarmonyOS Next ecosystem. I hope this article can help colleagues better understand and use the restricted open permissions and ACL