Nsnam - User contributions [en]

GSOC2009Netfilter

2009-07-28T10:59:17Z

Qasimj: /* Network Address Translation */

== 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.

<pre>netfilter.ProcessHook ((uint8_t)1, NF_INET_PRE_ROUTING, packet, device, device);</pre>

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.

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

''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.

<pre>netfilter.ProcessHook ((uint8_t)1, NF_INET_LOCAL_OUT, packetCopy, outDev, outDev);</pre>

=== 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.

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

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.

<pre>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;</pre>

=== 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.

<pre>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;</pre>

=== Hashes ===

The '''Ipv4Netfilter''' class maintains two 7-tuple hashes.

<pre>TupleHash m_unconfirmed;
TupleHash m_hash;</pre>

''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.

=== Connection tracking hook callbacks ===

Connection tracking makes use of the netfilter hooks by registering functions/methods that perform the actual work at 4 of the hooks except NF_INET_FORWARD. This is done in the constructor of '''Ipv4Netfilter''' as shown below:

<pre>NetfilterHookCallback preRouting = MakeCallback (&Ipv4Netfilter::NetfilterConntrackIn, this);
NetfilterHookCallback localIn = MakeCallback (&Ipv4ConntrackL3Protocol::Ipv4Confirm, PeekPointer (ipv4));

Ipv4NetfilterHook nfh = Ipv4NetfilterHook (1, NF_INET_PRE_ROUTING, 1, preRouting);
Ipv4NetfilterHook nfh1 = Ipv4NetfilterHook (1, NF_INET_LOCAL_OUT, 1, preRouting);
Ipv4NetfilterHook nfh2 = Ipv4NetfilterHook (1, NF_INET_POST_ROUTING, 1, localIn);
Ipv4NetfilterHook nfh3 = Ipv4NetfilterHook (1, NF_INET_LOCAL_IN, 1, localIn);

this->RegisterNetfilterHook (nfh);
this->RegisterNetfilterHook (nfh1);
this->RegisterNetfilterHook (nfh2);
this->RegisterNetfilterHook (nfh3);</pre>

=== Protocol Helpers ===

Connection tracking makes use of protocol helpers to get its job done. The '''Ipv4Netfilter''' class maintains vectors for L3 and L4 protocol helpers. When a packet is encountered by connection tracking, it determines the L3 protocol for that packet and looks for an L3 protocol helper for that packet. If, for instance, the L3 protocol is IPv4 (the only supported protocol right now), the ''protocol'' field within the IP header is consulted to determine the L4 protocol and thus the L4 protocol helper. '''Ipv4Netfilter::FindL4ProtocolHelper''' is used to perform this lookup.

==== 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.

'''Ipv4ConntrackL3Protocol''' implements the layer 3 protocol helper for IPv4.

==== Layer 4 Protocol Helpers ====

Similar to to L3 protocol helpers, each L4 protocol helper derives from '''NetfilterConntrackL4Protocol'''. This class also has the same virtual functions as L3 protocol helper. In addition to the above, it has a method '''GetProtocol''' which is used to get the L4 protocol number. The numbers are similar to Linux kernel. For example, TCP has layer 4 protocol number "6" which is respresented by ''IPPROTO_TCP''.

In addition to the above, in order to support packet filtering/mangling, a L4 protocol helper must provide implementations of the following methods.

''New''

This is called when a new connection for this protocol is encountered. It can allocate/initialize protocol specific data structures regarding the new connection so that the protocol specific state can be maintained.

''Error''

This checks whether the current packet is valid according to the protocol. If the packet is not valid, its traversal through the framework can be cut short.

''PacketVerdict''

This updates the protocol specific data structures to maintain connection state. It is also used to increase the timeout value if connection tracking has seen a reply to a packet. If no reply is encountered, the timeout will not be extended and thus the state regarding that connection would be deleted.

Currently, the code does not implement the above three callbacks but they will be supported in the future to get maximum advantage.

'''TcpConntrackL4Protocol''' and '''UdpConntrackL4Protocol''' implement the L4 protocol for the respective protocols. The TCP L4 protocol helper can be made more intelligent as is the case in the Linux kernel. I did not delve into this because it would have sidetracked me from the main goal of this project.

== Network Address Translation ==

NAT is also a set of hook callbacks that are registered at 4 of the hooks except NF_INET_FORWARD. This section will be updated with more information soon.

GSOC2009Netfilter

2009-07-28T10:57:53Z

Qasimj: /* Connection Tracking */

GSOC2009Netfilter

2009-07-27T20:30:05Z

Qasimj: /* NF_INET_PRE_ROUTING */

GSOC2009Netfilter

2009-07-27T20:27:11Z

Qasimj: New page: == 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 ...

GSOC2009NetworkAddressTranslation

2009-07-27T20:08:33Z

Qasimj: /* Approach */

== Introduction ==

The aim of this project is to add Network Address Translation (NAT) functionality to ns-3. Instead of just implementing NAT, we are working on introducing an extensible framework. This way, if firewall functionality needs to implemented in the future, the framework can be used to do that. The inspiration for such a framework comes from the netfilter in the Linux kernel.

Netfilter creates fives hooks in the Linux kernel networking stack. A developer can register functions at each of the hooks. These functions get called when a packet traverses the hook. While registering a function at a hook, a priority needs to be specified which will determine the order in which the function will be executed. Userspace utilities such as iptables do not interact directly with netfilter, rather, they interact with kernel modules which in turn interact with the netfilter framework.

We aim to implement something similar to netfilter framework for ns-3. This will make it easy to add firewall functionality to ns-3 in the future.

== Background ==

A Linux kernel module can register multiple functions at each of the netfilter hooks. The netfilter framework maintains a 2-dimensional array nf_hooks[NFPROTO_NUMPROTO][NF_MAXHOOKS] of circular linked lists. When a function is registered using nf_register_hook, a variable of type "struct nf_hook_ops" (which contains the function to be registered) is added to the appropriate list. The position within the list is determined by the priority specified in the "struct nf_hook_ops" type variable.

When a packet traverses the hook, for instance, in ip_rcv function, NF_HOOK macro is called which ends up invoking nf_hook_slow. This is the interface between the routing code and the netfilter framework. As this is the NF_PREROUTING hook, and assuming that IPv4 is being used, the linked list at nf_hooks[PF_INET][NF_PREROUTING] is consulted and the functions registered at the hook are invoked. The nf_iterate function is used to iterate through the linked list, invoking the "hook" member of the "struct nf_hook_ops" variable in turn.

The iptables userspace utility is used to add/remove/update the rules for the netfilter framework. It does not interact directly with the netfilter framework, instead, iptables works with kernel modules which in turn use the netfilter framework to implement the rule.

A rule is composed of two parts. A selection criterion and a verdict for the packet that matches the selection criteria. The verdict might entail dropping the packet, letting the packet go, changing the packet in a certain manner etc.

