Menu

Firewalls

This topic describes how to add support for firewalls with the Knox SDK.

About Knox firewalls

Knox Firewall implements two internet access control alternatives:

  • IP address rules
  • Domain name rules

IP address rules

The developer can set ALLOW , DENY, REDIRECT, and REDIRECT_EXCEPTION rules through FirewallRule APIs.

IP rules have effect only if enableFirewall has been called with TRUE. Any admin can add IP rules, but only one administrator can activate IP rules enforcement at a time.

Warning: IP Address rules rely on iptables. Other features based on iptables may cause conflicts and unexpected behavior, for example, Tethering and B2C Firewall. As of Knox 3.2.1, VPN client compatibility with the firewall has been improved - to minimize conflict, VPN connections are only established after the firewall has finished configuring.

Domain name rules

If IP addresses cannot be used, DNS rules can be implemented to restrict traffic. You can filter DNS requests by setting the DENY and ALLOW lists with DomainFilterRule().

Using domain name rules and firewall at the same time

Knox SDK 3.3 now supports the concurrent use of DomainFilterRule() and FirewallRule APIs on a specified device by introducing a new API enableDomainFilterOnIptables() that enables this new feature.

enableDomainFilterOnIptables() is a compatibility API that enables administrators to set domain name rules and firewall rules at the same time. After enabling this API, admins are able to do the following:

  • Use FirewallRule to block all IPs in a specified device.
  • Use the DomainFilterRule() to allow specific domains to be white listed even if the IPs were blocked using Firewall policies.

Note: When enableDomainFilterOnIptables() is set to false, the API is disabled and the rules no longer take effect. This setting means admins have to set ALLOW rules for addDomainFilterRules for URLs and addRules for IPs separately. Also, enableDomainFilterOnIptables() doesn't support multiple administrators. Only one admin can enable or disable the API.

Multiple administrator scenarios

When a device is managed by multiple administrators, IP rules behave as follows:

  • All admins can add IP rules
  • Only one admin can enforce IP rules at time

Implementation

Get firewall

Firewalls can be implemented globally or separately for the device side and the container. 

//Create EnterpriseDeviceManager
EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);

//Get firewall
Firewall firewall = edm.getFirewall();

Add IP rules

You can use addRule API to add rules to allow or deny or redirect IP requests. 

 // In order to validate the application's signature related to the rule, fill this
 // variable with the desired signature.
 String signature = null;

 int numRules = 5;
 FirewallRule[] rules = new FirewallRule[numRules];

 // To Add a Deny Rule
 rules[0] = new FirewallRule(RuleType.DENY, AddressType.IPV4);
 rules[0].setIpAddress("*");
 rules[0].setPortNumber("80");
 rules[0].setApplication(new AppIdentity("com.android.chrome",signature));

 // To Add a Allow Rule
 rules[1] = new FirewallRule(RuleType.ALLOW, AddressType.IPV4);
 rules[1].setIpAddress("192.168.1.2");
 rules[1].setPortNumber("80");
 rules[1].setPortLocation(PortLocation.LOCAL);
 rules[1].setApplication(new AppIdentity("com.android.chrome",signature));
 rules[1].setNetworkInterface(NetworkInterface.WIFI_DATA_ONLY);
 rules[1].setDirection(Direction.INPUT);
 rules[1].setProtocol(Protocol.TCP);

 // To Add a Redirect Rule
 rules[2] = new FirewallRule(RuleType.REDIRECT, AddressType.IPV4);
 rules[2].setIpAddress("*");
 rules[2].setPortNumber("443");
 rules[2].setPortLocation(PortLocation.REMOTE);
 rules[2].setNetworkInterface(NetworkInterface.MOBILE_DATA_ONLY);
 rules[2].setTargetIpAddress("192.168.2.1");
 rules[2].setTargetPortNumber("60");

 // To Add a Redirect Exception Rule
 rules[3] = new FirewallRule(RuleType.REDIRECT_EXCEPTION, AddressType.IPV4);
 rules[3].setIpAddress("192.168.1.1");
 rules[3].setPortNumber("443");
 rules[3].setProtocol(Protocol.TCP);

 // To Add a Allow Rule (Using IPv6 Address)
 rules[4] = new FirewallRule(RuleType.ALLOW, AddressType.IPV6);
 rules[4].setIpAddress("2001:12C0:8000:AAAA:200:192:176:65");
 rules[4].setPortNumber("80");
 rules[4].setPortLocation(PortLocation.LOCAL);
 rules[4].setPackageName("com.android.chrome");
 rules[4].setNetworkInterface(NetworkInterface.WIFI_DATA_ONLY);
 rules[4].setDirection(Direction.INPUT);
 rules[4].setProtocol(Protocol.TCP);
 FirewallResponse[] response = firewall.addRules(rules);

 // Add rule to use as a Proxy (http)
 FirewallRule[] proxyRule = new FirewallRule[1];
 // All traffic coming through the port 80 is redirected to the proxy server configured on IP
 // 192.168.100.10
 proxyRule[0] = new FirewallRule(RuleType.REDIRECT, AddressType.IPV4);
 proxyRule[0].setIpAddress("*");
 proxyRule[0].setPortNumber("80");
 proxyRule[0].setTargetIpAddress("192.168.100.10");
 proxyRule[0].setTargetPortNumber("680");

 FirewallResponse[] ProxyResponse = firewall.addRules(proxyRule);

 // Add rule to restrict the network used for an application
 // All traffic used by the application, in this case Chrome, is blocked on Mobile Interface.
 FirewallRule[] appRule = new FirewallRule[1];
 appRule[0] = new FirewallRule(RuleType.DENY, AddressType.IPV4);
 appRule[0].setIpAddress("*");
 appRule[0].setPortNumber("*");
 appRule[0].setApplication(new AppIdentity("com.android.chrome",signature));
 appRule[0].setNetworkInterface(NetworkInterface.WIFI_DATA_ONLY);

 FirewallResponse[] appResponse = firewall.addRules(appRule);

