GSOC2009Netfilter

Hooks

Hooks are places in the IP stack where a packet is handed over to the netfilter framework. There are five such places.

NF_INET_PRE_ROUTING

When a packet is received by a node, this hook is the first one to receive the packet. As the name implies, an incoming packet is processed by this hook even before a routing decision determines whether or not the packet is destined for the current node.

In case of destination Network Address Translation, the destination IP address should be changed at this hook so that the routing decision can send the packet to the correct interface.

In the ns-3 IP stack, this hook is placed in Ipv4L3Protocol::Receive method.

netfilter.ProcessHook ((uint8_t)1, NF_INET_PRE_ROUTING, packet, device, device);

The above method belongs to Ipv4Netfilter class which implement core functionality of the netfilter framework. This method hands over the packet to the netfilter framework. Each of the hooks is actually a callback chain implemented by the class NetfilterCallbackChain.

The first argument is the protocol family, which is just 1 right now. Later on, this can be changed to PF_INET and PF_INET6 for IPv4 and IPv6 respectively. The second argument denotes the hook number, third is the packet that should traverse this hook, fourth and fifth arguments indicate the incoming and outgoing NetDevice for this packet. These arguments may be NULL depending on which hook is considered. The last argument is by default a NULL callback that returns an unsigned int and has one argument which is the packet. This is termed as the ContinueCallback. We will talk about this when callback chains are introduced.

NF_INET_LOCAL_IN

The incoming packets that have the destination IP address of the node receiving the packet traverse this hook. Typically, this happens after the routing decision determines that the packet is destined for the node. In this case, Ipv4L3Protocol::LocalDeliver is invoked. Therefore, this hook is placed inside this method.

Callback<uint32_t, Ptr<Packet> > ccb = MakeCallback (&Ipv4Netfilter::NetfilterConntrackConfirm, &netfilter);
netfilter.ProcessHook ((uint8_t)1, NF_INET_LOCAL_IN, pkt, device, device, ccb); 

ccb above is the ContinueCallback which will be discussed in detail later on. The next line calls is the actual hook where packet is handed over to the netfilter framework.

NF_INET_FORWARD

This is meant for packets that are destined for nodes other than the one currently receiving the packet. Packets will traverse this hook if the node receiving the packet is acting as a router. Currently, this hook has not been added to the ns-3 IP stack.

NF_INET_LOCAL_OUT

Packets that are created and sent out by a node traverse this hook. This is only meant for outgoing packets. This hook is placed before a routing decision has been made regarding an outgoing packet. The Ipv4L3Protocol::Send method has various cases for outgoing packets. This hook is placed at appropriate locations for each of these cases. I have only tested "case 3" where a route is passed along with the packet.

netfilter.ProcessHook ((uint8_t)1, NF_INET_LOCAL_OUT, packetCopy, outDev, outDev);

NF_INET_POST_ROUTING

This is the last hook on the outgoing path. Outgoing packets traverse this hook after a routing decision has been made. Source Network Address Translation (SNAT) is performed at this hook. This hook is placed inside Ipv4L3Protocol::SendRealOut as this method is invoked after RouteOutput method has been called for the current routing protocol.

Callback<uint32_t, Ptr<Packet> > ccb = MakeCallback (&Ipv4Netfilter::NetfilterConntrackConfirm, &netfilter);
netfilter.ProcessHook ((uint8_t)1, NF_INET_POST_ROUTING, packet, outDev, outDev, ccb);

It should be noted that Ipv4Netfilter::NetfilterConntrackConfirm has been specified as the ContinueCallback for two hooks, NF_INET_LOCAL_IN and NF_INET_POST_ROUTING. The netfilter framwork can support dropping of packets as well. This means that a packet which traverses the NF_INET_LOCAL_OUT hook might get dropped because of a rule match. Therefore, this packet will never make it to NF_INET_POST_ROUTING and hence it does not make any sense to maintain state regarding the connection this packet belongs to. Only when an outgoing packet traverses both NF_INET_LOCAL_OUT and NF_INET_POST_ROUTING should we expect a reply. So, the NetfilterConntrackConfirm callback "confirms" the connection by creating an entry in the confirmed hash (m_hash) belonging to the Ipv4Netfilter class.

Similarly, for incoming packets, the NF_INET_LOCAL_IN hook has NetfilterConntrackConfirm set as the ContinueCallback. Both the hooks that have this callback set as the continue callback are last entry (NF_INET_LOCAL_IN) and exit points in the netfilter framework. Therefore, it makes sense to "confirm" a connection at these hooks.

Callback Chains

Each of the hooks are equipped with a chain of callbacks provided by NetfilterCallbackChain class. A developer can register callbacks with a specified priority into this chain. When a packet is handed over to a hook, the callbacks registered in the associated chain are invoked in the order of priority.

