1# Data Loss Prevention Kit开发指导 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-loss-prevention-kit/js-apis-dlppermission.md)模块。 51 52 ```ts 53 import dlpPermission from '@ohos.dlpPermission'; 54 ``` 55 562. 打开DLP文件，系统会自动安装应用的DLP沙箱分身应用。以下代码应在应用页Ability中使用。 57 58 ```ts 59 async OpenDlpFile(dlpUri: string, fileName: string, fd: number) { 60 let want:Want = { 61 "action": "ohos.want.action.viewData", 62 "bundleName": "com.example.example_bundle_name", 63 "abilityName": "exampleAbility", 64 "uri": dlpUri, 65 "parameters": { 66 "fileName": { 67 "name": fileName 68 }, 69 "keyFd": { 70 "type": "FD", 71 "value": fd 72 } 73 } 74 } 75 76 try { 77 console.log('openDLPFile:' + JSON.stringify(want)); 78 console.log('openDLPFile: delegator:' + JSON.stringify(this.context)); 79 this.context.startAbility(want); 80 } catch (err) { 81 console.error('openDLPFile startAbility failed', (err as BusinessError).code, (err as BusinessError).message); 82 return; 83 } 84 } 85 ``` 86 87 以上代码需要在module.json5文件中增加ohos.want.action.viewData： 88 89 ```json 90 "skills":[ 91 { 92 "entities":[ 93 ... 94 ], 95 "actions":[ 96 ... 97 "ohos.want.action.viewData" 98 ] 99 } 100 ] 101 ``` 102 1033. 查询当前应用是否在沙箱中。 104 105 ```ts 106 dlpPermission.isInSandbox().then((data)=> { 107 console.log('isInSandbox, result: ' + JSON.stringify(data)); 108 }).catch((err:BusinessError) => { 109 console.log('isInSandbox: ' + JSON.stringify(err)); 110 }); 111 ``` 112 1134. 查询当前编辑的文档权限，根据文档授权的不同，DLP沙箱被限制的权限有所不同，参考[沙箱限制](#沙箱限制)。 114 115 ```ts 116 dlpPermission.getDLPPermissionInfo().then((data)=> { 117 console.log('getDLPPermissionInfo, result: ' + JSON.stringify(data)); 118 }).catch((err:BusinessError) => { 119 console.log('getDLPPermissionInfo: ' + JSON.stringify(err)); 120 }); 121 ``` 122 1235. 获取当前可支持DLP方案的文件扩展名类型列表，用于应用判断能否生成DLP文档，可用在实现类似文件管理器设置DLP权限的场景。 124 125 ```ts 126 dlpPermission.getDLPSupportedFileTypes((err, result) => { 127 console.log('getDLPSupportedFileTypes: ' + JSON.stringify(err)); 128 console.log('getDLPSupportedFileTypes: ' + JSON.stringify(result)); 129 }); 130 ``` 131 1326. 判断当前打开文件是否是DLP文件。 133 134 ```ts 135 import dlpPermission from '@ohos.dlpPermission'; 136 import fs from '@ohos.file.fs'; 137 import { BusinessError } from '@ohos.base'; 138 139 let uri = "file://docs/storage/Users/currentUser/Desktop/test.txt.dlp"; 140 let file = fs.openSync(uri); 141 try { 142 let res = dlpPermission.isDLPFile(file.fd); // 是否加密DLP文件 143 console.info('res', res); 144 } catch (err) { 145 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 146 } 147 fs.closeSync(file); 148 ``` 149 1507. 订阅、取消订阅DLP打开事件。 151 152 ```ts 153 event(info: dlpPermission.AccessedDLPFileInfo) { 154 console.info('openDlpFile event', info.uri, info.lastOpenTime) 155 } 156 unSubscribe() { 157 try { 158 dlpPermission.off('openDLPFile', this.event); // 取消订阅 159 } catch (err) { 160 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 161 } 162 } 163 subscribe() { 164 try { 165 dlpPermission.on('openDLPFile', this.event); // 订阅 166 } catch (err) { 167 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 168 } 169 } 170 onCreate() { 171 this.subscribe(); 172 } 173 onDestroy() { 174 this.unSubscribe(); 175 } 176 ``` 177 1788. 获取DLP文件打开记录。 179 180 ```ts 181 async getDLPFileAccessRecords() { 182 try { 183 let res:Array<dlpPermission.AccessedDLPFileInfo> = await dlpPermission.getDLPFileAccessRecords(); // 获取DLP访问列表 184 console.info('res', JSON.stringify(res)) 185 } catch (err) { 186 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 187 } 188 } 189 ``` 190 1919. 获取DLP文件保留沙箱记录。 192 193 ```ts 194 async getRetentionSandboxList() { 195 try { 196 let res:Array<dlpPermission.RetentionSandboxInfo> = await dlpPermission.getRetentionSandboxList(); // 获取沙箱保留列表 197 console.info('res', JSON.stringify(res)) 198 } catch (err) { 199 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 200 } 201 } 202 ``` 203 20410. 设置沙箱应用配置信息。 205 206 ```ts 207 async setSandboxAppConfig() { 208 try { 209 await dlpPermission.setSandboxAppConfig('configInfo'); // 设置沙箱应用配置信息 210 } catch (err) { 211 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 212 } 213 } 214 ``` 215 21611. 清理沙箱应用配置信息。 217 218 ```ts 219 async cleanSandboxAppConfig() { 220 try { 221 await dlpPermission.cleanSandboxAppConfig(); // 清理沙箱应用配置信息 222 } catch (err) { 223 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 224 } 225 } 226 ``` 227 22812. 查询沙箱应用配置信息。 229 230 ```ts 231 async getSandboxAppConfig() { 232 try { 233 let res:string = await dlpPermission.getSandboxAppConfig(); // 查询沙箱应用配置信息 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 24113. 以无边框形式打开DLP权限管理应用。此方法只能在UIAbility上下文中调用，只支持Stage模式。 242 243 ```ts 244 import dlpPermission from '@ohos.dlpPermission'; 245 import common from '@ohos.app.ability.common'; 246 import AbilityConstant from '@ohos.app.ability.AbilityConstant'; 247 import UIAbility from '@ohos.app.ability.UIAbility' 248 import Want from '@ohos.app.ability.Want'; 249 import { BusinessError } from '@ohos.base'; 250 251 try { 252 let context = getContext() as common.UIAbilityContext; // 获取当前UIAbilityContext 253 let want: Want = { 254 "uri": "file://docs/storage/Users/currentUser/Desktop/1.txt", 255 "parameters": { 256 "displayName": "1.txt" 257 } 258 }; // 请求参数 259 dlpPermission.startDLPManagerForResult(context, want).then((res) => { 260 console.info('res.resultCode', res.resultCode); 261 console.info('res.want', JSON.stringify(res.want)); 262 }); // 打开DLP权限管理应用 263 } catch (err) { 264 console.error('error', err.code, err.message); // 失败报错 265 } 266 ``` 267