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| CURRENT_USER | 1      | Current user.|
53
54## CertificateDialogErrorCode
55
56Enumerates the error codes reported when the certificate management dialog box APIs are called.
57
58**System capability**: SystemCapability.Security.CertificateManagerDialog
59
60**Model restriction**: This API can be used only in the stage model.
61
62| Name      | Value|  Description     |
63| ---------- | ------ | --------- |
64| ERROR_GENERIC  | 29700001      | Internal error.|
65| ERROR_OPERATION_CANCELED<sup>14+</sup>  | 29700002      | The user canceled the operation when the API is called.|
66| ERROR_OPERATION_FAILED<sup>14+</sup>  | 29700003      | The certificate installation fails.|
67| ERROR_DEVICE_NOT_SUPPORTED<sup>14+</sup>  | 29700004      | The device does not support the API called.|
68
69## certificateManagerDialog.openCertificateManagerDialog
70
71openCertificateManagerDialog(context: common.Context, pageType: CertificateDialogPageType): Promise\<void>
72
73Opens the certificate management dialog box and displays the page of the specified type. This API uses a promise to return the result.
74
75**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER
76
77**System capability**: SystemCapability.Security.CertificateManagerDialog
78
79**Model restriction**: This API can be used only in the stage model.
80
81**Parameters**
82
83| Name  | Type                                             | Mandatory| Description                      |
84| -------- | ------------------------------------------------- | ---- | -------------------------- |
85| context | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md)                   | Yes  | Context of the application.|
86| pageType | [CertificateDialogPageType](#certificatedialogpagetype)                   | Yes  | Type of the page to display.|
87
88**Return value**
89
90| Type                                       | Description                |
91| ------------------------------------------- | -------------------- |
92| Promise\<void> | Promise that returns no value.|
93
94**Error codes**
95
96For details about the error codes, see [Certificate Management Dialog Box Error Codes](errorcode-certManagerDialog.md).
97
98| ID| Error Message                                                    |
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**Example**
105```ts
106import certificateManagerDialog from '@ohos.security.certManagerDialog';
107import { BusinessError } from '@kit.BasicServicesKit';
108import { common } from '@kit.AbilityKit';
109
110/* context is application context information, which is obtained by the caller. The context here is only an example. */
111let context: common.Context = getContext(this);
112/* 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. */
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
128Opens a dialog box for installing a certificate. This API uses a promise to return the result.
129
130**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER
131
132**System capability**: SystemCapability.Security.CertificateManagerDialog
133
134**Model restriction**: This API can be used only in the stage model.
135
136**Parameters**
137
138| Name  | Type                                             | Mandatory| Description                      |
139| -------- | ------------------------------------------------- | ---- | -------------------------- |
140| context | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md)                   | Yes  | Context of the application.|
141| certType<sup>14+</sup> | [CertificateType](#certificatetype14)                   | Yes  | Type of the certificate to install.|
142| certScope<sup>14+</sup> | [CertificateScope](#certificatescope14)                   | Yes  | Usage scope of the certificate.|
143| cert | Uint8Array                  | Yes  | Data of the certificate to install.|
144
145**Return value**
146
147| Type                                       | Description                |
148| ------------------------------------------- | -------------------- |
149| Promise\<string> | Promise used to return the certificate URI.|
150
151**Error codes**
152
153For details about the error codes, see [Certificate Management Dialog Box Error Codes](errorcode-certManagerDialog.md).
154
155| ID| Error Message                                                    |
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**Example**
165```ts
166import certificateManagerDialog from '@ohos.security.certManagerDialog';
167import { BusinessError } from '@kit.BasicServicesKit';
168import { common } from '@kit.AbilityKit';
169
170/* context is application context information, which is obtained by the caller. The context here is only an example. */
171let context: common.Context = getContext(this);
172/* certificateType specifies the certificate type. The value CA_CERT here indicates a CA certificate. */
173let certificateType: certificateManagerDialog.CertificateType = certificateManagerDialog.CertificateType.CA_CERT;
174/* certificateScope specifies the usage scope of the certificate. The value CURRENT_USER here means the certificate can be used by the the current user. */
175let certificateScope: certificateManagerDialog.CertificateScope = certificateManagerDialog.CertificateScope.CURRENT_USER;
176/* The CA certificate data must be assigned by the service. In this example, the data is not CA certificate data. */
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```
190