1# @ohos.security.certManagerDialog (Certificate Management Dialog Box) 2 3<!--Kit: Device Certificate Kit--> 4<!--Subsystem: Security--> 5<!--Owner: @chaceli--> 6<!--Designer: @chande--> 7<!--Tester: @zhangzhi1995--> 8<!--Adviser: @zengyawen--> 9 10The **certificateManagerDialog** module provides APIs for opening the certificate management pages, on which the certificates are installed, stored, used, and destroyed. 11 12> **NOTE** 13> 14> The initial APIs of this module are supported since API version 13. Newly added APIs will be marked with a superscript to indicate their earliest API version. 15 16## Modules to Import 17 18```ts 19import certificateManagerDialog from '@ohos.security.certManagerDialog'; 20``` 21 22## CertificateDialogPageType 23 24Enumerates the page types of the certificate management dialog box. 25 26**System capability**: SystemCapability.Security.CertificateManagerDialog 27 28**Model restriction**: This API can be used only in the stage model. 29 30| Name | Value| Description | 31| ---------- | ------ | --------- | 32| PAGE_MAIN | 1 | Main page of the Certificate Manager application.| 33| PAGE_CA_CERTIFICATE | 2 | CA certificate list page.| 34| PAGE_CREDENTIAL | 3 | Credential list page.| 35| PAGE_INSTALL_CERTIFICATE | 4 | Certificate installation page.| 36 37## CertificateType<sup>14+</sup> 38 39Enumerates the types of the certificate to be installed. 40 41**System capability**: SystemCapability.Security.CertificateManagerDialog 42 43**Model restriction**: This API can be used only in the stage model. 44 45| Name | Value| Description | 46| ---------- | ------ | --------- | 47| CA_CERT | 1 | CA certificate.| 48 49## CertificateScope<sup>14+</sup> 50 51Defines the usage scope of the certificate to be installed. 52 53**System capability**: SystemCapability.Security.CertificateManagerDialog 54 55**Model restriction**: This API can be used only in the stage model. 56 57| Name | Value| Description | 58| ---------- | ------ | --------- | 59| NOT_SPECIFIED<sup>18+</sup> | 0 | No user is specified.| 60| CURRENT_USER | 1 | The installed certificate is accessible only to the current user.| 61| GLOBAL_USER<sup>18+</sup> | 2 | The installed certificate is accessible to all users.| 62 63 64## CertificateDialogErrorCode 65 66Enumerates the error codes reported when the certificate management dialog box APIs are called. 67 68**System capability**: SystemCapability.Security.CertificateManagerDialog 69 70**Model restriction**: This API can be used only in the stage model. 71 72| Name | Value| Description | 73| ---------- | ------ | --------- | 74| ERROR_GENERIC | 29700001 | Internal error.| 75| ERROR_OPERATION_CANCELED<sup>14+</sup> | 29700002 | The user canceled the operation when the API is called.| 76| ERROR_OPERATION_FAILED<sup>14+</sup> | 29700003 | The certificate installation fails.| 77| ERROR_DEVICE_NOT_SUPPORTED<sup>14+</sup> | 29700004 | The device does not support the API called.| 78| ERROR_NOT_COMPLY_SECURITY_POLICY<sup>18+</sup> | 29700005 | The device security policy is not met when the API is called.| 79 80## CertificateDialogProperty<sup>18+</sup> 81 82Defines the property of the certificate management dialog box. 83 84**System capability**: SystemCapability.Security.CertificateManagerDialog 85 86**Model restriction**: This API can be used only in the stage model. 87 88| Name | Type | Read-Only| Optional| Description | 89| ----------------- | ------- | ---- | ---- | ---------------------------- | 90| showInstallButton | boolean | No | No | Whether to display the button for installing the certificate. The value **true** means to display the button; the value **false** means the opposite.| 91 92## certificateManagerDialog.openCertificateManagerDialog 93 94openCertificateManagerDialog(context: common.Context, pageType: CertificateDialogPageType): Promise\<void> 95 96Opens the certificate management dialog box and displays the page of the specified type. This API uses a promise to return the result. 97 98**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 99 100**System capability**: SystemCapability.Security.CertificateManagerDialog 101 102**Model restriction**: This API can be used only in the stage model. 103 104**Parameters** 105 106| Name | Type | Mandatory| Description | 107| -------- | ------------------------------------------------- | ---- | -------------------------- | 108| context | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md) | Yes | Context of the application.| 109| pageType | [CertificateDialogPageType](#certificatedialogpagetype) | Yes | Type of the page to display.| 110 111**Return value** 112 113| Type | Description | 114| ------------------------------------------- | -------------------- | 115| Promise\<void> | Promise that returns no value.| 116 117**Error codes** 118 119For details about the error codes, see [Certificate Management Dialog Box Error Codes](errorcode-certManagerDialog.md). 120 121| ID| Error Message | 122| -------- | ------------------------------------------------------------ | 123| 201 | Permission verification failed. The application does not have the permission required to call the API. | 124| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 125| 29700001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 126 127**Example** 128```ts 129import { certificateManagerDialog } from '@kit.DeviceCertificateKit'; 130import { BusinessError } from '@kit.BasicServicesKit'; 131import { common } from '@kit.AbilityKit'; 132import { UIContext } from '@kit.ArkUI'; 133 134/* context is application context information, which is obtained by the caller. The context here is only an example. */ 135let context: common.Context = new UIContext().getHostContext() as common.Context; 136/* pageType specifies the type of the page to display. In this example, pageType is PAGE_MAIN, which indicates the main page of the Certificate Management application. */ 137let pageType: certificateManagerDialog.CertificateDialogPageType = certificateManagerDialog.CertificateDialogPageType.PAGE_MAIN; 138try { 139 certificateManagerDialog.openCertificateManagerDialog(context, pageType).then(() => { 140 console.info('Succeeded in opening certificate manager dialog.'); 141 }).catch((err: BusinessError) => { 142 console.error(`Failed to open certificate manager dialog. Code: ${err.code}, message: ${err.message}`); 143 }) 144} catch (error) { 145 console.error(`Failed to open certificate manager dialog. Code: ${error.code}, message: ${error.message}`); 146} 147``` 148## certificateManagerDialog.openInstallCertificateDialog<sup>14+</sup> 149 150openInstallCertificateDialog(context: common.Context, certType: CertificateType, certScope: CertificateScope, cert: Uint8Array): Promise\<string> 151 152Opens a dialog box for installing a certificate. This API uses a promise to return the result. 153 154**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 155 156**System capability**: SystemCapability.Security.CertificateManagerDialog 157 158**Device support**: This API is available on PCs/2-in-1 devices. For other devices, error code 29700004 is returned. 159 160**Model restriction**: This API can be used only in the stage model. 161 162**Parameters** 163 164| Name | Type | Mandatory| Description | 165| -------- | ------------------------------------------------- | ---- | -------------------------- | 166| context | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md) | Yes | Context of the application.| 167| certType | [CertificateType](#certificatetype14) | Yes | Type of the certificate to install.| 168| certScope | [CertificateScope](#certificatescope14) | Yes | Defines the usage scope of the certificate to be installed.| 169| cert | Uint8Array | Yes | Data of the certificate to install.| 170 171**Return value** 172 173| Type | Description | 174| ------------------------------------------- | -------------------- | 175| Promise\<string> | Promise used to return the certificate URI. The value contains up to 256 bytes.| 176 177**Error codes** 178 179For details about the error codes, see [Certificate Management Dialog Box Error Codes](errorcode-certManagerDialog.md). 180 181| ID| Error Message | 182| -------- | ------------------------------------------------------------ | 183| 201 | Permission verification failed. The application does not have the permission required to call the API. | 184| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 185| 29700001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 186| 29700002 | The user cancels the installation operation. | 187| 29700003 | The user install certificate failed in the certificate manager dialog, such as the certificate is in an invalid format. | 188| 29700004 | The API is not supported on this device. | 189| 29700005<sup>18+</sup> | The operation does not comply with the device security policy, such as the device does not allow users to manage the ca certificate of the global user. | 190 191**Example** 192```ts 193import { certificateManagerDialog } from '@kit.DeviceCertificateKit'; 194import { BusinessError } from '@kit.BasicServicesKit'; 195import { common } from '@kit.AbilityKit'; 196import { UIContext } from '@kit.ArkUI'; 197 198/* context is application context information, which is obtained by the caller. The context here is only an example. */ 199let context: common.Context = new UIContext().getHostContext() as common.Context; 200/* certificateType specifies the certificate type. The value CA_CERT here indicates a CA certificate. */ 201let certificateType: certificateManagerDialog.CertificateType = certificateManagerDialog.CertificateType.CA_CERT; 202/* certificateScope specifies the usage scope of the certificate. The value CURRENT_USER here means the certificate can be used by the current user. */ 203let certificateScope: certificateManagerDialog.CertificateScope = certificateManagerDialog.CertificateScope.CURRENT_USER; 204/* The CA certificate data must be assigned by the service. In this example, the data is not CA certificate data. */ 205let caCert: Uint8Array = new Uint8Array([ 206 0x30, 0x82, 0x0b, 0xc1, 0x02, 0x01, 207]); 208try { 209 certificateManagerDialog.openInstallCertificateDialog(context, certificateType, certificateScope, caCert).then((uri: string) => { 210 console.info('Succeeded opening install certificate'); 211 }).catch((err: BusinessError) => { 212 console.error(`Failed to open install certificate dialog. Code: ${err.code}, message: ${err.message}`); 213 }) 214} catch (error) { 215 console.error(`Failed to open install certificate dialog. Code: ${error.code}, message: ${error.message}`); 216} 217``` 218 219## certificateManagerDialog.openUninstallCertificateDialog<sup>18+</sup> 220 221openUninstallCertificateDialog(context: common.Context, certType: CertificateType, certUri: string): Promise\<void> 222 223Opens a dialog box for deleting a certificate. This API uses a promise to return the result. 224 225**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 226 227**System capability**: SystemCapability.Security.CertificateManagerDialog 228 229**Device support**: This API is available on PCs/2-in-1 devices. For other devices, error code 29700004 is returned. 230 231**Model restriction**: This API can be used only in the stage model. 232 233**Parameters** 234 235| Name | Type | Mandatory| Description | 236| -------- | ------------------------------------------------- | ---- | -------------------------- | 237| context | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md) | Yes | Context of the application.| 238| certType | [CertificateType](#certificatetype14) | Yes | Type of the certificate to delete.| 239| certUri | string | Yes | Unique identifier of the certificate to delete. The value contains up to 256 bytes.| 240 241**Return value** 242 243| Type | Description | 244| ------------------------------------------- | -------------------- | 245| Promise\<void> | Promise that returns no value.| 246 247**Error codes** 248 249For details about the error codes, see [Certificate Management Dialog Box Error Codes](errorcode-certManagerDialog.md). 250 251| ID| Error Message | 252| -------- | ------------------------------------------------------------ | 253| 201 | Permission verification failed. The application does not have the permission required to call the API. | 254| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 255| 29700001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 256| 29700002 | The user cancels the uninstallation operation. | 257| 29700003 | The user uninstall certificate failed in the certificate manager dialog, such as the certificate uri is not exist. | 258| 29700004 | The API is not supported on this device. | 259| 29700005 | The operation does not comply with the device security policy, such as the device does not allow users to manage the ca certificate of the global user. | 260 261**Example** 262```ts 263import { certificateManagerDialog } from '@kit.DeviceCertificateKit'; 264import { BusinessError } from '@kit.BasicServicesKit'; 265import { common } from '@kit.AbilityKit'; 266import { UIContext } from '@kit.ArkUI'; 267 268/* context is application context information, which is obtained by the caller. The context here is only an example. */ 269let context: common.Context = new UIContext().getHostContext() as common.Context; 270/* certificateType specifies the certificate type. The value CA_CERT here indicates a CA certificate. */ 271let certificateType: certificateManagerDialog.CertificateType = certificateManagerDialog.CertificateType.CA_CERT; 272/* certUri is the unique identifier of the certificate installed. The value here is only an example. */ 273let certUri: string = "test"; 274try { 275 certificateManagerDialog.openUninstallCertificateDialog(context, certificateType, certUri).then(() => { 276 console.info('Succeeded opening uninstall certificate'); 277 }).catch((err: BusinessError) => { 278 console.error(`Failed to open uninstall certificate dialog. Code: ${err.code}, message: ${err.message}`); 279 }) 280} catch (error) { 281 console.error(`Failed to open uninstall certificate dialog. Code: ${error.code}, message: ${error.message}`); 282} 283``` 284 285## certificateManagerDialog.openCertificateDetailDialog<sup>18+</sup> 286 287openCertificateDetailDialog(context: common.Context, cert: Uint8Array, property: CertificateDialogProperty): Promise\<void> 288 289Opens the certificate management dialog box and displays the certificate details. This API uses a promise to return the result. 290 291**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 292 293**System capability**: SystemCapability.Security.CertificateManagerDialog 294 295**Device support**: This API is available on PCs/2-in-1 devices. For other devices, error code 29700004 is returned. 296 297**Model restriction**: This API can be used only in the stage model. 298 299**Parameters** 300 301| Name | Type | Mandatory| Description | 302| -------- | ------------------------------------------------- | ---- | -------------------------- | 303| context | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md) | Yes | Context of the application.| 304| cert | Uint8Array | Yes | Data of the certificate to install. | 305| property | [CertificateDialogProperty](#certificatedialogproperty18) | Yes | Property of the certificate management dialog box.| 306 307**Return value** 308 309| Type | Description | 310| ------------------------------------------- | -------------------- | 311| Promise\<void> | Promise that returns no value.| 312 313**Error codes** 314 315For details about the error codes, see [Certificate Management Dialog Box Error Codes](errorcode-certManagerDialog.md). 316 317| ID| Error Message | 318| -------- | ------------------------------------------------------------ | 319| 201 | Permission verification failed. The application does not have the permission required to call the API. | 320| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 321| 29700001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 322| 29700003 | Show the certificate detail dialog fail, such as the certificate is in an invalid format. | 323| 29700004 | The API is not supported on this device. | 324 325**Example** 326```ts 327import { certificateManagerDialog } from '@kit.DeviceCertificateKit'; 328import { BusinessError } from '@kit.BasicServicesKit'; 329import { common } from '@kit.AbilityKit'; 330import { UIContext } from '@kit.ArkUI'; 331 332/* context is application context information, which is obtained by the caller. The context here is only an example. */ 333let context: common.Context = new UIContext().getHostContext() as common.Context; 334/* The CA certificate data must be assigned by the service. In this example, the data is not CA certificate data. */ 335let caCert: Uint8Array = new Uint8Array([ 336 0x30, 0x82, 0x0b, 0xc1, 0x02, 0x01, 337]); 338let property: certificateManagerDialog.CertificateDialogProperty = { 339 showInstallButton: false /* Do not display the button for installing the certificate.*/ 340}; 341try { 342 certificateManagerDialog.openCertificateDetailDialog(context, caCert, property).then(() => { 343 console.info('Succeeded opening certificate detail dialog.'); 344 }).catch((err: BusinessError) => { 345 console.error(`Failed to open certificate detail dialog. Code: ${err.code}, message: ${err.message}`); 346 }) 347} catch (error) { 348 console.error(`Failed to open certificate detail dialog. Code: ${error.code}, message: ${error.message}`); 349} 350``` 351 352## certificateManagerDialog.openAuthorizeDialog<sup>20+</sup> 353 354openAuthorizeDialog(context: common.Context): Promise\<string> 355 356Opens the authorization page of the certificate management dialog box to grant a certificate to the application. This API uses a promise to return the result. 357 358**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 359 360**System capability**: SystemCapability.Security.CertificateManagerDialog 361 362**Model restriction**: This API can be used only in the stage model. 363 364| Name | Type | Mandatory| Description | 365|---------|--------------------------------------------------------------------|----|-------------| 366| context | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md) | Yes | Context of the application.| 367 368**Return value** 369 370| Type | Description | 371|------------------|--------------------------------------| 372| Promise\<string> | Promise used to return the URI of the certificate authorized. The value contains up to 256 bytes.| 373 374**Error codes** 375 376For details about the error codes, see [Certificate Management Dialog Box Error Codes](errorcode-certManagerDialog.md). 377 378| ID | Error Message | 379|----------|-------------------------------------------------------------------------------------------------------------------------------------------------| 380| 201 | Permission verification failed. The application does not have the permission required to call the API. | 381| 401 | Invalid parameter. Possible causes: 1. A mandatory parameter is left unspecified. 2. Incorrect parameter type. 3. Parameter verification failed. | 382| 29700001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 383| 29700002 | The user cancels the authorization. | 384 385**Example** 386```ts 387import { certificateManagerDialog } from '@kit.DeviceCertificateKit'; 388import { BusinessError } from '@kit.BasicServicesKit'; 389import { common } from '@kit.AbilityKit'; 390import { UIContext } from '@kit.ArkUI'; 391 392/* context is application context information, which is obtained by the caller. The context here is only an example. */ 393let context: common.Context = new UIContext().getHostContext() as common.Context; 394try { 395 certificateManagerDialog.openAuthorizeDialog(context).then((uri: string) => { 396 console.info(`Success to authorize certificate, uri: ${uri}`) 397 }).catch((err: BusinessError) => { 398 console.error(`Failed to authorize certificate. Code: ${err.code}, message: ${err.message}`); 399 }); 400} catch (err) { 401 let error = err as BusinessError; 402 console.error(`Failed to authorize certificate. Code: ${error.code}, message: ${error.message}`); 403} 404``` 405