1/* 2 * Copyright (c) 2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit DeviceCertificateKit 19 */ 20 21import type common from '@ohos.app.ability.common'; 22 23/** 24 * OpenHarmony Universal CertificateManager 25 * 26 * @namespace certificateManagerDialog 27 * @syscap SystemCapability.Security.CertificateManagerDialog 28 * @stagemodelonly 29 * @since 13 30 */ 31declare namespace certificateManagerDialog { 32 /** 33 * Enum for result code 34 * 35 * @enum { number } 36 * @syscap SystemCapability.Security.CertificateManagerDialog 37 * @stagemodelonly 38 * @since 13 39 */ 40 export enum CertificateDialogErrorCode { 41 42 /** 43 * Indicates that internal error. 44 * 45 * @syscap SystemCapability.Security.CertificateManagerDialog 46 * @stagemodelonly 47 * @since 13 48 */ 49 ERROR_GENERIC = 29700001, 50 51 /** 52 * Indicates the user cancels the operation. 53 * 54 * @syscap SystemCapability.Security.CertificateManagerDialog 55 * @stagemodelonly 56 * @since 14 57 */ 58 ERROR_OPERATION_CANCELED = 29700002, 59 60 /** 61 * Indicates that the user operation failed in the certificate manager dialog, such as install certificate failed. 62 * 63 * @syscap SystemCapability.Security.CertificateManagerDialog 64 * @stagemodelonly 65 * @since 14 66 */ 67 ERROR_OPERATION_FAILED = 29700003, 68 69 /** 70 * Indicates that the API is not supported on this device. 71 * 72 * @syscap SystemCapability.Security.CertificateManagerDialog 73 * @stagemodelonly 74 * @since 14 75 */ 76 ERROR_DEVICE_NOT_SUPPORTED = 29700004, 77 78 /** 79 * Indicates that 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.. 80 * 81 * @syscap SystemCapability.Security.CertificateManagerDialog 82 * @stagemodelonly 83 * @since 18 84 */ 85 ERROR_NOT_COMPLY_SECURITY_POLICY = 29700005, 86 } 87 88 89 /** 90 * Enum for page type of certificate manager dialog 91 * 92 * @enum { number } 93 * @syscap SystemCapability.Security.CertificateManagerDialog 94 * @stagemodelonly 95 * @since 13 96 */ 97 export enum CertificateDialogPageType { 98 /** 99 * Indicates the main entrance page. 100 * 101 * @syscap SystemCapability.Security.CertificateManagerDialog 102 * @stagemodelonly 103 * @since 13 104 */ 105 PAGE_MAIN = 1, 106 107 /** 108 * Indicates the CA certificate list page. 109 * 110 * @syscap SystemCapability.Security.CertificateManagerDialog 111 * @stagemodelonly 112 * @since 13 113 */ 114 PAGE_CA_CERTIFICATE = 2, 115 116 /** 117 * Indicates the Credential list page. 118 * 119 * @syscap SystemCapability.Security.CertificateManagerDialog 120 * @stagemodelonly 121 * @since 13 122 */ 123 PAGE_CREDENTIAL = 3, 124 125 /** 126 * Indicates the install certificate page. 127 * 128 * @syscap SystemCapability.Security.CertificateManagerDialog 129 * @stagemodelonly 130 * @since 13 131 */ 132 PAGE_INSTALL_CERTIFICATE = 4 133 } 134 135 /** 136 * open certificate manager dialog and show the specified page. 137 * 138 * @permission ohos.permission.ACCESS_CERT_MANAGER 139 * @param { common.Context } context - Hap context information. 140 * @param { CertificateDialogPageType } pageType - Indicates page type. 141 * @returns { Promise<void> } The promise returned by the function. 142 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 143 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 144 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 145 * @throws { BusinessError } 29700001 - Internal error. Possible causes: 1. IPC communication failed; 146 * <br>2. Memory operation error; 3. File operation error. 147 * @syscap SystemCapability.Security.CertificateManagerDialog 148 * @stagemodelonly 149 * @since 13 150 */ 151 function openCertificateManagerDialog(context: common.Context, pageType: CertificateDialogPageType): Promise<void>; 152 153 154 155 /** 156 * Enum for certificate type 157 * 158 * @enum { number } 159 * @syscap SystemCapability.Security.CertificateManagerDialog 160 * @stagemodelonly 161 * @since 14 162 */ 163 export enum CertificateType { 164 /** 165 * Indicates CA certificate. 166 * 167 * @syscap SystemCapability.Security.CertificateManagerDialog 168 * @stagemodelonly 169 * @since 14 170 */ 171 CA_CERT = 1 172 } 173 174 /** 175 * Enum for certificate scope 176 * 177 * @enum { number } 178 * @syscap SystemCapability.Security.CertificateManagerDialog 179 * @stagemodelonly 180 * @since 14 181 */ 182 export enum CertificateScope { 183 /** 184 * Indicates the certificate scope is not specified and user can select the scope in the certificate install dialog. 185 * 186 * @syscap SystemCapability.Security.CertificateManagerDialog 187 * @stagemodelonly 188 * @since 18 189 */ 190 NOT_SPECIFIED = 0, 191 192 /** 193 * Indicates the certificate is for current user. 194 * 195 * @syscap SystemCapability.Security.CertificateManagerDialog 196 * @stagemodelonly 197 * @since 14 198 */ 199 CURRENT_USER = 1, 200 201 /** 202 * Indicates the certificate is for all users. 203 * 204 * @syscap SystemCapability.Security.CertificateManagerDialog 205 * @stagemodelonly 206 * @since 18 207 */ 208 GLOBAL_USER = 2, 209 } 210 211 /** 212 * open install certificate dialog. 213 * 214 * @permission ohos.permission.ACCESS_CERT_MANAGER 215 * @param { common.Context } context - Hap context information 216 * @param { CertificateType } certType - Indicates the type of certificate to be installed. 217 * @param { CertificateScope } certScope - Indicates the user scope of certificate to be installed. 218 * @param { Uint8Array } cert - Indicates the contents of the certificate file to be installed. 219 * @returns { Promise<string> } The uri of installed certificate. 220 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 221 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 222 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 223 * @throws { BusinessError } 29700001 - Internal error. Possible causes: 1. IPC communication failed; 224 * <br>2. Memory operation error; 3. File operation error. 225 * @throws { BusinessError } 29700002 - The user cancels the installation operation. 226 * @throws { BusinessError } 29700003 - The user install certificate failed in the certificate manager dialog. 227 * @throws { BusinessError } 29700004 - The API is not supported on this device. 228 * @syscap SystemCapability.Security.CertificateManagerDialog 229 * @stagemodelonly 230 * @since 14 231 */ 232 /** 233 * open install certificate dialog. 234 * 235 * @permission ohos.permission.ACCESS_CERT_MANAGER 236 * @param { common.Context } context - Hap context information 237 * @param { CertificateType } certType - Indicates the type of certificate to be installed. 238 * @param { CertificateScope } certScope - Indicates the user scope of certificate to be installed. 239 * @param { Uint8Array } cert - Indicates the contents of the certificate file to be installed. 240 * @returns { Promise<string> } The uri of installed certificate. 241 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 242 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 243 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 244 * @throws { BusinessError } 29700001 - Internal error. Possible causes: 1. IPC communication failed; 245 * <br>2. Memory operation error; 3. File operation error. 246 * @throws { BusinessError } 29700002 - The user cancels the installation operation. 247 * @throws { BusinessError } 29700003 - The user install certificate failed in the certificate manager dialog, such as the certificate is in an invalid format. 248 * @throws { BusinessError } 29700004 - The API is not supported on this device. 249 * @throws { BusinessError } 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. 250 * @syscap SystemCapability.Security.CertificateManagerDialog 251 * @stagemodelonly 252 * @since 18 253 */ 254 function openInstallCertificateDialog(context: common.Context, certType: CertificateType, certScope: CertificateScope, cert: Uint8Array): Promise<string>; 255 256 /** 257 * open uninstall certificate dialog. 258 * 259 * @permission ohos.permission.ACCESS_CERT_MANAGER 260 * @param { common.Context } context - Hap context information 261 * @param { CertificateType } certType - Indicates the type of certificate to be uninstalled. 262 * @param { string } certUri - Indicates the certificate uri to be uninstalled. 263 * @returns { Promise<void> } The promise returned by the function. 264 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 265 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 266 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 267 * @throws { BusinessError } 29700001 - Internal error. Possible causes: 1. IPC communication failed; 268 * <br>2. Memory operation error; 3. File operation error. 269 * @throws { BusinessError } 29700002 - The user cancels the uninstallation operation. 270 * @throws { BusinessError } 29700003 - The user uninstall certificate failed in the certificate manager dialog, such as the certificate uri is not exist. 271 * @throws { BusinessError } 29700004 - The API is not supported on this device. 272 * @throws { BusinessError } 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. 273 * @syscap SystemCapability.Security.CertificateManagerDialog 274 * @stagemodelonly 275 * @since 18 276 */ 277 function openUninstallCertificateDialog(context: common.Context, certType: CertificateType, certUri: string): Promise<void>; 278 279 /** 280 * Provides the certificate dialog property. 281 * 282 * @typedef CertificateDialogProperty 283 * @syscap SystemCapability.Security.CertificateManagerDialog 284 * @stagemodelonly 285 * @since 18 286 */ 287 export interface CertificateDialogProperty { 288 /** 289 * Indicates if the certificate dialog show install button. 290 * 291 * @type { boolean } 292 * @syscap SystemCapability.Security.CertificateManagerDialog 293 * @stagemodelonly 294 * @since 18 295 */ 296 showInstallButton: boolean; 297 } 298 299 /** 300 * open certificate manager dialog and show the certificate detail page. 301 * 302 * @permission ohos.permission.ACCESS_CERT_MANAGER 303 * @param { common.Context } context - Hap context information 304 * @param { Uint8Array } cert - Indicates the contents of the certificate file. 305 * @param { CertificateDialogProperty } property - the certificate dialog property. 306 * @returns { Promise<void> } The promise returned by the function. 307 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 308 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 309 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 310 * @throws { BusinessError } 29700001 - Internal error. Possible causes: 1. IPC communication failed; 311 * <br>2. Memory operation error; 3. File operation error. 312 * @throws { BusinessError } 29700003 - Show the certificate detail dialog fail, such as the certificate is in an invalid format. 313 * @throws { BusinessError } 29700004 - The API is not supported on this device. 314 * @syscap SystemCapability.Security.CertificateManagerDialog 315 * @stagemodelonly 316 * @since 18 317 */ 318 function openCertificateDetailDialog(context: common.Context, cert: Uint8Array, property: CertificateDialogProperty): Promise<void>; 319 320 /** 321 * Opens the authorization page of the certificate management dialog box. On the page displayed, the user can 322 * authorize a certificate for the application. 323 * 324 * @permission ohos.permission.ACCESS_CERT_MANAGER 325 * @param { common.Context } context Context of the HAP. 326 * @returns { Promise<string> } Promise used to return the URI of the certificate authorized. 327 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the 328 * permission required to call the API. 329 * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. A mandatory parameter is left 330 * unspecified. 331 * 2. Incorrect parameter type. 3. Parameter verification failed. 332 * @throws { BusinessError } 29700001 Internal error. Possible causes: 1. IPC communication failed; 333 * <br>2. Memory operation error; 3. File operation error. 334 * @throws { BusinessError } 29700002 The user cancels the authorization. 335 * @syscap SystemCapability.Security.CertificateManagerDialog 336 * @stagemodelonly 337 * @since 20 338 */ 339 function openAuthorizeDialog(context: common.Context): Promise<string>; 340} 341 342export default certificateManagerDialog; 343