1# 数据防泄漏服务开发指导 2 3DLP是系统提供的系统级的数据防泄漏解决方案，提供一种称为DLP的文件格式。后缀格式为“原始文件名（包含原始文件后缀）.dlp”，例如“test.docx.dlp”，文件由授权凭证和原始文件密文组成。 4 5通过端云协同认证（需要联网）来获取文件的访问授权，授权类型包含只读、编辑、文件拥有者三种。 6 7- 只读：能读取文件内容但不能修改。 8- 编辑：能够读写文件内容，但不能修改文件权限配置。 9- 文件拥有者：可读写文件、修改权限配置、恢复原始原始文件等。 10 11应用需要访问DLP文件时，系统会自动安装应用的DLP沙箱分身应用，相当于完全独立的应用，数据和配置会继承原应用，但相互之间并不共享。分身应用在运行时会处于DLP沙箱环境中，访问外部的权限会被限制，以防止数据的泄漏。每当打开一个新的DLP文件会生成一个应用沙箱分身，沙箱应用之间也是相互隔离的，当应用关闭后应用分身会自动卸载，沙箱期间产生的临时数据也会丢弃。 12 13正常情况下，应用不会感知到沙箱的存在，访问的也是解密后的明文，和访问普通文件没有区别，但由于DLP沙箱会限制其访问外部的权限（例如网络、剪切板、截屏、录屏、蓝牙等）。为了更好的用户体验，需要应用进行适配，例如文件只读的情况下，不应显示“保存”按钮，不应主动联网等。 14 15## 沙箱限制 16 17当应用进入DLP沙箱状态时，可以申请的权限将受到限制，根据DLP文件授权类型不同，限制也不相同，如下表： 18 19| 权限名 | 说明 | 授权类型：只读 | 授权类型：编辑/文件拥有者 | 20| -------- | -------- | -------- | -------- | 21| ohos.permission.USE_BLUETOOTH | 允许应用使用蓝牙。 | 禁止 | 禁止 | 22| ohos.permission.INTERNET |允许应用访问网络。 | 禁止 | 禁止 | 23| ohos.permission.DISTRIBUTED_DATASYNC | 允许应用与远程设备交换用户数据（如图片、音乐、视频、应用数据等）。 | 禁止 | 禁止 | 24| ohos.permission.WRITE_MEDIA | 应用读写用户媒体文件，如视频、音频、图片等，需要申请此权限。 | 禁止 | 允许 | 25| ohos.permission.NFC_TAG | 允许应用使用NFC。 | 禁止 | 允许 | 26 27## 接口说明 28 29| 接口名 | 描述 | 30| -------- | -------- | 31| isDLPFile(fd: number): Promise<boolean> <br> isDLPFile(fd: number, callback: AsyncCallback<boolean>): void| 判断是否是dlp文件。 | 32| getDLPPermissionInfo(): Promise<DLPPermissionInfo> <br>getDLPPermissionInfo(callback: AsyncCallback<DLPPermissionInfo>): void | 获取当前沙箱应用的权限类型。 | 33| getOriginalFileName(fileName: string): string | 获取dlp文件原始文件名。 | 34| getDLPSuffix(): string | 获取dlp文件dlp后缀名。 | 35| on(type: 'openDLPFile', listener: Callback<AccessedDLPFileInfo>): void | 注册dlp文件打开事件监听，用于原始应用获取dlp文件打开事件。 | 36| off(type: 'openDLPFile', listener?: Callback<AccessedDLPFileInfo>): void | 取消dlp文件打开事件监听。 | 37| isInSandbox(): Promise<boolean> <br>isInSandbox(callback: AsyncCallback<boolean>): void | 判断当前是否是dlp沙箱应用。 | 38| getDLPSupportedFileTypes(): Promise<Array<string>><br>getDLPSupportedFileTypes(callback: AsyncCallback<Array<string>>): void | 获取当前系统支持添加权限保护的文件格式类型。 | 39| setRetentionState(docUris: Array<string>): Promise<void> <br> setRetentionState(docUris: Array<string>, callback: AsyncCallback<void>): void | 设置dlp分身应用保留状态。 | 40| cancelRetentionState(docUris: Array<string>): Promise<void><br> cancelRetentionState(docUris: Array<string>, callback: AsyncCallback<void>): void | 取消dlp分身应用保留状态。 | 41| getRetentionSandboxList(bundleName?: string): Promise<Array<RetentionSandboxInfo>> <br> getRetentionSandboxList(bundleName: string, callback: AsyncCallback<Array<RetentionSandboxInfo>>): void <br> getRetentionSandboxList(callback: AsyncCallback<Array<RetentionSandboxInfo>>): void| 获取当前保留沙箱列表。 | 42| getDLPFileAccessRecords(): Promise<Array<AccessedDLPFileInfo>> <br> getDLPFileAccessRecords(callback: AsyncCallback<Array<AccessedDLPFileInfo>>): void | 获取dlp文件访问记录。 | 43|setSandboxAppConfig(configInfo: string): Promise<void>|设置沙箱应用配置信息。| 44|getSandboxAppConfig(): Promise<string>|查询沙箱应用配置信息。| 45|cleanSandboxAppConfig(): Promise<void>|清理沙箱应用配置信息。| 46| startDLPManagerForResult(context: common.UIAbilityContext, want: Want): Promise<DLPManagerResult> <br> | 在当前UIAbility界面以无边框形式打开DLP权限管理应用（只支持Stage模式）。 | 47 48## 开发步骤 49 501. 引入[dlpPermission](../../reference/apis-data-protection-kit/js-apis-dlppermission.md)模块。 51 52 ```ts 53 import { dlpPermission } from '@kit.DataProtectionKit'; 54 ``` 55 562. 打开DLP文件，系统会自动安装应用的DLP沙箱分身应用。以下代码应在应用页Ability中使用。 57 58 ```ts 59 import { common, Want } from '@kit.AbilityKit'; 60 import { BusinessError } from '@kit.BasicServicesKit'; 61 import { UIContext } from '@kit.ArkUI'; 62 63 function OpenDlpFile(dlpUri: string, fileName: string, fd: number) { 64 let want: Want = { 65 "action": "ohos.want.action.viewData", 66 "bundleName": "com.example.example_bundle_name", 67 "abilityName": "exampleAbility", 68 "uri": dlpUri, 69 "parameters": { 70 "fileName": { 71 "name": fileName 72 }, 73 "keyFd": { 74 "type": "FD", 75 "value": fd 76 } 77 } 78 } 79 80 let context = new UIContext().getHostContext() as common.UIAbilityContext; // 获取当前UIAbilityContext。 81 82 try { 83 console.log('openDLPFile:' + JSON.stringify(want)); 84 console.log('openDLPFile: delegator:' + JSON.stringify(context)); 85 context.startAbility(want); 86 } catch (err) { 87 console.error('openDLPFile startAbility failed', (err as BusinessError).code, (err as BusinessError).message); 88 return; 89 } 90 } 91 ``` 92 93 以上代码需要在module.json5文件中增加ohos.want.action.viewData： 94 95 ```json 96 "skills":[ 97 { 98 "entities":[ 99 // ... 100 ], 101 "actions":[ 102 // ... 103 "ohos.want.action.viewData" 104 ] 105 } 106 ] 107 ``` 108 1093. 生成DLP文件。 110 111 [该功能云端对接模块当前需要开发者自行搭建](../DataProtectionKit/dlp-overview.md)，并且该功能需要配置域账号环境。 112 113 3.1 当前支持生成DLP文件的原文件类型: ".doc", ".docm", ".docx", ".dot", ".dotm", ".dotx", ".odp", ".odt", ".pdf", ".pot", ".potm", ".potx", ".ppa", ".ppam", ".pps", ".ppsm", ".ppsx", ".ppt", ".pptm", ".pptx", ".rtf", ".txt", ".wps", ".xla", ".xlam", ".xls", ".xlsb", ".xlsm", ".xlsx", ".xlt", ".xltm", ".xltx", ".xlw", ".xml", ".xps"。 114 115 3.2 首先要有一个DLP权限应用有读写权限的(比如文件管理的文档目录下)并且属于以上文件类型之一的原文件。 116 117 3.3 以无边框形式打开DLP权限管理应用。此方法只能在UIAbility上下文中调用，只支持Stage模式。调用以下代码，拉起DLP管理应用的设置权限页面，输入相关的授权账号信息，点击保存，在拉起的filepicker中选择DLP文件的保存路径，保存DLP文件。 118 119 ```ts 120 import { dlpPermission } from '@kit.DataProtectionKit'; 121 import { common, Want } from '@kit.AbilityKit'; 122 import { BusinessError } from '@kit.BasicServicesKit'; 123 import { UIContext } from '@kit.ArkUI'; 124 125 try { 126 let fileUri: string = "file://docs/storage/Users/currentUser/test.txt"; 127 let fileName: string = "test.txt"; 128 let context = new UIContext().getHostContext() as common.UIAbilityContext; // 获取当前UIAbilityContext。 129 let want: Want = { 130 'uri': fileUri, 131 'parameters': { 132 'displayName': fileName 133 } 134 }; // 请求参数。 135 dlpPermission.startDLPManagerForResult(context, want).then((res: dlpPermission.DLPManagerResult) => { 136 console.info('startDLPManagerForResult res.resultCode:' + res.resultCode); 137 console.info('startDLPManagerForResult res.want:' + JSON.stringify(res.want)); 138 }); // 拉起DLP权限管理应用 设置权限。 139 } catch (err) { 140 console.error('startDLPManagerForResult error:' + (err as BusinessError).code + (err as BusinessError).message); 141 } 142 ``` 143 1444. 查询当前应用是否在沙箱中。 145 146 ```ts 147 import { dlpPermission } from '@kit.DataProtectionKit'; 148 import { BusinessError } from '@kit.BasicServicesKit'; 149 150 dlpPermission.isInSandbox().then((data)=> { 151 console.log('isInSandbox, result: ' + JSON.stringify(data)); 152 }).catch((err:BusinessError) => { 153 console.log('isInSandbox: ' + JSON.stringify(err)); 154 }); 155 ``` 156 1575. 查询当前编辑的文件权限，根据文件授权的不同，DLP沙箱被限制的权限有所不同，参考[沙箱限制](#沙箱限制)。 158 159 ```ts 160 import { dlpPermission } from '@kit.DataProtectionKit'; 161 import { BusinessError } from '@kit.BasicServicesKit'; 162 163 dlpPermission.getDLPPermissionInfo().then((data)=> { 164 console.log('getDLPPermissionInfo, result: ' + JSON.stringify(data)); 165 }).catch((err:BusinessError) => { 166 console.log('getDLPPermissionInfo: ' + JSON.stringify(err)); 167 }); 168 ``` 169 1706. 获取当前可支持DLP方案的文件扩展名类型列表，用于应用判断能否生成DLP文件，可用在实现类似文件管理器设置DLP权限的场景。 171 172 ```ts 173 import { dlpPermission } from '@kit.DataProtectionKit'; 174 175 dlpPermission.getDLPSupportedFileTypes((err, result) => { 176 console.log('getDLPSupportedFileTypes: ' + JSON.stringify(err)); 177 console.log('getDLPSupportedFileTypes: ' + JSON.stringify(result)); 178 }); 179 ``` 180 1817. 判断当前打开文件是否是DLP文件。 182 183 ```ts 184 import { dlpPermission } from '@kit.DataProtectionKit'; 185 import { fileIo } from '@kit.CoreFileKit'; 186 import { BusinessError } from '@kit.BasicServicesKit'; 187 188 let uri = "file://docs/storage/Users/currentUser/Desktop/test.txt.dlp"; 189 let file = fileIo.openSync(uri); 190 try { 191 let res = dlpPermission.isDLPFile(file.fd); // 是否加密DLP文件。 192 console.info('res', res); 193 } catch (err) { 194 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错。 195 } 196 fileIo.closeSync(file); 197 ``` 198 1998. 订阅、取消订阅DLP打开事件。 200 201 ```ts 202 import { dlpPermission } from '@kit.DataProtectionKit'; 203 import { BusinessError } from '@kit.BasicServicesKit'; 204 205 class SubscribeExample { 206 event(info: dlpPermission.AccessedDLPFileInfo) { 207 console.info('openDlpFile event', info.uri, info.lastOpenTime) 208 } 209 unSubscribe() { 210 try { 211 dlpPermission.off('openDLPFile', this.event); // 取消订阅。 212 } catch (err) { 213 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错。 214 } 215 } 216 subscribe() { 217 try { 218 dlpPermission.on('openDLPFile', this.event); // 订阅。 219 } catch (err) { 220 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错。 221 } 222 } 223 onCreate() { 224 this.subscribe(); 225 } 226 onDestroy() { 227 this.unSubscribe(); 228 } 229 } 230 ``` 231 2329. 获取DLP文件打开记录。 233 234 ```ts 235 import { dlpPermission } from '@kit.DataProtectionKit'; 236 import { BusinessError } from '@kit.BasicServicesKit'; 237 238 async function getDLPFileAccessRecords() { 239 try { 240 let res:Array<dlpPermission.AccessedDLPFileInfo> = await dlpPermission.getDLPFileAccessRecords(); // 获取DLP访问列表。 241 console.info('res', JSON.stringify(res)) 242 } catch (err) { 243 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错。 244 } 245 } 246 ``` 247 24810. 获取DLP文件保留沙箱记录。 249 250 ```ts 251 import { dlpPermission } from '@kit.DataProtectionKit'; 252 import { BusinessError } from '@kit.BasicServicesKit'; 253 254 async function getRetentionSandboxList() { 255 try { 256 let res:Array<dlpPermission.RetentionSandboxInfo> = await dlpPermission.getRetentionSandboxList(); // 获取沙箱保留列表。 257 console.info('res', JSON.stringify(res)) 258 } catch (err) { 259 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错。 260 } 261 } 262 ``` 263 26411. 设置沙箱应用配置信息。 265 266 ```ts 267 import { dlpPermission } from '@kit.DataProtectionKit'; 268 import { BusinessError } from '@kit.BasicServicesKit'; 269 270 async function setSandboxAppConfig() { 271 try { 272 await dlpPermission.setSandboxAppConfig('configInfo'); // 设置沙箱应用配置信息。 273 } catch (err) { 274 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错。 275 } 276 } 277 ``` 278 27912. 清理沙箱应用配置信息。 280 281 ```ts 282 import { dlpPermission } from '@kit.DataProtectionKit'; 283 import { BusinessError } from '@kit.BasicServicesKit'; 284 285 async function cleanSandboxAppConfig() { 286 try { 287 await dlpPermission.cleanSandboxAppConfig(); // 清理沙箱应用配置信息。 288 } catch (err) { 289 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错。 290 } 291 } 292 ``` 293 29413. 查询沙箱应用配置信息。 295 296 ```ts 297 import { dlpPermission } from '@kit.DataProtectionKit'; 298 import { BusinessError } from '@kit.BasicServicesKit'; 299 300 async function getSandboxAppConfig() { 301 try { 302 let res:string = await dlpPermission.getSandboxAppConfig(); // 查询沙箱应用配置信息。 303 console.info('res', JSON.stringify(res)) 304 } catch (err) { 305 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错。 306 } 307 } 308 ``` 309 31014. 以无边框形式打开DLP权限管理应用。此方法只能在UIAbility上下文中调用，只支持Stage模式。 311 312 ```ts 313 import { dlpPermission } from '@kit.DataProtectionKit'; 314 import { common, Want } from '@kit.AbilityKit'; 315 import { UIContext } from '@kit.ArkUI'; 316 317 try { 318 let context = new UIContext().getHostContext() as common.UIAbilityContext; // 获取当前UIAbilityContext。 319 let want: Want = { 320 "uri": "file://docs/storage/Users/currentUser/Desktop/1.txt", 321 "parameters": { 322 "displayName": "1.txt" 323 } 324 }; // 请求参数。 325 dlpPermission.startDLPManagerForResult(context, want).then((res) => { 326 console.info('res.resultCode', res.resultCode); 327 console.info('res.want', JSON.stringify(res.want)); 328 }); // 打开DLP权限管理应用。 329 } catch (err) { 330 console.error('error', err.code, err.message); // 失败报错。 331 } 332 ``` 333 33415. 查询当前系统是否提供DLP特性。 335 ```ts 336 import { dlpPermission } from '@kit.DataProtectionKit'; 337 import { BusinessError } from '@kit.BasicServicesKit'; 338 339 dlpPermission.isDLPFeatureProvided().then((res) => { 340 console.info('res', JSON.stringify(res)); 341 }).catch((err: BusinessError) => { 342 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错。 343 }); 344 ``` 345