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