1# @ohos.security.certManagerDialog (Certificate Management Dialog Box) 2 3The **certificateManagerDialog** module provides APIs for opening the certificate management pages, on which the certificates are installed, stored, used, and destroyed. 4 5> **NOTE** 6> 7> 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. 8 9## Modules to Import 10 11```ts 12import certificateManagerDialog from '@ohos.security.certManagerDialog'; 13``` 14 15## CertificateDialogPageType 16 17Enumerates the page types of the certificate management dialog box. 18 19**System capability**: SystemCapability.Security.CertificateManagerDialog 20 21**Model restriction**: This API can be used only in the stage model. 22 23| Name | Value| Description | 24| ---------- | ------ | --------- | 25| PAGE_MAIN | 1 | Main page of the Certificate Manager application.| 26| PAGE_CA_CERTIFICATE | 2 | CA certificate list page.| 27| PAGE_CREDENTIAL | 3 | Credential list page.| 28| PAGE_INSTALL_CERTIFICATE | 4 | Certificate installation page.| 29 30## CertificateType<sup>14+</sup> 31 32Enumerates the types of the certificate to be installed. 33 34**System capability**: SystemCapability.Security.CertificateManagerDialog 35 36**Model restriction**: This API can be used only in the stage model. 37 38| Name | Value| Description | 39| ---------- | ------ | --------- | 40| CA_CERT | 1 | CA certificate.| 41 42## CertificateScope<sup>14+</sup> 43 44Defines the usage scope of the certificate to be installed. 45 46**System capability**: SystemCapability.Security.CertificateManagerDialog 47 48**Model restriction**: This API can be used only in the stage model. 49 50| Name | Value| Description | 51| ---------- | ------ | --------- | 52| NOT_SPECIFIED<sup>16+</sup> | 0 | No user is specified.| 53| CURRENT_USER | 1 | The installed certificate is accessible only to the current user.| 54| GLOBAL_USER<sup>16+</sup> | 2 | The installed certificate is accessible to all users.| 55 56 57## CertificateDialogErrorCode 58 59Enumerates the error codes reported when the certificate management dialog box APIs are called. 60 61**System capability**: SystemCapability.Security.CertificateManagerDialog 62 63**Model restriction**: This API can be used only in the stage model. 64 65| Name | Value| Description | 66| ---------- | ------ | --------- | 67| ERROR_GENERIC | 29700001 | Internal error.| 68| ERROR_OPERATION_CANCELED<sup>14+</sup> | 29700002 | The user canceled the operation when the API is called.| 69| ERROR_OPERATION_FAILED<sup>14+</sup> | 29700003 | The certificate installation fails.| 70| ERROR_DEVICE_NOT_SUPPORTED<sup>14+</sup> | 29700004 | The device does not support the API called.| 71 72## certificateManagerDialog.openCertificateManagerDialog 73 74openCertificateManagerDialog(context: common.Context, pageType: CertificateDialogPageType): Promise\<void> 75 76Opens the certificate management dialog box and displays the page of the specified type. This API uses a promise to return the result. 77 78**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 79 80**System capability**: SystemCapability.Security.CertificateManagerDialog 81 82**Model restriction**: This API can be used only in the stage model. 83 84**Parameters** 85 86| Name | Type | Mandatory| Description | 87| -------- | ------------------------------------------------- | ---- | -------------------------- | 88| context | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md) | Yes | Context of the application.| 89| pageType | [CertificateDialogPageType](#certificatedialogpagetype) | Yes | Type of the page to display.| 90 91**Return value** 92 93| Type | Description | 94| ------------------------------------------- | -------------------- | 95| Promise\<void> | Promise that returns no value.| 96 97**Error codes** 98 99For details about the error codes, see [Certificate Management Dialog Box Error Codes](errorcode-certManagerDialog.md). 100 101| ID| Error Message | 102| -------- | ------------------------------------------------------------ | 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| 29700001 | Internal error. | 106 107**Example** 108```ts 109import certificateManagerDialog from '@ohos.security.certManagerDialog'; 110import { BusinessError } from '@kit.BasicServicesKit'; 111import { common } from '@kit.AbilityKit'; 112 113/* context is application context information, which is obtained by the caller. The context here is only an example. */ 114let context: common.Context = getContext(this); 115/* 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. */ 116let pageType: certificateManagerDialog.CertificateDialogPageType = certificateManagerDialog.CertificateDialogPageType.PAGE_MAIN; 117try { 118 certificateManagerDialog.openCertificateManagerDialog(context, pageType).then(() => { 119 console.info('Succeeded in opening certificate manager dialog.'); 120 }).catch((err: BusinessError) => { 121 console.error(`Failed to open certificate manager dialog. Code: ${err.code}, message: ${err.message}`); 122 }) 123} catch (error) { 124 console.error(`Failed to open certificate manager dialog. Code: ${error.code}, message: ${error.message}`); 125} 126``` 127## certificateManagerDialog.openInstallCertificateDialog<sup>14+</sup> 128 129openInstallCertificateDialog(context: common.Context, certType: CertificateType, certScope: CertificateScope, cert: Uint8Array): Promise\<string> 130 131Opens a dialog box for installing a certificate. This API uses a promise to return the result. 132 133This API is available only to 2-in-1 devices. 134 135**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 136 137**System capability**: SystemCapability.Security.CertificateManagerDialog 138 139**Model restriction**: This API can be used only in the stage model. 140 141**Parameters** 142 143| Name | Type | Mandatory| Description | 144| -------- | ------------------------------------------------- | ---- | -------------------------- | 145| context | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md) | Yes | Context of the application.| 146| certType | [CertificateType](#certificatetype14) | Yes | Type of the certificate to install.| 147| certScope | [CertificateScope](#certificatescope14) | Yes | Usage scope of the certificate.| 148| cert | Uint8Array | Yes | Data of the certificate to install.| 149 150**Return value** 151 152| Type | Description | 153| ------------------------------------------- | -------------------- | 154| Promise\<string> | Promise used to return the certificate URI.| 155 156**Error codes** 157 158For details about the error codes, see [Certificate Management Dialog Box Error Codes](errorcode-certManagerDialog.md). 159 160| ID| Error Message | 161| -------- | ------------------------------------------------------------ | 162| 201 | Permission verification failed. The application does not have the permission required to call the API. | 163| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 164| 29700001 | Internal error. | 165| 29700002 | The user cancels the installation operation. | 166| 29700003 | The user install certificate failed in the certificate manager dialog, such as the certificate is in an invalid format. | 167| 29700004 | The API is not supported on this device. | 168| 29700005<sup>16+</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. | 169 170**Example** 171```ts 172import certificateManagerDialog from '@ohos.security.certManagerDialog'; 173import { BusinessError } from '@kit.BasicServicesKit'; 174import { common } from '@kit.AbilityKit'; 175 176/* context is application context information, which is obtained by the caller. The context here is only an example. */ 177let context: common.Context = getContext(this); 178/* certificateType specifies the certificate type. The value CA_CERT here indicates a CA certificate. */ 179let certificateType: certificateManagerDialog.CertificateType = certificateManagerDialog.CertificateType.CA_CERT; 180/* certificateScope specifies the usage scope of the certificate. The value CURRENT_USER here means the certificate can be used by the the current user. */ 181let certificateScope: certificateManagerDialog.CertificateScope = certificateManagerDialog.CertificateScope.CURRENT_USER; 182/* The CA certificate data must be assigned by the service. In this example, the data is not CA certificate data. */ 183let caCert: Uint8Array = new Uint8Array([ 184 0x30, 0x82, 0x0b, 0xc1, 0x02, 0x01, 185]); 186try { 187 certificateManagerDialog.openInstallCertificateDialog(context, certificateType, certificateScope, caCert).then((uri: string) => { 188 console.info('Succeeded opening install certificate'); 189 }).catch((err: BusinessError) => { 190 console.error(`Failed to open install certificate dialog. Code: ${err.code}, message: ${err.message}`); 191 }) 192} catch (error) { 193 console.error(`Failed to open install certificate dialog. Code: ${error.code}, message: ${error.message}`); 194} 195``` 196 197## certificateManagerDialog.openUninstallCertificateDialog<sup>16+</sup> 198 199openUninstallCertificateDialog(context: common.Context, certType: CertificateType, certUri: string): Promise\<void> 200 201Opens a dialog box for uninstalling a certificate. This API uses a promise to return the result. 202 203This API is available only to 2-in-1 devices. 204 205**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 206 207**System capability**: SystemCapability.Security.CertificateManagerDialog 208 209**Model restriction**: This API can be used only in the stage model. 210 211**Parameters** 212 213| Name | Type | Mandatory| Description | 214| -------- | ------------------------------------------------- | ---- | -------------------------- | 215| context | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md) | Yes | Context of the application.| 216| certType | [CertificateType](#certificatetype14) | Yes | Type of the certificate to uninstall.| 217| certUri | string | Yes | Unique identifier of the certificate to uninstall.| 218 219**Return value** 220 221| Type | Description | 222| ------------------------------------------- | -------------------- | 223| Promise\<void> | Promise that returns no value.| 224 225**Error codes** 226 227For details about the error codes, see [Certificate Management Dialog Box Error Codes](errorcode-certManagerDialog.md). 228 229| ID| Error Message | 230| -------- | ------------------------------------------------------------ | 231| 201 | Permission verification failed. The application does not have the permission required to call the API. | 232| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 233| 29700001 | Internal error. | 234| 29700002 | The user cancels the uninstallation operation. | 235| 29700003 | The user uninstall certificate failed in the certificate manager dialog, such as the certificate uri is not exist. | 236| 29700004 | The API is not supported on this device. | 237| 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. | 238 239**Example** 240```ts 241import certificateManagerDialog from '@ohos.security.certManagerDialog'; 242import { BusinessError } from '@kit.BasicServicesKit'; 243import { common } from '@kit.AbilityKit'; 244 245/* context is application context information, which is obtained by the caller. The context here is only an example. */ 246let context: common.Context = getContext(this); 247/* certificateType specifies the certificate type. The value CA_CERT here indicates a CA certificate. */ 248let certificateType: certificateManagerDialog.CertificateType = certificateManagerDialog.CertificateType.CA_CERT; 249/* certUri is the unique identifier of the certificate installed. The value here is only an example. */ 250let certUri: string = "test"; 251try { 252 certificateManagerDialog.openUninstallCertificateDialog(context, certificateType, certUri).then(() => { 253 console.info('Succeeded opening uninstall certificate'); 254 }).catch((err: BusinessError) => { 255 console.error(`Failed to open uninstall certificate dialog. Code: ${err.code}, message: ${err.message}`); 256 }) 257} catch (error) { 258 console.error(`Failed to open uninstall certificate dialog. Code: ${error.code}, message: ${error.message}`); 259} 260``` 261