1# @ohos.net.networkSecurity (Network Security)
2
3本模块提供网络安全校验能力。应用可以通过证书校验API完成证书校验功能。
4
5> **说明：**
6>
7> 本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8
9## 导入模块
10
11```ts
12import { networkSecurity } from '@kit.NetworkKit';
13```
14
15## 完整实例
16
17```ts
18import { networkSecurity } from '@kit.NetworkKit';
19
20// Define certificate blobs
21const cert: networkSecurity.CertBlob = {
22  type: networkSecurity.CertType.CERT_TYPE_PEM,
23  data: '-----BEGIN CERTIFICATE-----\n... (certificate data) ...\n-----END CERTIFICATE-----',
24};
25
26const caCert: networkSecurity.CertBlob = {
27  type: networkSecurity.CertType.CERT_TYPE_PEM,
28  data: '-----BEGIN CERTIFICATE-----\n... (CA certificate data) ...\n-----END CERTIFICATE-----',
29};
30
31// Perform asynchronous certificate verification
32networkSecurity.certVerification(cert, caCert)
33  .then((result) => {
34    console.info('Certificate verification result:', result);
35  })
36  .catch((error: BusinessError) => {
37    console.error('Certificate verification failed:', error);
38  });
39```
40
41> **注意**：
42>
43> 请务必将示例中的证书数据替换为实际的证书内容。
44
45## CertType
46
47证书编码类型。
48
49**系统能力**: SystemCapability.Communication.NetStack
50
51| 名称          | 值    |      说明     |
52| ------------- | ----- | ------------- |
53| CERT_TYPE_PEM | 0     | PEM格式证书。 |
54| CERT_TYPE_DER | 1     | DER格式证书。 |
55
56
57## CertBlob
58
59证书数据。
60
61**系统能力**: SystemCapability.Communication.NetStack
62
63| 名称  | 类型                   | 必填      | 说明           |
64| ----- | --------------------- | --------- | -------------- |
65| type  | CertType              | 是      | 证书编码类型。  |
66| data  | string \| ArrayBuffer | 是       | 证书内容。      |
67
68
69## networkSecurity.certVerification
70
71certVerification(cert: CertBlob, caCert?: CertBlob): Promise\<number\>
72
73从证书管理获取系统预置的CA证书和用户安装的CA证书，对应用传入的证书进行校验。
74
75**系统能力**: SystemCapability.Communication.NetStack
76
77**参数**
78
79| 参数名 | 类型     | 必填 | 说明                   |
80| ------ | -------- | ---- | ---------------------- |
81| cert   | CertBlob | 是   | 被校验的证书。       |
82| caCert | CertBlob | 否   | 传入自定义的CA证书。 |
83
84**返回值：**
85
86| 类型            | 说明                                                         |
87| --------------- | ------------------------------------------------------------ |
88| Promise\<number\> | 以promise形式返回一个数字，表示证书验证的结果。如果证书验证成功，则返回0； 否则验证失败。 |
89
90**错误码：**
91
92| 错误码ID | 错误信息                                             |
93| -------- | ---------------------------------------------------- |
94| 401      | Parameter error.                                     |
95| 2305001  | Unspecified error.                                   |
96| 2305002  | Unable to get issuer certificate.                    |
97| 2305003  | Unable to get certificate revocation list (CRL).     |
98| 2305004  | Unable to decrypt certificate signature.             |
99| 2305005  | Unable to decrypt CRL signature.                     |
100| 2305006  | Unable to decode issuer public key.                  |
101| 2305007  | Certificate signature failure.                       |
102| 2305008  | CRL signature failure.                               |
103| 2305009  | Certificate is not yet valid.                        |
104| 2305010  | Certificate has expired.                             |
105| 2305011  | CRL is not yet valid.                                |
106| 2305012  | CRL has expired.                                     |
107| 2305018  | Self-signed certificate.                             |
108| 2305023  | Certificate has been revoked.                        |
109| 2305024  | Invalid certificate authority (CA).                  |
110| 2305027  | Certificate is untrusted.                            |
111| 2305069  | Invalid certificate verification context.            |
112
113> **说明：**
114>
115> 这些错误代码对应于证书验证过程中的各种失败，提供有关所遇到问题的详细信息。
116
117**示例：**
118
119```ts
120import { networkSecurity } from '@kit.NetworkKit';
121import { BusinessError } from '@kit.BasicServicesKit';
122
123// Define certificate blobs
124const cert:networkSecurity.CertBlob = {
125  type: networkSecurity.CertType.CERT_TYPE_PEM,
126  data: '-----BEGIN CERTIFICATE-----\n... (certificate data) ...\n-----END CERTIFICATE-----',
127};
128
129const caCert:networkSecurity.CertBlob = {
130  type: networkSecurity.CertType.CERT_TYPE_PEM,
131  data: '-----BEGIN CERTIFICATE-----\n... (CA certificate data) ...\n-----END CERTIFICATE-----',
132};
133
134// Perform asynchronous certificate verification
135networkSecurity.certVerification(cert, caCert)
136  .then((result) => {
137    console.info('Certificate verification result:', result);
138  })
139  .catch((error: BusinessError) => {
140    console.error('Certificate verification failed:', error);
141  });
142```
143> **注意**：
144>
145> 请务必将示例中的证书数据替换为实际的证书内容。
146
147
148
149## networkSecurity.certVerificationSync
150
151certVerificationSync(cert: CertBlob, caCert?: CertBlob): number
152
153从证书管理获取系统预置的CA证书和用户安装的CA证书，对应用传入的证书进行校验。
154
155**系统能力**：SystemCapability.Communication.NetStack
156
157**参数**：
158
159| 参数名 | 类型     | 必填 | 说明                   |
160| ------ | -------- | ---- | ---------------------- |
161| cert   | CertBlob | 是  | 被校验的证书。       |
162| caCert | CertBlob | 否   | 传入自定义的CA证书。 |
163
164**返回值：**
165
166| 类型   | 说明                                                         |
167| ------ | ------------------------------------------------------------ |
168| number | 表示证书验证的结果。如果证书验证成功，则返回0； 否则验证失败。 |
169
170**错误码：**
171
172| 错误码ID | 错误信息                                             |
173| -------- | ---------------------------------------------------- |
174| 401      | Parameter error.                                     |
175| 2305001  | Unspecified error.                                   |
176| 2305002  | Unable to get issuer certificate.                    |
177| 2305003  | Unable to get certificate revocation list (CRL).     |
178| 2305004  | Unable to decrypt certificate signature.             |
179| 2305005  | Unable to decrypt CRL signature.                     |
180| 2305006  | Unable to decode issuer public key.                  |
181| 2305007  | Certificate signature failure.                       |
182| 2305008  | CRL signature failure.                               |
183| 2305009  | Certificate is not yet valid.                        |
184| 2305010  | Certificate has expired.                             |
185| 2305011  | CRL is not yet valid.                                |
186| 2305012  | CRL has expired.                                     |
187| 2305018  | Self-signed certificate.                             |
188| 2305023  | Certificate has been revoked.                        |
189| 2305024  | Invalid certificate authority (CA).                  |
190| 2305027  | Certificate is untrusted.                            |
191| 2305069  | Invalid certificate verification context.            |
192
193> **说明：**
194>
195> 这些错误代码对应于证书验证过程中的各种失败，提供有关所遇到问题的详细信息。
196
197**示例：**
198
199```ts
200import { networkSecurity } from '@kit.NetworkKit';
201import { BusinessError } from '@kit.BasicServicesKit';
202
203// Create certificate blobs
204const cert: networkSecurity.CertBlob = {
205  type: networkSecurity.CertType.CERT_TYPE_PEM,
206  data: '-----BEGIN CERTIFICATE-----\n...'
207};
208
209const caCert: networkSecurity.CertBlob = {
210  type: networkSecurity.CertType.CERT_TYPE_PEM,
211  data: '-----BEGIN CERTIFICATE-----\n...'
212};
213
214// Asynchronous verification
215networkSecurity.certVerification(cert, caCert)
216  .then((result) => {
217    console.info('Verification Result:', result);
218  })
219  .catch((error: BusinessError) => {
220    console.error('Verification Error:', error);
221  });
222
223// Synchronous verification
224let resultSync: number = networkSecurity.certVerificationSync(cert, caCert);
225console.info('Synchronous Verification Result:', resultSync);
226```
227
228> **注意**：
229>
230> 请务必将示例中的证书数据替换为实际的证书内容。
231