1# @ohos.net.networkSecurity (Network Security) 2 3The **networkSecurity** module provides the network security verification capability. Specifically, it provides APIs for applications to verify the certificates in use. 4 5> **NOTE** 6> 7> 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. 8 9## Modules to Import 10 11```ts 12import { networkSecurity } from '@kit.NetworkKit'; 13``` 14 15## Sample Code 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> **NOTE** 42> 43> Be sure to replace the certificate data in the example with the actual certificate data. 44 45## CertType 46 47Enumerates certificate types. 48 49**System capability**: SystemCapability.Communication.NetStack 50 51| Name | Value | Description | 52| ------------- | ----- | ------------- | 53| CERT_TYPE_PEM | 0 | PEM certificate| 54| CERT_TYPE_DER | 1 | DER certificate.| 55 56 57## CertBlob 58 59Defines the certificate data. 60 61**System capability**: SystemCapability.Communication.NetStack 62 63| Name | Type | Mandatory | Description | 64| ----- | --------------------- | --------- | -------------- | 65| type | CertType | Yes | Certificate type. | 66| data | string \| ArrayBuffer | Yes | Certificate data. | 67 68 69## networkSecurity.certVerification 70 71certVerification(cert: CertBlob, caCert?: CertBlob): Promise\<number\> 72 73Obtains the preset CA certificate and custom CA certificate from the certificate management module, and verifies the certificate passed by the application. 74 75**System capability**: SystemCapability.Communication.NetStack 76 77**Parameters** 78 79| Name| Type | Mandatory| Description | 80| ------ | -------- | ---- | ---------------------- | 81| cert | CertBlob | Yes | Certificate to be verified. | 82| caCert | CertBlob | No | Custom CA certificate.| 83 84**Return values:** 85 86| Type | Description | 87| --------------- | ------------------------------------------------------------ | 88| Promise\<number\> | Promise used to return the result. The value **0** indicates that the certificate verification is successful, and a non-0 value indicates that the verification has failed.| 89 90**Error codes** 91 92| ID| Error Message | 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> **NOTE** 114> 115> If any of the preceding error codes is reported during certificate verification, rectify the error based on the detailed information about the error description. 116 117**Example** 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> **NOTE** 144> 145> Be sure to replace the certificate data in the example with the actual certificate data. 146 147 148 149## networkSecurity.certVerificationSync 150 151certVerificationSync(cert: CertBlob, caCert?: CertBlob): number 152 153Obtains the preset CA certificate and custom CA certificate from the certificate management module, and verifies the certificate passed by the application. 154 155**System capability**: SystemCapability.Communication.NetStack 156 157**Parameters** 158 159| Name| Type | Mandatory| Description | 160| ------ | -------- | ---- | ---------------------- | 161| cert | CertBlob | Yes | Certificate to be verified. | 162| caCert | CertBlob | No | Custom CA certificate.| 163 164**Return values:** 165 166| Type | Description | 167| ------ | ------------------------------------------------------------ | 168| number | Certificate verification result. The value **0** indicates that the certificate verification is successful, and a non-0 value indicates that the verification has failed.| 169 170**Error codes** 171 172| ID| Error Message | 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> **NOTE** 194> 195> If any of the preceding error codes is reported during certificate verification, rectify the error based on the detailed information about the error description. 196 197**Example** 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> **NOTE** 229> 230> Be sure to replace the certificate data in the example with the actual certificate data. 231 232## networkSecurity.isCleartextPermitted<sup>18+</sup> 233 234isCleartextPermitted(): boolean 235 236Checks whether plaintext HTTP access is allowed from the preset **network_config.json** file of the application. By default, plaintext HTTP access is allowed. 237 238**Required permissions**: ohos.permission.INTERNET 239 240**System capability**: SystemCapability.Communication.NetStack 241 242**Return values:** 243 244| Type | Description | 245| ------ | ------------------------------------------------------------ | 246| boolean | Boolean value indicating whether plaintext HTTP is allowed. The value **true** indicates that plaintext HTTP is allowed, and the value **false** indicates the opposite. The default value is **true**.| 247 248**Error codes** 249 250| ID| Error Message | 251| -------- | ---------------------------------------------------- | 252| 201 | Permission denied. | 253 254**Example** 255 256```ts 257import { networkSecurity } from '@kit.NetworkKit'; 258import { BusinessError } from '@kit.BasicServicesKit'; 259 260try { 261 let result: boolean = networkSecurity.isCleartextPermitted(); 262 console.info(`isCleartextPermitted Result: ${JSON.stringify(result)}`); 263} catch (error) { 264 console.error(`isCleartextPermitted Error: ${JSON.stringify(error)}`); 265} 266``` 267 268## networkSecurity.isCleartextPermittedByHostName<sup>18+</sup> 269 270isCleartextPermittedByHostName(hostName: string): boolean 271 272Checks whether host name–based plaintext HTTP access is allowed from the preset **network_config.json** file of the application. By default, plaintext HTTP access is allowed. 273 274**Required permissions**: ohos.permission.INTERNET 275 276**System capability**: SystemCapability.Communication.NetStack 277 278**Parameters** 279 280| Name| Type | Mandatory| Description | 281| ------ | -------- | ---- | ---------------------- | 282| hostName | string | Yes | Host name.| 283 284**Return values:** 285 286| Type | Description | 287| ------ | ------------------------------------------------------------ | 288| boolean | Boolean value indicating whether host name–based plaintext HTTP is allowed. The value **true** indicates that plaintext HTTP is allowed, and the value **false** indicates the opposite. The default value is **true**.| 289 290**Error codes** 291 292| ID| Error Message | 293| -------- | ---------------------------------------------------- | 294| 201 | Permission denied. | 295 296**Example** 297 298```ts 299import { networkSecurity } from '@kit.NetworkKit'; 300import { BusinessError } from '@kit.BasicServicesKit'; 301 302try { 303 let result: boolean = networkSecurity.isCleartextPermittedByHostName("xxx"); 304 console.info(`isCleartextPermitted Result: ${JSON.stringify(result)}`); 305} catch (error) { 306 console.error(`isCleartextPermitted Error: ${JSON.stringify(error)}`); 307} 308``` 309