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