1
2
3# @ohos.enterprise.securityManager (Security Management)
4
5The **securityManager** module provides device security management capabilities, including obtaining the security patch status and file system encryption status.
6
7> **NOTE**
8>
9> The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version.
10>
11> The APIs of this module can be used only in the stage model.
12>
13> The APIs of this module can be called only by a [device administrator application](../../mdm/mdm-kit-guide.md#introduction) that is enabled.
14
15## Modules to Import
16
17```ts
18import { securityManager } from '@kit.MDMKit';
19```
20
21## securityManager.uninstallUserCertificate
22
23uninstallUserCertificate(admin: Want, certUri: string): Promise<void>
24
25Uninstalls a user certificate through the specified device administrator application. This API uses a promise to return the result.
26
27**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE
28
29**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
30
31**Parameters**
32
33| Name | Type                                                   | Mandatory| Description                             |
34| ------- | ------------------------------------------------------- | ---- | --------------------------------- |
35| admin   | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes  | Device administrator application.                   |
36| certUri | string                                                  | Yes  | Certificate URI, which is returned by **installUserCertificate()**.|
37
38**Return value**
39
40| Type               | Description                                                        |
41| ------------------- | ------------------------------------------------------------ |
42| Promise<void> | Promise that returns no value. An error object will be thrown if the operation fails.|
43
44**Error codes**
45
46For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md).
47
48| ID| Error Message                                                    |
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**Example**
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
77Installs a user certificate through the specified device administrator application. This API uses a promise to return the result.
78
79**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE
80
81**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
82
83**Parameters**
84
85| Name     | Type                                                   | Mandatory| Description          |
86| ----------- | ------------------------------------------------------- | ---- | -------------- |
87| admin       | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes  | Device administrator application.|
88| certificate | [CertBlob](#certblob)                                   | Yes  | Information about the certificate to install.    |
89
90**Return value**
91
92| Type                 | Description                                                |
93| --------------------- | ---------------------------------------------------- |
94| Promise<string> | Promise used to return the URI of the installed certificate. This URI can be used to uninstall the certificate.|
95
96**Error codes**
97
98For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md).
99
100| ID| Error Message                                                    |
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**Example**
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
138Obtains security status.
139
140**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SECURITY
141
142**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
143
144**Parameters**
145
146| Name| Type                                                   | Mandatory| Description                                                        |
147| ------ | ------------------------------------------------------- | ---- | ------------------------------------------------------------ |
148| admin  | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes  | Device administrator application.                                              |
149| item   | string                                                  | Yes  | Type of the security status to obtain.<br>- **patch**: device security patch.<br>- **encryption**: device file system encryption.<!--RP1--><!--RP1End-->|
150
151**Return value**
152
153| Type  | Description                |
154| ------ | -------------------- |
155| string | Security status obtained.|
156
157**Error codes**
158
159For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md).
160
161| ID| Error Message                                                    |
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**Example**
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
189Sets the device password policy through the specified device administrator application.
190
191**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SECURITY
192
193**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
194
195**Parameters**
196
197| Name     | Type                                      | Mandatory  | Description                      |
198| -------- | ---------------------------------------- | ---- | ------------------------------- |
199| admin    | [Want](../apis-ability-kit/js-apis-app-ability-want.md)     | Yes   | Device administrator application.                 |
200| policy | [PasswordPolicy](#passwordpolicy) | Yes| Device password policy to set.|
201
202**Error codes**
203
204For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md).
205
206| ID| Error Message                                                                      |
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**Example**
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: 'The password must contain at least eight characters, including at least one uppercase letter, one lowercase letter, one digit, and one special character.',
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
239Obtains the device password policy through the specified device administrator application.
240
241**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SECURITY
242
243**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
244
245**Parameters**
246
247| Name     | Type                                      | Mandatory  | Description                      |
248| -------- | ---------------------------------------- | ---- | ------------------------------- |
249| admin    | [Want](../apis-ability-kit/js-apis-app-ability-want.md)     | Yes   | Device administrator application.                 |
250
251**Return value**
252
253| Type                  | Description                     |
254| --------------------- | ------------------------- |
255| [PasswordPolicy](#passwordpolicy) | Device password policy obtained.|
256
257**Error codes**
258
259For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md).
260
261| ID| Error Message                                                                      |
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**Example**
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
289Sets the device clipboard policy through the specified device administrator application.
290
291**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SECURITY
292
293**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
294
295**Parameters**
296
297| Name     | Type                                      | Mandatory  | Description                      |
298| -------- | ---------------------------------------- | ---- | ------------------------------- |
299| admin    | [Want](../apis-ability-kit/js-apis-app-ability-want.md)     | Yes   | Device administrator application.                 |
300| tokenId | number | Yes| Application token ID, which can be obtained from [ApplicationInfo](../apis-ability-kit/js-apis-bundleManager-applicationInfo.md) of the application. Currently, a maximum of 100 token IDs can be saved.|
301| policy | [ClipboardPolicy](#clipboardpolicy) | Yes| Clipboard policy to set.|
302
303**Error codes**
304
305For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md).
306
307| ID| Error Message                                                                      |
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**Example**
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
335Obtains the device clipboard policy through the specified device administrator application.
336
337**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SECURITY
338
339**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
340
341**Parameters**
342
343| Name     | Type                                      | Mandatory  | Description                      |
344| -------- | ---------------------------------------- | ---- | ------------------------------- |
345| admin    | [Want](../apis-ability-kit/js-apis-app-ability-want.md)     | Yes   | Device administrator application.                 |
346| tokenId | number | No| Application token ID, which can be obtained from [ApplicationInfo](../apis-ability-kit/js-apis-bundleManager-applicationInfo.md) of the application.|
347
348**Return value**
349
350| Type                  | Description                     |
351| --------------------- | ------------------------- |
352| ClipboardPolicy | Device clipboard policy obtained.|
353
354**Error codes**
355
356For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md).
357
358| ID| Error Message                                                                      |
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**Example**
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
384Represents the certificate information.
385
386**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
387
388| Name  | Type      | Mandatory| Description              |
389| ------ | ---------- | ---- | ------------------ |
390| inData | Uint8Array | Yes  | Binary content of the certificate.|
391| alias  | string     | Yes  | Certificate alias.        |
392
393## PasswordPolicy
394
395Represents a device password policy.
396
397**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
398
399| Name        | Type    | Mandatory| Description                           |
400| ----------- | --------| ---- | ------------------------------- |
401| complexityRegex | string | No| Regular expression for password complexity.|
402| validityPeriod | number | No| Password validity period, in ms.|
403| additionalDescription | string | No| Description of the device password.|
404
405## ClipboardPolicy
406
407Represents a device clipboard policy.
408
409**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
410
411| Name        | Value| Description                           |
412| ----------- | -------- | ------------------------------- |
413| DEFAULT | 0  | Default policy.|
414| IN_APP | 1  | Allow the clipboard to be used in the same application.|
415| LOCAL_DEVICE | 2  | Allow the clipboard to be used on the same device.|
416| CROSS_DEVICE | 3  | Allow the clipboard to be used across devices.|
417