== Approach ==

In order to implement Network Address Translation, we need to be able to defragment the IP packets. The implementation of this part has been postponed as the development can continue without it. However, IP packet defragmentation will be added to ns-3 later on.

Connection tracking implements protocol specific handlers for NAT. For instance, FTP, ICMP, SIP etc. Although this project will not implement the handlers themselves but it aims to provide an API so that developers can implement protocol specific connection tracking.

* Five hooks (using ns-3 callbacks)
* A class that stores the NAT mappings (7-tuples)
* Connection tracking
* Network Address Translation
* A mechanism to configure NAT

More details regarding the implementation can be found at [[GSOC2009Netfilter | ns-3 Netfilter implementation details]]

== Schedule ==

The first two weeks will be spent studying the ns-3 networking stack and how a framework similar to netfilter can be implemented for ns-3.

* Week 3: Implement and test IP packet defragmentation
* Week 4,5: Implement hooks using ns-3 callbacks and a class for storing the created NAT mappings
* Week 6: Test basic NAT functionality
* Week 7-8: Implement Connection tracking API and start testing
* Week 9: Implement any NAT helpers or user configuration options
* Week 10: Merge with ns-3 codebase

== Midterm Report ==

The midterm report for this project can be found at [[GSoC2009NetworkAddressTranslationMidtermReport | NAT Midterm Report]]

== Questions ==

GSOC2009NetworkAddressTranslation

2009-07-27T20:01:04Z

Qasimj: /* Introduction */

== Introduction ==

The aim of this project is to add Network Address Translation (NAT) functionality to ns-3. Instead of just implementing NAT, we are working on introducing an extensible framework. This way, if firewall functionality needs to implemented in the future, the framework can be used to do that. The inspiration for such a framework comes from the netfilter in the Linux kernel.

Netfilter creates fives hooks in the Linux kernel networking stack. A developer can register functions at each of the hooks. These functions get called when a packet traverses the hook. While registering a function at a hook, a priority needs to be specified which will determine the order in which the function will be executed. Userspace utilities such as iptables do not interact directly with netfilter, rather, they interact with kernel modules which in turn interact with the netfilter framework.

We aim to implement something similar to netfilter framework for ns-3. This will make it easy to add firewall functionality to ns-3 in the future.

== Background ==

A Linux kernel module can register multiple functions at each of the netfilter hooks. The netfilter framework maintains a 2-dimensional array nf_hooks[NFPROTO_NUMPROTO][NF_MAXHOOKS] of circular linked lists. When a function is registered using nf_register_hook, a variable of type "struct nf_hook_ops" (which contains the function to be registered) is added to the appropriate list. The position within the list is determined by the priority specified in the "struct nf_hook_ops" type variable.

When a packet traverses the hook, for instance, in ip_rcv function, NF_HOOK macro is called which ends up invoking nf_hook_slow. This is the interface between the routing code and the netfilter framework. As this is the NF_PREROUTING hook, and assuming that IPv4 is being used, the linked list at nf_hooks[PF_INET][NF_PREROUTING] is consulted and the functions registered at the hook are invoked. The nf_iterate function is used to iterate through the linked list, invoking the "hook" member of the "struct nf_hook_ops" variable in turn.

The iptables userspace utility is used to add/remove/update the rules for the netfilter framework. It does not interact directly with the netfilter framework, instead, iptables works with kernel modules which in turn use the netfilter framework to implement the rule.

A rule is composed of two parts. A selection criterion and a verdict for the packet that matches the selection criteria. The verdict might entail dropping the packet, letting the packet go, changing the packet in a certain manner etc.

== Approach ==

In order to implement Network Address Translation, we need to be able to defragment the IP packets. Also, hooks will be implemented using the ns-3 callbacks. These hooks will be added to appropriate locations in the ns-3 networking stack. More details will be added soon.

There will be a class which will store the mappings created by Network Address Translation. Moreover, there needs to be way for the user to configure NAT. This should be dynamic considering that the framework can be used for packet inspection or firewall.

Connection tracking will implement protocol specific handlers for NAT. For instance, FTP, ICMP, SIP etc. Although this project will not implement the handlers themselves but it aims to provide an API so that developers can implement protocol specific connection tracking.

* IP packet defragmentation
* Five hooks (using ns-3 callbacks)
* A class that stores the NAT mappings (4-tuples)
* A mechanism to configure NAT
* Connection tracking

== Schedule ==

The first two weeks will be spent studying the ns-3 networking stack and how a framework similar to netfilter can be implemented for ns-3.

* Week 3: Implement and test IP packet defragmentation
* Week 4,5: Implement hooks using ns-3 callbacks and a class for storing the created NAT mappings
* Week 6: Test basic NAT functionality
* Week 7-8: Implement Connection tracking API and start testing
* Week 9: Implement any NAT helpers or user configuration options
* Week 10: Merge with ns-3 codebase

== Midterm Report ==

The midterm report for this project can be found at [[GSoC2009NetworkAddressTranslationMidtermReport | NAT Midterm Report]]

== Questions ==

GSOC2009NetworkAddressTranslationMidtermReport

2009-07-11T10:34:24Z

Qasimj:

== Aim ==

The aim of this project is to implement Network Address Translation functionality for ns-3. Early on, we decided to build an extensible framework which can ease the task of adding firewall functionality to ns-3 and hence increase code reusability as well.

== Background ==

I referred to the Linux kernel Netfilter framework for the ns-3 Netfilter implementation. Netfilter consists of five hooks which are possible places where the processing of the packet is handed over to the Netfilter framework. A developer can register functions at any of the hooks and those functions are called in turn as a packet traverses the hooks.

IPtables is a userspace utility that makes use of the Netfilter framework inside Linux kernel in order to facilitate the specification of firewall rules. However, IPtables does not interact directly with the Netfilter framework. Instead, there is a set of Linux kernel modules that mediate between IPtables and Netfilter. Modules are (un)pluggable pieces of code that run in kernel mode.

Connection tracking is an important part of the Netfilter framework. The framework provides a connection tracking API so that modules can register themselves as layer 3 protocol helpers, layer 4 protocol helpers, NAT helpers, protocol specific NAT helpers etc. IPv4 connection tracking is implemented by registerting connection tracking specific functions at each of the hooks except the forwarding one.

== Milestones ==

The project milsestones are as follows.

* Implementation of Hooks within the IP stack
* Connection tracking implementation using hooks
* Implementation of NAT using the connection tracking API

Connection tracking is the largest module in this project. It involves implementation of hook functions that are required for connection tracking and includes data structures such as a hash for maintaining state regarding existing connections. Moreover, each Packet should have some additional information (in the form of a byte tag) so that when it traverses a hook, those changes can be noticed by other hooks. This information is necessary in order to determine if a packet is a reply packet.

