1# App Permission Management 2 3## Introduction 4 5In OpenHarmony, apps and system services run in independent sandboxes. Both processes and data are isolated from each other to protect the security of app data. However, services or apps running in the sandboxes provide some APIs to implement specific functionalities. To access these APIs across processes, apps in other sandboxes need the required permissions, which are granted and managed based on a permission management mechanism. 6 7App permission management provides the following features: 8 9- Provides a mechanism for defining permissions, allowing system services and apps to define new permissions for their sensitive APIs. To access these APIs, other apps need the required permissions. 10 11- Allows apps to request permissions defined by the system or other applications. Upon obtaining the permissions, the apps can access the sensitive APIs provided by the system or other apps. 12- Allows users to view and manage the permission granting status. 13 14**Figure 1** App permission management architecture 15 16 17 18 19App permission management provides permission management for the app framework subsystem and provides APIs for apps to request permissions and query the permission granting status. The open-source app permission management applies to mini and small systems. 20 21- The mini system is designed for devices with memory larger than or equal to 128 KiB and equipped with MCU processors including ARM Cortex-M and 32-bit RISC-V. It provides a variety of lightweight network protocols, lightweight graphics frameworks, and IoT read/write components via bus. The mini system applies to smart home products, such as LinkIoT module devices, sensors and wearables. 22- The small system is oriented to devices with memory larger than or equal to 1 MiB and equipped with processors like ARM Cortex-A. It provides higher security capabilities, standard graphics frameworks, and video encoding and decoding. The small system applies to smart home products, such as IP cameras, peephole cameras, and routers as well as smart travel products, such as event data recorders (EDRs). 23 24## Directory Structure 25 26``` 27/base/security/permission_lite 28├── interfaces # APIs 29│ ├── innerkits # Internal APIs 30│ └── kits # External APIs 31└── services # Services 32 ├── ipc_auth # IPC communication authentication 33 ├── js_api # JS API encapsulation 34 ├── pms # Permission management logic and server 35 ├── pms_base # Service registration 36 └── pms_client # Permission management client 37``` 38 39## Usage 40 41### Available APIs 42 43The APIs for app permission management of the mini and small systems can be called only by system apps and services. The following table describes the APIs. 44 45| API | Description | 46| ------------------------------------------------------------ | -------------------------------------------------- | 47| int CheckPermission(int uid, const char *permissionName) | Checks whether an app has the permission to access system service APIs.| 48| int CheckSelfPermission(const char *permissionName) | Checks whether the caller has the permission to access system service APIs. | 49| int QueryPermission(const char *identifier, PermissionSaved **permissions, int *permNum) | Queries all permissions requested by an app and checks whether the requested permissions have been granted. | 50| int GrantPermission(const char *identifier, const char *permName) | Grants a permission to an app. | 51| int RevokePermission(const char *identifier, const char *permName) | Revokes a permission from an app. | 52| int GrantRuntimePermission(int uid, const char *permissionName) | Grants a permission during the running of an app. | 53| int RevokeRuntimePermission(int uid, const char *permissionName) | Revokes a permission during the running of an app. | 54| int UpdatePermissionFlags(const char *identifier, const char *permissionName, const int flags) | Updates the flags of the permission specified by an app. | 55 56 57 58The following table describes the APIs for IPC authentication of the mini and small systems. 59 60| API | Description | 61| ------------------------------------------------------------ | ------------------------------------------------------------ | 62| int GetCommunicationStrategy(RegParams params, PolicyTrans **policies, unsigned int *policyNum) | Obtains the access policies for a service API. This API can be called only by System Ability Manager (SAMGR). | 63| int IsCommunicationAllowed(AuthParams params) | Checks whether a process has the permission to access an API of another process. This API can be called only by SAMGR.| 64 65 66 67### How to Use 68 69**App Permission Management for a Mini or Small System** 70 71The following uses the app permission development of the bundle manager service (BMS) as an example. Declare the required sensitive permissions in the **config.json** file during development. During app installation, the BMS calls APIs of the app permission management component to check whether the required permissions are available. If yes, the installation proceeds; otherwise, the installation fails. 72 731. During development, determine and declare the permission (ohos.permission.INSTALL\_BUNDLE) required for installing the app. 74 If the FA model is used, declare the permission in the **config.json** file. The following is an example: 75 ```json 76 { 77 "module": { 78 "package": "ohos.demo.kitframework", 79 "deviceType": [ 80 "phone", "tv","tablet", "car","smartWatch","sportsWatch","smartCamera", "smartVision" 81 ], 82 "reqPermissions": [{ 83 "name": "ohos.permission.INSTALL_BUNDLE", 84 "reason": "install bundle", 85 "usedScene": { 86 "ability": [ 87 "KitFramework" 88 ], 89 "when": "always" 90 } 91 }, 92 { 93 "name": "ohos.permission.LISTEN_BUNDLE_CHANGE", 94 "reason": "install bundle", 95 "usedScene": { 96 "ability": [ 97 "KitFramework" 98 ], 99 "when": "always" 100 } 101 }, 102 { 103 "name": "ohos.permission.GET_BUNDLE_INFO", 104 "reason": "install bundle", 105 "usedScene": { 106 "ability": [ 107 "KitFramework" 108 ], 109 "when": "always" 110 } 111 } 112 ] 113 } 114 } 115 ``` 116 If the stage model is used, declare the permission in **module.json5**. The following is an example: 117 ```json 118 { 119 "module": { 120 "requestPermissions": [{ 121 "name": "ohos.permission.INSTALL_BUNDLE", 122 "reason": "install bundle", 123 "usedScene": { 124 "ability": [ 125 "KitFramework" 126 ], 127 "when": "always" 128 } 129 }, 130 { 131 "name": "ohos.permission.LISTEN_BUNDLE_CHANGE", 132 "reason": "install bundle", 133 "usedScene": { 134 "ability": [ 135 "KitFramework" 136 ], 137 "when": "always" 138 } 139 }, 140 { 141 "name": "ohos.permission.GET_BUNDLE_INFO", 142 "reason": "install bundle", 143 "usedScene": { 144 "ability": [ 145 "KitFramework" 146 ], 147 "when": "always" 148 } 149 }] 150 } 151 } 152 ``` 153 1542. When developing the app installation API, use the **CheckPermission()** API to check whether the BMS has the permission to install the application. For example, **CheckPermission()** is called with the permission name **ohos.permission.INSTALL\_BUNDLE** as the input parameter to check whether the BMS has the permission to install the app. If the BMS has the permission, the installation continues. Otherwise, the installation fails. 155 156 ```c++ 157 constexpr static char PERMISSION_INSTALL_BUNDLE[] = "ohos.permission.INSTALL_BUNDLE"; 158 159 bool Install(const char *hapPath, const InstallParam *installParam, InstallerCallback installerCallback) 160 { 161 if ((hapPath == nullptr) || (installerCallback == nullptr) || (installParam == nullptr)) { 162 HILOG_ERROR(HILOG_MODULE_APP, "BundleManager install failed due to nullptr parameters"); 163 return false; 164 } 165 // Check whether the ohos.permission.INSTALL_BUNDLE permission has been granted. 166 if (CheckPermission(0, static_cast<const char *>(PERMISSION_INSTALL_BUNDLE)) != GRANTED) { 167 HILOG_ERROR(HILOG_MODULE_APP, "BundleManager install failed due to permission denied"); 168 return false; // App installation fails. 169 } 170 // Installation process. 171 ... 172 } 173 ``` 174 175 176**IPC Authentication for a Mini or Small System** 177 178The following example describes how to use the IPC authentication component to configure the policies for accessing the BMS feature. In this example, the service registered by the BMS with SAMGR is **bundlems**, and the feature registered is **BmsFeature**. 179 1801. Configure the access policy in the header file **base/security/permission\_lite/services/ipc\_auth/include/policy\_preset.h** in the source code directory. There are three types of access policies: 181 182 - **RANGE**: allows access from the processes with UIDs in the specified range. **uidMin** and **uidMax** must be specified. 183 - **FIXED**: allows access from the processes with the specified UIDs. **fixedUid** must be specified, and a maximum of eight UIDs are allowed. 184 - **BUNDLENAME**: allows access from the specified app. **bundleName** must be specified. 185 186 ```c++ 187 FeaturePolicy bmsFeature[] = { 188 { 189 "BmsFeature", 190 { 191 { 192 .type=FIXED, // Allow access from the processes with the specified UIDs. 193 .fixedUid={2, 3, 8} 194 }, 195 { 196 .type=RANGE, // Allow access from the processes with UIDs in the specified range. 197 .uidMin=100, 198 .uidMax=__INT_MAX__, 199 }, 200 } 201 }, 202 { 203 "BmsInnerFeature", 204 { 205 { 206 .type=FIXED, // Allow access from the processes with the specified UIDs. 207 .fixedUid={2, 3, 8} 208 }, 209 { 210 .type=RANGE, 211 .uidMin=100, 212 .uidMax=999, 213 }, 214 } 215 }, 216 }; 217 ``` 218 2192. Add the policies configured for the features in Step 1 to the global policy settings. You need to set the number of features. 220 221 ```c++ 222 static PolicySetting g_presetPolicies[] = { 223 {"permissionms", pmsFeature, 1}, 224 {"abilityms", amsFeature, 2}, 225 {"bundlems", bmsFeature, 2}, // BMS feature defined in step 1. The number of BMS features is 2. 226 {"dtbschedsrv", dmsFeature, 1}, 227 {"samgr", samgrFeature, 1}, 228 {"appspawn", appspawnFeature, 1}, 229 {"WMS", wmsFeature, 1}, 230 {"bundle_daemon", bdsFeature, 1}, 231 }; 232 ``` 233 2343. Register the **BmsFeature** defined in Step 1 with SAMGR. 235 236 ```c++ 237 const char BMS_SERVICE[] = "bundlems"; 238 const char BMS_FEATURE[] = "BmsFeature"; 239 static void Init() 240 { 241 SamgrLite *sm = SAMGR_GetInstance(); 242 if (sm == nullptr) { 243 return; 244 } 245 // Register the service with SAMGR. 246 sm->RegisterFeature(BMS_SERVICE, reinterpret_cast<Feature *>(BundleMsFeature::GetInstance())); 247 sm->RegisterFeatureApi(BMS_SERVICE, BMS_FEATURE, 248 GetBmsFeatureApi(reinterpret_cast<Feature *>(BundleMsFeature::GetInstance()))); 249 HILOG_DEBUG(HILOG_MODULE_APP, "BundleMS feature start success"); 250 } 251 APP_FEATURE_INIT(Init); 252 ``` 253 254 255When the specified services are registered with SAMGR, SAMGR calls **GetCommunicationStrategy()** of the IPC authentication component to obtain the access policy for the services. When other services or apps access these services over IPC, SAMGR calls **IsCommunicationAllowed()** of the IPC authentication component to check the permission of the caller service. If the access policy is met, the access is allowed. Otherwise, the access is rejected. 256 257## Repositories Involved 258Security subsystem 259 260**[security\_permission\_lite](https://gitee.com/openharmony/security_permission_lite)**
