1# @ohos.security.certManagerDialog (证书管理对话框模块) 2 3<!--Kit: Device Certificate Kit--> 4<!--Subsystem: Security--> 5<!--Owner: @chaceli--> 6<!--Designer: @chande--> 7<!--Tester: @zhangzhi1995--> 8<!--Adviser: @zengyawen--> 9 10证书管理对话框主要提供拉起证书管理界面的能力，用户在拉起的证书管理对话框可对证书进行管理（安装，存储，使用，销毁）。 11 12> **说明：** 13> 14> 本模块首批接口从API version 13开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15 16## 导入模块 17 18```ts 19import certificateManagerDialog from '@ohos.security.certManagerDialog'; 20``` 21 22## CertificateDialogPageType 23 24表示证书管理对话框的页面类型。 25 26**系统能力：** SystemCapability.Security.CertificateManagerDialog 27 28**模型约束：** 此接口仅可在Stage模型下使用。 29 30| 名称 | 值 | 说明 | 31| ---------- | ------ | --------- | 32| PAGE_MAIN | 1 | 证书管理应用主页面。 | 33| PAGE_CA_CERTIFICATE | 2 | CA证书列表页面。 | 34| PAGE_CREDENTIAL | 3 | 凭据列表页面。 | 35| PAGE_INSTALL_CERTIFICATE | 4 | 安装证书页面。 | 36 37## CertificateType<sup>14+</sup> 38 39表示安装证书的类型。 40 41**系统能力：** SystemCapability.Security.CertificateManagerDialog 42 43**模型约束：** 此接口仅可在Stage模型下使用。 44 45| 名称 | 值 | 说明 | 46| ---------- | ------ | --------- | 47| CA_CERT | 1 | CA证书。 | 48 49## CertificateScope<sup>14+</sup> 50 51表示安装证书的使用范围。 52 53**系统能力：** SystemCapability.Security.CertificateManagerDialog 54 55**模型约束：** 此接口仅可在Stage模型下使用。 56 57| 名称 | 值 | 说明 | 58| ---------- | ------ | --------- | 59| NOT_SPECIFIED<sup>18+</sup> | 0 | 未指定用户。 | 60| CURRENT_USER | 1 | 当前用户。 | 61| GLOBAL_USER<sup>18+</sup> | 2 | 公共目录。 | 62 63 64## CertificateDialogErrorCode 65 66表示调用证书管理对话框相关API的错误码。 67 68**系统能力：** SystemCapability.Security.CertificateManagerDialog 69 70**模型约束：** 此接口仅可在Stage模型下使用。 71 72| 名称 | 值 | 说明 | 73| ---------- | ------ | --------- | 74| ERROR_GENERIC | 29700001 | 表示调用接口时发生内部错误。 | 75| ERROR_OPERATION_CANCELED<sup>14+</sup> | 29700002 | 表示调用接口时用户取消操作。 | 76| ERROR_OPERATION_FAILED<sup>14+</sup> | 29700003 | 表示调用接口时安装证书失败。 | 77| ERROR_DEVICE_NOT_SUPPORTED<sup>14+</sup> | 29700004 | 表示调用接口时设备类型不支持。 | 78| ERROR_NOT_COMPLY_SECURITY_POLICY<sup>18+</sup> | 29700005 | 表示调用接口时不符合设备安全策略。 | 79 80## CertificateDialogProperty<sup>18+</sup> 81 82表示证书管理对话框的属性。 83 84**系统能力：** SystemCapability.Security.CertificateManagerDialog 85 86**模型约束：** 此接口仅可在Stage模型下使用。 87 88| 名称 | 类型 | 只读 | 可选 | 说明 | 89| ----------------- | ------- | ---- | ---- | ---------------------------- | 90| showInstallButton | boolean | 否 | 否 | 表示是否显示安装证书的按钮，true为显示，false为不显示。 | 91 92## certificateManagerDialog.openCertificateManagerDialog 93 94openCertificateManagerDialog(context: common.Context, pageType: CertificateDialogPageType): Promise\<void> 95 96表示拉起证书管理对话框，显示相应的页面，使用Promise方式异步返回结果。 97 98**需要权限：** ohos.permission.ACCESS_CERT_MANAGER 99 100**系统能力：** SystemCapability.Security.CertificateManagerDialog 101 102**模型约束：** 此接口仅可在Stage模型下使用。 103 104**参数**： 105 106| 参数名 | 类型 | 必填 | 说明 | 107| -------- | ------------------------------------------------- | ---- | -------------------------- | 108| context | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md) | 是 | 表示应用的上下文信息。 | 109| pageType | [CertificateDialogPageType](#certificatedialogpagetype) | 是 | 表示页面类型。 | 110 111**返回值**： 112 113| 类型 | 说明 | 114| ------------------------------------------- | -------------------- | 115| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 116 117**错误码：** 118 119以下错误码的详细介绍请参见[证书管理对话框错误码](errorcode-certManagerDialog.md)。 120 121| 错误码ID | 错误信息 | 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**示例**： 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为应用的上下文信息，调用方自行获取，此处仅为示例 */ 135let context: common.Context = new UIContext().getHostContext() as common.Context; 136/* pageType为页面类型，此处赋值PAGE_MAIN，即拉起证书管理主界面 */ 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 152表示拉起证书管理安装证书向导，显示相应的页面，使用Promise方式异步返回结果。 153 154**需要权限：** ohos.permission.ACCESS_CERT_MANAGER 155 156**系统能力：** SystemCapability.Security.CertificateManagerDialog 157 158**设备行为差异：** 该接口在PC/2in1设备可正常调用，在其他设备中返回29700004错误码。 159 160**模型约束：** 此接口仅可在Stage模型下使用。 161 162**参数**： 163 164| 参数名 | 类型 | 必填 | 说明 | 165| -------- | ------------------------------------------------- | ---- | -------------------------- | 166| context | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md) | 是 | 表示应用的上下文信息。 | 167| certType | [CertificateType](#certificatetype14) | 是 | 表示安装证书类型。 | 168| certScope | [CertificateScope](#certificatescope14) | 是 | 表示安装证书的使用范围。 | 169| cert | Uint8Array | 是 | 表示安装证书数据。 | 170 171**返回值**： 172 173| 类型 | 说明 | 174| ------------------------------------------- | -------------------- | 175| Promise\<string> | Promise对象。表示返回证书uri的结果，最大长度为256字节。 | 176 177**错误码：** 178 179以下错误码的详细介绍请参见[证书管理对话框错误码](errorcode-certManagerDialog.md)。 180 181| 错误码ID | 错误信息 | 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**示例**： 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为应用的上下文信息，调用方自行获取，此处仅为示例 */ 199let context: common.Context = new UIContext().getHostContext() as common.Context; 200/* certificateType为证书类型，此处赋值CA_CERT，即安装CA证书 */ 201let certificateType: certificateManagerDialog.CertificateType = certificateManagerDialog.CertificateType.CA_CERT; 202/* certificateScope为证书使用范围，此处赋值CURRENT_USER，即当前用户下可用 */ 203let certificateScope: certificateManagerDialog.CertificateScope = certificateManagerDialog.CertificateScope.CURRENT_USER; 204/* 安装的CA证书数据需要业务赋值，本例数据非CA证书数据 */ 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 223表示拉起证书管理删除证书向导，显示相应的页面，使用Promise方式异步返回结果。 224 225**需要权限：** ohos.permission.ACCESS_CERT_MANAGER 226 227**系统能力：** SystemCapability.Security.CertificateManagerDialog 228 229**设备行为差异：** 该接口在PC/2in1设备可正常调用，在其他设备中返回29700004错误码。 230 231**模型约束：** 此接口仅可在Stage模型下使用。 232 233**参数**： 234 235| 参数名 | 类型 | 必填 | 说明 | 236| -------- | ------------------------------------------------- | ---- | -------------------------- | 237| context | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md) | 是 | 表示应用的上下文信息。 | 238| certType | [CertificateType](#certificatetype14) | 是 | 表示删除证书类型。 | 239| certUri | string | 是 | 表示待删除证书的唯一标识符，最大长度为256字节。 | 240 241**返回值**： 242 243| 类型 | 说明 | 244| ------------------------------------------- | -------------------- | 245| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 246 247**错误码：** 248 249以下错误码的详细介绍请参见[证书管理对话框错误码](errorcode-certManagerDialog.md)。 250 251| 错误码ID | 错误信息 | 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**示例**： 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为应用的上下文信息，调用方自行获取，此处仅为示例 */ 269let context: common.Context = new UIContext().getHostContext() as common.Context; 270/* certificateType为证书类型，此处赋值CA_CERT，即安装CA证书 */ 271let certificateType: certificateManagerDialog.CertificateType = certificateManagerDialog.CertificateType.CA_CERT; 272/* certUri为业务安装证书返回的唯一标识符，此处仅为示例 */ 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 289表示拉起证书管理对话框显示证书的详情，使用Promise方式异步返回结果。 290 291**需要权限：** ohos.permission.ACCESS_CERT_MANAGER 292 293**系统能力：** SystemCapability.Security.CertificateManagerDialog 294 295**设备行为差异：** 该接口在PC/2in1设备可正常调用，在其他设备中返回29700004错误码。 296 297**模型约束：** 此接口仅可在Stage模型下使用。 298 299**参数**： 300 301| 参数名 | 类型 | 必填 | 说明 | 302| -------- | ------------------------------------------------- | ---- | -------------------------- | 303| context | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md) | 是 | 表示应用的上下文信息。 | 304| cert | Uint8Array | 是 | 表示安装证书数据。 | 305| property | [CertificateDialogProperty](#certificatedialogproperty18) | 是 | 表示拉起证书管理对话框的属性。 | 306 307**返回值**： 308 309| 类型 | 说明 | 310| ------------------------------------------- | -------------------- | 311| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 312 313**错误码：** 314 315以下错误码的详细介绍请参见[证书管理对话框错误码](errorcode-certManagerDialog.md)。 316 317| 错误码ID | 错误信息 | 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**示例**： 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为应用的上下文信息，调用方自行获取，此处仅为示例 */ 333let context: common.Context = new UIContext().getHostContext() as common.Context; 334/* 安装的CA证书数据需要业务赋值，本例数据非CA证书数据 */ 335let caCert: Uint8Array = new Uint8Array([ 336 0x30, 0x82, 0x0b, 0xc1, 0x02, 0x01, 337]); 338let property: certificateManagerDialog.CertificateDialogProperty = { 339 showInstallButton: false /* 不显示安装按钮 */ 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 356打开证书管理对话框的授权页面。在弹出的页面中，用户可以为应用授权证书。使用Promise方式异步返回结果。 357 358**需要权限：** ohos.permission.ACCESS_CERT_MANAGER 359 360**系统能力：** SystemCapability.Security.CertificateManagerDialog 361 362**模型约束：** 此接口仅可在Stage模型下使用。 363 364**参数**： 365 366| 参数名 | 类型 | 必填 | 说明 | 367|---------|--------------------------------------------------------------------|----|-------------| 368| context | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md) | 是 | 表示应用的上下文信息。 | 369 370**返回值**： 371 372| 类型 | 说明 | 373|------------------|--------------------------------------| 374| Promise\<string> | Promise对象。表示返回授权证书uri的结果，最大长度为256字节。 | 375 376**错误码：** 377 378以下错误码的详细介绍请参见[证书管理对话框错误码](errorcode-certManagerDialog.md)。 379 380| 错误码ID | 错误信息 | 381|----------|-------------------------------------------------------------------------------------------------------------------------------------------------| 382| 201 | Permission verification failed. The application does not have the permission required to call the API. | 383| 401 | Invalid parameter. Possible causes: 1. A mandatory parameter is left unspecified. 2. Incorrect parameter type. 3. Parameter verification failed. | 384| 29700001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 385| 29700002 | The user cancels the authorization. | 386 387**示例**： 388```ts 389import { certificateManagerDialog } from '@kit.DeviceCertificateKit'; 390import { BusinessError } from '@kit.BasicServicesKit'; 391import { common } from '@kit.AbilityKit'; 392import { UIContext } from '@kit.ArkUI'; 393 394/* context为应用的上下文信息，调用方自行获取，此处仅为示例 */ 395let context: common.Context = new UIContext().getHostContext() as common.Context; 396try { 397 certificateManagerDialog.openAuthorizeDialog(context).then((uri: string) => { 398 console.info(`Success to authorize certificate, uri: ${uri}`) 399 }).catch((err: BusinessError) => { 400 console.error(`Failed to authorize certificate. Code: ${err.code}, message: ${err.message}`); 401 }); 402} catch (err) { 403 let error = err as BusinessError; 404 console.error(`Failed to authorize certificate. Code: ${error.code}, message: ${error.message}`); 405} 406```