1# @ohos.security.certManagerDialog (证书管理对话框模块) 2 3证书管理对话框主要提供拉起证书管理界面的能力，用户在拉起的证书管理对话框可对证书进行管理（安装，存储，使用，销毁）。 4 5> **说明：** 6> 7> 本模块首批接口从API version 13开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```ts 12import certificateManagerDialog from '@ohos.security.certManagerDialog'; 13``` 14 15## CertificateDialogPageType 16 17表示证书管理对话框的页面类型。 18 19**系统能力：** SystemCapability.Security.CertificateManagerDialog 20 21**模型约束：** 此接口仅可在Stage模型下使用。 22 23| 名称 | 值 | 说明 | 24| ---------- | ------ | --------- | 25| PAGE_MAIN | 1 | 证书管理应用主页面。 | 26| PAGE_CA_CERTIFICATE | 2 | CA证书列表页面。 | 27| PAGE_CREDENTIAL | 3 | 凭据列表页面。 | 28| PAGE_INSTALL_CERTIFICATE | 4 | 安装证书页面。 | 29 30## CertificateType<sup>14+</sup> 31 32表示安装证书的类型。 33 34**系统能力：** SystemCapability.Security.CertificateManagerDialog 35 36**模型约束：** 此接口仅可在Stage模型下使用。 37 38| 名称 | 值 | 说明 | 39| ---------- | ------ | --------- | 40| CA_CERT | 1 | CA证书。 | 41 42## CertificateScope<sup>14+</sup> 43 44表示安装证书的使用范围。 45 46**系统能力：** SystemCapability.Security.CertificateManagerDialog 47 48**模型约束：** 此接口仅可在Stage模型下使用。 49 50| 名称 | 值 | 说明 | 51| ---------- | ------ | --------- | 52| NOT_SPECIFIED<sup>18+</sup> | 0 | 未指定用户。 | 53| CURRENT_USER | 1 | 当前用户。 | 54| GLOBAL_USER<sup>18+</sup> | 2 | 公共目录。 | 55 56 57## CertificateDialogErrorCode 58 59表示调用证书管理对话框相关API的错误码。 60 61**系统能力：** SystemCapability.Security.CertificateManagerDialog 62 63**模型约束：** 此接口仅可在Stage模型下使用。 64 65| 名称 | 值 | 说明 | 66| ---------- | ------ | --------- | 67| ERROR_GENERIC | 29700001 | 表示调用接口时发生内部错误。 | 68| ERROR_OPERATION_CANCELED<sup>14+</sup> | 29700002 | 表示调用接口时用户取消操作。 | 69| ERROR_OPERATION_FAILED<sup>14+</sup> | 29700003 | 表示调用接口时安装证书失败。 | 70| ERROR_DEVICE_NOT_SUPPORTED<sup>14+</sup> | 29700004 | 表示调用接口时设备类型不支持。 | 71| ERROR_NOT_COMPLY_SECURITY_POLICY<sup>18+</sup> | 29700005 | 表示调用接口时不符合设备安全策略。 | 72 73## CertificateDialogProperty<sup>18+</sup> 74 75表示证书管理对话框的属性。 76 77**系统能力：** SystemCapability.Security.CertificateManagerDialog 78 79**模型约束：** 此接口仅可在Stage模型下使用。 80 81| 名称 | 类型 | 只读 | 可选 | 说明 | 82| ----------------- | ------- | ---- | ---- | ---------------------------- | 83| showInstallButton | boolean | 否 | 否 | 表示是否显示安装证书的按钮，true为显示，false为不显示。 | 84 85## certificateManagerDialog.openCertificateManagerDialog 86 87openCertificateManagerDialog(context: common.Context, pageType: CertificateDialogPageType): Promise\<void> 88 89表示拉起证书管理对话框，显示相应的页面，使用Promise方式异步返回结果。 90 91**需要权限：** ohos.permission.ACCESS_CERT_MANAGER 92 93**系统能力：** SystemCapability.Security.CertificateManagerDialog 94 95**模型约束：** 此接口仅可在Stage模型下使用。 96 97**参数**： 98 99| 参数名 | 类型 | 必填 | 说明 | 100| -------- | ------------------------------------------------- | ---- | -------------------------- | 101| context | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md) | 是 | 表示应用的上下文信息。 | 102| pageType | [CertificateDialogPageType](#certificatedialogpagetype) | 是 | 表示页面类型。 | 103 104**返回值**： 105 106| 类型 | 说明 | 107| ------------------------------------------- | -------------------- | 108| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 109 110**错误码：** 111 112以下错误码的详细介绍请参见[证书管理对话框错误码](errorcode-certManagerDialog.md)。 113 114| 错误码ID | 错误信息 | 115| -------- | ------------------------------------------------------------ | 116| 201 | Permission verification failed. The application does not have the permission required to call the API. | 117| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 118| 29700001 | Internal error. | 119 120**示例**： 121```ts 122import { certificateManagerDialog } from '@kit.DeviceCertificateKit'; 123import { BusinessError } from '@kit.BasicServicesKit'; 124import { common } from '@kit.AbilityKit'; 125import { UIContext } from '@kit.ArkUI'; 126 127/* context为应用的上下文信息，调用方自行获取，此处仅为示例 */ 128let context: common.Context = new UIContext().getHostContext() as common.Context; 129/* pageType为页面类型，此处赋值PAGE_MAIN，即拉起证书管理主界面 */ 130let pageType: certificateManagerDialog.CertificateDialogPageType = certificateManagerDialog.CertificateDialogPageType.PAGE_MAIN; 131try { 132 certificateManagerDialog.openCertificateManagerDialog(context, pageType).then(() => { 133 console.info('Succeeded in opening certificate manager dialog.'); 134 }).catch((err: BusinessError) => { 135 console.error(`Failed to open certificate manager dialog. Code: ${err.code}, message: ${err.message}`); 136 }) 137} catch (error) { 138 console.error(`Failed to open certificate manager dialog. Code: ${error.code}, message: ${error.message}`); 139} 140``` 141## certificateManagerDialog.openInstallCertificateDialog<sup>14+</sup> 142 143openInstallCertificateDialog(context: common.Context, certType: CertificateType, certScope: CertificateScope, cert: Uint8Array): Promise\<string> 144 145表示拉起证书管理安装证书向导，显示相应的页面，使用Promise方式异步返回结果。 146 147仅2in1设备支持。 148 149**需要权限：** ohos.permission.ACCESS_CERT_MANAGER 150 151**系统能力：** SystemCapability.Security.CertificateManagerDialog 152 153**模型约束：** 此接口仅可在Stage模型下使用。 154 155**参数**： 156 157| 参数名 | 类型 | 必填 | 说明 | 158| -------- | ------------------------------------------------- | ---- | -------------------------- | 159| context | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md) | 是 | 表示应用的上下文信息。 | 160| certType | [CertificateType](#certificatetype14) | 是 | 表示安装证书类型。 | 161| certScope | [CertificateScope](#certificatescope14) | 是 | 表示安装证书的使用范围。 | 162| cert | Uint8Array | 是 | 表示安装证书数据。 | 163 164**返回值**： 165 166| 类型 | 说明 | 167| ------------------------------------------- | -------------------- | 168| Promise\<string> | Promise对象。表示返回证书uri的结果，最大长度为256字节。 | 169 170**错误码：** 171 172以下错误码的详细介绍请参见[证书管理对话框错误码](errorcode-certManagerDialog.md)。 173 174| 错误码ID | 错误信息 | 175| -------- | ------------------------------------------------------------ | 176| 201 | Permission verification failed. The application does not have the permission required to call the API. | 177| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 178| 29700001 | Internal error. | 179| 29700002 | The user cancels the installation operation. | 180| 29700003 | The user install certificate failed in the certificate manager dialog, such as the certificate is in an invalid format. | 181| 29700004 | The API is not supported on this device. | 182| 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. | 183 184**示例**： 185```ts 186import { certificateManagerDialog } from '@kit.DeviceCertificateKit'; 187import { BusinessError } from '@kit.BasicServicesKit'; 188import { common } from '@kit.AbilityKit'; 189import { UIContext } from '@kit.ArkUI'; 190 191/* context为应用的上下文信息，调用方自行获取，此处仅为示例 */ 192let context: common.Context = new UIContext().getHostContext() as common.Context; 193/* certificateType为证书类型，此处赋值CA_CERT，即安装CA证书 */ 194let certificateType: certificateManagerDialog.CertificateType = certificateManagerDialog.CertificateType.CA_CERT; 195/* certificateScope为证书使用范围，此处赋值CURRENT_USER，即当前用户下可用 */ 196let certificateScope: certificateManagerDialog.CertificateScope = certificateManagerDialog.CertificateScope.CURRENT_USER; 197/* 安装的CA证书数据需要业务赋值，本例数据非CA证书数据 */ 198let caCert: Uint8Array = new Uint8Array([ 199 0x30, 0x82, 0x0b, 0xc1, 0x02, 0x01, 200]); 201try { 202 certificateManagerDialog.openInstallCertificateDialog(context, certificateType, certificateScope, caCert).then((uri: string) => { 203 console.info('Succeeded opening install certificate'); 204 }).catch((err: BusinessError) => { 205 console.error(`Failed to open install certificate dialog. Code: ${err.code}, message: ${err.message}`); 206 }) 207} catch (error) { 208 console.error(`Failed to open install certificate dialog. Code: ${error.code}, message: ${error.message}`); 209} 210``` 211 212## certificateManagerDialog.openUninstallCertificateDialog<sup>18+</sup> 213 214openUninstallCertificateDialog(context: common.Context, certType: CertificateType, certUri: string): Promise\<void> 215 216表示拉起证书管理删除证书向导，显示相应的页面，使用Promise方式异步返回结果。 217 218仅2in1设备支持。 219 220**需要权限：** ohos.permission.ACCESS_CERT_MANAGER 221 222**系统能力：** SystemCapability.Security.CertificateManagerDialog 223 224**模型约束：** 此接口仅可在Stage模型下使用。 225 226**参数**： 227 228| 参数名 | 类型 | 必填 | 说明 | 229| -------- | ------------------------------------------------- | ---- | -------------------------- | 230| context | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md) | 是 | 表示应用的上下文信息。 | 231| certType | [CertificateType](#certificatetype14) | 是 | 表示删除证书类型。 | 232| certUri | string | 是 | 表示待删除证书的唯一标识符，最大长度为256字节。 | 233 234**返回值**： 235 236| 类型 | 说明 | 237| ------------------------------------------- | -------------------- | 238| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 239 240**错误码：** 241 242以下错误码的详细介绍请参见[证书管理对话框错误码](errorcode-certManagerDialog.md)。 243 244| 错误码ID | 错误信息 | 245| -------- | ------------------------------------------------------------ | 246| 201 | Permission verification failed. The application does not have the permission required to call the API. | 247| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 248| 29700001 | Internal error. | 249| 29700002 | The user cancels the uninstallation operation. | 250| 29700003 | The user uninstall certificate failed in the certificate manager dialog, such as the certificate uri is not exist. | 251| 29700004 | The API is not supported on this device. | 252| 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. | 253 254**示例**： 255```ts 256import { certificateManagerDialog } from '@kit.DeviceCertificateKit'; 257import { BusinessError } from '@kit.BasicServicesKit'; 258import { common } from '@kit.AbilityKit'; 259import { UIContext } from '@kit.ArkUI'; 260 261/* context为应用的上下文信息，调用方自行获取，此处仅为示例 */ 262let context: common.Context = new UIContext().getHostContext() as common.Context; 263/* certificateType为证书类型，此处赋值CA_CERT，即安装CA证书 */ 264let certificateType: certificateManagerDialog.CertificateType = certificateManagerDialog.CertificateType.CA_CERT; 265/* certUri为业务安装证书返回的唯一标识符，此处仅为示例 */ 266let certUri: string = "test"; 267try { 268 certificateManagerDialog.openUninstallCertificateDialog(context, certificateType, certUri).then(() => { 269 console.info('Succeeded opening uninstall certificate'); 270 }).catch((err: BusinessError) => { 271 console.error(`Failed to open uninstall certificate dialog. Code: ${err.code}, message: ${err.message}`); 272 }) 273} catch (error) { 274 console.error(`Failed to open uninstall certificate dialog. Code: ${error.code}, message: ${error.message}`); 275} 276``` 277 278## certificateManagerDialog.openCertificateDetailDialog<sup>18+</sup> 279 280openCertificateDetailDialog(context: common.Context, cert: Uint8Array, property: CertificateDialogProperty): Promise\<void> 281 282表示拉起证书管理对话框显示证书的详情，使用Promise方式异步返回结果。 283 284仅2in1设备支持。 285 286**需要权限：** ohos.permission.ACCESS_CERT_MANAGER 287 288**系统能力：** SystemCapability.Security.CertificateManagerDialog 289 290**模型约束：** 此接口仅可在Stage模型下使用。 291 292**参数**： 293 294| 参数名 | 类型 | 必填 | 说明 | 295| -------- | ------------------------------------------------- | ---- | -------------------------- | 296| context | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md) | 是 | 表示应用的上下文信息。 | 297| cert | Uint8Array | 是 | 表示安装证书数据。 | 298| property | [CertificateDialogProperty](#certificatedialogproperty18) | 是 | 表示拉起证书管理对话框的属性。 | 299 300**返回值**： 301 302| 类型 | 说明 | 303| ------------------------------------------- | -------------------- | 304| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 305 306**错误码：** 307 308以下错误码的详细介绍请参见[证书管理对话框错误码](errorcode-certManagerDialog.md)。 309 310| 错误码ID | 错误信息 | 311| -------- | ------------------------------------------------------------ | 312| 201 | Permission verification failed. The application does not have the permission required to call the API. | 313| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 314| 29700001 | Internal error. | 315| 29700003 | Show the certificate detail dialog fail, such as the certificate is in an invalid format. | 316| 29700004 | The API is not supported on this device. | 317 318**示例**： 319```ts 320import { certificateManagerDialog } from '@kit.DeviceCertificateKit'; 321import { BusinessError } from '@kit.BasicServicesKit'; 322import { common } from '@kit.AbilityKit'; 323import { UIContext } from '@kit.ArkUI'; 324 325/* context为应用的上下文信息，调用方自行获取，此处仅为示例 */ 326let context: common.Context = new UIContext().getHostContext() as common.Context; 327/* 安装的CA证书数据需要业务赋值，本例数据非CA证书数据 */ 328let caCert: Uint8Array = new Uint8Array([ 329 0x30, 0x82, 0x0b, 0xc1, 0x02, 0x01, 330]); 331let property: certificateManagerDialog.CertificateDialogProperty = { 332 showInstallButton: false /* 不显示安装按钮 */ 333}; 334try { 335 certificateManagerDialog.openCertificateDetailDialog(context, caCert, property).then(() => { 336 console.info('Succeeded opening certificate detail dialog.'); 337 }).catch((err: BusinessError) => { 338 console.error(`Failed to open certificate detail dialog. Code: ${err.code}, message: ${err.message}`); 339 }) 340} catch (error) { 341 console.error(`Failed to open certificate detail dialog. Code: ${error.code}, message: ${error.message}`); 342} 343``` 344