说明

本开发指导需使用API version 11及以上版本SDK。

## 场景说明

1. 典型场景。

   * 安装应用证书凭据。
   * 获取应用证书凭据。
   * 使用应用证书凭据对数据进行签名、验签。
   * 卸载指定的应用证书凭据。
2. 安装应用证书凭据支持的算法类型和签名验签支持的参数组合。

   * 证书管理安装凭据及使用凭据中的密钥进行签名、验签，依赖[密钥管理服务](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/huks-overview)（HUKS）能力。
   * 证书管理支持的算法为HUKS支持的子集，当前仅支持RSA、ECC及SM2算法类型的私有凭据安装及使用。
   * 签名、验签支持的参数组合，详见HUKS声明的[签名/验签介绍及算法规格](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/huks-signing-signature-verification-overview)中RSA、ECC及SM2的描述。

## 接口说明

详细接口说明可参考[@ohos.security.certManager (证书管理模块)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-certmanager)。

以上场景涉及的常用接口如下表所示。

展开

| 实例名 | 接口名 | 描述 |
| --- | --- | --- |
| certificateManager | installPrivateCertificate(keystore: Uint8Array, keystorePwd: string, certAlias: string, callback: AsyncCallback<CMResult>) : void | 使用callback方式安装应用证书凭据。 |
| certificateManager | installPrivateCertificate(keystore: Uint8Array, keystorePwd: string, certAlias: string) : Promise<CMResult> | 使用Promise方式安装应用证书凭据。 |
| certificateManager | installPrivateCertificate(keystore: Uint8Array, keystorePwd: string, certAlias: string, level: AuthStorageLevel) : Promise<CMResult>18+ | 使用Promise方式安装应用证书凭据，并指定凭据的存储级别。 |
| certificateManager | getPrivateCertificate(keyUri: string, callback: AsyncCallback<CMResult>) : void | 使用callback方式获取应用证书凭据。 |
| certificateManager | getPrivateCertificate(keyUri: string) : Promise<CMResult> | 使用Promise方式获取应用证书凭据。 |
| certificateManager | uninstallPrivateCertificate(keyUri: string, callback: AsyncCallback<void>) : void | 使用callback方式卸载应用证书凭据。 |
| certificateManager | uninstallPrivateCertificate(keyUri: string) : Promise<void> | 使用Promise方式卸载应用证书凭据。 |
| certificateManager | init(authUri: string, spec: CMSignatureSpec, callback: AsyncCallback<CMHandle>) : void | 使用callback方式进行签名验签的初始化操作。 |
| certificateManager | init(authUri: string, spec: CMSignatureSpec) : Promise<CMHandle> | 使用Promise方式进行签名验签的初始化操作。 |
| certificateManager | update(handle: Uint8Array, data: Uint8Array, callback: AsyncCallback<void>) : void | 使用callback方式对待签名、验签的数据进行更新操作。 |
| certificateManager | update(handle: Uint8Array, data: Uint8Array) : Promise<void> | 使用Promise方式对待签名、验签的数据进行更新操作。 |
| certificateManager | finish(handle: Uint8Array, callback: AsyncCallback<CMResult>) : void | 使用callback方式完成数据的签名操作。 |
| certificateManager | finish(handle: Uint8Array, signature: Uint8Array, callback: AsyncCallback<CMResult>) : void | 使用callback方式完成数据的签名操作。 |
| certificateManager | finish(handle: Uint8Array, signature?: Uint8Array) : Promise<CMResult> | 使用Promise方式完成数据的签名、验签操作。 |
| certificateManager | abort(handle: Uint8Array, callback: AsyncCallback<void>) : void | 使用callback方式中止签名、验签操作。 |
| certificateManager | abort(handle: Uint8Array) : Promise<void> | 使用Promise方式中止签名、验签操作。 |

## 开发步骤

1. 权限申请和声明。

   需要申请的权限：ohos.permission.ACCESS\_CERT\_MANAGER

   申请流程请参考：[申请应用权限](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/determine-application-mode)

   声明权限请参考：[声明权限](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/declare-permissions)
2. 导入相关模块。

   收起

   自动换行

   深色代码主题

   复制

   ```
   1. import { certificateManager } from '@kit.DeviceCertificateKit';
   ```
