One of the most powerful tools to have when doing any type of design that involves communication protocols is a protocol analyzer. It allows you to see exactly what the communicating devices are seeing which is very useful for troubleshooting many types of problems that might come up. This is especially important for wireless communications because this is often the only way to see what type of data is going over the air. It also allows the user to see if there are any rogue frames, check for breaches of the communication protocol, analyze traffic, or reverse engineer a proprietary protocol. And of course, it’s extremely useful for learning about how a protocol operates and behaves in real-life.

Wireshark is probably one of the most well-known of all protocol analyzers. It’s widely used in the IT world for analyzing network problems, bottlenecks, failed hardware, and a host of other things. It’s also used in the security world for snooping, packet analysis, and reverse engineering. Over the past 2-3 years, wireshark support for the IEEE 802.15.4 protocol has been growing and improving due to contributions from the wireless sensor network community and the increased interest and usage of protocols that ride on top of 802.15.4 such as Zigbee and 6LoWPAN (IPv6 over 802.15.4). However it has always been a challenge to get raw 802.15.4 data frames fed into Wireshark.

The problem with feeding wireshark is that it usually uses libpcap (winpcap on windows) for the packet capture and those libraries mainly capture data from network interfaces, ie: ethernet or Wi-Fi. The 802.15.4/6LoWPAN community got around this by emulating an ethernet interface on the Atmel Raven USB boards and encapsulating 802.15.4 frames inside ethernet packets. One of the first companies to put out an interface for 802.15.4 to Wireshark was Exegin and they actually used a gateway router that took 802.15.4 frames, encapsulated them into UDP payloads, ran them down a UDP/IP stack into an ethernet interface, and from there, got them inside libpcap to feed wireshark. There was some serious protocol stacking going on there just to get data into the analyzer.


So anyways, there is an actual point to this post. I though it would be interesting to convert the Freakduino boards into a wireless sniffer and feed the raw data into wireshark. It also demonstrates how Arduino-based boards can be turned into powerful, low-cost tools for communications software development and security research.

One of the benefits of an open source protocol stack is that you can configure it however you want. In the case of chibi and chibiArduino, the main modification was to put the radio into promiscuous mode. In this mode, the radio is just a listener that accepts all packets and dumps them out to the serial port. The modifications to the stack were actually very minimal. The protocol stack relies on the hardware features of the Atmel radio to do a lot of the 802.15.4 protocol handling. To enable promiscuous mode, all the extended hardware features such as address filtering and auto-ACK were disabled. The associated Arduino sketch is minimal, almost shorter than the hello_world example, and just waits for received data and dumps it out the serial port. The Chibi promiscuous mode demo is also mainly a two line change from the original demo. Before proceeding, you'll want to get the Chibi stack (from v0.91) or chibiArduino stack (from v0.51) from the project pages

Once you have access to the raw data, the next step is to figure out how to get it into Wireshark. There are three main ways to feed the shark: capture data via a network interface, open a static packet capture file, or piping the data into the program. I chose the last option which is probably the least common way to get data into wireshark and deserves a bit more explanation.  

Wireshark supports packet capture via named pipes which is a form of interprocess communications (IPC) supported by most OSes. Interprocess communications is a way for one program (process) on an OS to talk to another. In the case of named pipes, one program creates a pseudo file to write into and another program opens that file and reads from it. People that use Linux or Unix are probably familiar with the pipe operator (“|”) which sends data from one program into another. A named pipe behaves similarly but the pipe has a filename and location associated with it.

Once the communications method was established, the next task was to take the raw data from the serial port and put it in the packet capture format that wireshark understands. Normally this is handled by libpcap but since libpcap doesn’t support serial port interfaces natively, I decided it was easiest just to implement this manually.

The libpcap capture format is a binary format that’s fairly straightforward. At the beginning of the capture, you need to pass in a global header which tells wireshark some needed parameters like endian-ness and the base data link protocol. After that, you need to add a frame header for each raw frame you pass into it. The frame header give wireshark the length of the frame and the timestamp. The raw data frame comes after the frame header.

That’s pretty much it. I wrote an application to open a named pipe, take the raw data from the serial port, add on the headers, and feed it into wireshark. To use it, you just need to run the program, open wireshark, and input the named pipe in the capture interface. I call the application "WSbridge" and you can get it from the Projects page under WSBridge.

I’ve also put together a little tutorial on how to use it with the Freakduino . I’ve made the firmware modifications in the chibi and chibiArduino stack so either one can be used to capture the raw data and output it via the serial port. You'll need to enable the promiscuous mode feature inside the stack. Don't forget to disable it after you're done :)

The application was written in two different languages. For Windows, I wrote the application in C# since I figured it’d be easier to support all the different Windows flavors using the .Net framework. I know some good C# developers too so I figured it'd be easier for them to improve on the code if its written in their preferred language. I also wrote the application in C for Linux and Mac OSX. Unfortunately, it works fine on Linux but I can’t seem to get the serial port to dump data in Mac OSX with the wsbridge application. I naively assumed that both OSes would behave similarly since both of them are Unix based and support a standard POSIX interface. Interestingly enough, everything is perfectly fine on OSX with the standard chibi or chibiArduino command line interface using a terminal program so I figure there must be something I'm missing in my application code. If anyone wants to take a crack at getting the application to work on OSX, it’d be much appreciated.

Also, I wrote both applications as console programs so that they can be used in a batch file. That way, you don’t need to manually open both programs each time you want to capture data. The location of the pipes are different on Windows and Linux. Windows puts their named pipes in the \\.\pipe\ location by default. I put the location of the named pipe in the /tmp/ directory on Linux since it's universally writeable by applications. Notice that on Windows, backslashes are used but on Linux, forward slashes are used. You can change the locations and names of the pipes in the source code, too.

The tutorial is below. One thing to note is that the tutorial assumes that Wireshark is installed, the Chibi or chibiArduino release supporting promiscuous mode has been downloaded, and you're using hardware that supports the protocol stacks. Also, please feel free to post any comments, questions, or suggestions about the tutorial.

That’s about it. Hope you enjoy it and happy sniffing :)

{gallery}2010-12-28 Wireshark2{/gallery}