• 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## **Constraints**
14
15- Programming language: JS
16
17## When to Use
18
19Typical firewall scenarios include:
20- IP address-based access control
211. Restricting network access for specific applications
222. Restricting network communication to specific IP addresses, protocols, and ports
233. Restricting network communication of specific applications to specific IP addresses, protocols, and ports
244. 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- Domain name-based access control
261. 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.)
272. 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.)
283. Putting interception rules into effect immediately after delivery (This function is applicable only to the TCP protocol. An intercepted TCP connection must be disconnected.)
29<!--Del-->
30- Traceable network access
311. Query of interception records for system applications
322. Automatic saving of interception rules and automatic recovery upon startup
33<!--DelEnd-->
34
35The following describes the development procedure specific to each application scenario.
36
37## Available APIs
38
39For the complete list of APIs and example code, see [Network Firewall](../reference/apis-network-kit/js-apis-net-netfirewall.md).
40
41| Name                                                                                              | Description             |
42| -------------------------------------------------------------------------------------------------- | ----------------- |
43| setNetFirewallPolicy(userId: number, policy: NetFirewallPolicy): Promise\<void>                    | Sets a firewall policy.   |
44| getNetFirewallPolicy(userId: number): Promise\<NetFirewallPolicy>                                  | Obtains a firewall policy.   |
45| addNetFirewallRule(rule: NetFirewallRule): Promise\<number>                                        | Adds a firewall rule.   |
46| updateNetFirewallRule(rule: NetFirewallRule): Promise\<void>                                       | Updates a firewall rule.  |
47| removeNetFirewallRule(userId: number, ruleId: number): Promise\<void>                              | Removes a firewall rule.   |
48| getNetFirewallRules(userId: number, requestParam: RequestParam): Promise\<FirewallRulePage>        | Performs pagination query on firewall rules.|
49| getNetFirewallRule(userId: number, ruleId: number): Promise\<NetFirewallRule>                      | Queries a firewall rule.|
50| <!--DelRow-->getInterceptedRecords(userId: number, requestParam: RequestParam): Promise\<InterceptedRecordPage> | Queries firewall interception records.|
51
52## IP address-based access control
53
541. Use a network cable to connect the device to a network port.
552. Import the **netFirewall** namespace from **@kit.NetworkKit**.
563. Call **setNetFirewallPolicy** to enable the firewall.
574. Call **addNetFirewallRule** to add firewall rules.
58
59```ts
60// Import the netFirewall namespace from @kit.NetworkKit.
61import { netFirewall } '@kit.NetworkKit';
62import { BusinessError } from '@kit.BasicServicesKit';
63
64// Define the firewall policy to enable the firewall and deny inbound traffic while allowing outbound traffic.
65let policy: netFirewall.NetFirewallPolicy = {
66  isOpen: true,
67  inAction: netFirewall.FirewallRuleAction.RULE_DENY,
68  outAction: netFirewall.FirewallRuleAction.RULE_ALLOW
69};
70// Set the firewall policy for user 100.
71netFirewall.setNetFirewallPolicy(100, policy).then(() => {
72  console.info("set firewall policy success.");
73}).catch((error : BusinessError) => {
74  console.error("set firewall policy failed: " + JSON.stringify(error));
75});
76
77// Initialize firewall rules for specific types of IP addresses.
78let ipRule: netFirewall.NetFirewallRule = {
79  name: "rule1",
80  description: "rule1 description",
81  direction: netFirewall.NetFirewallRuleDirection.RULE_IN,
82  action:netFirewall.NetFirewallRuleDirection.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    }],
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    }],
110  protocol: 6,
111  localPorts: [
112    {
113      startPort: 1000,
114      endPort: 1000
115    },{
116      startPort: 2000,
117      endPort: 2001
118    }],
119  remotePorts: [
120    {
121      startPort: 443,
122      endPort: 443
123    }],
124  userId: 100
125};
126// Add firewall rules.
127netFirewall.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**.
1383. Call **setNetFirewallPolicy** to enable the firewall in user mode.
1394. Call **addNetFirewallRule** to add firewall rules in user mode.
140
141```ts
142// Import the netFirewall namespace from @kit.NetworkKit.
143import { netFirewall } '@kit.NetworkKit';
144import { BusinessError } from '@kit.BasicServicesKit';
145
146// Define the firewall policy to enable the firewall and deny inbound traffic while allowing outbound traffic.
147let policy: netFirewall.NetFirewallPolicy = {
148  isOpen: true,
149  inAction: netFirewall.FirewallRuleAction.RULE_DENY,
150  outAction: netFirewall.FirewallRuleAction.RULE_ALLOW
151};
152// Set the firewall policy for user 100.
153netFirewall.setNetFirewallPolicy(100, policy).then(() => {
154  console.info("set firewall policy success.");
155}).catch((error : BusinessError) => {
156  console.error("set firewall policy failed: " + JSON.stringify(error));
157});
158
159// Initialize firewall rules for specific types of domain names.
160let domainRule: netFirewall.NetFirewallRule = {
161  name: "rule2",
162  description: "rule2 description",
163  direction: netFirewall.NetFirewallRuleDirection.RULE_IN,
164  action:netFirewall.NetFirewallRuleDirection.RULE_DENY,
165  type: netFirewall.NetFirewallRuleType.RULE_DOMAIN,
166  isEnabled: true,
167  appUid: 20002,
168  domains: [
169    {
170      isWildcard: false,
171      domain: "www.openharmony.cn"
172    },{
173      isWildcard: true,
174      domain: "*.openharmony.cn"
175    }],
176  userId: 100
177};
178// Add firewall rules.
179netFirewall.addNetFirewallRule(domainRule).then((result: number) => {
180  console.info('rule Id: ', result);
181}, (reason: BusinessError) => {
182  console.error('add firewall rule failed: ', JSON.stringify(reason));
183});
184```
185
186<!--Del-->
187## Query of Firewall Interception Records
188
1891. Use a network cable to connect the device to a network port.
1902. Import the **netFirewall** namespace from **@kit.NetworkKit**.
1913. Call **getInterceptRecords** to query firewall interception records in user mode.
192
193```ts
194// Import the netFirewall namespace from @kit.NetworkKit.
195import { netFirewall } '@kit.NetworkKit';
196import { BusinessError } from '@kit.BasicServicesKit';
197
198// Call getInterceptedRecords to perform pagination query on firewall interception records.
199let interceptRecordParam: netFirewall.RequestParam = {
200  page: 1,
201  pageSize: 10,
202  orderField: netFirewall.NetFirewallOrderField.ORDER_BY_RECORD_TIME,
203  orderType: netFirewall.NetFirewallOrderType.ORDER_DESC
204};
205netFirewall.getInterceptedRecords(100, interceptRecordParam).then((result: netFirewall.InterceptedRecordPage) => {
206  console.info("result:", JSON.stringify(result));
207}, (error: BusinessError) => {
208  console.error("get intercept records failed: " + JSON.stringify(error));
209});
210```
211<!--DelEnd-->
212