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| CURRENT_USER | 1      | 当前用户 |
53
54## CertificateDialogErrorCode
55
56表示调用证书管理对话框相关API的错误码。
57
58**系统能力：** SystemCapability.Security.CertificateManagerDialog
59
60**模型约束：** 此接口仅可在Stage模型下使用。
61
62| 名称       | 值 |  说明      |
63| ---------- | ------ | --------- |
64| ERROR_GENERIC  | 29700001      | 表示调用接口时发生内部错误。 |
65| ERROR_OPERATION_CANCELED<sup>14+</sup>  | 29700002      | 表示调用接口时用户取消操作。 |
66| ERROR_OPERATION_FAILED<sup>14+</sup>  | 29700003      | 表示调用接口时安装证书失败。 |
67| ERROR_DEVICE_NOT_SUPPORTED<sup>14+</sup>  | 29700004      | 表示调用接口时设备类型不支持。 |
68
69## certificateManagerDialog.openCertificateManagerDialog
70
71openCertificateManagerDialog(context: common.Context, pageType: CertificateDialogPageType): Promise\<void>
72
73表示拉起证书管理对话框，显示相应的页面，使用Promise方式异步返回结果。
74
75**需要权限：** ohos.permission.ACCESS_CERT_MANAGER
76
77**系统能力：** SystemCapability.Security.CertificateManagerDialog
78
79**模型约束：** 此接口仅可在Stage模型下使用。
80
81**参数**：
82
83| 参数名   | 类型                                              | 必填 | 说明                       |
84| -------- | ------------------------------------------------- | ---- | -------------------------- |
85| context | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md)                   | 是   | 表示应用的上下文信息。 |
86| pageType | [CertificateDialogPageType](#certificatedialogpagetype)                   | 是   | 表示页面类型。 |
87
88**返回值**：
89
90| 类型                                        | 说明                 |
91| ------------------------------------------- | -------------------- |
92| Promise\<void> | Promise对象。无返回结果的Promise对象。 |
93
94**错误码：**
95
96以下错误码的详细介绍请参见[证书管理对话框错误码](errorcode-certManagerDialog.md)。
97
98| 错误码ID | 错误信息                                                     |
99| -------- | ------------------------------------------------------------ |
100| 201      | Permission verification failed. The application does not have the permission required to call the API.     |
101| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
102| 29700001 | Internal error.     |
103
104**示例**：
105```ts
106import certificateManagerDialog from '@ohos.security.certManagerDialog';
107import { BusinessError } from '@kit.BasicServicesKit';
108import { common } from '@kit.AbilityKit';
109
110/* context为应用的上下文信息，调用方自行获取，此处仅为示例 */
111let context: common.Context = getContext(this);
112/* pageType为页面类型，此处赋值PAGE_MAIN，即拉起证书管理主界面 */
113let pageType: certificateManagerDialog.CertificateDialogPageType = certificateManagerDialog.CertificateDialogPageType.PAGE_MAIN;
114try {
115  certificateManagerDialog.openCertificateManagerDialog(context, pageType).then(() => {
116    console.info('Succeeded in opening certificate manager dialog.');
117  }).catch((err: BusinessError) => {
118    console.error(`Failed to open certificate manager dialog. Code: ${err.code}, message: ${err.message}`);
119  })
120} catch (error) {
121  console.error(`Failed to open certificate manager dialog. Code: ${error.code}, message: ${error.message}`);
122}
123```
124## certificateManagerDialog.openInstallCertificateDialog<sup>14+</sup>
125
126openInstallCertificateDialog(context: common.Context, certType: CertificateType, certScope: CertificateScope, cert: Uint8Array): Promise\<string>
127
128表示拉起证书管理安装证书向导，显示相应的页面，使用Promise方式异步返回结果。
129
130**需要权限：** ohos.permission.ACCESS_CERT_MANAGER
131
132**系统能力：** SystemCapability.Security.CertificateManagerDialog
133
134**模型约束：** 此接口仅可在Stage模型下使用。
135
136**参数**：
137
138| 参数名   | 类型                                              | 必填 | 说明                       |
139| -------- | ------------------------------------------------- | ---- | -------------------------- |
140| context | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md)                   | 是   | 表示应用的上下文信息。 |
141| certType<sup>14+</sup> | [CertificateType](#certificatetype14)                   | 是   | 表示安装证书类型。 |
142| certScope<sup>14+</sup> | [CertificateScope](#certificatescope14)                   | 是   | 表示证书使用范围类型。 |
143| cert | Uint8Array                  | 是   | 表示安装证书数据。 |
144
145**返回值**：
146
147| 类型                                        | 说明                 |
148| ------------------------------------------- | -------------------- |
149| Promise\<string> | Promise对象。表示返回证书uri的结果。 |
150
151**错误码：**
152
153以下错误码的详细介绍请参见[证书管理对话框错误码](errorcode-certManagerDialog.md)。
154
155| 错误码ID | 错误信息                                                     |
156| -------- | ------------------------------------------------------------ |
157| 201      | Permission verification failed. The application does not have the permission required to call the API.     |
158| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
159| 29700001 | Internal error.     |
160| 29700002<sup>14+</sup> | The user cancels the installation operation.     |
161| 29700003<sup>14+</sup> | The user install certificate failed in the certificate manager dialog.     |
162| 29700004<sup>14+</sup> | The API is not supported on this device.     |
163
164**示例**：
165```ts
166import certificateManagerDialog from '@ohos.security.certManagerDialog';
167import { BusinessError } from '@kit.BasicServicesKit';
168import { common } from '@kit.AbilityKit';
169
170/* context为应用的上下文信息，调用方自行获取，此处仅为示例 */
171let context: common.Context = getContext(this);
172/* certificateType为证书类型，此处赋值CA_CERT，即安装CA证书 */
173let certificateType: certificateManagerDialog.CertificateType = certificateManagerDialog.CertificateType.CA_CERT;
174/* certificateScope为证书使用范围，此处赋值CURRENT_USER，即当前用户下可用 */
175let certificateScope: certificateManagerDialog.CertificateScope = certificateManagerDialog.CertificateScope.CURRENT_USER;
176/* 安装的CA证书数据需要业务赋值，本例数据非CA证书数据 */
177let caCert: Uint8Array = new Uint8Array([
178  0x30, 0x82, 0x0b, 0xc1, 0x02, 0x01,
179]);
180try {
181  certificateManagerDialog.openInstallCertificateDialog(context, certificateType, certificateScope, caCert).then((uri: string) => {
182    console.info('Succeeded opening install certificate');
183  }).catch((err: BusinessError) => {
184    console.error(`Failed to open install certificate dialog. Code: ${err.code}, message: ${err.message}`);
185  })
186} catch (error) {
187  console.error(`Failed to open install certificate dialog. Code: ${error.code}, message: ${error.message}`);
188}
189```