1# 沙箱管理服务
2
3## 简介
4
5沙箱管理服务是OpenHarmony提供的系统服务之一，该服务负责应用沙箱间文件共享规则的管理和持久化等事务。
6
7应用沙箱目录隔离会影响应用间的文件共享操作。为了对合法的应用间文件共享规则进行持久化管理，新增沙箱管理部件以支持共享文件读写规则的持久化存储、管理、激活操作。
8
9沙箱管理模块主要提供以下功能：
10
111. 持久化规则存储
122. 持久化规则管理
133. 临时/持久化规则设置与激活
144. 提供相应inner api
15
16### 规则生效周期
17- 持久化规则：规则在应用卸载前有效
18- 临时规则：规则在应用当次生命周期内有效
19
20
21### 限制与约束
221. SetPolicy接口调用者须具有ohos.permission.SET_SANDBOX_POLICY权限，权限定义详见[access_token](https://gitee.com/openharmony/security_access_token)仓
232. 除SetPolicy、CheckPersistPolicy接口外，其余接口调用者需具有ohos.permission.FILE_ACCESS_PERSIST权限，权限定义详见[access_token](https://gitee.com/openharmony/security_access_token)仓
243. 所有接口中，std::vector\<PolicyInfo\>的大小上限为500条
25
26## 目录
27
28```
29/base/accesscontrol/sandbox_manager
30├── config                      # 覆盖率设置目录
31├── frameworks                  # 框架层，基础功能代码存放目录
32│   ├── common                  # 框架公共代码存放目录
33│   ├── sandbox_manager         # 沙箱管理服务框架代码存放目录
34│   └── test                    # 测试代码存放目录
35├── interfaces/innerkits/       # 接口层
36│   └── sandbox_manager         # 沙箱管理接口代码存放目录
37└── services                    # 服务层
38    ├── common                  # 服务公共代码存放目录
39    └── sandbox_manager
40        └── main                # 沙箱管理服务侧代码存放目录
41
42```
43
44## 使用
45### 接口说明
46
47| **接口** | **接口描述** |
48| --- | --- |
49| int32_t PersistPolicy(const std::vector\<PolicyInfo\> &policy, std::vector<uint32_t> &result); | 添加调用者持久化规则 |
50| int32_t UnPersistPolicy(const std::vector\<PolicyInfo\> &policy, std::vector<uint32_t> &result); | 删除调用者持久化规则 |
51| int32_t PersistPolicy(uint64_t tokenId, const std::vector\<PolicyInfo\> &policy, std::vector<uint32_t> &result);| 添加指定tokenId的持久化规则 |
52| int32_t UnPersistPolicy(uint64_t tokenId, const std::vector\<PolicyInfo\> &policy, std::vector<uint32_t> &result);| 删除指定tokenId的持久化规则 |
53| int32_t SetPolicy(uint64_t tokenId, const std::vector\<PolicyInfo\> &policy, uint64_t policyFlag); | 设置临时规则 |
54| int32_t StartAccessingPolicy(const std::vector\<PolicyInfo\> &policy, std::vector<uint32_t> &result);| 使能持久化规则 |
55| int32_t StopAccessingPolicy(const std::vector\<PolicyInfo\> &policy, std::vector<uint32_t> &result);| 禁用持久化规则 |
56| int32_t CheckPersistPolicy(uint64_t tokenId, const std::vector\<PolicyInfo\> &policy, std::vector<bool> &result);| 校验规则是否已持久化 |
57
58### inner api使用
59#### 设置/删除持久化规则
60```
61// 须拥有对应权限
62#include "sandbox_manager_kit.h"
63
64std::vector<PolicyInfo> policys;
65std::vector<uint32_t> results; // 每条policy的结果都保存在result中
66
67// 设置自身持久化规则
68int32_t sandboxManagerErrCode = SandboxManagerKit::PersistPolicy(policys, results);
69// 删除自身持久化规则
70int32_t sandboxManagerErrCode = SandboxManagerKit::UnPersistPolicy(policys, results);
71// 设置指定tokenId的持久化规则
72uint64_t tokenId;
73int32_t sandboxManagerErrCode = SandboxManagerKit::PersistPolicy(tokenId, policys, results);
74// 删除指定tokenId的持久化规则
75int32_t sandboxManagerErrCode = SandboxManagerKit::UnPersistPolicy(tokenId, policys, results);
76```
77
78#### 设置临时规则
79```
80// 须拥有对应权限
81#include "sandbox_manager_kit.h"
82
83std::vector<PolicyInfo> policys;
84uint64_t targetTokenId; // 设置临时规则的目标应用tokenId
85uint64_t policyFlag; // 是否允许目标应用对设置的规则进行持久化，0-不允许，1-允许
86
87int32_t sandboxManagerErrCode = SandboxManagerKit::SetPolicy(targetTokenId, policys, policyFlag);
88```
89
90#### 使能/禁用持久化规则
91```
92// 须拥有对应权限
93#include "sandbox_manager_kit.h"
94
95std::vector<PolicyInfo> policys; // 列表中的规则须已设置持久化
96std::vector<uint32_t> results; // 每条policy的结果都保存在result中
97
98// 使能自身持久化规则
99int32_t sandboxManagerErrCode = SandboxManagerKit::StartAccessingPolicy(policys, results);
100// 禁用自身持久化规则
101int32_t sandboxManagerErrCode = SandboxManagerKit::StopAccessingPolicy(policys, results);
102```
103
104#### 查询规则持久化状态
105```
106// 无需权限即可查询
107#include "sandbox_manager_kit.h"
108
109uint64_t tokenId; // 查询对应tokenId的持久化规则
110std::vector<PolicyInfo> policys;
111std::vector<bool> results; // 查询结果，true-已持久化，false-未持久化
112
113int32_t sandboxManagerErrCode = SandboxManagerKit::CheckPersistPolicy(tokenId, policys, results);
114```
115
116### 系统开发者如何使用本模块
1171. 在部件bundle.json的deps-components中添加"sandbox_manager"
1182. 在部件的.cfg文件中配置需要的权限名
1193. 在需要引用本模块的gn脚本的external_deps中添加"sandbox_manager:libsandbox_manager_sdk"
1204. 在需要引用本模块的代码文件中#include "sandbox_manager_kit.h"
1215. 调用本模块的inner api，参考[inner api使用](#inner-api使用)
1226. inner api错误码请见[sandbox_manager_err_code.h](./interfaces/innerkits/sandbox_manager/include/sandbox_manager_err_code.h)
1237. PolicyInfo类及输入的result返回值请见[policy_info.h](./interfaces/innerkits/sandbox_manager/include/policy_info.h)中的PolicyInfo、SandboxRetType和OperateMode
124
125### 应用开发者如何使用本模块
126本模块不提供JS api，请通过filemanagement和ability的相关接口间接调用本模块。
127
128## 相关仓
129
130**[filemanagement\_app\_file\_service](https://gitee.com/openharmony/filemanagement_app_file_service/blob/master/README_ZH.md)**
131
132**[ability\_ability\_runtime](https://gitee.com/openharmony/ability_ability_runtime/blob/master/README_zh.md)**
133