Connection tracking module also provides an API so that IPv4 and TCPv4 helpers can register themselves using this API. This has the advantage of extensibility, as helpers for other protocols like SCTP can be written and registered using the API. This way whenever an SCTP packet will be encountered by the connection tracking hook functions, it will be handed over to the SCTP helper for further processing and updating of the current state.

== Implementation ==

=== Netfilter Hooks ===

Ipv4Netfilter is the main class which provides the functionality for registering and unregistering a function at a hook. Ipv4NetfilterHook class represents information that should be contained within a hook element before it is registered. For instance, a hook element must have the hook function that needs to be registered and will be invoked when a packet traverses this hook, the priority of the hook function, protocol family the hook is responsible for and which particular and the hook number where it should be registered. Hook numbers as represented as NF_INET_PREROUTING, NF_INET_POSTROUTING etc.

The priority of hook function is important because more than one function can be registered at a hook. Essentially, there is a priority list maintained at each hook. This is implemented using the '''NetfilterCallbackChain''' class.

When a hook function is registered using '''RegisterNetfilterHook''', it is placed within the above mentioned priority list based on its priority. It will be invoked according to its priority when a packet traverses the hook at which this function was registered. Similarly, when a hook function is unregistered using ''UnRegisterNetfilterHook'', the corresponding '''Ipv4NetfilterHook''' object is removed from the NetfilterCallbackChain for that hook.

Hooks have inserted at appropriate locations by inspecting ns-3 IP stack source code. For example, the PREROUTING hook has been placed in ''Ipv4L3Protocol::Receive'' method. It is important to note that this hook should be placed before the proceedings are handed over to the RouteInput method for whatever routing protocols have been registered. In order to insert the hooks, it was necessary to have a Ipv4Netfilter object as a private member of Ipv4L3Protocol class. I also had a detailed discussion with T.J. Kopena regarding this matter and we had concluded that it is better to add this as a member rather than aggregating an object of Ipv4Netfilter with Ipv4L3Protocol.

When a packet traverses a hook, it is handed over to the Netfilter framework using the ''Ipv4Netfilter::ProcessHook'' method. This method essentially invokes all registered callbacks in this hook's callback chain. As mentioned earlier, these callbacks are invoked in the order of priority.

The POSTROUTING hook is placed at multiple places, in Ipv4L3Protocol::Send and ''Ipv4L3Protocol::SendRealOut''. This is so because there can be five different scenarios for sending the packet as mentioned in the comments of ''Ipv4L3Protocol::Send''.

Although, I have not defined a log component for the Netfilter framework as yet, but I will definitely do that. In order to test the hooks, I had simply used the existing Ipv4L3Protocol log component. Also, I had registered functions at the Netfilter hooks within the Ipv4L3Protocol constructor. This will not stay the same and will be replaced by a user configuration API which will allow the script writer to register functions at any of the hooks. This will be done towards the end of the project as the most important part is to implement the core functionality of this framework.

The output from the log component clearly indicates that the hook functions are called at appropriate locations. I have used the example "first.cc" to demonstrate the hook functions. In this example, four packets are exchanged. This is obvious from the output below:

