• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 应用证书凭据开发指导
2
3<!--Kit: Device Certificate Kit-->
4<!--Subsystem: Security-->
5<!--Owner: @chaceli-->
6<!--Designer: @chande-->
7<!--Tester: @zhangzhi1995-->
8<!--Adviser: @zengyawen-->
9
10> **说明**
11>
12> 本开发指导需使用API version 11及以上版本SDK。
13
14## 场景说明
15
161. 典型场景。
17
18   - 安装应用证书凭据。
19   - 获取应用证书凭据。
20   - 使用应用证书凭据对数据进行签名、验签。
21   - 卸载指定的应用证书凭据。
22
232. 支持安装的应用证书凭据算法类型和签名验签支持的参数组合。
24
25   - 证书管理安装凭据及使用凭据中的密钥进行签名、验签，依赖[密钥管理服务](../UniversalKeystoreKit/huks-overview.md)（HUKS）能力。
26   - 证书管理支持的算法为其子集，当前仅支持RSA、ECC及SM2算法类型的私有凭据安装及使用。
27   - 签名、验签支持的参数组合，详见HUKS声明的[签名/验签介绍及算法规格](../UniversalKeystoreKit/huks-signing-signature-verification-overview.md)中RSA、ECC及SM2的描述。
28
29## 接口说明
30
31详细接口说明可参考[API参考](../../reference/apis-device-certificate-kit/js-apis-certManager.md)。
32
33以上场景涉及的常用接口如下表所示。
34
35| 实例名          | 接口名                                                       | 描述                                         |
36| --------------- | ------------------------------------------------------------ | -------------------------------------------- |
37| certificateManager        | installPrivateCertificate(keystore: Uint8Array, keystorePwd: string, certAlias: string, callback: AsyncCallback\<CMResult>) : void  | 使用callback方式安装应用证书凭据。        |
38| certificateManager        | installPrivateCertificate(keystore: Uint8Array, keystorePwd: string, certAlias: string) : Promise\<CMResult> | 使用promise方式安装应用证书凭据。               |
39| certificateManager        | installPrivateCertificate(keystore: Uint8Array, keystorePwd: string, certAlias: string, level: AuthStorageLevel) : Promise\<CMResult><sup>18+</sup> | 使用promise方式安装应用证书凭据，并指定凭据的存储级别。 |
40| certificateManager        | getPrivateCertificate(keyUri: string, callback: AsyncCallback\<CMResult>) : void    | 使用callback方式获取应用证书凭据。       |
41| certificateManager        | getPrivateCertificate(keyUri: string) : Promise\<CMResult>                         | 使用promise方式获取应用证书凭据。        |
42| certificateManager        | uninstallPrivateCertificate(keyUri: string, callback: AsyncCallback\<void>) : void  | 使用callback方式卸载应用证书凭据。      |
43| certificateManager        | uninstallPrivateCertificate(keyUri: string) : Promise\<void> | 使用promise方式卸载应用证书凭据。 |
44| certificateManager | init(authUri: string, spec: CMSignatureSpec, callback: AsyncCallback\<CMHandle>) : void | 使用callback方式进行签名验签的初始化操作。 |
45| certificateManager | init(authUri: string, spec: CMSignatureSpec) : Promise\<CMHandle>  | 使用promise方式进行签名验签的初始化操作。 |
46| certificateManager        | update(handle: Uint8Array, data: Uint8Array, callback: AsyncCallback\<void>) : void         | 使用callback方式对待签名、验签的数据进行更新操作。        |
47| certificateManager        | update(handle: Uint8Array, data: Uint8Array) : Promise\<void> | 使用promise方式对待签名、验签的数据进行更新操作。 |
48| certificateManager        | finish(handle: Uint8Array, callback: AsyncCallback\<CMResult>) : void         | 使用callback方式完成数据的签名操作。        |
49| certificateManager        | finish(handle: Uint8Array, signature: Uint8Array, callback: AsyncCallback\<CMResult>) : void     | 使用callback方式完成数据的签名操作。        |
50| certificateManager        | finish(handle: Uint8Array, signature?: Uint8Array) : Promise\<CMResult> | 使用promise方式完成数据的签名、验签操作。 |
51| certificateManager        | abort(handle: Uint8Array, callback: AsyncCallback\<void>) : void         | 使用callback方式中止签名、验证操作。        |
52| certificateManager        | abort(handle: Uint8Array) : Promise\<void> | 使用promise方式中止签名、验证操作。 |
53
54## 开发步骤
55
561. 权限申请和声明。
57
58   需要申请的权限：ohos.permission.ACCESS_CERT_MANAGER
59
60   申请流程请参考：[申请应用权限](../AccessToken/determine-application-mode.md)
61
62   声明权限请参考：[声明权限](../AccessToken/declare-permissions.md)
63
642. 导入相关模块。
65
66   ```ts
67   import { certificateManager } from '@kit.DeviceCertificateKit';
68   ```
69
703. 安装应用证书凭据，获取应用证书凭据，并使用应用证书凭据进行签名、验签，最后删除应用证书凭据。
71
72   ```ts
73   async function privateCredSample() {
74     /* 安装的凭据数据需要业务赋值，本例数据非凭据数据。 */
75     let keystore: Uint8Array = new Uint8Array([
76       0x30, 0x82, 0x04, 0x6a, 0x02, 0x01, 0x03, 0x30, 0x82, 0x04, 0x30, 0x06, 0x09,
77     ]);
78
79     /* 安装凭据对应的密码，业务赋值。 */
80     let keystorePwd: string = '123456';
81     let appKeyUri: string = '';
82     try {
83       /* 安装应用证书凭据。 */
84       const res: certificateManager.CMResult = await certificateManager.installPrivateCertificate(keystore, keystorePwd, "testPriCredential");
85       appKeyUri = (res.uri != undefined) ? res.uri : '';
86     } catch (err) {
87       console.error(`Failed to install private certificate. Code: ${err.code}, message: ${err.message}`);
88     }
89
90     try {
91       /* 获取应用证书凭据。 */
92       let res: certificateManager.CMResult = await certificateManager.getPrivateCertificate(appKeyUri);
93       if (res === undefined || res.credential == undefined) {
94         console.error('The result of getting private certificate is undefined.');
95       } else {
96         let credential = res.credential;
97         console.info('Succeeded in getting private certificate.');
98       }
99     } catch (err) {
100       console.error(`Failed to get private certificate. Code: ${err.code}, message: ${err.message}`);
101    }
102
103     try {
104       /* srcData为待签名、验签的数据，业务自行赋值。 */
105       let srcData: Uint8Array = new Uint8Array([
106         0x86, 0xf7, 0x0d, 0x01, 0x07, 0x01,
107       ]);
108
109       /* 构造签名的属性参数。 */
110       const signSpec: certificateManager.CMSignatureSpec = {
111         purpose: certificateManager.CmKeyPurpose.CM_KEY_PURPOSE_SIGN,
112         padding: certificateManager.CmKeyPadding.CM_PADDING_PSS,
113         digest: certificateManager.CmKeyDigest.CM_DIGEST_SHA256
114       };
115
116       /* 签名。 */
117       const signHandle: certificateManager.CMHandle = await certificateManager.init(appKeyUri, signSpec);
118       await certificateManager.update(signHandle.handle, srcData);
119       const signResult: certificateManager.CMResult = await certificateManager.finish(signHandle.handle);
120
121       /* 构造验签的属性参数。 */
122       const verifySpec: certificateManager.CMSignatureSpec = {
123         purpose: certificateManager.CmKeyPurpose.CM_KEY_PURPOSE_VERIFY,
124         padding: certificateManager.CmKeyPadding.CM_PADDING_PSS,
125         digest: certificateManager.CmKeyDigest.CM_DIGEST_SHA256
126       };
127
128       /* 验签。 */
129       const verifyHandle: certificateManager.CMHandle = await certificateManager.init(appKeyUri, verifySpec);
130       await certificateManager.update(verifyHandle.handle, srcData);
131       const verifyResult = await certificateManager.finish(verifyHandle.handle, signResult.outData);
132       console.info('Succeeded in signing and verifying.');
133     } catch (err) {
134       console.error(`Failed to sign or verify. Code: ${err.code}, message: ${err.message}`);
135     }
136
137     try {
138       /* 删除应用证书凭据。 */
139       await certificateManager.uninstallPrivateCertificate(appKeyUri);
140     } catch (err) {
141       console.error(`Failed to uninstall private certificate. Code: ${err.code}, message: ${err.message}`);
142     }
143   }
144   ```