• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Network Firewall
2
3## Introduction
4
5The network firewall module provides the following functions:
6- Basic firewall management functions, such as enabling and disabling of firewalls and firewall rules, and audit.
7- Firewall rule configuration, including the rule name, description, operation, applicable application, protocol type, address, port, and outbound/inbound direction.
8- DNS policy configuration, including the domain names allowed or not allowed for resolution and the DNS server (active or standby) used for resolution (application level).
9
10> **NOTE**
11> To maximize the application running efficiency, all APIs are called asynchronously in callback or promise mode. The following code examples use the promise mode. For details about the APIs, see [API Reference](../reference/apis-network-kit/js-apis-net-netfirewall.md).
12
13## When to Use
14
15Typical firewall scenarios include:
16- IP address-based access control
171. Restricting network access for specific applications
182. Restricting network communication to specific IP addresses, protocols, and ports
193. Restricting network communication of specific applications to specific IP addresses, protocols, and ports
204. Putting interception rules into effect immediately after delivery (This function is applicable only to the TCP protocol. An intercepted TCP connection must be disconnected.)
21- Domain name-based access control
221. Restricting DNS resolution of an application for specific domain names (This function is applicable to standard unencrypted DNS protocols, but not encrypted and private DNS protocols.)
232. Restricting DNS resolution of specific applications for specific domain names (This function is applicable to standard unencrypted DNS protocols, but not encrypted and private DNS protocols.)
243. Putting interception rules into effect immediately after delivery (This function is applicable only to the TCP protocol. An intercepted TCP connection must be disconnected.)
25<!--Del-->
26- Traceable network access
271. Query of interception records for system applications
282. Automatic saving of interception rules and automatic recovery upon startup
29<!--DelEnd-->
30
31The following describes the development procedure specific to each application scenario.
32
33## IP address-based access control
34
351. Use a network cable to connect the device to a network port.
362. Import the **netFirewall** namespace from **@kit.NetworkKit**.
37
38    ```ts
39    // Import the netFirewall namespace from @kit.NetworkKit.
40    import { netFirewall } from '@kit.NetworkKit';
41    import { BusinessError } from '@kit.BasicServicesKit';
42    ```
43
443. Call **setNetFirewallPolicy** to enable the firewall.
45
46    ```ts
47    interface IpType{
48          family:number;
49          type:number;
50          address?:string;
51          mask?:number;
52          startIp?:string;
53          endIp?:string;
54    }
55    interface IpPort{
56        startPort:number;
57        endPort:number;
58    }
59
60    // Define the firewall policy to enable the firewall and deny inbound traffic while allowing outbound traffic.
61    let policy: netFirewall.NetFirewallPolicy = {
62      isOpen: true,
63      inAction: netFirewall.FirewallRuleAction.RULE_DENY,
64      outAction: netFirewall.FirewallRuleAction.RULE_ALLOW
65    };
66    // Set the firewall policy for user 100.
67    netFirewall.setNetFirewallPolicy(100, policy).then(() => {
68      console.info("set firewall policy success.");
69    }).catch((error : BusinessError) => {
70      console.error("set firewall policy failed: " + JSON.stringify(error));
71    });
72    ```
73
744. Call **addNetFirewallRule** to add firewall rules.
75
76    ```ts
77    // Initialize firewall rules for specific types of IP addresses.
78    let ipRule: netFirewall.NetFirewallRule = {
79      name: "rule1",
80      description: "rule1 description",
81      direction: netFirewall.NetFirewallRuleDirection.RULE_IN,
82      action:netFirewall.FirewallRuleAction.RULE_DENY,
83      type: netFirewall.NetFirewallRuleType.RULE_IP,
84      isEnabled: true,
85      appUid: 20001,
86      localIps: [
87        {
88          family: 1,
89          type: 1,
90          address: "10.10.1.1",
91          mask: 24
92        },{
93          family: 1,
94          type: 2,
95          startIp: "10.20.1.1",
96          endIp: "10.20.1.10"
97        }] as IpType[],
98      remoteIps:[
99        {
100          family: 1,
101          type: 1,
102          address: "20.10.1.1",
103          mask: 24
104        },{
105          family: 1,
106          type: 2,
107          startIp: "20.20.1.1",
108          endIp: "20.20.1.10"
109        }] as IpType[],
110      protocol: 6,
111      localPorts: [
112        {
113          startPort: 1000,
114          endPort: 1000
115        },{
116          startPort: 2000,
117          endPort: 2001
118        }] as IpPort[],
119      remotePorts: [
120        {
121          startPort: 443,
122          endPort: 443
123        }] as IpPort[],
124      userId: 100
125    };
126    // Add firewall rules.
127    netFirewall.addNetFirewallRule(ipRule).then((result: number) => {
128      console.info('rule Id: ', result);
129    }, (reason: BusinessError) => {
130      console.error('add firewall rule failed: ', JSON.stringify(reason));
131    });
132    ```
133
134## Domain Name-based Access Control
135
1361. Use a network cable to connect the device to a network port.
1372. Import the **netFirewall** namespace from **@kit.NetworkKit**.
138
139    ```ts
140    // Import the netFirewall namespace from @kit.NetworkKit.
141    import { netFirewall } from '@kit.NetworkKit';
142    import { BusinessError } from '@kit.BasicServicesKit';
143    ```
144
1453. Call **setNetFirewallPolicy** to enable the firewall in user mode.
146
147    ```ts
148    interface domain{
149        isWildcard: boolean;
150        domain: string;
151    }
152
153    // Define the firewall policy to enable the firewall and deny inbound traffic while allowing outbound traffic.
154    let policy: netFirewall.NetFirewallPolicy = {
155      isOpen: true,
156      inAction: netFirewall.FirewallRuleAction.RULE_DENY,
157      outAction: netFirewall.FirewallRuleAction.RULE_ALLOW
158    };
159    // Set the firewall policy for user 100.
160    netFirewall.setNetFirewallPolicy(100, policy).then(() => {
161      console.info("set firewall policy success.");
162    }).catch((error : BusinessError) => {
163      console.error("set firewall policy failed: " + JSON.stringify(error));
164    });
165    ```
166
1674. Call **addNetFirewallRule** to add firewall rules in user mode.
168
169    ```ts
170    // Initialize firewall rules for specific types of domain names.
171    let domainRule: netFirewall.NetFirewallRule = {
172      name: "rule2",
173      description: "rule2 description",
174      direction: netFirewall.NetFirewallRuleDirection.RULE_IN,
175      action:netFirewall.FirewallRuleAction.RULE_DENY,
176      type: netFirewall.NetFirewallRuleType.RULE_DOMAIN,
177      isEnabled: true,
178      appUid: 20002,
179      domains: [
180        {
181          isWildcard: false,
182          domain: "www.openharmony.cn"
183        },{
184          isWildcard: true,
185          domain: "*.openharmony.cn"
186        }] as domain[],
187      userId: 100
188    };
189
190    // Add firewall rules.
191    netFirewall.addNetFirewallRule(domainRule).then((result: number) => {
192      console.info('rule Id: ', result);
193    }, (reason: BusinessError) => {
194      console.error('add firewall rule failed: ', JSON.stringify(reason));
195    });
196    ```
197
198<!--Del-->
199## Query of Firewall Interception Records
200
2011. Use a network cable to connect the device to a network port.
2022. Import the **netFirewall** namespace from **@kit.NetworkKit**.
203
204    ```ts
205    // Import the netFirewall namespace from @kit.NetworkKit.
206    import { netFirewall } from '@kit.NetworkKit';
207    import { BusinessError } from '@kit.BasicServicesKit';
208    ```
209
2103. Call **getInterceptRecords** to query firewall interception records in user mode.
211
212    ```ts
213    // Call getInterceptedRecords to perform pagination query on firewall interception records.
214    let interceptRecordParam: netFirewall.RequestParam = {
215      page: 1,
216      pageSize: 10,
217      orderField: netFirewall.NetFirewallOrderField.ORDER_BY_RECORD_TIME,
218      orderType: netFirewall.NetFirewallOrderType.ORDER_DESC
219    };
220    netFirewall.getInterceptedRecords(100, interceptRecordParam).then((result: netFirewall.InterceptedRecordPage) => {
221      console.info("result:", JSON.stringify(result));
222    }, (error: BusinessError) => {
223      console.error("get intercept records failed: " + JSON.stringify(error));
224    });
225    ```
226<!--DelEnd-->
227