1# @ohos.net.networkSecurity (网络安全校验) 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'; 19import { BusinessError } from '@kit.BasicServicesKit'; 20 21// Define certificate blobs 22const cert: networkSecurity.CertBlob = { 23 type: networkSecurity.CertType.CERT_TYPE_PEM, 24 data: '-----BEGIN CERTIFICATE-----\n... (certificate data) ...\n-----END CERTIFICATE-----', 25}; 26 27const caCert: networkSecurity.CertBlob = { 28 type: networkSecurity.CertType.CERT_TYPE_PEM, 29 data: '-----BEGIN CERTIFICATE-----\n... (CA certificate data) ...\n-----END CERTIFICATE-----', 30}; 31 32// Perform asynchronous certificate verification 33networkSecurity.certVerification(cert, caCert) 34 .then((result) => { 35 console.info('Certificate verification result:', result); 36 }) 37 .catch((error: BusinessError) => { 38 console.error('Certificate verification failed:', error); 39 }); 40``` 41 42> **注意**： 43> 44> 请务必将示例中的证书数据替换为实际的证书内容。 45 46## CertType 47 48证书编码类型。 49 50**系统能力**: SystemCapability.Communication.NetStack 51 52| 名称 | 值 | 说明 | 53| ------------- | ----- | ------------- | 54| CERT_TYPE_PEM | 0 | PEM格式证书。 | 55| CERT_TYPE_DER | 1 | DER格式证书。 | 56 57 58## CertBlob 59 60证书数据。 61 62**系统能力**: SystemCapability.Communication.NetStack 63 64| 名称 | 类型 | 必填 | 说明 | 65| ----- | --------------------- | --------- | -------------- | 66| type | CertType | 是 | 证书编码类型。 | 67| data | string \| ArrayBuffer | 是 | 证书内容。 | 68 69 70## networkSecurity.certVerification 71 72certVerification(cert: CertBlob, caCert?: CertBlob): Promise\<number\> 73 74从证书管理获取系统预置的CA证书和用户安装的CA证书，对应用传入的证书进行校验。 75 76**系统能力**: SystemCapability.Communication.NetStack 77 78**参数** 79 80| 参数名 | 类型 | 必填 | 说明 | 81| ------ | -------- | ---- | ---------------------- | 82| cert | CertBlob | 是 | 被校验的证书。 | 83| caCert | CertBlob | 否 | 传入自定义的CA证书。 | 84 85**返回值：** 86 87| 类型 | 说明 | 88| --------------- | ------------------------------------------------------------ | 89| Promise\<number\> | 以promise形式返回一个数字，表示证书验证的结果。如果证书验证成功，则返回0； 否则验证失败。 | 90 91**错误码：** 92 93以下错误码的详细介绍请参见[网络安全校验错误码](errorcode-net-networkSecurity.md)和[通用错误码](../errorcode-universal.md)。 94 95| 错误码ID | 错误信息 | 96| -------- | ---------------------------------------------------- | 97| 401 | Parameter error. | 98| 2305001 | Unspecified error. | 99| 2305002 | Unable to get issuer certificate. | 100| 2305003 | Unable to get certificate revocation list (CRL). | 101| 2305004 | Unable to decrypt certificate signature. | 102| 2305005 | Unable to decrypt CRL signature. | 103| 2305006 | Unable to decode issuer public key. | 104| 2305007 | Certificate signature failure. | 105| 2305008 | CRL signature failure. | 106| 2305009 | Certificate is not yet valid. | 107| 2305010 | Certificate has expired. | 108| 2305011 | CRL is not yet valid. | 109| 2305012 | CRL has expired. | 110| 2305018 | Self-signed certificate. | 111| 2305023 | Certificate has been revoked. | 112| 2305024 | Invalid certificate authority (CA). | 113| 2305027 | Certificate is untrusted. | 114| 2305069 | Invalid certificate verification context. | 115 116> **说明：** 117> 118> 这些错误代码对应于证书验证过程中的各种失败。 119 120**示例：** 121 122```ts 123import { networkSecurity } from '@kit.NetworkKit'; 124import { BusinessError } from '@kit.BasicServicesKit'; 125 126// Define certificate blobs 127const cert:networkSecurity.CertBlob = { 128 type: networkSecurity.CertType.CERT_TYPE_PEM, 129 data: '-----BEGIN CERTIFICATE-----\n... (certificate data) ...\n-----END CERTIFICATE-----', 130}; 131 132const caCert:networkSecurity.CertBlob = { 133 type: networkSecurity.CertType.CERT_TYPE_PEM, 134 data: '-----BEGIN CERTIFICATE-----\n... (CA certificate data) ...\n-----END CERTIFICATE-----', 135}; 136 137// Perform asynchronous certificate verification 138networkSecurity.certVerification(cert, caCert) 139 .then((result) => { 140 console.info('Certificate verification result:', result); 141 }) 142 .catch((error: BusinessError) => { 143 console.error('Certificate verification failed:', error); 144 }); 145``` 146> **注意**： 147> 148> 请务必将示例中的证书数据替换为实际的证书内容。 149 150 151 152## networkSecurity.certVerificationSync 153 154certVerificationSync(cert: CertBlob, caCert?: CertBlob): number 155 156从证书管理获取系统预置的CA证书和用户安装的CA证书，对应用传入的证书进行校验。 157 158**系统能力**：SystemCapability.Communication.NetStack 159 160**参数**： 161 162| 参数名 | 类型 | 必填 | 说明 | 163| ------ | -------- | ---- | ---------------------- | 164| cert | CertBlob | 是 | 被校验的证书。 | 165| caCert | CertBlob | 否 | 传入自定义的CA证书。 | 166 167**返回值：** 168 169| 类型 | 说明 | 170| ------ | ------------------------------------------------------------ | 171| number | 表示证书验证的结果。如果证书验证成功，则返回0； 否则验证失败。 | 172 173**错误码：** 174 175以下错误码的详细介绍请参见[网络安全校验错误码](errorcode-net-networkSecurity.md)和[通用错误码](../errorcode-universal.md)。 176 177| 错误码ID | 错误信息 | 178| -------- | ---------------------------------------------------- | 179| 401 | Parameter error. | 180| 2305001 | Unspecified error. | 181| 2305002 | Unable to get issuer certificate. | 182| 2305003 | Unable to get certificate revocation list (CRL). | 183| 2305004 | Unable to decrypt certificate signature. | 184| 2305005 | Unable to decrypt CRL signature. | 185| 2305006 | Unable to decode issuer public key. | 186| 2305007 | Certificate signature failure. | 187| 2305008 | CRL signature failure. | 188| 2305009 | Certificate is not yet valid. | 189| 2305010 | Certificate has expired. | 190| 2305011 | CRL is not yet valid. | 191| 2305012 | CRL has expired. | 192| 2305018 | Self-signed certificate. | 193| 2305023 | Certificate has been revoked. | 194| 2305024 | Invalid certificate authority (CA). | 195| 2305027 | Certificate is untrusted. | 196| 2305069 | Invalid certificate verification context. | 197 198> **说明：** 199> 200> 这些错误代码对应于证书验证过程中的各种失败。 201 202**示例：** 203 204```ts 205import { networkSecurity } from '@kit.NetworkKit'; 206import { BusinessError } from '@kit.BasicServicesKit'; 207 208// Create certificate blobs 209const cert: networkSecurity.CertBlob = { 210 type: networkSecurity.CertType.CERT_TYPE_PEM, 211 data: '-----BEGIN CERTIFICATE-----\n...' 212}; 213 214const caCert: networkSecurity.CertBlob = { 215 type: networkSecurity.CertType.CERT_TYPE_PEM, 216 data: '-----BEGIN CERTIFICATE-----\n...' 217}; 218 219// Asynchronous verification 220networkSecurity.certVerification(cert, caCert) 221 .then((result) => { 222 console.info('Verification Result:', result); 223 }) 224 .catch((error: BusinessError) => { 225 console.error('Verification Error:', error); 226 }); 227 228// Synchronous verification 229let resultSync: number = networkSecurity.certVerificationSync(cert, caCert); 230console.info('Synchronous Verification Result:', resultSync); 231``` 232 233> **注意**： 234> 235> 请务必将示例中的证书数据替换为实际的证书内容。 236 237## networkSecurity.isCleartextPermitted<sup>18+</sup> 238 239isCleartextPermitted(): boolean 240 241从应用预置network_config.json文件中获取整体明文HTTP是否允许信息，默认允许明文HTTP访问。 242 243**需要权限**：ohos.permission.INTERNET 244 245**系统能力**：SystemCapability.Communication.NetStack 246 247**返回值：** 248 249| 类型 | 说明 | 250| ------ | ------------------------------------------------------------ | 251| boolean | 整体明文HTTP是否允许。返回true表示允许访问明文HTTP，false表示不允许。默认返回true。 | 252 253**错误码：** 254 255以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 256 257| 错误码ID | 错误信息 | 258| -------- | ---------------------------------------------------- | 259| 201 | Permission denied. | 260 261**示例：** 262 263```ts 264import { networkSecurity } from '@kit.NetworkKit'; 265import { BusinessError } from '@kit.BasicServicesKit'; 266 267try { 268 let result: boolean = networkSecurity.isCleartextPermitted(); 269 console.info(`isCleartextPermitted Result: ${JSON.stringify(result)}`); 270} catch (error) { 271 console.error(`isCleartextPermitted Error: ${JSON.stringify(error)}`); 272} 273``` 274 275## networkSecurity.isCleartextPermittedByHostName<sup>18+</sup> 276 277isCleartextPermittedByHostName(hostName: string): boolean 278 279从应用预置network_config.json文件中获取按域名明文HTTP是否允许信息，默认允许明文HTTP访问。 280 281**需要权限**：ohos.permission.INTERNET 282 283**系统能力**：SystemCapability.Communication.NetStack 284 285**参数**： 286 287| 参数名 | 类型 | 必填 | 说明 | 288| ------ | -------- | ---- | ---------------------- | 289| hostName | string | 是 | 需要查询的主机名。| 290 291**返回值：** 292 293| 类型 | 说明 | 294| ------ | ------------------------------------------------------------ | 295| boolean | 按域名明文HTTP是否允许。返回true表示允许明文HTTP访问该主机，false表示不允许。默认返回true。 | 296 297**错误码：** 298 299以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 300 301| 错误码ID | 错误信息 | 302| -------- | ---------------------------------------------------- | 303| 201 | Permission denied. | 304 305**示例：** 306 307```ts 308import { networkSecurity } from '@kit.NetworkKit'; 309import { BusinessError } from '@kit.BasicServicesKit'; 310 311try { 312 let result: boolean = networkSecurity.isCleartextPermittedByHostName("xxx"); 313 console.info(`isCleartextPermitted Result: ${JSON.stringify(result)}`); 314} catch (error) { 315 console.error(`isCleartextPermitted Error: ${JSON.stringify(error)}`); 316} 317```