The Application Firewall is responsible for intercepting network connections and analyzing them to only permit the ones that are in your interest - while not bugging you about it.

Connection Handling  network

The Portmaster uses a two tiered view of connections:

  • Communication describes a logical connection between a local application and an Internet entity, identified by a domain. A Communication may have multiple Links.
  • Link represents a physical connection between a local application and a remote server. It is defined and identified through the IP/Port pair.

Packets are intercepted and then handled by the Portmaster.

Decision Making  firewall firewall/master.go

The Portmaster makes decisions about a connection at multiple stages:

  • Before resolving DNS / fetching Stamp data
    • Communication level: function DecideOnCommunicationBeforeIntel
  • After resolving DNS / fetching Stamp data
    • Communication level: function DecideOnCommunicationAfterIntel
  • With the interception of the first packet
    • Communication level: function DecideOnCommunication
    • Link level: function DecideOnLink
  • On every packet until all inspection subsystems are finished (Link level)

Decision Flow

In order to help you understand the complete decision process, we have developed the flow graph below. You can also find a PDF version here.

Packet Interception  firewall/interception network/packet

The interception module (a seperate one for each OS) provides the firewall with a stream of packet objects, which the firewall can inspect and then issue a verdict through these packet objects.

Verdicts may be:

  • Accept: Packet is allowed to pass.
  • Block: Packet is dropped, a TCP-Reset or ICMP host unreachable message is sent to the sender.
  • Drop: Packet is dropped silently.
  • PermanentAccept: This packet is allowed to pass, also tell the interception package to accept all future packets of this Link.
  • PermanentBlock: This packet is blocked, as well as all future packets of this Link.
  • PermanentDrop: This packet is dropped, as well as all future packets of this Link.
  • RerouteToNameserver: Reroute this packet to the local nameserver for handling.
  • RerouteToTunnel: Reroute this packet (and its Link) to the local Gate17 entry point for further handling.

The permanent editions of verdicts were created to drastically improve performance of the portmaster, as such Links will be “handed over” back to the OS and will not be intercepted by the Portmaster anymore. The trade-off here is that connections cannot be killed, should you change your mind about it later on - but this is usually not the case.

An Example: The Story of a Connection

This little story of a packet aims to illustrate how the Portmaster works. Please note that this story may be fundamentally different depending on your settings.

You fire up Firefox to access a web page on the Internet. After clicking on the bookmark you want, Firefox sends a DNS request to resolve the website/domain you are accessing: example.com..

Before resolving DNS
The Portmaster takes over this request and first checks if Firefox is allowed to talk to example.com.. After verifying that this is the case, the Portmaster concurrently resolves the query and requests any intelligence data from Stamp.
After resolving DNS
With these, the permission to access example.com. is checked again - with the newly gained data. When all this goes well, the Portmaster returns the DNS answer to Firefox.

interception of the first packet
Firefox then opens a connection to the server behind example.com.. The Portmaster intercepts the packet and checks if it already knows what to with it. The packet is put “on hold”, while the Portmaster decides what to do. The Portmaster then finally marks the connection as permitted and the packet can continue.

But it’s not quite over yet. The Portmaster may still further inspect packets to ensure your privacy or detect attacks. One of these things is to check if connections are encrypted (with TLS) and block them if they are not, but you require that.