SYSADMIN Singwall Building a Netfilter firewall module SINGING LESSON We’ll show you how to build your own Netfil- ter extension with this example of a musical firewall. BY MARK VOGELSBERGER The Singwall module described in this article provides a means for the admin to listen to network traffic in real- time. Singwall is a singing firewall exten- sion for Netfilter. The firewall chirps when a packet arrives, and the pitch of the sound varies depending on the port number addressed by the packet. Hooked The Netfilter model lets developers pro- gram kernel modules that hook into the have to be a pro- chain of execution for network packets. picpics, Fotolia picpics, grammer to access the The first task the module needs to han- powers of Netfilter. dle is registering a hook. This registra- However, if you are tion tells the kernel what the module ready for a little pro- wants to do. Registration is managed gramming, you can use the through two appropriately named func- built-in Netfilter hooks to create tions: nf_register_hook(struct nc_hook_ your own custom firewall modules. ops*) and nf_unregister_hook(struct nc_ This article takes you through the hook_ops*). The latter function removes steps of building a custom Netfilter mod- the hook. It is important to unload the ule. The discussion focuses on the exam- module, as failure to do so could cause ple of a “singing” firewall that plays a fairly messy kernel errors. The crystalli- sound whenever a packet arrives, how- zation point for registering a hook is the ever, the concepts in this article also nc_hook_ops structure: etfilter is the Linux kernel sub- applies to your own creative uses of the system behind firewall tools Netfilter subsystem. struct nf_hook_ops { Nsuch as the famous Iptables. struct list_head list; The Netfilter subsystem provides the A Singing Firewall nf_hookfn *hook; structure for packet filtering and address Firewall log entries keep administrators struct module *owner; translation by offering a series of hooks up to date on data packets, but from a int pf; into the network protocol stack. physiological and psychological point of int hooknum; You can find many commands, scripts, view, peering at log files all day can be- int priority; and front-end applications for accessing come tedious, and important informa- }; the Netfilter subsystem – including tools tion can get lost. Of course, you’ll need such as Shorewall and Firestarter, as the log files anyway, but why not have a This structure provides all the informa- well as the native Iptables – so you don’t secondary alert system? tion the kernel needs to deploy the hook. 64 ISSUE 71 OCTOBER 2006 WWW.LINUX - MAGAZINE.COM Singwall SYSADMIN The first entry in the structure is for second on the list: skb. This argument is ing, whereas NF_ACCEPT lets the packet management in a linked list. The hook a pointer to a sk_buff structure (a socket through. This arrangement makes it function itself is stored as a pointer in buffer). The kernel uses this critical net- quite easy to write a minimal firewall. hook. The Linux kernel uses this hook work data structure to transfer data effi- If the filter does not like the looks of the function pointer later to call the kernel ciently between the individual network packet it has just inspected, the hook re- module. The owner entry stores the cor- layers. turns NF_DROP, and the kernel takes responding module; this entry is also care of the dirty work. The singing fire- found in numerous other kernel struc- Packet Analysis wall always returns NF_ACCEPT, as it tures. The packet analysis we want the singing simply analyzes the network data with- firewall to perform can be handled using out filtering them. Choosing a Protocol the socket buffer. The complex sk_buff The last three entries in the nc_hook_ops structure is provided by linux/skbuff.h. Opus 1 structure are of particular interest: pf This structure uses a data pointer to As an overture, let’s ask Singwall to tag specifies the protocol family (OSI net- point to the network data and extracts UDP, TCP, and ICMP packets with tones work layer) the hook is interested in. a variety of management information. of different pitches. In case of TCP, a sec- linux/socket.h contains a list of possible In the case of TCP data, the firewall first ond tone will indicate the port, and thus pf values. extracts the TCP header, which in turn will tell us the underlying service based The PF_INET value is reserved for gives the firewall the ability to extract on analysis of the TCP header. Ipv4, because the Ipv4 protocol system the port number. The tcphdr structure stores the header is the network protocol used by the Sing- The hook’s return values specify what data. To extract the port number, Sing- wall module. The hooknum value speci- kind of post-processing actions to apply wall reads the dest field. The value first fies the position where the hook latches to the packets. The return values, which has to be converted to the machine’s in. Hooks are numbered, and a macro are listed in linux/netfilter.h, include set- byte order. The ntohs(unsigned short int assigns names to them. The possible val- tings such as NF_DROP and NF_ACCEPT. netshort) function handles this, return- ues for IPv4 are listed in linux/netfilter_ NF_DROP drops the packet after process- ing the port number as an integer. The ipv4.h. We want the singing firewall to make a different noise for different incoming incoming network data and outgoing packet types. Two hooks – hooknum=NF_IP_LOCAL_OUT for out- going packets and hooknum=NF_IP_ Investigate protocol LOCAL_IN for incoming packets – will handle this. The last entry in the nf_hook_ops others UDP ICMP TCP structure specifies the priority with which the kernel should insert the new frequency in writ e hook into the list of existing hooks. Net- ring buffer filter processes hooks based on their pri- ority. The priority values for IPv4 are 200 300 100 frequency value also detailed in linux/netfilter_ipv4.h. We can assign a value of priority=NF_ IP_PRI_FIRST for the Singwall to put the identify service hook at the top of the list. Arguments FTP SSH HTTP SSL A hook prototype, or the hook function to be more precise, is defined in linux/ frequency in netfilter.h: write ring buffer typedef unsigned int nf_hookfn( 1000 1500 2000 2500 frequency value unsigned int hooknum, struct sk_buff **skb, const struct net_device *in, const struct net_device *out, int (*okfn)(struct sk_buff *) end of analysis ); The critical argument, and in fact the Figure 1: The kernel uses a Netfilter hook to pass incoming packets to Singwall. The module only relevant argument for Singwall, is analyzes the protocol, calculates a frequency, and writes the results to a ring buffer. WWW.LINUX - MAGAZINE.COM ISSUE 71 OCTOBER 2006 65 SYSADMIN Singwall packet analysis process is shown in arrive so quickly that the tone_pos_coun- sion. Although ping 127.0.0.1 -f or mass Figure 1. ter and tone_counter become unsynchro- downloads led to multiple resyncs, this A problem at the hardware/ human nized by more than the RANGE_SYNC did not spoil the sing-along session. interface prevents a straightforward im- value, the code resynchronizes, setting Singwall uses the PC speaker to output plementation. Network traffic is typically tone_pos_counter to the value of tone_ tones. The code tells the speaker to so fast that the human ear would not be counter. squawk at the required frequency (al- able to register the individual beeps. To The ring buffer is shown in Figure 2a. though we have had a few issues with slow things down, Singwall implements This approach ignores many packets in mute speakers on newer hardware). We a ring buffer with a length of RING_SIZE. case of heavy traffic, but as field tests decided on a tone length of 20 millisec- The hook fucn writes the tones to play to show, ignoring packets does not onds – this is a compromise between this buffer. necessarily mean you will miss hearing audibility and fast handling, which is Two counters store the position of the any connections. important to avoid missing more packets next tone to be played (tone_counter) The singing firewall implementation than necessary. and the position of the next free entry we have looked at thus far had no trou- Of course, we need to avoid a situ- (tone_pos_counter). If network packets ble following a normal web surfing ses- ation where the firewall is blocking the Listing 1: Singwall Listing 1: Singwall 001 #include <linux/version.h> counter(void) { 054 pr_ 108 {tone[tone_pos_ ak;} func; 002 #include <linux/module.h> 031 if(tone_pos_counter<RING_ debug("SingingFirewall: counter]=100; check=1;} 128 case 443: {tone[tone_ 152 nfho_out.hooknum = NF_IP_ Resyncing %d<---%d!\n", 003 #include <linux/kernel.h> SIZE-1) 109 if (sk->nh.iph->protocol == pos_counter]=2500;check=1;bre LOCAL_OUT; tone_pos_counter++; 055 tone_counter,tone_pos_ IPPROTO_UDP) ak;} 004 #include <linux/netfilter.h> 153 nfho_out.pf = PF_INET; 032 else tone_pos_counter=0; counter); 110 {tone[tone_pos_ 129 } 005 #include <linux/netfilter_ 154 nfho_out.priority = NF_IP_ 056 tone_pos_counter=tone_ counter]=200; check=1;} ipv4.h> 033 } 130 PRI_FIRST; counter; 111 if (sk->nh.iph->protocol == 006 #include <linux/init.h> 034 131 if (check) { 155 057 } 035 void update_tone_ IPPROTO_ICMP) 007 #include <linux/tcp.h> 132 update_tone_pos_ 156 nfho_in.hook = hook_ counter(void) { 058 } 112 {tone[tone_pos_ counter(); func; 008 #include <asm/io.h> counter]=300; check=1;} 036 if(tone_counter<RING_SIZE- 059 133 check_syncing(); 157 nfho_in.hooknum