1# @ohos.enterprise.securityManager（安全管理）
2
3本模块提供设备安全管理的能力，包括查询安全补丁状态、查询文件加密状态等。
4
5> **说明：**
6>
7> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>
9> 本模块接口仅可在Stage模型下使用。
10>
11> 本模块接口仅对[设备管理应用](../../mdm/mdm-kit-guide.md#功能介绍)开放，需将设备管理应用激活后调用，实现相应功能。
12
13## 导入模块
14
15```ts
16import { securityManager } from '@kit.MDMKit';
17```
18
19## securityManager.uninstallUserCertificate
20
21uninstallUserCertificate(admin: Want, certUri: string): Promise<void>
22
23指定设备管理应用卸载用户证书，使用Promise异步回调。
24
25**需要权限：** ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE
26
27**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
28
29**参数：**
30
31| 参数名  | 类型                                                    | 必填 | 说明                              |
32| ------- | ------------------------------------------------------- | ---- | --------------------------------- |
33| admin   | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是   | 设备管理应用。                    |
34| certUri | string                                                  | 是   | 证书uri，由安装用户证书接口返回。 |
35
36**返回值：**
37
38| 类型                | 说明                                                         |
39| ------------------- | ------------------------------------------------------------ |
40| Promise<void> | 无返回结果的Promise对象。当指定设备管理应用卸载用户证书失败时会抛出错误对象。 |
41
42**错误码**：
43
44以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
45
46| 错误码ID | 错误信息                                                     |
47| -------- | ------------------------------------------------------------ |
48| 9200001  | The application is not an administrator application of the device. |
49| 9200002  | The administrator application does not have permission to manage the device. |
50| 9201001  | Failed to manage the certificate.                            |
51| 201      | Permission verification failed. The application does not have the permission required to call the API. |
52| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
53
54**示例：**
55
56```ts
57import { Want } from '@kit.AbilityKit';
58import { BusinessError } from '@kit.BasicServicesKit';
59let wantTemp: Want = {
60  bundleName: 'com.example.myapplication',
61  abilityName: 'EntryAbility',
62};
63let aliasStr = "certName"
64securityManager.uninstallUserCertificate(wantTemp, aliasStr).then(() => {
65  console.info(`Succeeded in uninstalling user certificate.`);
66}).catch((err: BusinessError) => {
67  console.error(`Failed to uninstall user certificate. Code is ${err.code}, message is ${err.message}`);
68});
69```
70
71## securityManager.installUserCertificate
72
73installUserCertificate(admin: Want, certificate: CertBlob): Promise<string>
74
75指定设备管理应用安装用户证书，使用Promise异步回调。
76
77**需要权限：** ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE
78
79**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
80
81**参数：**
82
83| 参数名      | 类型                                                    | 必填 | 说明           |
84| ----------- | ------------------------------------------------------- | ---- | -------------- |
85| admin       | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是   | 设备管理应用。 |
86| certificate | [CertBlob](#certblob)                                   | 是   | 证书信息。     |
87
88**返回值：**
89
90| 类型                  | 说明                                                 |
91| --------------------- | ---------------------------------------------------- |
92| Promise<string> | Promise对象，返回当前证书安装后的uri，用于卸载证书。 |
93
94**错误码**：
95
96以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
97
98| 错误码ID | 错误信息                                                     |
99| -------- | ------------------------------------------------------------ |
100| 9200001  | The application is not an administrator application of the device. |
101| 9200002  | The administrator application does not have permission to manage the device. |
102| 9201001  | Failed to manage the certificate.                            |
103| 201      | Permission verification failed. The application does not have the permission required to call the API. |
104| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
105
106**示例：**
107
108```ts
109import { Want } from '@kit.AbilityKit';
110import { BusinessError } from '@kit.BasicServicesKit';
111let wantTemp: Want = {
112  bundleName: 'com.example.myapplication',
113  abilityName: 'EntryAbility',
114};
115let certFileArray: Uint8Array = new Uint8Array();
116// The variable context needs to be initialized in MainAbility's onCreate callback function
117// test.cer needs to be placed in the rawfile directory
118getContext().resourceManager.getRawFileContent("test.cer").then((value) => {
119  certFileArray = value
120  securityManager.installUserCertificate(wantTemp, { inData: certFileArray, alias: "cert_alias_xts" })
121    .then((result) => {
122      console.info(`Succeeded in installing user certificate, result : ${JSON.stringify(result)}`);
123    }).catch((err: BusinessError) => {
124    console.error(`Failed to install user certificate. Code: ${err.code}, message: ${err.message}`);
125  })
126}).catch((err: BusinessError) => {
127  console.error(`Failed to get row file content. message: ${err.message}`);
128  return
129});
130```
131
132## securityManager.getSecurityStatus
133
134getSecurityStatus(admin: Want, item: string): string
135
136获取安全策略信息。
137
138**需要权限：** ohos.permission.ENTERPRISE_MANAGE_SECURITY
139
140**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
141
142**参数：**
143
144| 参数名 | 类型                                                    | 必填 | 说明                                                         |
145| ------ | ------------------------------------------------------- | ---- | ------------------------------------------------------------ |
146| admin  | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是   | 设备管理应用。                                               |
147| item   | string                                                  | 是   | 安全策略名称。<br/>- patch：设备安全补丁。<br/>- encryption：设备文件系统加密。 <!--RP1--><!--RP1End-->|
148
149**返回值：**
150
151| 类型   | 说明                 |
152| ------ | -------------------- |
153| string | 返回安全策略状态值。 |
154
155**错误码**：
156
157以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
158
159| 错误码ID | 错误信息                                                     |
160| -------- | ------------------------------------------------------------ |
161| 9200001  | The application is not an administrator application of the device. |
162| 9200002  | The administrator application does not have permission to manage the device. |
163| 201      | Permission verification failed. The application does not have the permission required to call the API. |
164| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
165
166**示例：**
167
168```ts
169import { Want } from '@kit.AbilityKit';
170let wantTemp: Want = {
171  bundleName: 'com.example.myapplication',
172  abilityName: 'EntryAbility',
173};
174
175try {
176  let result: string = securityManager.getSecurityStatus(wantTemp, 'patch');
177  console.info(`Succeeded in getting security patch tag. tag: ${result}`);
178} catch (err) {
179  console.error(`Failed to get security patch tag. Code: ${err.code}, message: ${err.message}`);
180}
181```
182
183## securityManager.setPasswordPolicy<sup>12+</sup>
184
185setPasswordPolicy(admin: Want, policy: PasswordPolicy): void
186
187指定设备管理应用设置设备口令策略。
188
189**需要权限：** ohos.permission.ENTERPRISE_MANAGE_SECURITY
190
191**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
192
193**参数：**
194
195| 参数名      | 类型                                       | 必填   | 说明                       |
196| -------- | ---------------------------------------- | ---- | ------------------------------- |
197| admin    | [Want](../apis-ability-kit/js-apis-app-ability-want.md)     | 是    | 设备管理应用。                  |
198| policy | [PasswordPolicy](#passwordpolicy) | 是 | 设备口令策略。 |
199
200**错误码**：
201
202以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
203
204| 错误码ID | 错误信息                                                                       |
205| ------- | ---------------------------------------------------------------------------- |
206| 9200001 | The application is not an administrator application of the device.                        |
207| 9200002 | The administrator application does not have permission to manage the device. |
208| 201 | Permission verification failed. The application does not have the permission required to call the API. |
209| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
210
211**示例：**
212
213```ts
214import { Want } from '@kit.AbilityKit';
215let wantTemp: Want = {
216  bundleName: 'com.example.myapplication',
217  abilityName: 'EntryAbility',
218};
219
220let policy: securityManager.PasswordPolicy = {
221  complexityRegex: '^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{8,}$',
222  validityPeriod: 1,
223  additionalDescription: '至少八个字符，至少一个大写字母，一个小写字母，一个数字和一个特殊字符',
224}
225try {
226    securityManager.setPasswordPolicy(wantTemp, policy);
227    console.info(`Succeeded in setting password policy.`);
228} catch(err) {
229    console.error(`Failed to set password policy. Code: ${err.code}, message: ${err.message}`);
230}
231```
232
233## securityManager.getPasswordPolicy<sup>12+</sup>
234
235getPasswordPolicy(admin: Want): PasswordPolicy
236
237指定设备管理应用获取设备口令策略。
238
239**需要权限：** ohos.permission.ENTERPRISE_MANAGE_SECURITY
240
241**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
242
243**参数：**
244
245| 参数名      | 类型                                       | 必填   | 说明                       |
246| -------- | ---------------------------------------- | ---- | ------------------------------- |
247| admin    | [Want](../apis-ability-kit/js-apis-app-ability-want.md)     | 是    | 设备管理应用。                  |
248
249**返回值：**
250
251| 类型                   | 说明                      |
252| --------------------- | ------------------------- |
253| [PasswordPolicy](#passwordpolicy) | 设备口令策略。 |
254
255**错误码**：
256
257以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
258
259| 错误码ID | 错误信息                                                                       |
260| ------- | ---------------------------------------------------------------------------- |
261| 9200001 | The application is not an administrator application of the device.                        |
262| 9200002 | The administrator application does not have permission to manage the device. |
263| 201 | Permission verification failed. The application does not have the permission required to call the API. |
264| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
265
266**示例：**
267
268```ts
269import { Want } from '@kit.AbilityKit';
270let wantTemp: Want = {
271  bundleName: 'com.example.myapplication',
272  abilityName: 'EntryAbility',
273};
274
275try {
276    let result: securityManager.PasswordPolicy = securityManager.getPasswordPolicy(wantTemp);
277    console.info(`Succeeded in getting password policy, result : ${JSON.stringify(result)}`);
278} catch(err) {
279    console.error(`Failed to get password policy. Code: ${err.code}, message: ${err.message}`);
280}
281```
282
283## securityManager.setAppClipboardPolicy<sup>12+</sup>
284
285setAppClipboardPolicy(admin: Want, tokenId: number, policy: ClipboardPolicy): void
286
287指定设备管理应用设置设备剪贴板策略。
288
289**需要权限：** ohos.permission.ENTERPRISE_MANAGE_SECURITY
290
291**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
292
293**参数：**
294
295| 参数名      | 类型                                       | 必填   | 说明                       |
296| -------- | ---------------------------------------- | ---- | ------------------------------- |
297| admin    | [Want](../apis-ability-kit/js-apis-app-ability-want.md)     | 是    | 设备管理应用。                  |
298| tokenId | number | 是 | 目标应用的身份标识。可通过应用的[ApplicationInfo](../apis-ability-kit/js-apis-bundleManager-applicationInfo.md)获得。当前只支持最多100个tokenId被保存策略。 |
299| policy | [ClipboardPolicy](#clipboardpolicy) | 是 | 剪贴板策略。 |
300
301**错误码**：
302
303以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
304
305| 错误码ID | 错误信息                                                                       |
306| ------- | ---------------------------------------------------------------------------- |
307| 9200001 | The application is not an administrator application of the device.                        |
308| 9200002 | The administrator application does not have permission to manage the device. |
309| 201 | Permission verification failed. The application does not have the permission required to call the API. |
310| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
311
312**示例：**
313
314```ts
315import { Want } from '@kit.AbilityKit';
316let wantTemp: Want = {
317  bundleName: 'com.example.myapplication',
318  abilityName: 'EntryAbility',
319};
320let tokenId: number = 586874394;
321try {
322    securityManager.setAppClipboardPolicy(wantTemp, tokenId, securityManager.ClipboardPolicy.IN_APP);
323    console.info(`Succeeded in setting clipboard policy.`);
324} catch(err) {
325    console.error(`Failed to set clipboard policy. Code: ${err.code}, message: ${err.message}`);
326}
327```
328
329## securityManager.getAppClipboardPolicy<sup>12+</sup>
330
331getAppClipboardPolicy(admin: Want, tokenId?: number): string
332
333指定设备管理应用获取设备剪贴板策略。
334
335**需要权限：** ohos.permission.ENTERPRISE_MANAGE_SECURITY
336
337**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
338
339**参数：**
340
341| 参数名      | 类型                                       | 必填   | 说明                       |
342| -------- | ---------------------------------------- | ---- | ------------------------------- |
343| admin    | [Want](../apis-ability-kit/js-apis-app-ability-want.md)     | 是    | 设备管理应用。                  |
344| tokenId | number | 否 | 目标应用的身份标识。可通过应用的[ApplicationInfo](../apis-ability-kit/js-apis-bundleManager-applicationInfo.md)获得。 |
345
346**返回值：**
347
348| 类型                   | 说明                      |
349| --------------------- | ------------------------- |
350| ClipboardPolicy | 设备剪贴板策略。|
351
352**错误码**：
353
354以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
355
356| 错误码ID | 错误信息                                                                       |
357| ------- | ---------------------------------------------------------------------------- |
358| 9200001 | The application is not an administrator application of the device.                        |
359| 9200002 | The administrator application does not have permission to manage the device. |
360| 201 | Permission verification failed. The application does not have the permission required to call the API. |
361| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
362
363**示例：**
364
365```ts
366import { Want } from '@kit.AbilityKit';
367let wantTemp: Want = {
368  bundleName: 'com.example.myapplication',
369  abilityName: 'EntryAbility',
370};
371let tokenId: number = 586874394;
372try {
373    let result: string = securityManager.getAppClipboardPolicy(wantTemp, tokenId);
374    console.info(`Succeeded in getting password policy, result : ${result}`);
375} catch(err) {
376    console.error(`Failed to set clipboard policy. Code: ${err.code}, message: ${err.message}`);
377}
378```
379
380## securityManager.setWatermarkImage<sup>14+</sup>
381
382setWatermarkImage(admin: Want, bundleName: string, source: string | image.PixelMap, accountId: number): void
383
384指定应用设置水印策略，当前仅支持2in1使用。
385
386**需要权限：** ohos.permission.ENTERPRISE_MANAGE_SECURITY
387
388**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
389
390**参数：**
391
392| 参数名      | 类型                                       | 必填   | 说明                       |
393| -------- | ---------------------------------------- | ---- | ------------------------------- |
394| admin    | [Want](../apis-ability-kit/js-apis-app-ability-want.md)     | 是    | 设备管理应用。                  |
395| bundleName | string    | 是   | 被设置水印的应用包名。                                                       |
396| source | string \| [image.PixelMap](../apis-image-kit/js-apis-image.md)  | 是   | string表示图像路径，图像路径为应用沙箱路径等应用有权限访问的路径。<br>image.PixelMap表示图像对象，图像像素占用大小不能超过500KB。                                                       |
397| accountId     | number     | 是   | 用户ID。 |
398
399**错误码**：
400
401以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
402
403| 错误码ID | 错误信息                                                                       |
404| ------- | ---------------------------------------------------------------------------- |
405| 9200001 | The application is not an administrator application of the device.                        |
406| 9200002 | The administrator application does not have permission to manage the device. |
407| 201 | Permission verification failed. The application does not have the permission required to call the API. |
408| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
409
410**示例：**
411
412```ts
413import { Want } from '@kit.AbilityKit';
414let wantTemp: Want = {
415  bundleName: 'com.example.myapplication',
416  abilityName: 'EntryAbility',
417};
418let bundleName: string = 'com.example.myapplication';
419let source: string = '/data/storage/el1/base/test.png';
420let accountId: number = 100;
421try {
422    securityManager.setWatermarkImage(wantTemp, bundleName, source, accountId);
423    console.info(`Succeeded in setting set watermarkImage policy.`);
424} catch(err) {
425    console.error(`Failed to set watermarkImage policy. Code: ${err.code}, message: ${err.message}`);
426}
427```
428
429## securityManager.cancelWatermarkImage<sup>14+</sup>
430
431cancelWatermarkImage(admin: Want, bundleName: string, accountId: number): void
432
433指定应用取消水印策略，当前仅支持2in1使用。
434
435**需要权限：** ohos.permission.ENTERPRISE_MANAGE_SECURITY
436
437**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
438
439**参数：**
440
441| 参数名      | 类型                                       | 必填   | 说明                       |
442| -------- | ---------------------------------------- | ---- | ------------------------------- |
443| admin    | [Want](../apis-ability-kit/js-apis-app-ability-want.md)     | 是    | 设备管理应用。                  |
444| bundleName | string    | 是   | 被取消水印的应用包名。                                                       |
445| accountId     | number     | 是   | 用户ID。 |
446
447**错误码**：
448
449以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
450
451| 错误码ID | 错误信息                                                                       |
452| ------- | ---------------------------------------------------------------------------- |
453| 9200001 | The application is not an administrator application of the device.                        |
454| 9200002 | The administrator application does not have permission to manage the device. |
455| 201 | Permission verification failed. The application does not have the permission required to call the API. |
456| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
457
458**示例：**
459
460```ts
461import { Want } from '@kit.AbilityKit';
462let wantTemp: Want = {
463  bundleName: 'com.example.myapplication',
464  abilityName: 'EntryAbility',
465};
466let bundleName: string = 'com.example.myapplication';
467let accountId: number = 100;
468try {
469    securityManager.cancelWatermarkImage(wantTemp, bundleName, accountId);
470    console.info(`Succeeded in setting cancel watermarkImage policy.`);
471} catch(err) {
472    console.error(`Failed to cancel watermarkImage policy. Code: ${err.code}, message: ${err.message}`);
473}
474```
475
476## CertBlob
477
478证书信息。
479
480**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
481
482| 名称   | 类型       | 必填 | 说明               |
483| ------ | ---------- | ---- | ------------------ |
484| inData | Uint8Array | 是   | 证书的二进制内容。 |
485| alias  | string     | 是   | 证书别名。         |
486
487## PasswordPolicy
488
489设备口令策略。
490
491**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
492
493| 名称         | 类型     | 必填 | 说明                            |
494| ----------- | --------| ---- | ------------------------------- |
495| complexityRegex | string | 否 | 口令复杂度正则表达式。 |
496| validityPeriod | number | 否 | 密码有效期（单位：毫秒）。 |
497| additionalDescription | string | 否 | 描述文本。 |
498
499## ClipboardPolicy
500
501设备剪贴板策略。
502
503**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
504
505| 名称         | 值 | 说明                            |
506| ----------- | -------- | ------------------------------- |
507| DEFAULT | 0  | 默认。 |
508| IN_APP | 1  | 剪贴板可在同一应用使用。 |
509| LOCAL_DEVICE | 2  | 剪贴板可在同一设备使用。 |
510| CROSS_DEVICE | 3  | 剪贴板可跨设备使用。 |