All the features including connection tracking are provided by registering callbacks at the hooks. For instance, connection tracking is a set of callbacks registered at four of the hooks excluding NF_INET_FORWARD. The callbacks for connection tracking have a certain priority.

Callback Priority

Priority of callbacks plays a very important role in the netfilter framework. It determines the order in which the callback will be invoked when a packet traverses the hook. Network Address Translation makes use of information provided by connection tracking to determine when to create a new NAT mapping. For example, connection tracking indicates that it has encountered a new connection by changing changing the status of ConntrackTag for the packet to IP_CT_NEW. This is used by NAT module to create a new NAT mapping for this connection. As you may have guessed, NAT callbacks have a lower priority than connection tracking callbacks because NAT makes use of information provided by connection tracking. This information could only be available to NAT if connection tracking callbacks have already been invoked on the packet.

Similarly, in the future, when defragmentation support is added, the defragmentation callbacks can be added with a priority higher than that of connection tracking. This would make sure that packets processed by connection tracking are defragmented.

The hook priorities used by Linux kernel are shown here for reference. The ns-3 implementation also uses the same priorities.

typedef enum {
  NF_IP_PRI_FIRST = INT_MIN,
  NF_IP_PRI_CONNTRACK_DEFRAG = -400,
  NF_IP_PRI_RAW = -300,
  NF_IP_PRI_SELINUX_FIRST = -225,
  NF_IP_PRI_CONNTRACK = -200,
  NF_IP_PRI_MANGLE = -150,
  NF_IP_PRI_NAT_DST = -100,
  NF_IP_PRI_FILTER = 0,
  NF_IP_PRI_SECURITY = 50,
  NF_IP_PRI_NAT_SRC = 100,
  NF_IP_PRI_SELINUX_LAST = 225,
  NF_IP_PRI_CONNTRACK_CONFIRM = INT_MAX,
  NF_IP_PRI_LAST = INT_MAX,
} NetfilterIpv4HookPriorities;

Netfilter Callbacks

These are implemented by Ipv4NetfilterHook class. It has a priority, protocol family, hook number and callback. I think this class is a misnomer and will change it to Ipv4NetfilterHookCallback. The Ipv4Netfilter::RegisterNetfilterHook method can be used to register a hook callback. Again, this method will also be renamed to RegisterNetfilterHookCallback.

Connection Tracking

This module is used to maintain state regarding a connection. It is important to understand that it does not modify a packet in any way.

7-Tuple

Every packet is converted to a 7-tuple which serves as the key to the hashes maintained by the Ipv4Netfilter class.

Ipv4Address m_l3Source;
uint16_t m_l3Protocol;
uint16_t m_l4Source;

Ipv4Address m_l3Destination;
uint16_t m_l4Destination;
uint8_t m_protocolNumber;
uint8_t m_direction;

Hashes

The Ipv4Netfilter class maintains two 7-tuple hashes.

TupleHash m_unconfirmed;
TupleHash m_hash;

m_unconfirmed is used to store connection tracking information for packets that are "unconfirmed". By this we mean that for outgoing packets, the packet has not traversed the NF_INET_POST_ROUTING hook and for incoming packets, the packet has not traversed the NF_INET_LOCAL_IN hook. One of the reasons this could happen is because the packet gets dropped before it makes to the above mentioned hooks.

The tuple corresponding to a packet is added to the m_confirmed hash only when it has traversed the above mentioned hooks. The Ipv4Netfilter::NetfilterConntrackGetTuple method is used to get a tuple corresponding to a packet. Both of the above mentioned hashes have the 7-tuple corresponding to a packet as the key and an object of IpConntrackInfo as an element. This indicates the current connection tracking information for the connection that corresponds to the packet being processed.

The Linux kernel uses Jenkin's hash function for hashing 7-tuples. The same code has been borrowed from the Linux kernel for use in ns-3. However, it has not been tested extensively.

IpConntrackInfo

The objects of this class are elements for the hashes mentioned above. It maintains the connection tracking status for a connection. For instance, if the IPS_SEEN_REPLY_BIT is set, it indicates that connection tracking has seen a reply for this connection. That is, it has encountered packets in the direction other than the original. For instance, if a UDP packet was sent to a remote node, a reply UDP packet from the remote node will set this bit, indicating that the reply has been seen.

Protocol Helpers

Connection tracking makes use of protocol helpers to get its job done.

Layer 3 Protocol Helpers

Each L3 protocol helper inherits from NetfilterConntrackL3Protocol. This class has two virtual functions PacketToTuple and InvertTuple. Every L3 protocol helper must implement these functions to give protocol specific ways of converting a packet to a tuple and inverting a tuple. Inverting a tuple results in a tuple is representing the reply packet. This is necessary in order to identify a reply.