1# @ohos.enterprise.securityManager (Security Management) 2 3The **securityManager** module provides device security management capabilities, including obtaining the security patch status and file system encryption status. 4 5> **NOTE** 6> 7> 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. 8> 9> The APIs of this module can be used only in the stage model. 10> 11> The APIs of this module can be called only by a [device administrator application](../../mdm/mdm-kit-guide.md#introduction) that is enabled. 12 13## Modules to Import 14 15```ts 16import { securityManager } from '@kit.MDMKit'; 17``` 18 19## securityManager.uninstallUserCertificate 20 21uninstallUserCertificate(admin: Want, certUri: string): Promise<void> 22 23Uninstalls a user certificate. This API uses a promise to return the result. 24 25**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE 26 27**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 28 29**Parameters** 30 31| Name | Type | Mandatory| Description | 32| ------- | ------------------------------------------------------- | ---- | --------------------------------- | 33| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility. | 34| certUri | string | Yes | Certificate URI, which is set and returned by the [installUserCertificate](#securitymanagerinstallusercertificate) API for installing a user certificate.| 35 36**Return value** 37 38| Type | Description | 39| ------------------- | ------------------------------------------------------------ | 40| Promise<void> | Promise that returns no value. An error object will be thrown if the operation fails.| 41 42**Error codes** 43 44For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 45 46| ID| Error Message | 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**Example** 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 75Installs a user certificate. This API uses a promise to return the result. 76 77**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE 78 79**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 80 81**Parameters** 82 83| Name | Type | Mandatory| Description | 84| ----------- | ------------------------------------------------------- | ---- | -------------- | 85| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility.| 86| certificate | [CertBlob](#certblob) | Yes | Information about the certificate to install. The certificate file must be stored in a path that can be accessed by the application, such as the application sandbox path. | 87 88**Return value** 89 90| Type | Description | 91| --------------------- | ---------------------------------------------------- | 92| Promise<string> | Promise used to return the URI of the installed certificate. This URI can be used to uninstall the certificate.| 93 94**Error codes** 95 96For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 97 98| ID| Error Message | 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**Example** 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// Initialize the Context variable in the onCreate callback function of the MainAbility. 117// Place the test file test.cer 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 136Obtains security status. 137 138**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SECURITY 139 140**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 141 142**Parameters** 143 144| Name| Type | Mandatory| Description | 145| ------ | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 146| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility. | 147| item | string | Yes | Type of the security status to obtain.<br>- **patch**: device security patch.<br>- **encryption**: device file system encryption.<!--RP1--><!--RP1End-->| 148 149**Return value** 150 151| Type | Description | 152| ------ | -------------------- | 153| string | Security status obtained.| 154 155**Error codes** 156 157For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 158 159| ID| Error Message | 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**Example** 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 184 185setPasswordPolicy(admin: Want, policy: PasswordPolicy): void 186 187Sets the device password policy. 188 189**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SECURITY 190 191**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 192 193**Parameters** 194 195| Name | Type | Mandatory | Description | 196| -------- | ---------------------------------------- | ---- | ------------------------------- | 197| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility. | 198| policy | [PasswordPolicy](#passwordpolicy) | Yes| Device password policy to set.| 199 200**Error codes** 201 202For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 203 204| ID| Error Message | 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**Example** 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: 'The password must contain at least eight characters, including at least one uppercase letter, one lowercase letter, one digit, and one special character.', 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 234 235getPasswordPolicy(admin: Want): PasswordPolicy 236 237Obtains the device password policy. 238 239**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SECURITY 240 241**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 242 243**Parameters** 244 245| Name | Type | Mandatory | Description | 246| -------- | ---------------------------------------- | ---- | ------------------------------- | 247| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility. | 248 249**Return value** 250 251| Type | Description | 252| --------------------- | ------------------------- | 253| [PasswordPolicy](#passwordpolicy) | Device password policy obtained.| 254 255**Error codes** 256 257For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 258 259| ID| Error Message | 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**Example** 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 284 285setAppClipboardPolicy(admin: Want, tokenId: number, policy: ClipboardPolicy): void 286 287Sets the device clipboard policy. 288 289**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SECURITY 290 291**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 292 293**Parameters** 294 295| Name | Type | Mandatory | Description | 296| -------- | ---------------------------------------- | ---- | ------------------------------- | 297| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility. | 298| tokenId | number | Yes| Application token ID, which can be obtained using [bundleManager.getApplicationInfo](../apis-ability-kit/js-apis-bundleManager-applicationInfo.md). Currently, a maximum of 100 token IDs can be saved.| 299| policy | [ClipboardPolicy](#clipboardpolicy) | Yes| Clipboard policy to set.| 300 301**Error codes** 302 303For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 304 305| ID| Error Message | 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**Example** 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 330 331getAppClipboardPolicy(admin: Want, tokenId?: number): string 332 333Obtains the device clipboard policy. 334 335**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SECURITY 336 337**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 338 339**Parameters** 340 341| Name | Type | Mandatory | Description | 342| -------- | ---------------------------------------- | ---- | ------------------------------- | 343| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility. | 344| tokenId | number | No| Application token ID, which can be obtained using [bundleManager.getApplicationInfo](../apis-ability-kit/js-apis-bundleManager-applicationInfo.md). Currently, a maximum of 100 token IDs can be saved.| 345 346**Return value** 347 348| Type | Description | 349| --------------------- | ------------------------- | 350| [ClipboardPolicy](#clipboardpolicy) | Device clipboard policy obtained.| 351 352**Error codes** 353 354For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 355 356| ID| Error Message | 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**Example** 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 384Sets the watermark policy. Currently, this feature is available only for 2-in-1 devices. 385 386**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SECURITY 387 388**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 389 390**Parameters** 391 392| Name | Type | Mandatory | Description | 393| -------- | ---------------------------------------- | ---- | ------------------------------- | 394| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility. | 395| bundleName | string | Yes | Bundle name of the application for which the watermark is set. | 396| source | string \| [image.PixelMap](../apis-image-kit/js-apis-image.md) | Yes | **string** indicates the image path that can be accessed by the application, such as the application sandbox path.<br>**image.PixelMap** indicates an image object. The size of an image pixel cannot exceed 500 KB. | 397| accountId | number | Yes | User ID. You can call [getOsAccountLocalId](../apis-basic-services-kit/js-apis-osAccount.md#getosaccountlocalid9-1) of **@ohos.account.osAccount** to obtain the user ID.| 398 399**Error codes** 400 401For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 402 403| ID| Error Message | 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**Example** 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 433Cancels the watermark policy. Currently, this feature is available only for 2-in-1 devices. 434 435**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SECURITY 436 437**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 438 439**Parameters** 440 441| Name | Type | Mandatory | Description | 442| -------- | ---------------------------------------- | ---- | ------------------------------- | 443| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility. | 444| bundleName | string | Yes | Bundle name of the application for which the watermark is removed. | 445| accountId | number | Yes | User ID. You can call [getOsAccountLocalId](../apis-basic-services-kit/js-apis-osAccount.md#getosaccountlocalid9-1) of **@ohos.account.osAccount** to obtain the user ID.| 446 447**Error codes** 448 449For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 450 451| ID| Error Message | 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**Example** 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 478Represents the certificate information. 479 480**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 481 482| Name | Type | Mandatory| Description | 483| ------ | ---------- | ---- | ------------------ | 484| inData | Uint8Array | Yes | Binary content of the certificate.| 485| alias | string | Yes | Certificate alias. | 486 487## PasswordPolicy 488 489Represents a device password policy. 490 491**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 492 493| Name | Type | Mandatory| Description | 494| ----------- | --------| ---- | ------------------------------- | 495| complexityRegex | string | No| Regular expression for password complexity.| 496| validityPeriod | number | No| Password validity period, in ms.| 497| additionalDescription | string | No| Description of the device password.| 498 499## ClipboardPolicy 500 501Represents a device clipboard policy. 502 503**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 504 505| Name | Value| Description | 506| ----------- | -------- | ------------------------------- | 507| DEFAULT | 0 | Default policy.| 508| IN_APP | 1 | Allow the clipboard to be used in the same application.| 509| LOCAL_DEVICE | 2 | Allow the clipboard to be used on the same device.| 510| CROSS_DEVICE | 3 | Allow the clipboard to be used across devices.| 511
