1# 网络防火墙（仅对系统应用开放）
2
3## 简介
4
5网络防火墙提供如下功能：
6- 防火墙的基础能力，包括防火墙的使能、规则的启用与禁用、审计能力
7- 防火墙规则的配置能力，包括规则的名称、描述、操作、生效应用、协议类型、地址、端口、出站/入站方向等
8- DNS策略的配置能力，包括配置禁止/允许解析的域名、解析使用的DNS服务器（主选/备选）（应用级）
9
10> **说明：**
11> 为了保证应用的运行效率，所有API调用都是异步的，对于异步调用的API均提供了Promise的方式，以下示例均采用promise方式，更多方式可以查阅[API参考](../reference/apis-network-kit/js-apis-net-netfirewall.md)。
12
13## 约束
14
15- 开发语言：JS
16
17## 场景介绍
18
19防火墙的典型场景有：
20- 针对特定IP联网访问控制
211. 支持限制特定应用访问网络
222. 支持限制对特定IP、特定协议、特定端口的网络通信
233. 支持限制特定应用对特定IP、特定协议、特定端口的网络通信
244. 支持拦截规则下发后立即生效（此点针对TCP协议：需断开已有被拦截的TCP连接）
25- 针对域名联网访问控制支持拦截
261. 支持限制应用对特定域名的DNS解析能力（仅限制非加密标准DNS协议，不限制加密、私标DNS协议）
272. 支持限制特地应用对特定域名的DNS解析能力（仅限制非加密标准DNS协议，不限制加密、私标DNS协议）
283. 支持拦截规则下发后立即生效（此点针对TCP协议：需断开已有被拦截的TCP连接）
29- 联网访问控制支持可追溯
301. 支持拦截记录追溯，支持对系统应用提供查询拦截记录的能力
312. 支持所有拦截规则的自动保存和开机自动恢复
32
33以下分别介绍具体开发方式。
34
35## 接口说明
36
37完整的JS API说明以及实例代码请参考：[网络防火墙](../reference/apis-network-kit/js-apis-net-netfirewall.md)。
38
39| 接口                                                                                               | 描述              |
40| -------------------------------------------------------------------------------------------------- | ----------------- |
41| setNetFirewallPolicy(userId: number, policy: NetFirewallPolicy): Promise\<void>                    | 设置防火墙状态    |
42| getNetFirewallPolicy(userId: number): Promise\<NetFirewallPolicy>                                  | 查询防火墙状态    |
43| addNetFirewallRule(rule: NetFirewallRule): Promise\<number>                                        | 添加防火墙规则    |
44| updateNetFirewallRule(rule: NetFirewallRule): Promise\<void>                                       | 更新防火墙规则    |
45| removeNetFirewallRule(userId: number, ruleId: number): Promise\<void>                              | 删除防火墙规则    |
46| getNetFirewallRules(userId: number, requestParam: RequestParam): Promise\<FirewallRulePage>        | 分页查询防火墙规则 |
47| getNetFirewallRule(userId: number, ruleId: number): Promise\<NetFirewallRule>                      | 查询单条防火墙规则 |
48| getInterceptedRecords(userId: number, requestParam: RequestParam): Promise\<InterceptedRecordPage> | 查询防火墙拦截记录 |
49
50## 针对特定IP联网访问控制
51
521. 设备通过硬件接口，插入网线。
532. 从@ohos.net.netFirewall中导入netfirewall命名空间。
543. 用户调用setNetFirewallPolicy方法，打开防火墙。
554. 用户通过addNetFirewallRule方法，添加防火墙规则。
56
57```ts
58// 从@kit.NetworkKit中导入netFirewall命名空间
59import { netFirewall } '@kit.NetworkKit';
60import { BusinessError } from '@kit.BasicServicesKit';
61
62// 定义防火墙策略：打开，入站阻止，出站允许
63let policy: netFirewall.NetFirewallPolicy = {
64  isOpen: true,
65  inAction: netFirewall.FirewallRuleAction.RULE_DENY,
66  outAction: netFirewall.FirewallRuleAction.RULE_ALLOW
67};
68// 给用户100设置防火墙策略
69netFirewall.setNetFirewallPolicy(100, policy).then(() => {
70  console.info("set firewall policy success.");
71}).catch((error : BusinessError) => {
72  console.error("set firewall policy failed: " + JSON.stringify(error));
73});
74
75// 初始化具体的防火墙ip类型规则
76let ipRule: netFirewall.NetFirewallRule = {
77  name: "rule1",
78  description: "rule1 description",
79  direction: netFirewall.NetFirewallRuleDirection.RULE_IN,
80  action:netFirewall.NetFirewallRuleDirection.RULE_DENY,
81  type: netFirewall.NetFirewallRuleType.RULE_IP,
82  isEnabled: true,
83  appUid: 20001,
84  localIps: [
85    {
86      family: 1,
87      type: 1,
88      address: "10.10.1.1",
89      mask: 24
90    },{
91      family: 1,
92      type: 2,
93      startIp: "10.20.1.1",
94      endIp: "10.20.1.10"
95    }],
96  remoteIps:[
97    {
98      family: 1,
99      type: 1,
100      address: "20.10.1.1",
101      mask: 24
102    },{
103      family: 1,
104      type: 2,
105      startIp: "20.20.1.1",
106      endIp: "20.20.1.10"
107    }],
108  protocol: 6,
109  localPorts: [
110    {
111      startPort: 1000,
112      endPort: 1000
113    },{
114      startPort: 2000,
115      endPort: 2001
116    }],
117  remotePorts: [
118    {
119      startPort: 443,
120      endPort: 443
121    }],
122  userId: 100
123};
124// 添加防火墙规则
125netFirewall.addNetFirewallRule(ipRule).then((result: number) => {
126  console.info('rule Id: ', result);
127}, (reason: BusinessError) => {
128  console.error('add firewall rule failed: ', JSON.stringify(reason));
129});
130```
131
132## 针对域名联网访问控制支持拦截
133
1341. 设备通过硬件接口，插入网线。
1352. 从@ohos.net.netfirewall中导入netFirewall命名空间。
1363. 用户态调用setNetFirewallPolicy方法，打开防火墙。
1374. 用户态通过addNetFirewallRule方法，添加防火墙规则。
138
139```ts
140// 从@kit.NetworkKit中导入netFirewall命名空间
141import { netFirewall } '@kit.NetworkKit';
142import { BusinessError } from '@kit.BasicServicesKit';
143
144// 定义防火墙策略：打开，入站阻止，出站允许
145let policy: netFirewall.NetFirewallPolicy = {
146  isOpen: true,
147  inAction: netFirewall.FirewallRuleAction.RULE_DENY,
148  outAction: netFirewall.FirewallRuleAction.RULE_ALLOW
149};
150// 给用户100设置防火墙策略
151netFirewall.setNetFirewallPolicy(100, policy).then(() => {
152  console.info("set firewall policy success.");
153}).catch((error : BusinessError) => {
154  console.error("set firewall policy failed: " + JSON.stringify(error));
155});
156
157// 初始化具体的防火墙域名类型规则
158let domainRule: netFirewall.NetFirewallRule = {
159  name: "rule2",
160  description: "rule2 description",
161  direction: netFirewall.NetFirewallRuleDirection.RULE_IN,
162  action:netFirewall.NetFirewallRuleDirection.RULE_DENY,
163  type: netFirewall.NetFirewallRuleType.RULE_DOMAIN,
164  isEnabled: true,
165  appUid: 20002,
166  domains: [
167    {
168      isWildcard: false,
169      domain: "www.openharmony.cn"
170    },{
171      isWildcard: true,
172      domain: "*.openharmony.cn"
173    }],
174  userId: 100
175};
176// 添加防火墙规则
177netFirewall.addNetFirewallRule(domainRule).then((result: number) => {
178  console.info('rule Id: ', result);
179}, (reason: BusinessError) => {
180  console.error('add firewall rule failed: ', JSON.stringify(reason));
181});
182```
183
184## 查询防火墙拦截记录
185
1861. 设备通过硬件接口，插入网线。
1872. 从@ohos.net.netFirewall中导入netfirewall命名空间。
1883. 用户态通过getInterceptRecords方法查询拦截记录。
189
190```ts
191// 从@kit.NetworkKit中导入netFirewall命名空间
192import { netFirewall } '@kit.NetworkKit';
193import { BusinessError } from '@kit.BasicServicesKit';
194
195// 通过getInterceptedRecords方法分页查询拦截记录
196let interceptRecordParam: netFirewall.RequestParam = {
197  page: 1,
198  pageSize: 10,
199  orderField: netFirewall.NetFirewallOrderField.ORDER_BY_RECORD_TIME,
200  orderType: netFirewall.NetFirewallOrderType.ORDER_DESC
201};
202netFirewall.getInterceptedRecords(100, interceptRecordParam).then((result: netFirewall.InterceptedRecordPage) => {
203  console.info("result:", JSON.stringify(result));
204}, (error: BusinessError) => {
205  console.error("get intercept records failed: " + JSON.stringify(error));
206});
207```
208