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 62 function OpenDlpFile(dlpUri: string, fileName: string, fd: number) { 63 let want:Want = { 64 "action": "ohos.want.action.viewData", 65 "bundleName": "com.example.example_bundle_name", 66 "abilityName": "exampleAbility", 67 "uri": dlpUri, 68 "parameters": { 69 "fileName": { 70 "name": fileName 71 }, 72 "keyFd": { 73 "type": "FD", 74 "value": fd 75 } 76 } 77 } 78 79 let context = getContext() as common.UIAbilityContext; // 获取当前UIAbilityContext 80 81 try { 82 console.log('openDLPFile:' + JSON.stringify(want)); 83 console.log('openDLPFile: delegator:' + JSON.stringify(context)); 84 context.startAbility(want); 85 } catch (err) { 86 console.error('openDLPFile startAbility failed', (err as BusinessError).code, (err as BusinessError).message); 87 return; 88 } 89 } 90 ``` 91 92 以上代码需要在module.json5文件中增加ohos.want.action.viewData： 93 94 ```json 95 "skills":[ 96 { 97 "entities":[ 98 ... 99 ], 100 "actions":[ 101 ... 102 "ohos.want.action.viewData" 103 ] 104 } 105 ] 106 ``` 107 1083. 生成DLP文件 109 110 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"。 111 112 3.2 首先要有一个DLP权限应用有读写权限的(比如文件管理的文档目录下)并且属于以上文件类型之一的原文件。 113 114 3.3 以无边框形式打开DLP权限管理应用。此方法只能在UIAbility上下文中调用，只支持Stage模式。调用以下代码，拉起DLP管理应用的设置权限页面，输入相关的授权账号信息，点击保存，在拉起的filepicker中选择DLP文件的保存路径，保存DLP文件。[该功能云端对接模块当前需要开发者自行搭建](../DataProtectionKit/dlp-overview.md) 115 116 ```ts 117 import { dlpPermission } from '@kit.DataProtectionKit'; 118 import { common, Want } from '@kit.AbilityKit'; 119 import { BusinessError } from '@kit.BasicServicesKit'; 120 121 try { 122 let fileUri: string = "file://docs/storage/Users/currentUser/test.txt"; 123 let fileName: string = "test.txt"; 124 let context = getContext() as common.UIAbilityContext; // 获取当前UIAbilityContext 125 let want: Want = { 126 'uri': fileUri, 127 'parameters': { 128 'displayName': fileName 129 } 130 }; // 请求参数 131 dlpPermission.startDLPManagerForResult(context, want).then((res: dlpPermission.DLPManagerResult) => { 132 console.info('startDLPManagerForResult res.resultCode:' + res.resultCode); 133 console.info('startDLPManagerForResult res.want:' + JSON.stringify(res.want)); 134 }); // 拉起DLP权限管理应用 设置权限 135 } catch (err) { 136 console.error('startDLPManagerForResult error:' + (err as BusinessError).code + (err as BusinessError).message); 137 } 138 ``` 139 1404. 查询当前应用是否在沙箱中。 141 142 ```ts 143 import { dlpPermission } from '@kit.DataProtectionKit'; 144 import { BusinessError } from '@kit.BasicServicesKit'; 145 146 dlpPermission.isInSandbox().then((data)=> { 147 console.log('isInSandbox, result: ' + JSON.stringify(data)); 148 }).catch((err:BusinessError) => { 149 console.log('isInSandbox: ' + JSON.stringify(err)); 150 }); 151 ``` 152 1535. 查询当前编辑的文件权限，根据文件授权的不同，DLP沙箱被限制的权限有所不同，参考[沙箱限制](#沙箱限制)。 154 155 ```ts 156 import { dlpPermission } from '@kit.DataProtectionKit'; 157 import { BusinessError } from '@kit.BasicServicesKit'; 158 159 dlpPermission.getDLPPermissionInfo().then((data)=> { 160 console.log('getDLPPermissionInfo, result: ' + JSON.stringify(data)); 161 }).catch((err:BusinessError) => { 162 console.log('getDLPPermissionInfo: ' + JSON.stringify(err)); 163 }); 164 ``` 165 1666. 获取当前可支持DLP方案的文件扩展名类型列表，用于应用判断能否生成DLP文件，可用在实现类似文件管理器设置DLP权限的场景。 167 168 ```ts 169 import { dlpPermission } from '@kit.DataProtectionKit'; 170 dlpPermission.getDLPSupportedFileTypes((err, result) => { 171 console.log('getDLPSupportedFileTypes: ' + JSON.stringify(err)); 172 console.log('getDLPSupportedFileTypes: ' + JSON.stringify(result)); 173 }); 174 ``` 175 1767. 判断当前打开文件是否是DLP文件。 177 178 ```ts 179 import { dlpPermission } from '@kit.DataProtectionKit'; 180 import { fileIo } from '@kit.CoreFileKit'; 181 import { BusinessError } from '@kit.BasicServicesKit'; 182 183 let uri = "file://docs/storage/Users/currentUser/Desktop/test.txt.dlp"; 184 let file = fileIo.openSync(uri); 185 try { 186 let res = dlpPermission.isDLPFile(file.fd); // 是否加密DLP文件 187 console.info('res', res); 188 } catch (err) { 189 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 190 } 191 fileIo.closeSync(file); 192 ``` 193 1948. 订阅、取消订阅DLP打开事件。 195 196 ```ts 197 import { dlpPermission } from '@kit.DataProtectionKit'; 198 import { BusinessError } from '@kit.BasicServicesKit'; 199 class SubscribeExample { 200 event(info: dlpPermission.AccessedDLPFileInfo) { 201 console.info('openDlpFile event', info.uri, info.lastOpenTime) 202 } 203 unSubscribe() { 204 try { 205 dlpPermission.off('openDLPFile', this.event); // 取消订阅 206 } catch (err) { 207 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 208 } 209 } 210 subscribe() { 211 try { 212 dlpPermission.on('openDLPFile', this.event); // 订阅 213 } catch (err) { 214 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 215 } 216 } 217 onCreate() { 218 this.subscribe(); 219 } 220 onDestroy() { 221 this.unSubscribe(); 222 } 223 } 224 ``` 225 2269. 获取DLP文件打开记录。 227 228 ```ts 229 import { dlpPermission } from '@kit.DataProtectionKit'; 230 import { BusinessError } from '@kit.BasicServicesKit'; 231 async function getDLPFileAccessRecords() { 232 try { 233 let res:Array<dlpPermission.AccessedDLPFileInfo> = await dlpPermission.getDLPFileAccessRecords(); // 获取DLP访问列表 234 console.info('res', JSON.stringify(res)) 235 } catch (err) { 236 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 237 } 238 } 239 ``` 240 24110. 获取DLP文件保留沙箱记录。 242 243 ```ts 244 import { dlpPermission } from '@kit.DataProtectionKit'; 245 import { BusinessError } from '@kit.BasicServicesKit'; 246 async function getRetentionSandboxList() { 247 try { 248 let res:Array<dlpPermission.RetentionSandboxInfo> = await dlpPermission.getRetentionSandboxList(); // 获取沙箱保留列表 249 console.info('res', JSON.stringify(res)) 250 } catch (err) { 251 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 252 } 253 } 254 ``` 255 25611. 设置沙箱应用配置信息。 257 258 ```ts 259 import { dlpPermission } from '@kit.DataProtectionKit'; 260 import { BusinessError } from '@kit.BasicServicesKit'; 261 async function setSandboxAppConfig() { 262 try { 263 await dlpPermission.setSandboxAppConfig('configInfo'); // 设置沙箱应用配置信息 264 } catch (err) { 265 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 266 } 267 } 268 ``` 269 27012. 清理沙箱应用配置信息。 271 272 ```ts 273 import { dlpPermission } from '@kit.DataProtectionKit'; 274 import { BusinessError } from '@kit.BasicServicesKit'; 275 async function cleanSandboxAppConfig() { 276 try { 277 await dlpPermission.cleanSandboxAppConfig(); // 清理沙箱应用配置信息 278 } catch (err) { 279 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 280 } 281 } 282 ``` 283 28413. 查询沙箱应用配置信息。 285 286 ```ts 287 import { dlpPermission } from '@kit.DataProtectionKit'; 288 import { BusinessError } from '@kit.BasicServicesKit'; 289 async function getSandboxAppConfig() { 290 try { 291 let res:string = await dlpPermission.getSandboxAppConfig(); // 查询沙箱应用配置信息 292 console.info('res', JSON.stringify(res)) 293 } catch (err) { 294 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 295 } 296 } 297 ``` 298 29914. 以无边框形式打开DLP权限管理应用。此方法只能在UIAbility上下文中调用，只支持Stage模式。 300 301 ```ts 302 import { dlpPermission } from '@kit.DataProtectionKit'; 303 import { common, UIAbility, AbilityConstant, Want } from '@kit.AbilityKit'; 304 import { BusinessError } from '@kit.BasicServicesKit'; 305 306 try { 307 let context = getContext() as common.UIAbilityContext; // 获取当前UIAbilityContext 308 let want: Want = { 309 "uri": "file://docs/storage/Users/currentUser/Desktop/1.txt", 310 "parameters": { 311 "displayName": "1.txt" 312 } 313 }; // 请求参数 314 dlpPermission.startDLPManagerForResult(context, want).then((res) => { 315 console.info('res.resultCode', res.resultCode); 316 console.info('res.want', JSON.stringify(res.want)); 317 }); // 打开DLP权限管理应用 318 } catch (err) { 319 console.error('error', err.code, err.message); // 失败报错 320 } 321 ``` 322 32315. 查询当前系统是否提供DLP特性。 324 ```ts 325 import { dlpPermission } from '@kit.DataProtectionKit'; 326 import { BusinessError } from '@kit.BasicServicesKit'; 327 328 dlpPermission.isDLPFeatureProvided().then((res) => { 329 console.info('res', JSON.stringify(res)); 330 }).catch((err: BusinessError) => { 331 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 332 }); 333 ``` 334