<pre>Ipv4L3Protocol:Ipv4L3Protocol()
Ipv4L3Protocol:SetIpForward(0x83547b0, 1)
Ipv4L3Protocol:SetupLoopback()
Ipv4L3Protocol:AddIpv4Interface(0x83547b0, 0x8354858)
Ipv4L3Protocol:SetRoutingProtocol(0x83547b0)
Ipv4L3Protocol:GetNInterfaces()
Ipv4L3Protocol:IsUp(0x83547b0, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 0)
Ipv4L3Protocol:GetNAddresses(0x83547b0, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 0)
Ipv4L3Protocol:GetAddress(0x83547b0, 0, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 0)
Ipv4L3Protocol:GetAddress(0x83547b0, 0, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 0)
Ipv4L3Protocol:GetAddress(0x83547b0, 0, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 0)
Ipv4L3Protocol:GetAddress(0x83547b0, 0, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 0)
Ipv4L3Protocol:GetAddress(0x83547b0, 0, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 0)
Ipv4L3Protocol:GetNAddresses(0x83547b0, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 0)
Ipv4L3Protocol:GetNInterfaces()
Ipv4L3Protocol:Ipv4L3Protocol()
Ipv4L3Protocol:SetIpForward(0x8355090, 1)
Ipv4L3Protocol:SetupLoopback()
Ipv4L3Protocol:AddIpv4Interface(0x8355090, 0x8355188)
Ipv4L3Protocol:SetRoutingProtocol(0x8355090)
Ipv4L3Protocol:GetNInterfaces()
Ipv4L3Protocol:IsUp(0x8355090, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 0)
Ipv4L3Protocol:GetNAddresses(0x8355090, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 0)
Ipv4L3Protocol:GetAddress(0x8355090, 0, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 0)
Ipv4L3Protocol:GetAddress(0x8355090, 0, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 0)
Ipv4L3Protocol:GetAddress(0x8355090, 0, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 0)
Ipv4L3Protocol:GetAddress(0x8355090, 0, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 0)
Ipv4L3Protocol:GetAddress(0x8355090, 0, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 0)
Ipv4L3Protocol:GetNAddresses(0x8355090, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 0)
Ipv4L3Protocol:GetNInterfaces()
Ipv4L3Protocol:GetInterfaceForDevice(0x83547b0, 0)
Ipv4L3Protocol:AddInterface(0x83547b0, 0xbfadc414)
Ipv4L3Protocol:AddIpv4Interface(0x83547b0, 0x83554d8)
Ipv4L3Protocol:AddAddress(0x83547b0, 1, m_local=10.1.1.1; m_mask=255.255.255.0; m_broadcast=10.1.1.255; m_scope=2; m_secondary=0)
Ipv4L3Protocol:GetInterface(0x83547b0, 1)
Ipv4L3Protocol:IsUp(0x83547b0, 1)
Ipv4L3Protocol:GetInterface(0x83547b0, 1)
Ipv4L3Protocol:SetMetric(1, 1)
Ipv4L3Protocol:GetInterface(0x83547b0, 1)
Ipv4L3Protocol:SetUp(0x83547b0, 1)
Ipv4L3Protocol:GetInterface(0x83547b0, 1)
Ipv4L3Protocol:GetNAddresses(0x83547b0, 1)
Ipv4L3Protocol:GetInterface(0x83547b0, 1)
Ipv4L3Protocol:GetAddress(0x83547b0, 1, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 1)
Ipv4L3Protocol:GetAddress(0x83547b0, 1, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 1)
Ipv4L3Protocol:GetAddress(0x83547b0, 1, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 1)
Ipv4L3Protocol:GetAddress(0x83547b0, 1, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 1)
Ipv4L3Protocol:GetAddress(0x83547b0, 1, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 1)
Ipv4L3Protocol:GetNAddresses(0x83547b0, 1)
Ipv4L3Protocol:GetInterface(0x83547b0, 1)
Ipv4L3Protocol:GetInterfaceForDevice(0x8355090, 0)
Ipv4L3Protocol:AddInterface(0x8355090, 0xbfadc414)
Ipv4L3Protocol:AddIpv4Interface(0x8355090, 0x83558a8)
Ipv4L3Protocol:AddAddress(0x8355090, 1, m_local=10.1.1.2; m_mask=255.255.255.0; m_broadcast=10.1.1.255; m_scope=2; m_secondary=0)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Ipv4L3Protocol:IsUp(0x8355090, 1)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Ipv4L3Protocol:SetMetric(1, 1)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Ipv4L3Protocol:SetUp(0x8355090, 1)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Ipv4L3Protocol:GetNAddresses(0x8355090, 1)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Ipv4L3Protocol:GetAddress(0x8355090, 1, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Ipv4L3Protocol:GetAddress(0x8355090, 1, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Ipv4L3Protocol:GetAddress(0x8355090, 1, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Ipv4L3Protocol:GetAddress(0x8355090, 1, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Ipv4L3Protocol:GetAddress(0x8355090, 1, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Ipv4L3Protocol:GetNAddresses(0x8355090, 1)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Ipv4L3Protocol:GetAddress(0x8355090, 1, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Ipv4L3Protocol:GetNAddresses(0x83547b0, 1)
Ipv4L3Protocol:GetInterface(0x83547b0, 1)
Ipv4L3Protocol:GetAddress(0x83547b0, 1, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 1)
Ipv4L3Protocol:GetNetDevice(0x83547b0, 1)
Ipv4L3Protocol:GetInterface(0x83547b0, 1)
Ipv4L3Protocol:Send(0x83547b0, 0x8366758, 10.1.1.1, 10.1.1.2, 17, 0x8366738)
Ipv4L3Protocol:GetNAddresses(0x83547b0, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 0)
Ipv4L3Protocol:GetAddress(0x83547b0, 0, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 0)
Ipv4L3Protocol:Send(): Testing address 127.0.0.1 with mask 255.0.0.0
Ipv4L3Protocol:GetNAddresses(0x83547b0, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 0)
Ipv4L3Protocol:GetNAddresses(0x83547b0, 1)
Ipv4L3Protocol:GetInterface(0x83547b0, 1)
Ipv4L3Protocol:GetAddress(0x83547b0, 1, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 1)
Ipv4L3Protocol:Send(): Testing address 10.1.1.1 with mask 255.255.255.0
Ipv4L3Protocol:GetNAddresses(0x83547b0, 1)
Ipv4L3Protocol:GetInterface(0x83547b0, 1)
Ipv4L3Protocol:Send(): Ipv4L3Protocol::Send case 3: passed in with route
Ipv4L3Protocol:BuildHeader()
Ipv4L3Protocol:SendRealOut(0x83547b0, 0x8366758, 0xbfadbd00)
Ipv4L3Protocol:SampleHookFunction2(): Netfilter hook sample function 2 called
Ipv4L3Protocol:GetInterfaceForDevice(0x83547b0, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 1)
Ipv4L3Protocol:SendRealOut(): Send via NetDevice ifIndex 0 ipv4InterfaceIndex 1
Ipv4L3Protocol:SendRealOut(): Send to destination 10.1.1.2
Sent 1024 bytes to 10.1.1.2
Ipv4L3Protocol:Receive(0x8355090, 0xbfadbf58, 0x8366758, 2048, 02-06-00:00:00:00:00:01)
Ipv4L3Protocol:Receive(): Packet from 02-06-00:00:00:00:00:01 received on node 1
Ipv4L3Protocol:SampleHookFunction(): Netfilter hook sample function called
Ipv4L3Protocol:GetInterfaceForDevice(0x8355090, 0)
Ipv4L3Protocol:GetInterfaceForDevice(0x8355090, 0)
Ipv4L3Protocol:GetNInterfaces()
Ipv4L3Protocol:GetNAddresses(0x8355090, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 0)
Ipv4L3Protocol:GetAddress(0x8355090, 0, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 0)
Ipv4L3Protocol:GetNAddresses(0x8355090, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 0)
Ipv4L3Protocol:GetNInterfaces()
Ipv4L3Protocol:GetNAddresses(0x8355090, 1)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Ipv4L3Protocol:GetAddress(0x8355090, 1, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Ipv4L3Protocol:LocalDeliver(0x8355090, 0x8366668, 0xbfadbe48)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Received 1024 bytes from 10.1.1.1
Ipv4L3Protocol:GetNAddresses(0x8355090, 1)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Ipv4L3Protocol:GetAddress(0x8355090, 1, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Ipv4L3Protocol:GetNetDevice(0x8355090, 1)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Ipv4L3Protocol:Send(0x8355090, 0x8366758, 10.1.1.2, 10.1.1.1, 17, 0x83669d8)
Ipv4L3Protocol:GetNAddresses(0x8355090, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 0)
Ipv4L3Protocol:GetAddress(0x8355090, 0, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 0)
Ipv4L3Protocol:Send(): Testing address 127.0.0.1 with mask 255.0.0.0
Ipv4L3Protocol:GetNAddresses(0x8355090, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 0)
Ipv4L3Protocol:GetNAddresses(0x8355090, 1)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Ipv4L3Protocol:GetAddress(0x8355090, 1, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Ipv4L3Protocol:Send(): Testing address 10.1.1.2 with mask 255.255.255.0
Ipv4L3Protocol:GetNAddresses(0x8355090, 1)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Ipv4L3Protocol:Send(): Ipv4L3Protocol::Send case 3: passed in with route
Ipv4L3Protocol:BuildHeader()
Ipv4L3Protocol:SendRealOut(0x8355090, 0x8366758, 0xbfadbad0)
Ipv4L3Protocol:SampleHookFunction2(): Netfilter hook sample function 2 called
Ipv4L3Protocol:GetInterfaceForDevice(0x8355090, 0)
Ipv4L3Protocol:GetInterface(0x8355090, 1)
Ipv4L3Protocol:SendRealOut(): Send via NetDevice ifIndex 0 ipv4InterfaceIndex 1
Ipv4L3Protocol:SendRealOut(): Send to destination 10.1.1.1
Ipv4L3Protocol:Receive(0x83547b0, 0xbfadbf58, 0x8366758, 2048, 02-06-00:00:00:00:00:02)
Ipv4L3Protocol:Receive(): Packet from 02-06-00:00:00:00:00:02 received on node 0
Ipv4L3Protocol:SampleHookFunction(): Netfilter hook sample function called
Ipv4L3Protocol:GetInterfaceForDevice(0x83547b0, 0)
Ipv4L3Protocol:GetInterfaceForDevice(0x83547b0, 0)
Ipv4L3Protocol:GetNInterfaces()
Ipv4L3Protocol:GetNAddresses(0x83547b0, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 0)
Ipv4L3Protocol:GetAddress(0x83547b0, 0, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 0)
Ipv4L3Protocol:GetNAddresses(0x83547b0, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 0)
Ipv4L3Protocol:GetNInterfaces()
Ipv4L3Protocol:GetNAddresses(0x83547b0, 1)
Ipv4L3Protocol:GetInterface(0x83547b0, 1)
Ipv4L3Protocol:GetAddress(0x83547b0, 1, 0)
Ipv4L3Protocol:GetInterface(0x83547b0, 1)
Ipv4L3Protocol:LocalDeliver(0x83547b0, 0x8366c20, 0xbfadbe48)
Ipv4L3Protocol:GetInterface(0x83547b0, 1)
Received 1024 bytes from 10.1.1.2
Ipv4L3Protocol:DoDispose(0x83547b0)
Ipv4L3Protocol:DoDispose(0x8355090)
Ipv4L3Protocol:~Ipv4L3Protocol(0x83547b0)
Ipv4L3Protocol:~Ipv4L3Protocol(0x8355090)
</pre>

=== Connection Tracking ===

As mentioned earlier, connection tracking is implemented by registering appropriate connection tracking functions at each of the hooks except IP_FORWARD. Connection tracking is the largest and most essential component of this project. It significantly increases the code reusability, extensibility and ease of implementing a new helper class by providing an API to the developer.

The Ipv4Netfilter class maintains a list of layer 3 protocol helpers and layer 4 protocol helpers. These helpers are implemented by inheriting from '''NetfilterConntrackL3protocol''' and '''NetfilterConntrackL4Protocol''' respectively. When a packet traverses a hook, connection tracking looks up the layer 3 protocol helper from the list maintained by Ipv4Netfilter.

Ipv4Netfilter provides methods to register and unregister L3 protocol helpers using ''RegisterL3Protocol'' and ''UnRegisterL3Protocol'' respectively. Similar methods are available for registering and unregistering L4 Protocols.

Any L3 protocol helper needs to implement two callbacks, ''PacketToTuple'', which is used to convert a packet to a tuple that will be used by connection tracking, and ''GetL4Protocol'', which used to find out the L4 protocol for this packet such as TCP, UDP etc. This information is necessary in order to invoke the correct L4 helper. More importantly, each helper needs to register appropriate functions at each of the hooks. These functions maintain state in accordance with the protocol-specific rules.

Similar to L3 protocol helpers, each L4 protocol helper has to implement some callbacks which are invoked when a packet is handed over to the helper. These callbacks include, ''PacketToTupleCallback'', which is the same as before (but contains additional information at layer 4 such as the ports) and ''PacketVerdictCallback'', which determines whether this packet should continue to traverse the hooks, dropped or any of the other verdicts supported by the netfilter framework.

It is important to note that I am not focusing on implementing verdicts right now, because they will sidetrack me from the core functionality of this project. In order to implement, Network Address Translation, I do not need any kind of packet dropping support from the framework. Therefore, I will continue to implement modules which are relevant to NAT for now. Later on, after the project, the framework can be extended to include the support for verdicts and hence implement a firewall for ns-3.

Connection tracking needs to maintain state regarding on-going connections. For this purpose, a hash is maintained by the Ipv4Netfilter class. This hash stores connection tracking information regarding a four-tuple that consists of source IP address, source port, destination IP address and destination port. ns-3 code base does not have a hashing function for such a four-tuple. Therefore, I looked up the Linux kernel source code and found that it uses the Jenkins hash function.

GSOC2009NetworkAddressTranslationMidtermReport

2009-07-11T10:10:28Z

Qasimj: Made class names bold, method names italic

GSOC2009NetworkAddressTranslationMidtermReport

2009-07-11T10:02:08Z

Qasimj:

GSOC2009NetworkAddressTranslationMidtermReport

2009-07-11T10:00:46Z

Qasimj: New page: == Aim == The aim of this project is to implement Network Address Translation functionality for ns-3. Early on, we decided to build an extensible framework which can ease the task of addi...

== Aim ==

The aim of this project is to implement Network Address Translation functionality for ns-3. Early on, we decided to build an extensible framework which can ease the task of adding firewall functionality to ns-3 and hence increase code reusability as well.

== Background ==

I referred to the Linux kernel Netfilter framework for the ns-3 Netfilter implementation. Netfilter consists of five hooks which are possible places where the processing of the packet is handed over to the Netfilter framework. A developer can register functions at any of the hooks and those functions are called in turn as a packet traverses the hooks.

IPtables is a userspace utility that makes use of the Netfilter framework inside Linux kernel in order to facilitate the specification of firewall rules. However, IPtables does not interact directly with the Netfilter framework. Instead, there is a set of Linux kernel modules that mediate between IPtables and Netfilter. Modules are (un)pluggable pieces of code that run in kernel mode.

Connection tracking is an important part of the Netfilter framework. The framework provides a connection tracking API so that modules can register themselves as layer 3 protocol helpers, layer 4 protocol helpers, NAT helpers, protocol specific NAT helpers etc. IPv4 connection tracking is implemented by registerting connection tracking specific functions at each of the hooks except the forwarding one.

== Milestones ==

The project milsestones are as follows.

1. Implementation of Hooks within the IP stack
2. Connection tracking implementation using hooks
3. Implementation of NAT using the connection tracking API

Connection tracking is the largest module in this project. It involves implementation of hook functions that are required for connection tracking and includes data structures such as a hash for maintaining state regarding existing connections. Moreover, each Packet should have some additional information (in the form of a byte tag) so that when it traverses a hook, those changes can be noticed by other hooks. This information is necessary in order to determine if a packet is a reply packet.

Connection tracking module also provides an API so that IPv4 and TCPv4 helpers can register themselves using this API. This has the advantage of extensibility, as helpers for other protocols like SCTP can be written and registered using the API. This way whenever an SCTP packet will be encountered by the connection tracking hook functions, it will be handed over to the SCTP helper for further processing and updating of the current state.

== Implementation ==

Netfilter Hooks

Ipv4Netfilter is the main class which provides the functionality for registering and unregistering a function at a hook. Ipv4NetfilterHook class represents information that should be contained within a hook element before it is registered. For instance, a hook element must have the hook function that needs to be registered and will be invoked when a packet traverses this hook, the priority of the hook function, protocol family the hook is responsible for and which particular and the hook number where it should be registered. Hook numbers as represented as NF_INET_PREROUTING, NF_INET_POSTROUTING etc.

The priority of hook function is important because more than one function can be registered at a hook. Essentially, there is a priority list maintained at each hook. This is implemented using the NetfilterCallbackChain class.

When a hook function is registered using RegisterNetfilterHook, it is placed within the above mentioned priority list based on its priority. It will be invoked according to its priority when a packet traverses the hook at which this function was registered. Similarly, when a hook function is unregistered using UnRegisterNetfilterHook, the corresponding Ipv4NetfilterHook object is removed from the NetfilterCallbackChain for that hook.

Hooks have inserted at appropriate locations by inspecting ns-3 IP stack source code. For example, the PREROUTING hook has been placed in Ipv4L3Protocol::Receive method. It is important to note that this hook should be placed before the proceedings are handed over to the RouteInput method for whatever routing protocols have been registered. In order to insert the hooks, it was necessary to have a Ipv4Netfilter object as a private member of Ipv4L3Protocol class. I also had a detailed discussion with T.J. Kopena regarding this matter and we had concluded that it is better to add this as a member rather than aggregating an object of Ipv4Netfilter with Ipv4L3Protocol.

When a packet traverses a hook, it is handed over to the Netfilter framework using the Ipv4Netfilter::ProcessHook method. This method essentially invokes all registered callbacks in this hook's callback chain. As mentioned earlier, these callbacks are invoked in the order of priority.

The POSTROUTING hook is placed at multiple places, in Ipv4L3Protocol::Send and Ipv4L3Protocol::SendRealOut. This is so because there can be five different scenarios for sending the packet as mentioned in the comments of Ipv4L3Protocol::Send.

Although, I have not defined a log component for the Netfilter framework as yet, but I will definitely do that. In order to test the hooks, I had simply used the existing Ipv4L3Protocol log component. Also, I had registered functions at the Netfilter hooks within the Ipv4L3Protocol constructor. This will not stay the same and will be replaced by a user configuration API which will allow the script writer to register functions at any of the hooks. This will be done towards the end of the project as the most important part is to implement the core functionality of this framework.

The output from the log component clearly indicates that the hook functions are called at appropriate locations. I have used the example "first.cc" to demonstrate the hook functions. In this example, four packets are exchanged. This is obvious from the output below:

Connection Tracking

As mentioned earlier, connection tracking is implemented by registering appropriate connection tracking functions at each of the hooks except IP_FORWARD. Connection tracking is the largest and most essential component of this project. It significantly increases the code reusability, extensibility and ease of implementing a new helper class by providing an API to the developer.

The Ipv4Netfilter class maintains a list of layer 3 protocol helpers and layer 4 protocol helpers. These helpers are implemented by inherting from NetfilterConntrackL3protocol and NetfilterConntrackL4Protocol respectively. When a packet traverses a hook, connection tracking looks up the layer 3 protocol helper from the list maintained by Ipv4Netfilter.

Ipv4Netfilter provides methods to register and unregister L3 protocol helpers using RegisterL3Protocol and UnRegisterL3Protocol respectively. Similar methods are available for registering and unregistering L4 Protocols.

Any L3 protocol helper needs to implement two callbacks, PacketToTuple, which is used to convert a packet to a tuple that will be used by connection tracking, and GetL4Protocol, which used to find out the L4 protocol for this packet such as TCP, UDP etc. This information is necessary in order to invoke the correct L4 helper. More importantly, each helper needs to register appropriate functions at each of the hooks. These functions maintain state in accordance with the protocol-specific rules.

Similar to L3 protocol helpers, each L4 protocol helper has to implement some callbacks which are invoked when a packet is handed over to the helper. These callbacks include, PacketToTupleCallback, which is the same as before (but contains additional information at layer 4 such as the ports) and PacketVerdictCallback, which determines whether this packet should continue to traverse the hooks, dropped or any of the other verdicts supported by the netfilter framework.

It is important to note that I am not focusing on implementing verdicts right now, because they will sidetrack me from the core functionality of this project. In order to implement, Network Address Translation, I do not need any kind of packet dropping support from the framework. Therefore, I will continue to implement modules which are relevant to NAT for now. Later on, after the project, the framework can be extended to include the support for verdicts and hence implement a firewall for ns-3.

Connection tracking needs to maintain state regarding on-going connections. For this purpose, a hash is maintained by the Ipv4Netfilter class. This hash stores connection tracking information regarding a four-tuple that consists of source IP address, source port, destination IP address and destination port. ns-3 code base does not have a hashing function for such a four-tuple. Therefore, I looked up the Linux kernel source code and found that it uses the Jenkns-3 Netfilter Implementation

Midterm Report

Aim

The aim of this project is to implement Network Address Translation functionality for ns-3. Early on, we decided to build an extensible framework which can ease the task of adding firewall functionality to ns-3 and hence increase code reusability as well.

Background

I referred to the Linux kernel Netfilter framework for the ns-3 Netfilter implementation. Netfilter consists of five hooks which are possible places where the processing of the packet is handed over to the Netfilter framework. A developer can register functions at any of the hooks and those functions are called in turn as a packet traverses the hooks.

IPtables is a userspace utility that makes use of the Netfilter framework inside Linux kernel in order to facilitate the specification of firewall rules. However, IPtables does not interact directly with the Netfilter framework. Instead, there is a set of Linux kernel modules that mediate between IPtables and Netfilter. Modules are (un)pluggable pieces of code that run in kernel mode.

Connection tracking is an important part of the Netfilter framework. The framework provides a connection tracking API so that modules can register themselves as layer 3 protocol helpers, layer 4 protocol helpers, NAT helpers, protocol specific NAT helpers etc. IPv4 connection tracking is implemented by registerting connection tracking specific functions at each of the hooks except the forwarding one.

Milestones

The project milsestones are as follows.

1. Implementation of Hooks within the IP stack
2. Connection tracking implementation using hooks
3. Implementation of NAT using the connection tracking API

Connection tracking is the largest module in this project. It involves implementation of hook functions that are required for connection tracking and includes data structures such as a hash for maintaining state regarding existing connections. Moreover, each Packet should have some additional information (in the form of a byte tag) so that when it traverses a hook, those changes can be noticed by other hooks. This information is necessary in order to determine if a packet is a reply packet.

Connection tracking module also provides an API so that IPv4 and TCPv4 helpers can register themselves using this API. This has the advantage of extensibility, as helpers for other protocols like SCTP can be written and registered using the API. This way whenever an SCTP packet will be encountered by the connection tracking hook functions, it will be handed over to the SCTP helper for further processing and updating of the current state.

Implementation

Netfilter Hooks

Ipv4Netfilter is the main class which provides the functionality for registering and unregistering a function at a hook. Ipv4NetfilterHook class represents information that should be contained within a hook element before it is registered. For instance, a hook element must have the hook function that needs to be registered and will be invoked when a packet traverses this hook, the priority of the hook function, protocol family the hook is responsible for and which particular and the hook number where it should be registered. Hook numbers as represented as NF_INET_PREROUTING, NF_INET_POSTROUTING etc.

The priority of hook function is important because more than one function can be registered at a hook. Essentially, there is a priority list maintained at each hook. This is implemented using the NetfilterCallbackChain class.

When a hook function is registered using RegisterNetfilterHook, it is placed within the above mentioned priority list based on its priority. It will be invoked according to its priority when a packet traverses the hook at which this function was registered. Similarly, when a hook function is unregistered using UnRegisterNetfilterHook, the corresponding Ipv4NetfilterHook object is removed from the NetfilterCallbackChain for that hook.

Hooks have inserted at appropriate locations by inspecting ns-3 IP stack source code. For example, the PREROUTING hook has been placed in Ipv4L3Protocol::Receive method. It is important to note that this hook should be placed before the proceedings are handed over to the RouteInput method for whatever routing protocols have been registered. In order to insert the hooks, it was necessary to have a Ipv4Netfilter object as a private member of Ipv4L3Protocol class. I also had a detailed discussion with T.J. Kopena regarding this matter and we had concluded that it is better to add this as a member rather than aggregating an object of Ipv4Netfilter with Ipv4L3Protocol.

When a packet traverses a hook, it is handed over to the Netfilter framework using the Ipv4Netfilter::ProcessHook method. This method essentially invokes all registered callbacks in this hook's callback chain. As mentioned earlier, these callbacks are invoked in the order of priority.

The POSTROUTING hook is placed at multiple places, in Ipv4L3Protocol::Send and Ipv4L3Protocol::SendRealOut. This is so because there can be five different scenarios for sending the packet as mentioned in the comments of Ipv4L3Protocol::Send.

Although, I have not defined a log component for the Netfilter framework as yet, but I will definitely do that. In order to test the hooks, I had simply used the existing Ipv4L3Protocol log component. Also, I had registered functions at the Netfilter hooks within the Ipv4L3Protocol constructor. This will not stay the same and will be replaced by a user configuration API which will allow the script writer to register functions at any of the hooks. This will be done towards the end of the project as the most important part is to implement the core functionality of this framework.

The output from the log component clearly indicates that the hook functions are called at appropriate locations. I have used the example "first.cc" to demonstrate the hook functions. In this example, four packets are exchanged. This is obvious from the output below:

Connection Tracking

As mentioned earlier, connection tracking is implemented by registering appropriate connection tracking functions at each of the hooks except IP_FORWARD. Connection tracking is the largest and most essential component of this project. It significantly increases the code reusability, extensibility and ease of implementing a new helper class by providing an API to the developer.

The Ipv4Netfilter class maintains a list of layer 3 protocol helpers and layer 4 protocol helpers. These helpers are implemented by inherting from NetfilterConntrackL3protocol and NetfilterConntrackL4Protocol respectively. When a packet traverses a hook, connection tracking looks up the layer 3 protocol helper from the list maintained by Ipv4Netfilter.

Ipv4Netfilter provides methods to register and unregister L3 protocol helpers using RegisterL3Protocol and UnRegisterL3Protocol respectively. Similar methods are available for registering and unregistering L4 Protocols.

Any L3 protocol helper needs to implement two callbacks, PacketToTuple, which is used to convert a packet to a tuple that will be used by connection tracking, and GetL4Protocol, which used to find out the L4 protocol for this packet such as TCP, UDP etc. This information is necessary in order to invoke the correct L4 helper. More importantly, each helper needs to register appropriate functions at each of the hooks. These functions maintain state in accordance with the protocol-specific rules.

Similar to L3 protocol helpers, each L4 protocol helper has to implement some callbacks which are invoked when a packet is handed over to the helper. These callbacks include, PacketToTupleCallback, which is the same as before (but contains additional information at layer 4 such as the ports) and PacketVerdictCallback, which determines whether this packet should continue to traverse the hooks, dropped or any of the other verdicts supported by the netfilter framework.

It is important to note that I am not focusing on implementing verdicts right now, because they will sidetrack me from the core functionality of this project. In order to implement, Network Address Translation, I do not need any kind of packet dropping support from the framework. Therefore, I will continue to implement modules which are relevant to NAT for now. Later on, after the project, the framework can be extended to include the support for verdicts and hence implement a firewall for ns-3.

Connection tracking needs to maintain state regarding on-going connections. For this purpose, a hash is maintained by the Ipv4Netfilter class. This hash stores connection tracking information regarding a four-tuple that consists of source IP address, source port, destination IP address and destination port. ns-3 code base does not have a hashing function for such a four-tuple. Therefore, I looked up the Linux kernel source code and found that it uses the Jenkin's hash function for this purpose. I have borrowed this piece of code from the Linux Kernel and is availble using the the header file "jhash.h".

The NetfilterConntrackTuple class implements the above mentioned tuple. In addition to the four members mentioned above, protocol family and direction (original/reply) is also included as members of the class. ConntrackTupleHash class implements the hashing function for the NetfilterConntrackTuple.

In addition to the above, there also needs to be some information regarding what kind of changes are made to the packet while it traverses the hook. Borrowing from Linux kernel terminology, a packet is supposed to be "confirmed", if it traverses the PREROUTING hook, goes through it successfully and finally goes out of through POSTROUTING. In order to maintain this information on per packet basis, a byte tag can be added to the packet and modified as it traverses the relevant hooks.

As of now, I am in the process of implementing the IPv4 helper which will be followed by the implementation of TCPv4 helper. Once that is done, a NAT helper will be written to add Network Address Translation functionality to ns-3.

There also needs to be a mechanism for the user to configure NAT and add/remove hook functions. This constitues the third milestone and will also be provided.in's hash function for this purpose. I have borrowed this piece of code from the Linux Kernel and is availble using the the header file "jhash.h".

The NetfilterConntrackTuple class implements the above mentioned tuple. In addition to the four members mentioned above, protocol family and direction (original/reply) is also included as members of the class. ConntrackTupleHash class implements the hashing function for the NetfilterConntrackTuple.

In addition to the above, there also needs to be some information regarding what kind of changes are made to the packet while it traverses the hook. Borrowing from Linux kernel terminology, a packet is supposed to be "confirmed", if it traverses the PREROUTING hook, goes through it successfully and finally goes out of through POSTROUTING. In order to maintain this information on per packet basis, a byte tag can be added to the packet and modified as it traverses the relevant hooks.

As of now, I am in the process of implementing the IPv4 helper which will be followed by the implementation of TCPv4 helper. Once that is done, a NAT helper will be written to add Network Address Translation functionality to ns-3.

There also needs to be a mechanism for the user to configure NAT and add/remove hook functions. This constitues the third milestone and will also be provided.

GSOC2009NetworkAddressTranslation

2009-07-11T09:57:48Z

Qasimj: Added a link to the midterm report

== Introduction ==

The aim of this project is to add Network Address Translation (NAT) functionality to ns-3. Instead of just implementing NAT, we are working on implementing an extensible framework. This way if firewall functionality needs to implemented in the future, the framework can be used to do that. The inspiration for such a framework comes from the netfilter framework in the Linux kernel.

Netfilter creates fives hooks in the Linux kernel networking stack. A developer can register functions at each of the hooks. These functions get called when a packet traverses the hook. While registering a function at a hook, a priority needs to be specified which will determine the order in which the function will be executed. Userspace utilities such as iptables do not interact directly with netfilter, rather, they interact with kernel modules which in turn interact with the netfilter framework.

We aim to implement something similar to netfilter framework for ns-3. This will make it easy to add firewall functionality to ns-3 in the future.

== Background ==

A Linux kernel module can register multiple functions at each of the netfilter hooks. The netfilter framework maintains a 2-dimensional array nf_hooks[NFPROTO_NUMPROTO][NF_MAXHOOKS] of circular linked lists. When a function is registered using nf_register_hook, a variable of type "struct nf_hook_ops" (which contains the function to be registered) is added to the appropriate list. The position within the list is determined by the priority specified in the "struct nf_hook_ops" type variable.

When a packet traverses the hook, for instance, in ip_rcv function, NF_HOOK macro is called which ends up invoking nf_hook_slow. This is the interface between the routing code and the netfilter framework. As this is the NF_PREROUTING hook, and assuming that IPv4 is being used, the linked list at nf_hooks[PF_INET][NF_PREROUTING] is consulted and the functions registered at the hook are invoked. The nf_iterate function is used to iterate through the linked list, invoking the "hook" member of the "struct nf_hook_ops" variable in turn.

The iptables userspace utility is used to add/remove/update the rules for the netfilter framework. It does not interact directly with the netfilter framework, instead, iptables works with kernel modules which in turn use the netfilter framework to implement the rule.

A rule is composed of two parts. A selection criterion and a verdict for the packet that matches the selection criteria. The verdict might entail dropping the packet, letting the packet go, changing the packet in a certain manner etc.

== Approach ==

In order to implement Network Address Translation, we need to be able to defragment the IP packets. Also, hooks will be implemented using the ns-3 callbacks. These hooks will be added to appropriate locations in the ns-3 networking stack. More details will be added soon.

There will be a class which will store the mappings created by Network Address Translation. Moreover, there needs to be way for the user to configure NAT. This should be dynamic considering that the framework can be used for packet inspection or firewall.

Connection tracking will implement protocol specific handlers for NAT. For instance, FTP, ICMP, SIP etc. Although this project will not implement the handlers themselves but it aims to provide an API so that developers can implement protocol specific connection tracking.

* IP packet defragmentation
* Five hooks (using ns-3 callbacks)
* A class that stores the NAT mappings (4-tuples)
* A mechanism to configure NAT
* Connection tracking

== Schedule ==

The first two weeks will be spent studying the ns-3 networking stack and how a framework similar to netfilter can be implemented for ns-3.

* Week 3: Implement and test IP packet defragmentation
* Week 4,5: Implement hooks using ns-3 callbacks and a class for storing the created NAT mappings
* Week 6: Test basic NAT functionality
* Week 7-8: Implement Connection tracking API and start testing
* Week 9: Implement any NAT helpers or user configuration options
* Week 10: Merge with ns-3 codebase

== Midterm Report ==

The midterm report for this project can be found at [[GSoC2009NetworkAddressTranslationMidtermReport | NAT Midterm Report]]

== Questions ==

GSOC2009NetworkAddressTranslation

2009-06-11T09:29:07Z

Qasimj:

GSOC2009NetworkAddressTranslation

2009-06-11T09:23:03Z

Qasimj:

== Introduction ==

The aim of this project is to add Network Address Translation (NAT) functionality to ns-3. Instead of just implementing NAT, we are working on implementing an extensible framework. This way if firewall functionality needs to implemented in the future, the framework can be used to do that. The inspiration for such a framework comes from the netfilter framework in the Linux kernel.

Netfilter creates fives hooks in the Linux kernel networking stack. A developer can register functions at each of the hooks. These functions get called when a packet traverses the hook. While registering a function at a hook, a priority needs to be specified which will determine the order in which the function will be executed. Userspace utilities such as iptables do not interact directly with netfilter, rather, they interact with kernel modules which in turn interact with the netfilter framework.

We aim to implement something similar to netfilter framework for ns-3. This will make it easy to add firewall functionality to ns-3 in the future.

== Background ==

A Linux kernel module can register multiple functions at each of the netfilter hooks. The netfilter framework maintains a 2-dimensional array nf_hooks[NFPROTO_NUMPROTO][NF_MAXHOOKS] of circular linked lists. When a function is registered using nf_register_hook, a variable of type "struct nf_hook_ops" (which contains the function to be registered) is added to the appropriate list. The position within the list is determined by the priority specified in the "struct nf_hook_ops" type variable.

When a packet traverses the hook, for instance, in ip_rcv function, NF_HOOK macro is called which ends up invoking nf_hook_slow. This is the interface between the routing code and the netfilter framework. As this is the NF_PREROUTING hook, and assuming that IPv4 is being used, the linked list at nf_hooks[PF_INET][NF_PREROUTING] is consulted and the functions registered at the hook are invoked. The nf_iterate function is used to iterate through the linked list, invoking the "hook" member of the "struct nf_hook_ops" variable in turn.

== Approach ==

In order to implement Network Address Translation, we need to be able to defragment the IP packets. Also, hooks will be implemented using the ns-3 callbacks. These hooks will be added to appropriate locations in the ns-3 networking stack. More details will be added soon.

There will be a class which will store the mappings created by Network Address Translation. Moreover, there needs to be way for the user to configure NAT. This should be dynamic considering that the framework can be used for packet inspection or firewall.

Connection tracking will implement protocol specific handlers for NAT. For instance, FTP, ICMP, SIP etc. Although this project will not implement the handlers themselves but it aims to provide an API so that developers can implement protocol specific connection tracking.

* IP packet defragmentation
* Five hooks (using ns-3 callbacks)
* A class that stores the NAT mappings (4-tuples)
* A mechanism to configure NAT
* Connection tracking

== Schedule ==

The first two weeks will be spent studying the ns-3 networking stack and how a framework similar to netfilter can be implemented for ns-3.

* Week 3: Implement and test IP packet defragmentation
* Week 4,5: Implement hooks using ns-3 callbacks and a class for storing the created NAT mappings
* Week 6: Test basic NAT functionality
* Week 7-8: Implement Connection tracking API and start testing
* Week 9: Implement any NAT helpers or user configuration options
* Week 10: Merge with ns-3 codebase

== Questions ==

GSOC2009NetworkAddressTranslation

2009-06-06T10:39:20Z

Qasimj: /* Schedule */

GSOC2009NetworkAddressTranslation

2009-06-06T10:38:39Z

Qasimj: /* Approach */

GSOC2009NetworkAddressTranslation

2009-06-06T10:30:08Z

Qasimj: /* Approach */