Remove IP rules

An admin can use the clearRules API to remove the IP rules previously added. The rules added by other admins are not affected.

 // Clear only Allow Rules
 int bitmask = Firewall.FIREWALL_ALLOW_RULE;
 FirewallResponse[] response = firewall.clearRules(bitmask);

 // Clear only Deny Rules
 bitmask = Firewall.FIREWALL_DENY_RULE;
 response = firewall.clearRules(bitmask);

 // Clear only Allow and Deny Rules
 bitmask = Firewall.FIREWALL_ALLOW_RULE | Firewall.FIREWALL_DENY_RULE;
 response = firewall.clearRules(bitmask);

 // Clear All Rules
 bitmask = Firewall.FIREWALL_ALL_RULES;
 response = firewall.clearRules(bitmask);

Also, an admin can use the removeRules API to remove rules previously added through addRule. Once removed, the rules no longer take effect, meaning that a rule, used to allow, block or redirect some IP address, after removal no longer applies. The rules added by other admins are not affected.

For example:

FirewallResponse[] response = firewall.removeRules(rules);

Enable or disable firewall IP rules

An admin can use this API to turn on/off the enforcement of IP rules. Upon enabling it, all IP rules previously added by this admin are activated. If the admin disables it passing false, IP rules are not enforced any longer.

 // Enable the Firewall
 FirewallResponse responseForEnable = firewall.enableFirewall(true);

 // Disable the Firewall
 FirewallResponse responseForDisable = firewall.enableFirewall(false);

Add domain filtering rules

Use the addDomainFilterRule API to add rules to allow or block apps from accessing domains.

Admins can apply a rule for a specific app or for all applications at once, using FIREWALL_ALL_PACKAGES. If a rule with the FIREWALL_ALL_PACKAGES value is already in database and a rule is added with a specific application, the general one is not considered to resolve the domain access enforcement for this specific app.

EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 Firewall firewall = edm.getFirewall();

 List<DomainFilterRule> rules = new ArrayList<DomainFilterRule>();

 // Deny list , domains to block
 List<String> denyList = new ArrayList<String>();
 denyList.add("www.google.com");
 denyList.add("*android.com");
 denyList.add("www.samsung*");

 // Allow list, domains to allow
 List<String> allowList = new ArrayList<String>();
 allowList.add("www.youtube.com");

 // In order to validate the application's signature related to the rule, fill this
 // variable with the desired signature.
 String signature = null;

 // DNS server 1
 String dns1 = "8.8.8.8";
 // DNS server 2
 String dns2 = "8.8.4.4";

 // add rule for chrome application
 rules.add(new DomainFilterRule(new AppIdentity("com.android.chrome", signature), denyList,
         allowList, dns1, dns2));
 try {
     FirewallResponse[] response = firewall.addDomainFilterRules(rules);
     if (FirewallResponse.Result.SUCCESS == response[0].getResult()) {
         // success
     } else {
         // failed
     }
 } catch (SecurityException ex) {
     // missing required MDM permission
 }

Remove domain filtering rules

An admin can use the removeDomainFilterRules API to remove rules previously added through the addDomainFilterRules API. Once removed, the rules no longer take effect, meaning that a rule, used to block some domain name, after removed no longer blocks it.

To clear all rules in database pass CLEAR_ALL as parameter to this API. In order to clear just one of the lists—allow or deny—pass null to the corresponding list parameter on the class DomainFilterRule constructor or call corresponding set method from the same class.

List<DomainFilterRule> rules = new ArrayList<DomainFilterRule>();
       // Deny list , unblock domains
       List denyList = new ArrayList();
       denyList.add("www.google.com");
       denyList.add("*android.com");

       // Allow list, remove domain from allow list
       List allowList = new ArrayList();
       allowList.add("www.youtube.com");

       // In order to validate the application's signature related to the rule, fill this
       // variable with the desired signature.
       String signature = null;

       // remove rule for chrome application, assuming they were added like in
       // addDomainFilterRules examples
       rules.add(new DomainFilterRule(new AppIdentity("com.android.chrome",signature),
              denyList, allowList));
       try {
           FirewallResponse[] response = firewall.removeDomainFilterRules(rules);
           if (FirewallResponse.Result.SUCCESS == response[0].getResult()) {
               // success
           } else {
              //failed
           }
       } catch (SecurityException ex) {
           // missing required MDM permission
       }

Enable use of domain name and firewall rules at the same time

An admin can use enableDomainFilterOnIptables() API to enable the association between domain and firewall rules. This API matches each domain request against a list configured by the admin with DomainFilterRule(). With this API, admins are able to allow specific domains to be white listed even when all IPs are blocked by Firewall policy.

To enable enableDomainFilterOnIptables(), pass the parameter true. Once enabled, the app will analyze the domain name rules before the firewall rules to determine which requests are blocked are allowed.

To disable enableDomainFilterOnIptables(), pass the parameter false. Note that once the API is disabled, the rules no longer take effect, meaning admins will have to set ALLOW rules for addDomainFilterRules for URLs and addRules for IPs seperately.

Note: This API doesn't support multiple administrators. Only one admin can enable or disable the API.