Document

Introduction

The network firewall module provides the following functions:

Basic firewall management functions, such as enabling and disabling of firewalls and firewall rules, and audit.
Firewall rule configuration, including the rule name, description, operation, applicable application, protocol type, address, port, and outbound/inbound direction.
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).

NOTE

To ensure app running efficiency, all API calls are asynchronous. For asynchronous APIs, a promise is provided. The following examples use the promise mode. For more modes, see @ohos.net.netFirewall (Network Firewall).

When to Use

Typical firewall scenarios include:

IP address-based access control

Restricting network access for specific applications
Restricting network communication to specific IP addresses, protocols, ports, and physical NICs.
Restricting network communication of specific applications to specific IP addresses, protocols, ports, and physical NICs.
Applying interception rules immediately after they are delivered. For TCP, any existing intercepted TCP connections must be disconnected.

Domain name-based access control

Restricting DNS resolution for specific domain names. Only standard unencrypted DNS is restricted. Encrypted DNS and private DNS are not affected.
Restricting DNS resolution for specific domain names by specific applications. Only standard unencrypted DNS is restricted. Encrypted DNS and private DNS are not affected.
Applying interception rules immediately after they are delivered. For TCP, any existing intercepted TCP connections must be disconnected.

The following describes the development procedure specific to each application scenario.

IP address-based access control

Use a network cable to connect the device to a network port.

Import the netFirewall namespace from @kit.NetworkKit.

// Import the netFirewall namespace from @kit.NetworkKit.
import { netFirewall } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

Index.ets

Call setNetFirewallPolicy to enable the firewall.

// IP address type
interface IpType{
  family:number;
  type:number;
  address?:string;
  mask?:number;
  startIp?:string;
  endIp?:string;
}
// Port number
interface IpPort{
  startPort:number;
  endPort:number;
}
// ...
    // Define the firewall policy to enable the firewall and deny inbound traffic while allowing outbound traffic.
    let policy: netFirewall.NetFirewallPolicy = {
      isOpen: true,
      inAction: netFirewall.FirewallRuleAction.RULE_DENY,
      outAction: netFirewall.FirewallRuleAction.RULE_ALLOW
    };

    // Set the firewall policy for user 100.
    netFirewall.setNetFirewallPolicy(100, policy).then(() => {
      hilog.info(0x0000, 'testTag', `set firewall policy success.`);
    }).catch((error : BusinessError) => {
      hilog.error(0x0000, 'testTag', `error: set firewall policy failed: ${JSON.stringify(error)}`);
    });

Index.ets

Call addNetFirewallRule to add firewall rules.

// Initialize firewall rules for specific types of IP addresses.
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'
  }] as IpType[],
  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'
  }] as IpType[],
  protocol: 6,
  localPorts: [
    {
      startPort: 1000,
      endPort: 1000
    },{
    startPort: 2000,
    endPort: 2001
  }] as IpPort[],
  remotePorts: [
    {
      startPort: 443,
      endPort: 443
    }] as IpPort[],
  userId: 100,
  interface:'wlan0' // Supported since API version 26.0.0.
};
// Add firewall rules.
netFirewall.addNetFirewallRule(ipRule).then((result: number) => {
  // ...
  hilog.info(0x0000, 'testTag', `rule Id: ${result}`);
}, (reason: BusinessError) => {
  // ...
  hilog.error(0x0000, 'testTag', `error: add firewall rule failed:  ${JSON.stringify(reason)}`);
});

Index.ets

Domain Name-based Access Control

Use a network cable to connect the device to a network port.

Import the netFirewall namespace from @kit.NetworkKit.

// Import the netFirewall namespace from @kit.NetworkKit.
import { netFirewall } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

Index.ets

Call setNetFirewallPolicy to enable the firewall.

interface domain{
  isWildcard: boolean;
  domain: string;
}
// ...
    // Define the firewall policy to enable the firewall and deny inbound traffic while allowing outbound traffic.
    let policy: netFirewall.NetFirewallPolicy = {
      isOpen: true,
      inAction: netFirewall.FirewallRuleAction.RULE_DENY,
      outAction: netFirewall.FirewallRuleAction.RULE_ALLOW
    };

    // Set the firewall policy for user 100.
    netFirewall.setNetFirewallPolicy(100, policy).then(() => {
      hilog.info(0x0000, 'testTag', `set firewall policy success.`);
    }).catch((error : BusinessError) => {
      hilog.error(0x0000, 'testTag', `error: set firewall policy failed: ${JSON.stringify(error)}`);
    });

Index.ets

Call addNetFirewallRule to add firewall rules.

// Initialize firewall rules for specific types of domain names.
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.HarmonyOS.cn'
    },{
      isWildcard: true,
      domain: '*.HarmonyOS.cn'
    },{
      isWildcard: true,
      domain: '*w.HarmonyOS.cn' // Supported since API version 26.0.0.
    },{
      isWildcard: true,
      domain: 'www.HarmonyOS.*' // Supported since API version 26.0.0.
    },{
      isWildcard: true,
      domain: 'www.HarmonyOS.c*' // Supported since API version 26.0.0.
  }] as domain[],
  userId: 100,
  interface:'wlan0' // Supported since API version 26.0.0.
};

// Add firewall rules.
netFirewall.addNetFirewallRule(domainRule).then((result: number) => {
  // ...
  hilog.info(0x0000, 'testTag', `rule Id: ${result}`);
}, (reason: BusinessError) => {
  // ...
  hilog.error(0x0000, 'testTag', `error: add firewall rule failed:  ${JSON.stringify(reason)}`);
});

Index.ets

Using the Network Firewall

Introduction

When to Use

IP address-based access control

Domain Name-based Access Control