智能客服
你问我答,随时在线为你解决问题
本模块为应用程序提供网络防火墙能力。应用程序可以对机器进行防火墙拦截记录的查询。
本模块首批接口从API version 15开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
- import { netFirewall } from '@kit.NetworkKit';
setNetFirewallPolicy(userId: number, policy: NetFirewallPolicy): Promise<void>
设置系统用户ID的防火墙策略,包含防火墙开关状态,默认的出站/入站行为(允许/阻止)。支持不同的系统用户ID配置不同的防火墙策略。使用Promise异步回调。
同一系统用户下,多应用调用该接口下发策略,会以最新下发的策略为准。
需要权限:ohos.permission.MANAGE_NET_FIREWALL
系统能力:SystemCapability.Communication.NetManager.NetFirewall
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | number | 是 | 系统用户ID,只能是存在的用户ID。 |
| policy | NetFirewallPolicy | 是 | 设置的防火墙策略。 |
返回值:
| 类型 | 说明 |
|---|---|
| Promise<void> | 无返回结果的Promise对象。 |
错误码:
以下错误码的详细介绍请参见通用错误码、网络连接管理错误码和防火墙错误码。
| 错误码ID | 错误信息 |
|---|---|
| 201 | Permission denied. |
| 401 | Parameter error. |
| 2100001 | Invalid parameter value. |
| 2100002 | Operation failed. Cannot connect to service. |
| 2100003 | System internal error. |
| 29400000 | The specified user does not exist. |
示例:
- import { netFirewall } from '@kit.NetworkKit';
- import { BusinessError } from '@kit.BasicServicesKit';
-
- let policy: netFirewall.NetFirewallPolicy = {
- isOpen: true,
- inAction: netFirewall.FirewallRuleAction.RULE_DENY,
- outAction: netFirewall.FirewallRuleAction.RULE_ALLOW
- };
- netFirewall.setNetFirewallPolicy(100, policy).then(() => {
- console.info("set firewall policy success.");
- }).catch((error : BusinessError) => {
- console.error("set firewall policy failed: " + JSON.stringify(error));
- });
getNetFirewallPolicy(userId: number): Promise<NetFirewallPolicy>
查询系统用户ID的防火墙策略,包含防火墙开关状态,默认出站入站行为(允许/阻止)。使用Promise异步回调。
需要权限:ohos.permission.GET_NET_FIREWALL
系统能力:SystemCapability.Communication.NetManager.NetFirewall
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | number | 是 | 系统用户ID,只能是存在的用户ID。 |
返回值:
| 类型 | 说明 |
|---|---|
| Promise<NetFirewallPolicy> | 以Promise形式返回当前用户防火墙策略。 |
错误码:
以下错误码的详细介绍请参见通用错误码、网络连接管理错误码和防火墙错误码。
| 错误码ID | 错误信息 |
|---|---|
| 201 | Permission denied. |
| 401 | Parameter error. |
| 2100001 | Invalid parameter value. |
| 2100002 | Operation failed. Cannot connect to service. |
| 2100003 | System internal error. |
| 29400000 | The specified user does not exist. |
示例:
- import { netFirewall } from '@kit.NetworkKit';
- import { BusinessError } from '@kit.BasicServicesKit';
-
- netFirewall.getNetFirewallPolicy(100).then((result: netFirewall.NetFirewallPolicy) => {
- console.info('firewall policy: ', JSON.stringify(result));
- }, (reason: BusinessError) => {
- console.error('get firewall policy failed: ', JSON.stringify(reason));
- });
addNetFirewallRule(rule: NetFirewallRule): Promise<number>
添加系统用户ID的防火墙规则,目前支持的规则类型有:IP、Domain、DNS。使用Promise异步回调。
防火墙规则优先级说明(setNetFirewallPolicy和addNetFirewallRule无调用顺序要求):
规则类型补充说明:
防火墙规则添加上限说明:
需要权限:ohos.permission.MANAGE_NET_FIREWALL
系统能力:SystemCapability.Communication.NetManager.NetFirewall
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| rule | NetFirewallRule | 是 | 防火墙规则。 |
返回值:
| 类型 | 说明 |
|---|---|
| Promise<number> | 以Promise形式返回防火墙规则ID,防火墙规则ID由系统自动生成。 |
错误码:
以下错误码的详细介绍请参见通用错误码、网络连接管理错误码和防火墙错误码。
| 错误码ID | 错误信息 |
|---|---|
| 201 | Permission denied. |
| 401 | Parameter error. |
| 2100001 | Invalid parameter value. |
| 2100002 | Operation failed. Cannot connect to service. |
| 2100003 | System internal error. |
| 29400000 | The specified user does not exist. |
| 29400001 | The number of firewall rules exceeds the maximum. |
| 29400002 | The number of IP address rules in the firewall rule exceeds the maximum. |
| 29400003 | The number of port rules in the firewall rule exceeds the maximum. |
| 29400004 | The number of domain rules in the firewall rule exceeds the maximum. |
| 29400005 | The number of domain rules exceeds the maximum. |
| 29400007 | The dns rule is duplication. |
示例:
- import { netFirewall } from '@kit.NetworkKit';
- import { BusinessError } from '@kit.BasicServicesKit';
-
- let ipRule: netFirewall.NetFirewallRule = {
- name: "rule1",
- description: "rule1 description",
- direction: netFirewall.NetFirewallRuleDirection.RULE_IN,
- action:netFirewall.FirewallRuleAction.RULE_DENY,
- type: netFirewall.NetFirewallRuleType.RULE_IP,
- isEnabled: true,
- appUid: 20001,
- localIps: [
- {
- family: 1,
- type: 1,
- address: "10.10.1.1",
- mask: 32
- },{
- family: 1,
- type: 2,
- startIp: "10.20.1.1",
- endIp: "10.20.1.10"
- }],
- remoteIps:[
- {
- family: 1,
- type: 1,
- address: "20.10.1.1",
- mask: 32
- },{
- family: 1,
- type: 2,
- startIp: "20.20.1.1",
- endIp: "20.20.1.10"
- }],
- protocol: 6,
- localPorts: [
- {
- startPort: 1000,
- endPort: 1000
- },{
- startPort: 2000,
- endPort: 2001
- }],
- remotePorts: [
- {
- startPort: 443,
- endPort: 443
- }],
- userId: 100,
- interface:"wlan0" // 从API版本26.0.0开始支持
- };
- netFirewall.addNetFirewallRule(ipRule).then((result: number) => {
- console.info('rule Id: ', result);
- }, (reason: BusinessError) => {
- console.error('add firewall rule failed: ', JSON.stringify(reason));
- });
-
- let domainRule: netFirewall.NetFirewallRule = {
- name: "rule2",
- description: "rule2 description",
- direction: netFirewall.NetFirewallRuleDirection.RULE_IN,
- action:netFirewall.FirewallRuleAction.RULE_DENY,
- type: netFirewall.NetFirewallRuleType.RULE_DOMAIN,
- isEnabled: true,
- appUid: 20002,
- domains: [
- {
- isWildcard: false,
- domain: "www.example.cn"
- },{
- isWildcard: true,
- domain: "*.example.cn"
- },{
- isWildcard: true,
- domain: "*w.example.cn" // 从API版本26.0.0开始支持
- },{
- isWildcard: true,
- domain: "www.example.*" // 从API版本26.0.0开始支持
- },{
- isWildcard: true,
- domain: "www.example.c*" // 从API版本26.0.0开始支持
- }],
- userId: 100,
- interface:"wlan0" // 从API版本26.0.0开始支持
- };
- netFirewall.addNetFirewallRule(domainRule).then((result: number) => {
- console.info('rule Id: ', result);
- }, (reason: BusinessError) => {
- console.error('add firewall rule failed: ', JSON.stringify(reason));
- });
-
- let dnsRule: netFirewall.NetFirewallRule = {
- name: "rule3",
- description: "rule3 description",
- direction: netFirewall.NetFirewallRuleDirection.RULE_IN,
- action:netFirewall.FirewallRuleAction.RULE_DENY,
- type: netFirewall.NetFirewallRuleType.RULE_DNS,
- isEnabled: true,
- appUid: 20003,
- dns:{
- primaryDns: "4.4.4.4",
- standbyDns: "8.8.8.8",
- },
- userId: 100,
- interface:"wlan0" // 从API版本26.0.0开始支持
- };
- netFirewall.addNetFirewallRule(dnsRule).then((result: number) => {
- console.info('rule Id: ', result);
- }, (reason: BusinessError) => {
- console.error('add firewall rule failed: ', JSON.stringify(reason));
- });
removeNetFirewallRule(userId: number, ruleId: number): Promise<void>
删除系统用户ID的指定防火墙规则。使用Promise异步回调。
需要权限:ohos.permission.MANAGE_NET_FIREWALL
系统能力:SystemCapability.Communication.NetManager.NetFirewall
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | number | 是 | 系统用户ID,只能是存在的用户ID。 |
| ruleId | number | 是 | 防火墙规则ID。 |
返回值:
| 类型 | 说明 |
|---|---|
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
错误码:
以下错误码的详细介绍请参见通用错误码、网络连接管理错误码和防火墙错误码。
| 错误码ID | 错误信息 |
|---|---|
| 201 | Permission denied. |
| 401 | Parameter error. |
| 2100001 | Invalid parameter value. |
| 2100002 | Operation failed. Cannot connect to service. |
| 2100003 | System internal error. |
| 29400000 | The specified user does not exist. |
| 29400006 | The specified rule does not exist. |
示例:
- import { netFirewall } from '@kit.NetworkKit';
- import { BusinessError } from '@kit.BasicServicesKit';
-
- netFirewall.removeNetFirewallRule(100, 1).then(() => {
- console.info("delete firewall rule success.");
- }).catch((error : BusinessError) => {
- console.error("delete firewall rule failed: " + JSON.stringify(error));
- });
updateNetFirewallRule(rule: NetFirewallRule): Promise<void>
更新防火墙规则。使用Promise异步回调。
需要权限:ohos.permission.MANAGE_NET_FIREWALL
系统能力:SystemCapability.Communication.NetManager.NetFirewall
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| rule | NetFirewallRule | 是 | 防火墙规则。 |
返回值:
| 类型 | 说明 |
|---|---|
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
错误码:
以下错误码的详细介绍请参见通用错误码、网络连接管理错误码和防火墙错误码。
| 错误码ID | 错误信息 |
|---|---|
| 201 | Permission denied. |
| 401 | Parameter error. |
| 2100001 | Invalid parameter value. |
| 2100002 | Operation failed. Cannot connect to service. |
| 2100003 | System internal error. |
| 29400000 | The specified user does not exist. |
| 29400002 | The number of IP address rules in the firewall rule exceeds the maximum. |
| 29400003 | The number of port rules in the firewall rule exceeds the maximum. |
| 29400004 | The number of domain rules in the firewall rule exceeds the maximum. |
| 29400005 | The number of domain rules exceeds the maximum. |
| 29400006 | The specified rule does not exist. |
| 29400007 | The dns rule is duplication. |
示例:
- import { netFirewall } from '@kit.NetworkKit';
- import { BusinessError } from '@kit.BasicServicesKit';
-
- let ipRuleUpd: netFirewall.NetFirewallRule = {
- id: 1,
- name: "rule1",
- description: "rule1 description update",
- direction: netFirewall.NetFirewallRuleDirection.RULE_IN,
- action:netFirewall.FirewallRuleAction.RULE_DENY,
- type: netFirewall.NetFirewallRuleType.RULE_IP,
- isEnabled: false,
- appUid: 20001,
- localIps: [
- {
- family: 1,
- type: 1,
- address: "10.10.1.1",
- mask: 32
- },{
- family: 1,
- type: 2,
- startIp: "10.20.1.1",
- endIp: "10.20.1.10"
- }],
- userId: 100,
- interface:"wlan0" // 从API版本26.0.0开始支持
- };
- netFirewall.updateNetFirewallRule(ipRuleUpd).then(() => {
- console.info('update firewall rule success.');
- }, (reason: BusinessError) => {
- console.error('update firewall rule failed: ', JSON.stringify(reason));
- });
getNetFirewallRules(userId: number, requestParam: RequestParam): Promise<FirewallRulePage>
按用户ID获取防火墙规则,需要指定分页查询参数。目前支持根据防火墙规则名排序。使用Promise异步回调。
需要权限:ohos.permission.GET_NET_FIREWALL
系统能力:SystemCapability.Communication.NetManager.NetFirewall
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | number | 是 | 系统用户ID,只能是存在的用户ID。 |
| requestParam | RequestParam | 是 | 分页查询参数,其中orderField字段仅支持根据防火墙规则名排序。 |
返回值:
| 类型 | 说明 |
|---|---|
| Promise<FirewallRulePage> | 以Promise形式返回防火墙分页规则列表。 |
错误码:
以下错误码的详细介绍请参见通用错误码、网络连接管理错误码和防火墙错误码。
| 错误码ID | 错误信息 |
|---|---|
| 201 | Permission denied. |
| 401 | Parameter error. |
| 2100001 | Invalid parameter value. |
| 2100002 | Operation failed. Cannot connect to service. |
| 2100003 | System internal error. |
| 29400000 | The specified user does not exist. |
示例:
- import { netFirewall } from '@kit.NetworkKit';
- import { BusinessError } from '@kit.BasicServicesKit';
-
- let ruleParam: netFirewall.RequestParam = {
- page: 1,
- pageSize: 10,
- orderField: netFirewall.NetFirewallOrderField.ORDER_BY_RULE_NAME,
- orderType: netFirewall.NetFirewallOrderType.ORDER_ASC
- };
- netFirewall.getNetFirewallRules(100, ruleParam).then((result: netFirewall.FirewallRulePage) => {
- console.info("result:", JSON.stringify(result));
- }, (error: BusinessError) => {
- console.error("get firewall rules failed: " + JSON.stringify(error));
- });
getNetFirewallRule(userId: number, ruleId: number): Promise<NetFirewallRule>
通过userId和ruleId获取指定的防火墙规则。使用Promise异步回调。
需要权限:ohos.permission.GET_NET_FIREWALL
系统能力:SystemCapability.Communication.NetManager.NetFirewall
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | number | 是 | 系统用户ID,只能是存在的用户ID。 |
| ruleId | number | 是 | 防火墙规则ID。 |
返回值:
| 类型 | 说明 |
|---|---|
| Promise<NetFirewallRule> | 以Promise形式返回防火墙规则。 |
错误码:
以下错误码的详细介绍请参见通用错误码、网络连接管理错误码和防火墙错误码。
| 错误码ID | 错误信息 |
|---|---|
| 201 | Permission denied. |
| 401 | Parameter error. |
| 2100001 | Invalid parameter value. |
| 2100002 | Operation failed. Cannot connect to service. |
| 2100003 | System internal error. |
| 29400000 | The specified user does not exist. |
| 29400006 | The specified rule does not exist. |
示例:
- import { netFirewall } from '@kit.NetworkKit';
- import { BusinessError } from '@kit.BasicServicesKit';
-
- netFirewall.getNetFirewallRule(100, 1).then((rule: netFirewall.NetFirewallRule) => {
- console.info("result:", JSON.stringify(rule));
- }).catch((error : BusinessError) => {
- console.error(" get firewall rules failed: " + JSON.stringify(error));
- });
防火墙规则信息结构。
系统能力:SystemCapability.Communication.NetManager.NetFirewall
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| userId | number | 否 | 否 | 系统用户ID,只能是存在的用户ID。 |
| name | string | 否 | 否 | 规则名称,必填,最多128个字符。 |
| direction | NetFirewallRuleDirection | 否 | 否 | 规则方向,包含入站和出站。 |
| action | FirewallRuleAction | 否 | 否 | 行为,包含允许和阻止。 |
| type | NetFirewallRuleType | 否 | 否 | 规则类型,包含IP、Domain、DNS。 |
| isEnabled | boolean | 否 | 否 | 是否启用规则。true表示启用,false表示不启用。 |
| id | number | 否 | 是 | 防火墙规则的ID。 |
| description | string | 否 | 是 | 规则描述,可选,最多256个字符。 |
| appUid | number | 否 | 是 | 应用程序或服务UID。 |
| localIps | Array<NetFirewallIpParams> | 否 | 是 | 本地IP地址。当type=RULE_IP时有效,否则将被忽略,最多10个。 |
| remoteIps | Array<NetFirewallIpParams> | 否 | 是 | 远端IP地址。当type=RULE_IP时有效,否则将被忽略,最多10个。 |
| protocol | number | 否 | 是 | 协议,包含TCP:6,UDP:17。当type=RULE_IP时有效。 |
| localPorts | Array<NetFirewallPortParams> | 否 | 是 | 本地端口。当type=RULE_IP时有效,否则将被忽略,最多10个。 |
| remotePorts | Array<NetFirewallPortParams> | 否 | 是 | 远端端口。当type=RULE_IP时有效,否则将被忽略。最多10个。 |
| domains | Array<NetFirewallDomainParams> | 否 | 是 | 域名列表,当type=RULE_DOMAIN时有效,否则将被忽略,目前不支持中文域名。 |
| dns | NetFirewallDnsParams | 否 | 是 | DNS:当type=RULE_DNS时有效,否则将被忽略。当type=RULE_DNS时,该字段不能为空。 |
| interface | string | 否 | 是 | 物理网卡名称,例如wlan0。当type=RULE_IP时有效,否则将被忽略。可选,最多16个字符。 起始版本:26.0.0 模型约束:此接口仅可在Stage模型下使用。 |
查询输入信息结构。
系统能力:SystemCapability.Communication.NetManager.NetFirewall
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| page | number | 否 | 否 | 页码,值范围:[1, 1000]。 |
| pageSize | number | 否 | 否 | 页面大小,值范围:[1, 50]。 |
| orderField | NetFirewallOrderField | 否 | 否 | 排序方法。 该字段仅支持根据防火墙规则名排序。 |
| orderType | NetFirewallOrderType | 否 | 否 | 排序顺序。 |
防火墙规则页信息结构。
系统能力:SystemCapability.Communication.NetManager.NetFirewall
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| page | number | 否 | 否 | 当前页码,值范围:[1,1000]。 |
| pageSize | number | 否 | 否 | 页大小,值范围:[1,50]。 |
| totalPage | number | 否 | 否 | 总页数,值范围:[1,1000]。 |
| data | Array<NetFirewallRule> | 否 | 否 | 页面数据。 |
防火墙策略,包含防火墙开关状态,默认的出站/入站行为(允许/阻止)。
系统能力:SystemCapability.Communication.NetManager.NetFirewall
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| isOpen | boolean | 否 | 否 | 是否开启防火墙。true表示开启防火墙,false表示关闭防火墙。 |
| inAction | FirewallRuleAction | 否 | 否 | 入站行为。 |
| outAction | FirewallRuleAction | 否 | 否 | 出站行为。 |
枚举类型,防火墙规则方向,包含入站、出站。
系统能力:SystemCapability.Communication.NetManager.NetFirewall
| 名称 | 值 | 说明 |
|---|---|---|
| RULE_IN | 1 | 入站。 |
| RULE_OUT | 2 | 出站。 |
枚举类型,防火墙规则行为,包含允许网络连接、阻止网络连接。
系统能力:SystemCapability.Communication.NetManager.NetFirewall
| 名称 | 值 | 说明 |
|---|---|---|
| RULE_ALLOW | 0 | 允许。 |
| RULE_DENY | 1 | 阻止。 |
枚举类型,防火墙规则类型,包含IP、Domain、DNS。
系统能力:SystemCapability.Communication.NetManager.NetFirewall
| 名称 | 值 | 说明 |
|---|---|---|
| RULE_IP | 1 | IP类规则。 |
| RULE_DOMAIN | 2 | 域名类规则。 |
| RULE_DNS | 3 | DNS规则。 |
枚举类型,防火墙规则排序方法。
getNetFirewallRules接口,仅支持ORDER_BY_RULE_NAME字段。
系统能力:SystemCapability.Communication.NetManager.NetFirewall
| 名称 | 值 | 说明 |
|---|---|---|
| ORDER_BY_RULE_NAME | 1 | 根据防火墙规则名排序。 |
| ORDER_BY_RECORD_TIME | 100 | 根据记录时间排序。 |
枚举类型,防火墙规则排序顺序,包含升序或降序。
系统能力:SystemCapability.Communication.NetManager.NetFirewall
| 名称 | 值 | 说明 |
|---|---|---|
| ORDER_ASC | 1 | 按防火墙规则排序类型升序排序。 |
| ORDER_DESC | 100 | 按防火墙规则排序类型降序排序。 |
防火墙规则的IP参数,IP类型包括IPv4、IPv6,支持单个IP或IP段。
系统能力:SystemCapability.Communication.NetManager.NetFirewall
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| type | number | 否 | 否 | 1:IP地址或子网。该场景下必须指定address和mask字段,当使用单个IP时,mask字段需设置为32。 2:IP段,该场景下必须指定startIp和endIp字段。 |
| family | number | 否 | 是 | 1:表示family地址族设置为IPv4。 2:表示family地址族设置为IPv6。 默认IPv4,其他当前不支持。 |
| address | string | 否 | 是 | IP地址。当type等于1时需要设置,并且仅在type等于1时有效,否则将被忽略。 |
| mask | number | 否 | 是 | IPv4:子网掩码。 IPv6:前缀。 当type等于1时需要设置,并且仅在type等于1时有效,否则将被忽略。 |
| startIp | string | 否 | 是 | 起始IP。当type等于2时需要设置,并且仅在type等于2时有效,范围从0.0.0.1到255.255.255.254,否则将被忽略。 |
| endIp | string | 否 | 是 | 结束IP。当type等于2时需要设置,并且仅在type等于2时有效,范围从0.0.0.1到255.255.255.254,否则将被忽略。 |
防火墙规则端口参数。
系统能力:SystemCapability.Communication.NetManager.NetFirewall
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| startPort | number | 否 | 否 | 开始端口。 |
| endPort | number | 否 | 否 | 结束端口。 |
防火墙规则域名参数,目前不支持中文域名。
系统能力:SystemCapability.Communication.NetManager.NetFirewall
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| isWildcard | boolean | 否 | 否 | 是否包含通配符。true表示包含,false表示不包含。 |
| domain | string | 否 | 否 | 当isWildcard为false时,需要确定的完整域, 例如"www.example.cn";当isWildcard为true时,支持通配符规则,具体格式见下文说明。 |
当isWildcard为true时,domain支持使用通配符"",""可出现在域名的首部、尾部或首尾同时出现,表示匹配任意长度(包括零)的任意字符。支持以下通配符格式:
防火墙规则DNS信息。
当addNetFirewallRule的入参rule.type配置为RULE_DNS时,该字段不能为空。
系统能力:SystemCapability.Communication.NetManager.NetFirewall
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| primaryDns | string | 否 | 否 | 主域名服务器。 |
| standbyDns | string | 否 | 是 | 备份DNS。 |