1# @ohos.security.certManager (Certificate Management) 2 3<!--Kit: Device Certificate Kit--> 4<!--Subsystem: Security--> 5<!--Owner: @chaceli--> 6<!--Designer: @chande--> 7<!--Tester: @zhangzhi1995--> 8<!--Adviser: @zengyawen--> 9 10The **certManager** module provides system-level certificate management capabilities to implement management and secure use of certificates throughout their lifecycle (installation, storage, use, and destruction). 11 12> **NOTE** 13> 14> The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version. 15 16## Modules to Import 17 18```ts 19import { certificateManager } from '@kit.DeviceCertificateKit'; 20``` 21 22## CmKeyPurpose 23 24Enumerates the purposes of using the key. 25 26**System capability**: System SystemCapability.Security.CertificateManager 27 28| Name | Value| Description | 29| ---------- | ------ | --------- | 30| CM_KEY_PURPOSE_SIGN | 4 | Signs data.| 31| CM_KEY_PURPOSE_VERIFY | 8 | Verifies a signature.| 32 33## CmKeyDigest 34 35Enumerates the digest algorithms that can be used for signing and signature verification. 36 37**System capability**: System SystemCapability.Security.CertificateManager 38 39| Name | Value| Description | 40| ---------- | ------ | --------- | 41| CM_DIGEST_NONE | 0 | No digest algorithm is required. If this option is used, the service needs to pass in the data with the digest generated for signing or signature verification.| 42| CM_DIGEST_MD5 | 1 | MD5.| 43| CM_DIGEST_SHA1 | 2 | SHA-1.| 44| CM_DIGEST_SHA224 | 3 | SHA-224.| 45| CM_DIGEST_SHA256 | 4 | SHA-256.| 46| CM_DIGEST_SHA384 | 5 | SHA-384.| 47| CM_DIGEST_SHA512 | 6 | SHA-512.| 48| CM_DIGEST_SM3<sup>18+</sup> | 7 | SM3.| 49 50## CmKeyPadding 51 52Enumerates the padding modes that can be used for signing and signature verification. 53 54**System capability**: System SystemCapability.Security.CertificateManager 55 56| Name | Value| Description | 57| ---------- | ------ | --------- | 58| CM_PADDING_NONE | 0 | No padding.| 59| CM_PADDING_PSS | 1 | PSS.| 60| CM_PADDING_PKCS1_V1_5 | 2 | PKCS1-V1_5.| 61 62## CMSignatureSpec 63 64Represents a set of parameters used for signing or signature verification, including the key usage purpose, padding mode, and digest algorithm. 65 66**System capability**: System SystemCapability.Security.CertificateManager 67 68| Name | Type | Read-Only| Optional| Description | 69| -------------- | --------------------------------- | ---- | ------------------------------------------------------------ | ------------------------------------------------------------ | 70| purpose | [CmKeyPurpose](#cmkeypurpose) | No | No | Purpose of using the key.| 71| padding | [CmKeyPadding](#cmkeypadding) | No | Yes | Padding mode.| 72| digest | [CmKeyDigest](#cmkeydigest) | No | Yes | Digest algorithm.| 73 74 75## CertInfo 76 77Represents detailed information about a certificate. 78 79**System capability**: System SystemCapability.Security.CertificateManager 80 81| Name | Type | Read-Only| Optional| Description | 82| -------------- | --------------------------------- | ---- | ---- | ------------------------------------------------------------ | 83| uri | string | No | No | Unique identifier of a certificate. The value contains up to 256 bytes.| 84| certAlias | string | No | No | Alias of a certificate. The value contains up to 128 bytes.| 85| state | boolean | No | No | Certificate state. The value **true** indicates that the certificate is enabled, and **false** means the opposite.| 86| issuerName | string | No | No | Name of the certificate issuer. The value contains up to 256 bytes.| 87| subjectName | string | No | No | Name of the certificate subject. The value contains up to 1024 bytes.| 88| serial | string | No | No | Serial number of a certificate. The value contains up to 64 bytes.| 89| notBefore | string | No | No | Start date of a certificate. The value contains up to 32 bytes.| 90| notAfter | string | No | No | Expiry date of a certificate. The value contains up to 32 bytes.| 91| fingerprintSha256 | string | No | No | Fingerprint of a certificate. The value contains up to 128 bytes.| 92| cert | Uint8Array | No | No | Binary data of a certificate. The value contains up to 8196 bytes.| 93 94## CertAbstract 95 96Represents brief information about a certificate. 97 98**System capability**: System SystemCapability.Security.CertificateManager 99 100| Name | Type | Read-Only| Optional| Description | 101| -------------- | --------------------------------- | ---- | ---- | ------------------------------------------------------------ | 102| uri | string | No | No | Unique identifier of a certificate. The value contains up to 256 bytes.| 103| certAlias | string | No | No | Alias of a certificate. The value contains up to 128 bytes.| 104| state | boolean | No | No | Certificate state. The value **true** indicates that the certificate is enabled, and **false** means the opposite.| 105| subjectName | string | No | No | Name of the certificate subject. The value contains up to 1024 bytes.| 106 107## Credential 108 109Represents detailed information about a credential. 110 111**System capability**: System SystemCapability.Security.CertificateManager 112 113| Name | Type | Read-Only| Optional| Description | 114| -------------- | --------------------------------- | ---- | ---- | ------------------------------------------------------------ | 115| type | string | No | No | Type of a credential. The value contains up to 8 bytes.| 116| alias | string | No | No | Alias of a credential. The value contains up to 128 bytes.| 117| keyUri | string | No | No | Unique identifier of a credential. The value contains up to 256 bytes.| 118| certNum | number | No | No | Number of certificates contained in the credential.| 119| keyNum | number | No | No | Number of keys contained in the credential.| 120| credentialData | Uint8Array | No | No | Binary data of a credential. The value contains up to 20480 bytes.| 121 122## CredentialAbstract 123 124Represents brief information about a credential. 125 126**System capability**: System SystemCapability.Security.CertificateManager 127 128| Name | Type | Read-Only| Optional| Description | 129| -------------- | --------------------------------- | ---- | ---- | ------------------------------------------------------------ | 130| type | string | No| No | Type of a credential. The value contains up to 8 bytes.| 131| alias | string | No | No | Alias of a credential. The value contains up to 128 bytes.| 132| keyUri | string | No | No | Unique identifier of a credential. The value contains up to 256 bytes.| 133 134## CMResult 135 136Represents the result returned. 137 138**System capability**: System SystemCapability.Security.CertificateManager 139 140| Name | Type | Read-Only| Optional| Description | 141| -------------- | --------------------------------- | ---- | ---- | ------------------------------------------------------------ | 142| certList | Array<[CertAbstract](#certabstract)> | No | Yes | Brief certificate information.| 143| certInfo | [CertInfo](#certinfo) | No | Yes | Detailed certificate information.| 144| credentialList | Array<[CredentialAbstract](#credentialabstract)> | No | Yes | Brief credential information.| 145| credential | [Credential](#credential) | No | Yes | Detailed credential information.| 146| appUidList | Array\<string> | No | Yes | List of authorized applications.| 147| uri | string | No | Yes | Unique identifier of a certificate or credential. The value contains up to 256 bytes.| 148| outData | Uint8Array | No | Yes | Signature generated.| 149 150## CMHandle 151 152Represents the handle to a signing or signature verification operation. 153 154**System capability**: System SystemCapability.Security.CertificateManager 155 156| Name | Type | Read-Only| Optional| Description | 157| -------------- | --------------------------------- | ---- | ---- | ------------------------------------------------------------ | 158| handle | Uint8Array | No | No | Handle of the initialization for signing and signature verification. The value contains up to 8 bytes.| 159 160## CMErrorCode 161 162Enumerates the error codes used in the certificate management APIs. 163 164**System capability**: System SystemCapability.Security.CertificateManager 165 166| Name | Value| Description | 167| ---------- | ------ | --------- | 168| CM_ERROR_NO_PERMISSION | 201 | The application does not have the permission to call the API.| 169| CM_ERROR_INVALID_PARAMS | 401 | Invalid input parameter is found.| 170| CM_ERROR_GENERIC | 17500001 | An internal error occurs when the interface is called.| 171| CM_ERROR_NO_FOUND | 17500002 | The certificate or credential does not exist.| 172| CM_ERROR_INCORRECT_FORMAT | 17500003 | The certificate or credential is in invalid format.| 173| CM_ERROR_MAX_CERT_COUNT_REACHED<sup>12+</sup> | 17500004 | The number of certificates or credentials has reached the limit.| 174| CM_ERROR_NO_AUTHORIZATION<sup>12+</sup> | 17500005 | The application has not obtained user authorization.| 175| CM_ERROR_DEVICE_ENTER_ADVSECMODE<sup>18+</sup> | 17500007 | The device enters the advanced security mode.| 176| CM_ERROR_STORE_PATH_NOT_SUPPORTED<sup>20+</sup> | 17500009 | The device does not support the specified certificate storage path. | 177 178## CertType<sup>18+</sup> 179 180Enumerates the certificate types. 181 182**System capability**: System SystemCapability.Security.CertificateManager 183 184| Name | Value| Description | 185| ---------- | ------ | --------- | 186| CA_CERT_SYSTEM | 0 | System CA certificate.| 187| CA_CERT_USER | 1 | User CA certificate.| 188 189## CertScope<sup>18+</sup> 190 191Enumerates the certificate scopes. 192 193**System capability**: System SystemCapability.Security.CertificateManager 194 195| Name | Value| Description | 196| ---------- | ------ | --------- | 197| CURRENT_USER | 1 | The certificate is accessible only to the current user.| 198| GLOBAL_USER | 2 | The certificate is accessible to all users.| 199 200## CertAlgorithm<sup>20+</sup> 201 202Enumerates the certificate algorithms. 203 204**System capability**: System SystemCapability.Security.CertificateManager 205 206| Name | Value| Description | 207|---------------| ------ |--------------------------| 208| INTERNATIONAL | 1 | International cryptographic algorithm, such as RSA and NIST ECC.| 209| SM | 2 | Commercial cryptographic algorithm, such as SM2 and SM4. | 210 211## CertStoreProperty<sup>18+</sup> 212 213Represents the storage information about a certificate, including the certificate type and location. 214 215**System capability**: System SystemCapability.Security.CertificateManager 216 217| Name | Type | Read-Only| Optional| Description | 218|-----------|-----------------------------------| ---- | ------------------------------------------------------------ |---------------------------------------------| 219| certType | [CertType](#certtype18) | No | No | Type of the certificate. | 220| certScope | [CertScope](#certscope18) | No | Yes | Scope of the certificate. This parameter is mandatory when **certType** is **CA_CERT_USER**. | 221| certAlg<sup>20+</sup> | [CertAlgorithm](#certalgorithm20) | No | Yes | Certificate algorithm. This parameter is valid only when **certType** is set to **CA_CERT_SYSTEM**. The default value is **INTERNATIONAL**.| 222 223## AuthStorageLevel<sup>18+</sup> 224 225Enumerates the credential storage levels. 226 227**System capability**: System SystemCapability.Security.CertificateManager 228 229| Name | Value | Description | 230| ------------ | ---- | ------------------------------------------ | 231| EL1 | 1 | The credential can be accessed after the device is started. | 232| EL2 | 2 | The credential can be accessed after the device is unlocked for the first time. | 233| EL4 | 4 | The credential can be accessed after the device is unlocked. | 234 235## certificateManager.installPrivateCertificate 236 237installPrivateCertificate(keystore: Uint8Array, keystorePwd: string, certAlias: string, callback: AsyncCallback\<CMResult>): void 238 239Installs a private credential. This API uses an asynchronous callback to return the result. 240 241**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 242 243**System capability**: System SystemCapability.Security.CertificateManager 244 245**Parameters** 246 247| Name | Type | Mandatory| Description | 248| -------- | ------------------------------------------------- | ---- | -------------------------- | 249| keystore | Uint8Array | Yes | Keystore file with a key pair and certificate. The value contains up to 20480 bytes.| 250| keystorePwd | string | Yes | Password of the keystore file. The password cannot exceed 32 bytes.| 251| certAlias | string | Yes | Credential alias. Currently, the alias can contain only digits, letters, and underscores (_) and should not exceed 32 bytes.| 252| callback | AsyncCallback\<[CMResult](#cmresult)> | Yes | Callback used to return the result. If the operation is successful, **err** is **null** and **data** is **uri** in the [CMResult](#cmresult) object. Otherwise, **err** is an error object.| 253 254**Error codes** 255 256For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 257 258| ID| Error Message | 259| -------- | ------------------------------------------------------------ | 260| 201 | Permission verification failed. The application does not have the permission required to call the API. | 261| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 262| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 263| 17500003 | The keystore is in an invalid format or the keystore password is incorrect. | 264| 17500004 | The number of certificates or credentials reaches the maximum allowed. | 265 266**Example** 267```ts 268import { certificateManager } from '@kit.DeviceCertificateKit'; 269 270/* The credential data to be installed must be assigned by the service. The data in this example is not the real credential data. */ 271let keystore: Uint8Array = new Uint8Array([ 272 0x30, 0x82, 0x0b, 0xc1, 0x02, 0x01, 273]); 274let keystorePwd: string = "123456"; 275try { 276 certificateManager.installPrivateCertificate(keystore, keystorePwd, "test", (err, cmResult) => { 277 if (err != null) { 278 console.error(`Failed to install private certificate. Code: ${err.code}, message: ${err.message}`); 279 } else { 280 let uri: string = (cmResult?.uri == undefined) ? '' : cmResult.uri; 281 console.info('Succeeded in installing private certificate.'); 282 } 283 }); 284} catch (error) { 285 console.error(`Failed to install private certificate. Code: ${error.code}, message: ${error.message}`); 286} 287``` 288 289## certificateManager.installPrivateCertificate 290 291installPrivateCertificate(keystore: Uint8Array, keystorePwd: string, certAlias: string): Promise\<CMResult> 292 293Installs a private credential. This API uses a promise to return the result. 294 295**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 296 297**System capability**: System SystemCapability.Security.CertificateManager 298 299**Parameters** 300 301| Name | Type | Mandatory| Description | 302| -------- | ------------------------------------------------- | ---- | -------------------------- | 303| keystore | Uint8Array | Yes | Keystore file with a key pair and certificate. The value contains up to 20480 bytes.| 304| keystorePwd | string | Yes | Password of the keystore file. The password cannot exceed 32 bytes.| 305| certAlias | string | Yes | Credential alias. Currently, the alias can contain only digits, letters, and underscores (_) and should not exceed 32 bytes.| 306 307**Return value** 308 309| Type | Description | 310| ------------------------------- | ------------------------------------------------------------ | 311| Promise\<[CMResult](#cmresult)> | Promise used to return the operation result, that is, **uri** in the [CMResult](#cmresult) object.| 312 313**Error codes** 314 315For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 316 317| ID| Error Message | 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| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 322| 17500003 | The keystore is in an invalid format or the keystore password is incorrect. | 323| 17500004 | The number of certificates or credentials reaches the maximum allowed. | 324 325**Example** 326 327```ts 328import { certificateManager } from '@kit.DeviceCertificateKit'; 329import { BusinessError } from '@kit.BasicServicesKit'; 330 331/* The credential data to be installed must be assigned by the service. The data in this example is not the real credential data. */ 332let keystore: Uint8Array = new Uint8Array([ 333 0x30, 0x82, 0x0b, 0xc1, 0x02, 0x01, 334]); 335let keystorePwd: string = "123456"; 336try { 337 certificateManager.installPrivateCertificate(keystore, keystorePwd, 'test').then((cmResult) => { 338 let uri: string = (cmResult?.uri == undefined) ? '' : cmResult.uri; 339 console.info('Succeeded in installing private certificate.'); 340 }).catch((err: BusinessError) => { 341 console.error(`Failed to install private certificate. Code: ${err.code}, message: ${err.message}`); 342 }) 343} catch (error) { 344 console.error(`Failed to install private certificate. Code: ${error.code}, message: ${error.message}`); 345} 346``` 347 348## certificateManager.installPrivateCertificate<sup>18+</sup> 349 350installPrivateCertificate(keystore: Uint8Array, keystorePwd: string, certAlias: string, level: AuthStorageLevel): Promise\<CMResult> 351 352Installs a private credential and specifies its storage level. This API uses a promise to return the result. 353 354**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 355 356**System capability**: System SystemCapability.Security.CertificateManager 357 358**Parameters** 359 360| Name | Type | Mandatory| Description | 361| ----------- | ---------- | ---- | ------------------------------------------------------------ | 362| keystore | Uint8Array | Yes | Keystore file with a key pair and certificate. The value contains up to 20480 bytes. | 363| keystorePwd | string | Yes | Password of the keystore file.<br>The value contains up to 32 bytes. | 364| certAlias | string | Yes | Alias of the credential entered by the user. Only digits, letters, and underscores (_) are supported.<br>The value should contain up to 32 bytes.| 365| level | [AuthStorageLevel](#authstoragelevel18) | Yes | Credential storage level.| 366 367**Return value** 368 369| Type | Description | 370| ------------------------------- | ------------------------------------------------------------ | 371| Promise\<[CMResult](#cmresult)> | Promise used to return the operation result, that is, **uri** in the [CMResult](#cmresult) object.| 372 373**Error codes** 374 375For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 376 377| ID | Error Message | 378| ---------------------- | ------------------------------------------------------------ | 379| 201 | Permission verification failed. The application does not have the permission required to call the API. | 380| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 381| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 382| 17500003 | The keystore is in an invalid format or the keystore password is incorrect. | 383| 17500004 | The number of certificates or credentials reaches the maximum allowed. | 384 385**Example** 386 387```ts 388import { certificateManager } from '@kit.DeviceCertificateKit'; 389import { BusinessError } from '@kit.BasicServicesKit'; 390 391/* The data of the credential to be installed must be assigned based on the service. The data in this example is not the real credential data. */ 392let keystore: Uint8Array = new Uint8Array([ 393 0x30, 0x82, 0x0b, 0xc1, 0x02, 0x01, 394]); 395let keystorePwd: string = "123456"; 396try { 397 /* The credential can be used after the device is unlocked for the first time. */ 398 let level = certificateManager.AuthStorageLevel.EL2; 399 certificateManager.installPrivateCertificate(keystore, keystorePwd, 'test', level).then((cmResult) => { 400 let uri: string = (cmResult?.uri == undefined) ? '' : cmResult.uri; 401 console.info('Succeeded in installing private certificate.'); 402 }).catch((err: BusinessError) => { 403 console.error(`Failed to install private certificate. Code: ${err.code}, message: ${err.message}`); 404 }) 405} catch (error) { 406 console.error(`Failed to install private certificate. Code: ${error.code}, message: ${error.message}`); 407} 408``` 409 410## certificateManager.getPrivateCertificate 411 412getPrivateCertificate(keyUri: string, callback: AsyncCallback\<CMResult>): void 413 414Obtains detailed information about a private credential. This API uses an asynchronous callback to return the result. 415 416**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 417 418**System capability**: System SystemCapability.Security.CertificateManager 419 420**Parameters** 421 422| Name | Type | Mandatory| Description | 423| -------- | ------------------------------------------------- | ---- | -------------------------- | 424| keyUri | string | Yes | Unique identifier of the credential to be obtained. The value contains up to 256 bytes.| 425| callback | AsyncCallback\<[CMResult](#cmresult)> | Yes | Callback used to return the result. If the operation is successful, **err** is **null** and **data** is **credential** in the [CMResult](#cmresult) object. Otherwise, **err** is an error object.| 426 427**Error codes** 428 429For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 430 431| ID| Error Message | 432| -------- | ------------- | 433| 201 | Permission verification failed. The application does not have the permission required to call the API. | 434| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 435| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 436| 17500002 | The certificate does not exist. | 437 438**Example** 439```ts 440import { certificateManager } from '@kit.DeviceCertificateKit'; 441 442let uri: string = 'test'; /* The service needs to use the unique identifier of the credential to obtain the private credential details, which is not elaborated here. */ 443try { 444 certificateManager.getPrivateCertificate(uri, (err, cmResult) => { 445 if (err != null) { 446 console.error(`Failed to get private certificate. Code: ${err.code}, message: ${err.message}`); 447 } else { 448 if (cmResult?.credential == undefined) { 449 console.info('The result of getting private certificate is undefined.'); 450 } else { 451 let list = cmResult.credential; 452 console.info('Succeeded in getting private certificate.'); 453 } 454 } 455 }); 456} catch (error) { 457 console.error(`Failed to get private certificate. Code: ${error.code}, message: ${error.message}`); 458} 459``` 460 461## certificateManager.getPrivateCertificate 462 463getPrivateCertificate(keyUri: string): Promise\<CMResult> 464 465Obtains detailed information about a private credential. This API uses a promise to return the result. 466 467**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 468 469**System capability**: System SystemCapability.Security.CertificateManager 470 471**Parameters** 472 473| Name | Type | Mandatory| Description | 474| -------- | ------------------------------------------------- | ---- | -------------------------- | 475| keyUri | string | Yes | Unique identifier of the credential to be obtained. The value contains up to 256 bytes.| 476 477**Return value** 478 479| Type | Description | 480| ------------------------------- | ------------------------------------------------------------ | 481| Promise\<[CMResult](#cmresult)> | Promise used to return the private credential details obtained, that is, **credential** in the [CMResult](#cmresult) object.| 482 483**Error codes** 484 485For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 486 487| ID| Error Message | 488| -------- | ------------- | 489| 201 | Permission verification failed. The application does not have the permission required to call the API. | 490| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 491| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 492| 17500002 | The certificate does not exist. | 493 494**Example** 495```ts 496import { certificateManager } from '@kit.DeviceCertificateKit'; 497import { BusinessError } from '@kit.BasicServicesKit'; 498 499let uri: string = 'test'; /* The service needs to use the unique identifier of the credential to obtain the private credential details, which is not elaborated here. */ 500try { 501 certificateManager.getPrivateCertificate(uri).then((cmResult) => { 502 if (cmResult?.credential == undefined) { 503 console.info('The result of getting private certificate is undefined.'); 504 } else { 505 let list = cmResult.credential; 506 console.info('Succeeded in getting private certificate.'); 507 } 508 }).catch((err: BusinessError) => { 509 console.error(`Failed to get private certificate. Code: ${err.code}, message: ${err.message}`); 510 }) 511} catch (error) { 512 console.error(`Failed to get private certificate. Code: ${error.code}, message: ${error.message}`); 513} 514``` 515 516## certificateManager.uninstallPrivateCertificate 517 518uninstallPrivateCertificate(keyUri: string, callback: AsyncCallback\<void>): void 519 520Uninstalls a private credential. This API uses an asynchronous callback to return the result. 521 522**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 523 524**System capability**: System SystemCapability.Security.CertificateManager 525 526**Parameters** 527 528| Name | Type | Mandatory| Description | 529| -------- | ------------------------------------------------- | ---- | -------------------------- | 530| keyUri | string | Yes | Unique identifier of the credential to be uninstalled. The value contains up to 256 bytes.| 531| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| 532 533**Error codes** 534 535For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 536 537| ID| Error Message | 538| -------- | ------------- | 539| 201 | Permission verification failed. The application does not have the permission required to call the API. | 540| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 541| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 542| 17500002 | The certificate does not exist. | 543 544**Example** 545```ts 546import { certificateManager } from '@kit.DeviceCertificateKit'; 547 548let uri: string = 'test'; /* The service needs to use the unique identifier of the credential to delete the private credential, which is not elaborated here. */ 549try { 550 certificateManager.uninstallPrivateCertificate(uri, (err, result) => { 551 if (err != null) { 552 console.error(`Failed to uninstall private certificate. Code: ${err.code}, message: ${err.message}`); 553 } else { 554 console.info('Succeeded in uninstalling private certificate.'); 555 } 556 }); 557} catch (error) { 558 console.error(`Failed to uninstall private certificate. Code: ${error.code}, message: ${error.message}`); 559} 560``` 561 562## certificateManager.uninstallPrivateCertificate 563 564uninstallPrivateCertificate(keyUri: string): Promise\<void> 565 566Uninstalls a private credential. This API uses a promise to return the result. 567 568**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 569 570**System capability**: System SystemCapability.Security.CertificateManager 571 572**Parameters** 573 574| Name | Type | Mandatory| Description | 575| -------- | ------------------------------------------------- | ---- | -------------------------- | 576| keyUri | string | Yes | Unique identifier of the credential to be uninstalled. The value contains up to 256 bytes.| 577 578**Return value** 579 580| Type | Description | 581| ------------------------------------------- | -------------------- | 582| Promise\<void> | Promise that returns no value.| 583 584**Error codes** 585 586For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 587 588| ID| Error Message | 589| -------- | ------------- | 590| 201 | Permission verification failed. The application does not have the permission required to call the API. | 591| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 592| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 593| 17500002 | The certificate does not exist. | 594 595**Example** 596```ts 597import { certificateManager } from '@kit.DeviceCertificateKit'; 598import { BusinessError } from '@kit.BasicServicesKit'; 599 600let uri: string = 'test'; /* The service needs to use the unique identifier of the credential to delete the private credential, which is not elaborated here. */ 601try { 602 certificateManager.uninstallPrivateCertificate(uri).then((cmResult) => { 603 console.info('Succeeded in uninstalling private certificate.'); 604 }).catch((err: BusinessError) => { 605 console.error(`Failed to uninstall private certificate. Code: ${err.code}, message: ${err.message}`); 606 }) 607} catch (error) { 608 console.error(`Failed to uninstall private certificate. Code: ${error.code}, message: ${error.message}`); 609} 610``` 611 612## certificateManager.installUserTrustedCertificateSync<sup>18+</sup> 613 614installUserTrustedCertificateSync(cert: Uint8Array, certScope: CertScope) : CMResult 615 616Installs a user CA certificate. 617 618**Required permissions**: ohos.permission.ACCESS_ENTERPRISE_USER_TRUSTED_CERT<!--Del--> or ohos.permission.ACCESS_USER_TRUSTED_CERT<!--DelEnd--> 619 620**System capability**: System SystemCapability.Security.CertificateManager 621 622**Parameters** 623 624| Name | Type | Mandatory| Description | 625|-----------|----------------------------|----|--------------| 626| cert | Uint8Array | Yes | CA certificate data. The value contains up to 8196 bytes. | 627| certScope | [CertScope](#certscope18) | Yes | Scope of the CA certificate.| 628 629**Return value** 630 631| Type | Description | 632|-----------------------|-----------------------------------| 633| [CMResult](#cmresult) | CA certificate installation result. The **uri** property in **CMResult** is returned if the certificate is installed successfully.| 634 635**Error codes** 636 637For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 638 639| ID | Error Message | 640|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| 641| 201 | Permission verification failed. The application does not have the permission required to call the API. | 642| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 643| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 644| 17500003 | Indicates that the certificate is in an invalid format. | 645| 17500004 | Indicates that the number of certificates reaches the maximum allowed. | 646| 17500007 | Indicates that the device enters advanced security mode. In this mode, the user CA certificate cannot be installed. | 647 648**Example** 649 650```ts 651import {certificateManager} from '@kit.DeviceCertificateKit'; 652 653/* The CA certificate data must be assigned by the service. In this example, the data is not CA certificate data. */ 654let certData: Uint8Array = new Uint8Array([ 655 0x30, 0x82, 0x0b, 0xc1, 0x02, 0x01, 656]); 657try { 658 let result: certificateManager.CMResult = certificateManager.installUserTrustedCertificateSync(certData, certificateManager.CertScope.CURRENT_USER); 659 let certUri = result.uri; 660 if (certUri === undefined) { 661 console.error("The result of install user trusted certificate is undefined."); 662 } else { 663 console.info("Successed to install user trusted certificate."); 664 } 665} catch (error) { 666 console.error(`Failed to install user trusted certificate. Code: ${error.code}, message: ${error.message}`); 667} 668``` 669 670## certificateManager.uninstallUserTrustedCertificateSync<sup>18+</sup> 671 672uninstallUserTrustedCertificateSync(certUri: string) : void 673 674Uninstalls a user CA certificate. 675 676**Required permissions**: ohos.permission.ACCESS_ENTERPRISE_USER_TRUSTED_CERT<!--Del--> or ohos.permission.ACCESS_USER_TRUSTED_CERT<!--DelEnd--> 677 678**System capability**: System SystemCapability.Security.CertificateManager 679 680**Parameters** 681 682| Name | Type | Mandatory| Description | 683|-----------|----------------------------|----|--------------| 684| certUri | string | Yes | Unique identifier of the certificate to be uninstalled. The value contains up to 256 bytes. | 685 686**Error codes** 687 688For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 689 690| ID | Error Message | 691|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| 692| 201 | Permission verification failed. The application does not have the permission required to call the API. | 693| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 694| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 695| 17500002 | Indicates that the certificate does not exist. | 696 697**Example** 698 699```ts 700import {certificateManager} from '@kit.DeviceCertificateKit'; 701 702let certUri: string = "test"; /* The service needs to use the certificate identifier to delete the certificate, which is not elaborated here. */ 703try { 704 certificateManager.uninstallUserTrustedCertificateSync(certUri); 705} catch (error) { 706 console.error(`Failed to uninstall user trusted certificate. Code: ${error.code}, message: ${error.message}`); 707} 708``` 709 710## certificateManager.init 711 712init(authUri: string, spec: CMSignatureSpec, callback: AsyncCallback\<CMHandle>): void 713 714Initializes the signing or signature verification operation using the specified credential. This API uses an asynchronous callback to return the result. 715 716**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 717 718**System capability**: System SystemCapability.Security.CertificateManager 719 720**Parameters** 721 722| Name | Type | Mandatory| Description | 723| -------- | ------------------------------------------------- | ---- | -------------------------- | 724| authUri | string | Yes | Unique identifier of the credential to be used. The value contains up to 256 bytes.| 725| spec | [CMSignatureSpec](#cmsignaturespec) | Yes | Parameters for the signing or signature verification operation.| 726| callback | AsyncCallback\<[CMHandle](#cmhandle)> | Yes | Callback used to return the result. If the operation is successful, **err** is **null** and **data** is the obtained **CMHandle**. Otherwise, **err** is an error object.| 727 728**Error codes** 729 730For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 731 732| ID| Error Message | 733| -------- | ------------- | 734| 201 | Permission verification failed. The application does not have the permission required to call the API. | 735| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 736| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 737| 17500002 | The certificate does not exist. | 738| 17500005<sup>12+</sup> | The application is not authorized by the user. | 739 740**Example** 741```ts 742import { certificateManager } from '@kit.DeviceCertificateKit'; 743 744let uri: string = 'test'; /* The service needs to use the unique identifier of the credential to initialize signing and signature verification, which is not elaborated here. */ 745const req: certificateManager.CMSignatureSpec = { 746 purpose: certificateManager.CmKeyPurpose.CM_KEY_PURPOSE_SIGN, 747 padding: certificateManager.CmKeyPadding.CM_PADDING_PSS, 748 digest: certificateManager.CmKeyDigest.CM_DIGEST_SHA256 749} 750try { 751 certificateManager.init(uri, req, (err, cmHandle) => { 752 if (err != null) { 753 console.error(`Failed to init. Code: ${err.code}, message: ${err.message}`); 754 } else { 755 console.info('Succeeded in initiating.'); 756 } 757 }) 758} catch (error) { 759 console.error(`Failed to init. Code: ${error.code}, message: ${error.message}`); 760} 761``` 762 763## certificateManager.init 764 765init(authUri: string, spec: CMSignatureSpec): Promise\<CMHandle> 766 767Initializes the signing or signature verification operation using the specified credential. This API uses a promise to return the result. 768 769**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 770 771**System capability**: System SystemCapability.Security.CertificateManager 772 773**Parameters** 774 775| Name | Type | Mandatory| Description | 776| -------- | ------------------------------------------------- | ---- | -------------------------- | 777| authUri | string | Yes | Unique identifier of the credential to be used. The value contains up to 256 bytes.| 778| spec | [CMSignatureSpec](#cmsignaturespec) | Yes | Parameters for the signing or signature verification operation.| 779 780**Return value** 781 782| Type | Description | 783| ------------------------------------------- | -------------------- | 784| Promise\<[CMHandle](#cmhandle)> | Promise used to return a **CMHandle** object.| 785 786**Error codes** 787 788For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 789 790| ID| Error Message | 791| -------- | ------------- | 792| 201 | Permission verification failed. The application does not have the permission required to call the API. | 793| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 794| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 795| 17500002 | The certificate does not exist. | 796| 17500005<sup>12+</sup> | The application is not authorized by the user. | 797 798**Example** 799```ts 800import { certificateManager } from '@kit.DeviceCertificateKit'; 801import { BusinessError } from '@kit.BasicServicesKit'; 802 803let uri: string = 'test'; /* The service needs to use the unique identifier of the credential to initialize signing and signature verification, which is not elaborated here. */ 804const req: certificateManager.CMSignatureSpec = { 805 purpose: certificateManager.CmKeyPurpose.CM_KEY_PURPOSE_VERIFY, 806 padding: certificateManager.CmKeyPadding.CM_PADDING_PSS, 807 digest: certificateManager.CmKeyDigest.CM_DIGEST_MD5 808} 809try { 810 certificateManager.init(uri, req).then((handle) => { 811 console.info('Succeeded in initiating.'); 812 }).catch((err: BusinessError) => { 813 console.error(`Failed to init. Code: ${err.code}, message: ${err.message}`); 814 }) 815} catch (error) { 816 console.error(`Failed to init. Code: ${error.code}, message: ${error.message}`); 817} 818``` 819 820## certificateManager.update 821 822update(handle: Uint8Array, data: Uint8Array, callback: AsyncCallback\<void>): void 823 824Updates the data for the signing or signature verification operation. This API uses an asynchronous callback to return the result. 825 826**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 827 828**System capability**: System SystemCapability.Security.CertificateManager 829 830**Parameters** 831 832| Name | Type | Mandatory| Description | 833| -------- | ------------------------------------------------- | ---- | -------------------------- | 834| handle | Uint8Array | Yes | Handle of initialization. The value contains up to 8 bytes.| 835| data | Uint8Array | Yes | Data to be signed or verified.| 836| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| 837 838**Error codes** 839 840For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 841 842| ID| Error Message | 843| -------- | ------------------------------------------------------------ | 844| 201 | Permission verification failed. The application does not have the permission required to call the API. | 845| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 846| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 847 848**Example** 849```ts 850import { certificateManager } from '@kit.DeviceCertificateKit'; 851 852/* cmHandle is the value returned by init(). The value here is only an example. */ 853let cmHandle: Uint8Array = new Uint8Array([ 854 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08 855]); 856let srcData: Uint8Array = new Uint8Array([ 857 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08 858]); 859try { 860 certificateManager.update(cmHandle, srcData, (err, result) => { 861 if (err != null) { 862 console.error(`Failed to update. Code: ${err.code}, message: ${err.message}`); 863 } else { 864 console.info('Succeeded in updating.'); 865 } 866 }); 867} catch (error) { 868 console.error(`Failed to update. Code: ${error.code}, message: ${error.message}`); 869} 870``` 871 872## certificateManager.update 873 874update(handle: Uint8Array, data: Uint8Array): Promise\<void> 875 876Updates the data for the signing or signature verification operation. This API uses a promise to return the result. 877 878**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 879 880**System capability**: System SystemCapability.Security.CertificateManager 881 882**Parameters** 883 884| Name | Type | Mandatory| Description | 885| -------- | ------------------------------------------------- | ---- | -------------------------- | 886| handle | Uint8Array | Yes | Handle of initialization. The value contains up to 8 bytes.| 887| data | Uint8Array | Yes | Data to be signed or verified.| 888 889**Return value** 890 891| Type | Description | 892| ------------------------------------------- | -------------------- | 893| Promise\<void> | Promise that returns no value.| 894 895**Error codes** 896 897For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 898 899| ID| Error Message | 900| -------- | ------------------------------------------------------------ | 901| 201 | Permission verification failed. The application does not have the permission required to call the API. | 902| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 903| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 904 905**Example** 906```ts 907import { certificateManager } from '@kit.DeviceCertificateKit'; 908import { BusinessError } from '@kit.BasicServicesKit'; 909 910/* cmHandle is the value returned by init(). The value here is only an example. */ 911let cmHandle: Uint8Array = new Uint8Array([ 912 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08 913]); 914let srcData: Uint8Array = new Uint8Array([ 915 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08 916]); 917try { 918 certificateManager.update(cmHandle, srcData).then((result) => { 919 console.info('Succeeded in updating.'); 920 }).catch((err: BusinessError) => { 921 console.error(`Failed to update. Code: ${err.code}, message: ${err.message}`); 922 }) 923} catch (error) { 924 console.error(`Failed to update. Code: ${error.code}, message: ${error.message}`); 925} 926``` 927 928## certificateManager.finish 929 930finish(handle: Uint8Array, callback: AsyncCallback\<CMResult>): void 931 932Finishes the signing operation. This API uses an asynchronous callback to return the result. 933 934**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 935 936**System capability**: System SystemCapability.Security.CertificateManager 937 938**Parameters** 939 940| Name | Type | Mandatory| Description | 941| -------- | ------------------------------------------------- | ---- | -------------------------- | 942| handle | Uint8Array | Yes | Handle of initialization. The value contains up to 8 bytes.| 943| callback | AsyncCallback\<[CMResult](#cmresult)> | Yes | Callback used to return the result. If the operation is successful, **err** is **null** and **data** is the signature, that is, **outData** of the [CMResult](#cmresult) object. Otherwise, **err** is an error object.| 944 945**Error codes** 946 947For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 948 949| ID| Error Message | 950| -------- | ------------------------------------------------------------ | 951| 201 | Permission verification failed. The application does not have the permission required to call the API. | 952| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 953| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 954 955**Example** 956```ts 957import { certificateManager } from '@kit.DeviceCertificateKit'; 958 959/* cmHandle is the value returned by init(). The value here is only an example. */ 960let cmHandle: Uint8Array = new Uint8Array([ 961 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08 962]); 963try { 964 certificateManager.finish(cmHandle, (err, cmResult) => { 965 if (err != null) { 966 console.error(`Failed to finish. Code: ${err.code}, message: ${err.message}`); 967 } else { 968 if (cmResult?.outData != undefined) { 969 let signRes: Uint8Array = cmResult.outData; 970 console.info('Succeeded in finishing.'); 971 } else { 972 console.info('The result of finishing is undefined.'); 973 } 974 } 975 }); 976} catch(error) { 977 console.error(`Failed to finish. Code: ${error.code}, message: ${error.message}`); 978} 979``` 980 981## certificateManager.finish 982 983finish(handle: Uint8Array, signature: Uint8Array, callback: AsyncCallback\<CMResult>): void 984 985Finishes the signature verification operation. This API uses an asynchronous callback to return the result. 986 987**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 988 989**System capability**: System SystemCapability.Security.CertificateManager 990 991**Parameters** 992 993| Name | Type | Mandatory| Description | 994| -------- | ------------------------------------------------- | ---- | -------------------------- | 995| handle | Uint8Array | Yes | Handle of initialization. The value contains up to 8 bytes.| 996| signature | Uint8Array | Yes | Data to sign or verify.| 997| callback | AsyncCallback\<[CMResult](#cmresult)> | Yes | Callback used to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| 998 999**Error codes** 1000 1001For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 1002 1003| ID| Error Message | 1004| -------- | ------------------------------------------------------------ | 1005| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1006| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1007| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 1008 1009**Example** 1010```ts 1011import { certificateManager } from '@kit.DeviceCertificateKit'; 1012 1013/* cmHandle is the value returned by init(). The value here is only an example. */ 1014let cmHandle: Uint8Array = new Uint8Array([ 1015 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08 1016]); 1017let signRes: Uint8Array = new Uint8Array([ 1018 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08 1019]); 1020try { 1021 certificateManager.finish(cmHandle, signRes, (err, cmResult) => { 1022 if (err != null) { 1023 console.error(`Failed to finish. Code: ${err.code}, message: ${err.message}`); 1024 } else { 1025 console.info('Succeeded in finishing.'); 1026 } 1027 }); 1028} catch(error) { 1029 console.error(`Failed to finish. Code: ${error.code}, message: ${error.message}`); 1030} 1031``` 1032 1033## certificateManager.finish 1034 1035finish(handle: Uint8Array, signature?: Uint8Array): Promise\<CMResult> 1036 1037Finishes the signing or signature verification operation. This API uses a promise to return the result. 1038 1039**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 1040 1041**System capability**: System SystemCapability.Security.CertificateManager 1042 1043**Parameters** 1044 1045| Name | Type | Mandatory| Description | 1046| -------- | ------------------------------------------------- | ---- | -------------------------- | 1047| handle | Uint8Array | Yes | Handle of initialization. The value contains up to 8 bytes.| 1048| signature | Uint8Array | No | Data to sign or verify.| 1049 1050**Return value** 1051 1052| Type | Description | 1053| ------------------------------- | ------------------------------------------------------------ | 1054| Promise\<[CMResult](#cmresult)> | Promise used to return the signature of a signing operation, that is, **outData** in the [CMResult](#cmresult) object. For a signature verification operation, the promise returns no value.| 1055 1056**Error codes** 1057 1058For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 1059 1060| ID| Error Message | 1061| -------- | ------------------------------------------------------------ | 1062| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1063| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1064| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 1065 1066**Example** 1067```ts 1068import { certificateManager } from '@kit.DeviceCertificateKit'; 1069import { BusinessError } from '@kit.BasicServicesKit'; 1070 1071/* cmHandle is the value returned by init(). The value here is only an example. */ 1072let cmHandle: Uint8Array = new Uint8Array([ 1073 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08 1074]); 1075try { 1076 /* Finish the signing operation. */ 1077 certificateManager.finish(cmHandle).then((cmResult) => { 1078 if (cmResult?.outData != undefined) { 1079 let signRes1: Uint8Array = cmResult.outData; 1080 console.info('Succeeded in finishing signature.'); 1081 } else { 1082 console.info('The result of signature is undefined.'); 1083 } 1084 }).catch((err: BusinessError) => { 1085 console.error(`Failed to finish signature. Code: ${err.code}, message: ${err.message}`); 1086 }) 1087 1088 /* Signature generated. */ 1089 let signRes: Uint8Array = new Uint8Array([ 1090 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08 1091 ]); 1092 /* Finish the signature verification operation. */ 1093 certificateManager.finish(cmHandle, signRes).then((cmResult) => { 1094 console.info('Succeeded in finishing verification.'); 1095 }).catch((err: BusinessError) => { 1096 console.error(`Failed to finish verification. Code: ${err.code}, message: ${err.message}`); 1097 }) 1098} catch(error) { 1099 console.error(`Failed to finish. Code: ${error.code}, message: ${error.message}`); 1100} 1101``` 1102 1103## certificateManager.abort 1104 1105abort(handle: Uint8Array, callback: AsyncCallback\<void>): void 1106 1107Aborts the signing or signature verification operation. This API uses an asynchronous callback to return the result. 1108 1109**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 1110 1111**System capability**: System SystemCapability.Security.CertificateManager 1112 1113**Parameters** 1114 1115| Name | Type | Mandatory| Description | 1116| -------- | ------------------------------------------------- | ---- | -------------------------- | 1117| handle | Uint8Array | Yes | Handle of initialization. The value contains up to 8 bytes.| 1118| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| 1119 1120**Error codes** 1121 1122For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 1123 1124| ID| Error Message | 1125| -------- | ------------------------------------------------------------ | 1126| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1127| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1128| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 1129 1130**Example** 1131```ts 1132import { certificateManager } from '@kit.DeviceCertificateKit'; 1133 1134/* cmHandle is the value returned by init(). The value here is only an example. */ 1135let cmHandle: Uint8Array = new Uint8Array([ 1136 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08 1137]); 1138try { 1139 certificateManager.abort(cmHandle, (err, cmResult) => { 1140 if (err != null) { 1141 console.error(`Failed to abort. Code: ${err.code}, message: ${err.message}`); 1142 } else { 1143 console.info('Succeeded in aborting.'); 1144 } 1145 }); 1146} catch(error) { 1147 console.error(`Failed to abort. Code: ${error.code}, message: ${error.message}`); 1148} 1149``` 1150 1151## certificateManager.abort 1152 1153abort(handle: Uint8Array): Promise\<void> 1154 1155Aborts the signing or signature verification operation. This API uses a promise to return the result. 1156 1157**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 1158 1159**System capability**: System SystemCapability.Security.CertificateManager 1160 1161**Parameters** 1162 1163| Name | Type | Mandatory| Description | 1164| -------- | ------------------------------------------------- | ---- | -------------------------- | 1165| handle | Uint8Array | Yes | Handle of initialization. The value contains up to 8 bytes.| 1166 1167**Return value** 1168 1169| Type | Description | 1170| ------------------------------------------- | -------------------- | 1171| Promise\<void> | Promise that returns no value.| 1172 1173**Error codes** 1174 1175For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 1176 1177| ID| Error Message | 1178| -------- | ------------------------------------------------------------ | 1179| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1180| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1181| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 1182 1183**Example** 1184```ts 1185import { certificateManager } from '@kit.DeviceCertificateKit'; 1186import { BusinessError } from '@kit.BasicServicesKit'; 1187 1188/* cmHandle is the value returned by init(). The value here is only an example. */ 1189let cmHandle: Uint8Array = new Uint8Array([ 1190 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08 1191]); 1192try { 1193 certificateManager.abort(cmHandle).then((result) => { 1194 console.info('Succeeded in aborting.'); 1195 }).catch((err: BusinessError) => { 1196 console.error(`Failed to abort. Code: ${err.code}, message: ${err.message}`); 1197 }) 1198} catch (error) { 1199 console.error(`Failed to abort. Code: ${error.code}, message: ${error.message}`); 1200} 1201``` 1202 1203## certificateManager.getPublicCertificate<sup>12+</sup> 1204 1205getPublicCertificate(keyUri: string): Promise\<CMResult> 1206 1207Obtains detailed information about a public credential. This API uses a promise to return the result. 1208 1209**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 1210 1211**System capability**: System SystemCapability.Security.CertificateManager 1212 1213**Parameters** 1214 1215| Name | Type | Mandatory| Description | 1216| -------- | ------------------------------------------------- | ---- | -------------------------- | 1217| keyUri | string | Yes | Unique identifier of a user's public credential. The value contains up to 256 bytes.| 1218 1219**Return value** 1220 1221| Type | Description | 1222| ------------------------------- | ------------------------------------------------------------ | 1223| Promise\<[CMResult](#cmresult)> | Promise used to return the detailed information about the user's public credential obtained, that is, **credential** in the [CMResult](#cmresult) object.| 1224 1225**Error codes** 1226 1227For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 1228 1229| ID| Error Message | 1230| -------- | ------------- | 1231| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1232| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1233| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 1234| 17500002 | The certificate does not exist. | 1235| 17500005 | The application is not authorized by the user. | 1236 1237**Example** 1238```ts 1239import { certificateManager } from '@kit.DeviceCertificateKit'; 1240import { BusinessError } from '@kit.BasicServicesKit'; 1241 1242let uri: string = 'test'; /* The user needs to use the unique identifier of the credential to obtain the public credential details, which is not elaborated here. */ 1243try { 1244 certificateManager.getPublicCertificate(uri).then((cmResult) => { 1245 if (cmResult?.credential == undefined) { 1246 console.info('The result of getting public certificate is undefined.'); 1247 } else { 1248 let cred = cmResult.credential; 1249 console.info('Succeeded in getting Public certificate.'); 1250 } 1251 }).catch((err: BusinessError) => { 1252 console.error(`Failed to get Public certificate. Code: ${err.code}, message: ${err.message}`); 1253 }) 1254} catch (error) { 1255 console.error(`Failed to get Public certificate. Code: ${error.code}, message: ${error.message}`); 1256} 1257``` 1258 1259## certificateManager.isAuthorizedApp<sup>12+</sup> 1260 1261isAuthorizedApp(keyUri: string): Promise\<boolean> 1262 1263Checks whether this application is authorized by the specified user credential. This API uses a promise to return the result. 1264 1265**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 1266 1267**System capability**: System SystemCapability.Security.CertificateManager 1268 1269**Parameters** 1270 1271| Name | Type | Mandatory| Description | 1272| -------- | ------------------------------------------------- | ---- | -------------------------- | 1273| keyUri | string | Yes | Unique identifier of the credential authorized by the user to the application. The value contains up to 256 bytes.| 1274 1275**Return value** 1276 1277| Type | Description | 1278| ----------------- | ------------------------------------------------------------ | 1279| Promise\<boolean> | Promise used to return whether the application is authorized. The value **true** means authorized; the value **false** means the opposite.| 1280 1281**Error codes** 1282 1283For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 1284 1285| ID| Error Message | 1286| -------- | ------------- | 1287| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1288| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1289| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 1290 1291**Example** 1292```ts 1293import { certificateManager } from '@kit.DeviceCertificateKit'; 1294import { BusinessError } from '@kit.BasicServicesKit'; 1295 1296let uri: string = 'test'; /* Unique identifier of the credential. The process for authorizing the credential to the application is omitted here. */ 1297try { 1298 certificateManager.isAuthorizedApp(uri).then((res) => { 1299 if (res) { 1300 console.info('The application is authorized by the user.'); 1301 } else { 1302 console.info('The application is not authorized by the user.'); 1303 } 1304 }).catch((err: BusinessError) => { 1305 console.error(`Failed to check if the application is authorized. Code: ${err.code}, message: ${err.message}`); 1306 }) 1307} catch (error) { 1308 console.error(`Failed to check if the application is authorized. Code: ${error.code}, message: ${error.message}`); 1309} 1310``` 1311 1312## certificateManager.getAllUserTrustedCertificates<sup>12+</sup> 1313 1314getAllUserTrustedCertificates(): Promise\<CMResult> 1315 1316Obtains all user trusted root CA certificates of the device. This API uses a promise to return the result. 1317 1318**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 1319 1320**System capability**: System SystemCapability.Security.CertificateManager 1321 1322**Return value** 1323 1324| Type | Description | 1325| ------------------------------- | ------------------------------------------------------------ | 1326| Promise\<[CMResult](#cmresult)> | Promise used to return the user's root CA certificates obtained, that is, **certList** in the [CMResult](#cmresult) object.| 1327 1328**Error codes** 1329 1330For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 1331 1332| ID| Error Message | 1333| -------- | ------------- | 1334| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1335| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 1336 1337**Example** 1338```ts 1339import { certificateManager } from '@kit.DeviceCertificateKit'; 1340import { BusinessError } from '@kit.BasicServicesKit'; 1341 1342try { 1343 certificateManager.getAllUserTrustedCertificates().then((cmResult) => { 1344 if (cmResult === undefined) { // If the number of root CA certificates is 0, the returned cmResult is undefined. 1345 console.info('the count of the user trusted certificates is 0'); 1346 } else if (cmResult.certList == undefined) { 1347 console.info('The result of getting all user trusted certificates is undefined.'); 1348 } else { 1349 let list = cmResult.certList; 1350 console.info('Succeeded in getting all user trusted certificates.'); 1351 } 1352 }).catch((err: BusinessError) => { 1353 console.error(`Failed to get all user trusted certificates. Code: ${err.code}, message: ${err.message}`); 1354 }) 1355} catch (error) { 1356 console.error(`Failed to get all user trusted certificates. Code: ${error.code}, message: ${error.message}`); 1357} 1358``` 1359 1360## certificateManager.getAllUserTrustedCertificates<sup>18+</sup> 1361 1362getAllUserTrustedCertificates(scope: CertScope): Promise\<CMResult> 1363 1364Obtains the user root CA certificates based on the certificate scope. This API uses a promise to return the result. 1365 1366**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 1367 1368**System capability**: System SystemCapability.Security.CertificateManager 1369 1370**Parameters** 1371 1372| Name| Type | Mandatory| Description | 1373| ------ | ------------------------- | ---- | ---------------- | 1374| scope | [CertScope](#certscope18) | Yes | Scope of the certificates to obtain.| 1375 1376**Return value** 1377 1378| Type | Description | 1379| ------------------------------- | ------------------------------------------------------------ | 1380| Promise\<[CMResult](#cmresult)> | Promise used to return the user's root CA certificates obtained, that is, **certList** in the [CMResult](#cmresult) object.| 1381 1382**Error codes** 1383 1384For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 1385 1386| ID| Error Message | 1387| -------- | ------------------------------------------------------------ | 1388| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1389| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1390| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 1391 1392**Example** 1393 1394```ts 1395import { certificateManager } from '@kit.DeviceCertificateKit'; 1396import { BusinessError } from '@kit.BasicServicesKit'; 1397 1398try { 1399 /* Obtain the user root CA certificates of the current user. To obtain the user root CA certificates accessible to all users, pass in GLOBAL_USER. */ 1400 let scope: certificateManager.CertScope = certificateManager.CertScope.CURRENT_USER; 1401 certificateManager.getAllUserTrustedCertificates(scope).then((cmResult) => { 1402 if (cmResult === undefined) { // If the number of root CA certificates is 0, the returned cmResult is undefined. 1403 console.info('the count of the user trusted certificates is 0'); 1404 } else if (cmResult.certList == undefined) { 1405 console.info('The result of getting current user trusted certificates is undefined.'); 1406 } else { 1407 let list = cmResult.certList; 1408 console.info('Succeeded in getting current user trusted certificates.'); 1409 } 1410 }).catch((err: BusinessError) => { 1411 console.error(`Failed to get current user trusted certificates. Code: ${err.code}, message: ${err.message}`); 1412 }) 1413} catch (error) { 1414 console.error(`Failed to get current user trusted certificates. Code: ${error.code}, message: ${error.message}`); 1415} 1416``` 1417 1418## certificateManager.getUserTrustedCertificate<sup>12+</sup> 1419 1420getUserTrustedCertificate(certUri: string): Promise\<CMResult> 1421 1422Obtains the detailed information about a user root CA certificate. This API uses a promise to return the result. 1423 1424**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 1425 1426**System capability**: System SystemCapability.Security.CertificateManager 1427 1428**Parameters** 1429 1430| Name | Type | Mandatory| Description | 1431| -------- | ------------------------------------------------- | ---- | -------------------------- | 1432| certUri | string | Yes | Unique identifier of a user's root CA certificate. The value contains up to 256 bytes.| 1433 1434**Return value** 1435 1436| Type | Description | 1437| ------------------------------- | ------------------------------------------------------------ | 1438| Promise\<[CMResult](#cmresult)> | Promise used to return the detailed CA certificate information obtained, that is, **certInfo** in the [CMResult](#cmresult) object.| 1439 1440**Error codes** 1441 1442For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 1443 1444| ID| Error Message | 1445| -------- | ------------- | 1446| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1447| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1448| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 1449| 17500002 | The certificate does not exist. | 1450 1451**Example** 1452```ts 1453import { certificateManager } from '@kit.DeviceCertificateKit'; 1454import { BusinessError } from '@kit.BasicServicesKit'; 1455 1456let certUri: string = 'testUserCert'; /* The user needs to use the unique identifier of the CA certificate to obtain the user root CA certificate details, which is not elaborated here. */ 1457try { 1458 certificateManager.getUserTrustedCertificate(certUri).then((cmResult) => { 1459 if (cmResult?.certInfo == undefined) { 1460 console.info('The result of getting user trusted certificate is undefined.'); 1461 } else { 1462 let cert = cmResult.certInfo; 1463 console.info('Succeeded in getting user trusted certificate.'); 1464 } 1465 }).catch((err: BusinessError) => { 1466 console.error(`Failed to get user trusted certificate. Code: ${err.code}, message: ${err.message}`); 1467 }) 1468} catch (error) { 1469 console.error(`Failed to get user trusted certificate. Code: ${error.code}, message: ${error.message}`); 1470} 1471``` 1472## certificateManager.getPrivateCertificates<sup>13+</sup> 1473 1474getPrivateCertificates(): Promise\<CMResult> 1475 1476Obtains the credentials for installing the application. This API uses a promise to return the result asynchronously. 1477 1478**Required permissions**: ohos.permission.ACCESS_CERT_MANAGER 1479 1480**System capability**: System SystemCapability.Security.CertificateManager 1481 1482**Return value** 1483 1484| Type | Description | 1485| ------------------------------- | ------------------------------------------------------------ | 1486| Promise\<[CMResult](#cmresult)> | Promise used to return credentials obtained, which is **credentialList** in [CMResult](#cmresult).| 1487 1488**Error codes** 1489 1490For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 1491 1492| ID| Error Message | 1493| -------- | ------------- | 1494| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1495| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 1496 1497**Example** 1498```ts 1499import { certificateManager } from '@kit.DeviceCertificateKit'; 1500import { BusinessError } from '@kit.BasicServicesKit'; 1501 1502try { 1503 certificateManager.getPrivateCertificates().then((cmResult) => { 1504 if (cmResult === undefined) { // If the number of certificate credentials is 0, the returned cmResult is undefined. 1505 console.info('the count of the private certificates is 0'); 1506 } else if (cmResult.credentialList == undefined) { 1507 console.info('The result of getting all private certificates installed by the application is undefined.'); 1508 } else { 1509 let list = cmResult.credentialList; 1510 console.info('Succeeded in getting all private certificates installed by the application.'); 1511 } 1512 }).catch((err: BusinessError) => { 1513 console.error(`Failed to get all private certificates installed by the application. Code: ${err.code}, message: ${err.message}`); 1514 }) 1515} catch (error) { 1516 console.error(`Failed to get all private certificates installed by the application. Code: ${error.code}, message: ${error.message}`); 1517} 1518``` 1519## certificateManager.getCertificateStorePath<sup>18+</sup> 1520 1521getCertificateStorePath(property: CertStoreProperty): string; 1522 1523Obtains the certificate storage path. 1524 1525**System capability**: System SystemCapability.Security.CertificateManager 1526 1527**Parameters** 1528 1529| Name | Type | Mandatory| Description | 1530| -------- | ----------------------------------------- | ---- | -------------------------------- | 1531| property | [CertStoreProperty](#certstoreproperty18) | Yes | Storage information about the target certificate.| 1532 1533**Return value** 1534 1535| Type | Description | 1536| ------ | -------------------- | 1537| string | Certificate storage path.| 1538 1539**Error codes** 1540 1541For details about the following error codes, see [Certificate Management Error Codes](errorcode-certManager.md). 1542 1543| ID | Error Message | 1544|----------| ------------- | 1545| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1546| 17500001 | Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. | 1547| 17500009 | The device does not support the specified certificate store path, such as the overseas device does not support the certificate which algorithm is SM. | 1548 1549**Example** 1550```ts 1551import { certificateManager } from '@kit.DeviceCertificateKit'; 1552 1553try { 1554 /* Obtain the storage path of the system CA certificates. */ 1555 let property1: certificateManager.CertStoreProperty = { 1556 certType: certificateManager.CertType.CA_CERT_SYSTEM, 1557 } 1558 let systemCAPath = certificateManager.getCertificateStorePath(property1); 1559 console.info(`Success to get system ca path: ${systemCAPath}`); 1560 1561 /* Obtain the storage path of the CA certificates for the current user. */ 1562 let property2: certificateManager.CertStoreProperty = { 1563 certType: certificateManager.CertType.CA_CERT_USER, 1564 certScope: certificateManager.CertScope.CURRENT_USER, 1565 } 1566 let userCACurrentPath = certificateManager.getCertificateStorePath(property2); 1567 console.info(`Success to get current user's user ca path: ${userCACurrentPath}`); 1568 1569 /* Obtain the storage path of the CA certificates for all users. */ 1570 let property3: certificateManager.CertStoreProperty = { 1571 certType: certificateManager.CertType.CA_CERT_USER, 1572 certScope: certificateManager.CertScope.GLOBAL_USER, 1573 } 1574 let globalCACurrentPath = certificateManager.getCertificateStorePath(property3); 1575 console.info(`Success to get global user's user ca path: ${globalCACurrentPath}`); 1576 1577 /* Obtain the storage path of the system CA certificates of the SM algorithm. */ 1578 let property4: certificateManager.CertStoreProperty = { 1579 certType: certificateManager.CertType.CA_CERT_SYSTEM, 1580 certAlg: certificateManager.CertAlgorithm.SM, 1581 } 1582 let smSystemCAPath = certificateManager.getCertificateStorePath(property4); 1583 console.info(`Success to get SM system ca path: ${smSystemCAPath}`); 1584} catch (error) { 1585 console.error(`Failed to get store path. Code: ${error.code}, message: ${error.message}`); 1586} 1587``` 1588