3. 安装应用证书凭据，获取应用证书凭据，并使用应用证书凭据进行签名、验签，最后删除应用证书凭据。

   收起

   自动换行

   深色代码主题

   复制

   ```
   1. import { certificateManager } from '@kit.DeviceCertificateKit';
   2. import { BusinessError } from '@kit.BasicServicesKit';
   3. import { util } from '@kit.ArkTS';

   5. async function privateCredSample() {
   6. /* 安装的凭据数据需要业务赋值，本例数据非凭据数据。 */
   7. let keystoreBase64Str = 'MIIMJgIBAzCCC+AGCSqGSIb3DQEHAaCCC9EEggvNMIILyTCCBW4GCSqGSIb3DQEH' +
   8. // ...
   9. 'G615kxCjeS6uixCHuij3pgQUhHiChcSeohRPrVkVPSPmYr9tjAYCAgQA';
   10. /* 凭据数据转换为Uint8Array，凭据数据为der格式 */
   11. let keystore: Uint8Array = new util.Base64Helper().decodeSync(keystoreBase64Str);

   13. /* 安装凭据对应的密码，业务赋值。 */
   14. let keystorePwd: string = 'huawei';
   15. let appKeyUri: string = '';
   16. try {
   17. /* 安装应用证书凭据。 */
   18. const res: certificateManager.CMResult = await certificateManager.installPrivateCertificate(keystore, keystorePwd, 'testPriCredential');
   19. appKeyUri = (res.uri != undefined) ? res.uri : '';
   20. console.info(`InstallPrivateCertificate success appKeyUri: ${appKeyUri}`);
   21. } catch (err) {
   22. let e: BusinessError = err as BusinessError;
   23. console.error(`Failed to install private certificate. Code: ${e.code}, message: ${e.message}`);
   24. }

   26. try {
   27. /* 获取应用证书凭据。 */
   28. let res: certificateManager.CMResult = await certificateManager.getPrivateCertificate(appKeyUri);
   29. if (res === undefined || res.credential == undefined) {
   30. console.error('The result of getting private certificate is undefined.');
   31. } else {
   32. let credential = res.credential;
   33. console.info('Succeeded in getting private certificate.');
   34. }
   35. } catch (err) {
   36. console.error(`Failed to get private certificate. Code: ${err.code}, message: ${err.message}`);
   37. }

   39. try {
   40. /* srcData为待签名、验签的数据，业务自行赋值。 */
   41. let srcData: Uint8Array = new Uint8Array([
   42. 0x86, 0xf7, 0x0d, 0x01, 0x07, 0x01,
   43. ]);

   45. /* 构造签名的属性参数。 */
   46. const signSpec: certificateManager.CMSignatureSpec = {
   47. purpose: certificateManager.CmKeyPurpose.CM_KEY_PURPOSE_SIGN,
   48. padding: certificateManager.CmKeyPadding.CM_PADDING_PSS,
   49. digest: certificateManager.CmKeyDigest.CM_DIGEST_SHA256
   50. };

   52. /* 签名。 */
   53. const signHandle: certificateManager.CMHandle = await certificateManager.init(appKeyUri, signSpec);
   54. await certificateManager.update(signHandle.handle, srcData);
   55. const signResult: certificateManager.CMResult = await certificateManager.finish(signHandle.handle);

   57. /* 构造验签的属性参数。 */
   58. const verifySpec: certificateManager.CMSignatureSpec = {
   59. purpose: certificateManager.CmKeyPurpose.CM_KEY_PURPOSE_VERIFY,
   60. padding: certificateManager.CmKeyPadding.CM_PADDING_PSS,
   61. digest: certificateManager.CmKeyDigest.CM_DIGEST_SHA256
   62. };

   64. /* 验签。 */
   65. const verifyHandle: certificateManager.CMHandle = await certificateManager.init(appKeyUri, verifySpec);
   66. await certificateManager.update(verifyHandle.handle, srcData);
   67. const verifyResult = await certificateManager.finish(verifyHandle.handle, signResult.outData);
   68. console.info('Succeeded in signing and verifying.');
   69. } catch (err) {
   70. let e: BusinessError = err as BusinessError;
   71. console.error(`Failed to sign or verify. Code: ${e.code}, message: ${e.message}`);
   72. }

   74. try {
   75. /* 删除应用证书凭据。 */
   76. await certificateManager.uninstallPrivateCertificate(appKeyUri);
   77. } catch (err) {
   78. let e: BusinessError = err as BusinessError;
   79. console.error(`Failed to uninstall private certificate. Code: ${e.code}, message: ${e.message}`);
   80. }
   81. }
   ```

   [CertManagerGuidelines.ets](https://gitcode.com/HarmonyOS_Samples/guide-snippets/blob/HarmonyOS-feature-20251117/Security/DeviceCertificateKit/CertificateManagement/entry/src/main/ets/pages/CertManagerGuidelines.ets#L15-L161)