Introduction

Now that you have learned about Ethereal, how it works, and how to use it, you are armed and ready to read real network packet captures. In this chapter we discuss real world packet captures and traffic that you could be seeing on your network. You will learn how to read the captures, what to look for, and how to identify various types of network traffic. The Honeynet Project at http://project.honeynet.org provided some of the packet capture data in this chapter, which we have included on the accompanying CD-ROM in the /captures directory. They have a great challenge called Scan of the Month that will exercise your capture analysis abilities.

Scanning

Network scanning is used to identify available network resources. Also known as discovery or enumeration, network scanning can be used to discover available hosts, ports, or resources on the network. Once a vulnerable resource is detected it can be exploited and the device compromised. Sometimes there is an actual intruder behind the scanning and sometimes it is a result of worm activity. We will be focusing on active intruder scanning in this section, while worm activity will be covered in a later section. Security professionals also use network scanning to assist in securing and auditing the network. In this section we will be using Scan1.log, which contains several different types of scans and was provided by the Honeynet Research Alliance as part of the Honeynet Project Scan of the Month challenge. Scan1.log is located on the accompanying CD-ROM in the /captures directory.

Note

The Transmission Control Protocol (TCP) protocol is connection-oriented and is initialized by completing a 3-way handshake. The TCP 3-way handshake consists of an initial packet sent with the SYN flag, a return packet with both the SYN and ACK flags, and completed with a packet with an ACK flag.

TCP Connect Scan

The first scan that we will be analyzing is the TCP Connect scan. It is used to determine which ports are open and listening on a target device. This is the most basic form of scanning because it completes the TCP 3-way handshake with open ports, and immediately closes them. An intruder sends a SYN packet and analyzes the response. A response packet with the Reset (RST) and Acknowledgment (ACK) flags set indicates the port is closed. If a SYN/ACK is received it indicates that the port is open and listening. The intruder will then respond with an ACK to complete the connection followed by a RST/ACK to immediately close the connection. This aspect of the scan makes it easily detectable because the connection attempts error messages will be logged.

Figure 8.1 shows the attacker, 192.168.0.9, sending SYN packets to the target, 192.168.0.99. Most ports respond with a RST/ACK packet, however the highlighted packets show the SYN/ACK response, and subsequent ACK followed by the RST/ACK, exchanged on the domain name system (DNS) port. You will also notice that the intruder’s source port increases by one for each attempted connection.

Figure 8.1: TCP Connect Scan

Figure 8.2 shows the active ports on the target device. You can find these by using a filter such as tcp.flags.syn==1&&tcp.flags.ack==1 or tcp.flags==18, to view packets with the SYN and ACK flags set. The filter will show multiple responses for each port, as several scanning methods were used. We removed the duplicates by saving the marked packets to a file.

Figure 8.2: SYN/ACK Responses

Note

The filter tcp.flags==18 will display packets with the SYN and ACK flags set because the binary value of the TCP flags field of a SYN/ACK packet is 00010010, which equals 18 in decimal format.

SYN Scan

The next scan that we will be analyzing is a TCP SYN scan, also known as a half-open scan because a full TCP connection is never completed. It is used to determine which ports are open and listening on a target device. An intruder sends a SYN packet and analyzes the response. If an RST/ACK is received it indicates the port is closed. If a SYN/ACK is received it indicates that the port is open and listening. The intruder will then follow with an RST to close the connection. SYN scans are known as stealth scans because not as many devices will notice or log them, as they never create a full connection. However, many current firewalls and Intrusion Detection Systems (IDSs) will notice this type of activity.

In Figure 8.3, the attacker, 192.168.0.9, is sending SYN packets to the target, 192.168.0.99. Most ports respond with an RST/ACK packet, however the highlighted packets show the SYN/ACK response, and subsequent RST exchange on the https port. You will also notice that the intruder is using a somewhat static pair of source ports, 52198 and 52199.

Figure 8.3: SYN Scan

Xmas Scan

The Xmas scan determines which ports are open by sending packets with invalid flag settings to a target device. It is considered a stealth scan because it may be able to bypass some firewalls and IDSs more easily than the SYN scans. This Xmas scan sends packets with the Finish (FIN), Push (PSH), and Urgent (URG) flags set. Closed ports will respond with an RST/ACK and open ports will drop the packet and not respond. However, this type of scan will not work against systems running Microsoft Windows, Cisco, BSDI, HP/UX, MVS, and IRIX. They will all respond with RST packets, even from open ports.

Notice in Figure 8.4 that the attacker, 192.168.0.9, is sending packets to the target 192.168.0.99 with the FIN, PSH, and URG flags set. Most ports respond with an RST/ACK packet, however the highlighted packet for the sunrpc port never receives a response. This is an indication that the port is open and has dropped the packet. You will also notice that the intruder is using decoy addresses of 192.168.0.1, 192.168.0.199, and 192.168.0.254. Decoy addresses are often used to obscure the real intruder’s Internet Protocol (IP) address making it harder to track down the real source of the scan. Looking closely at those packets reveals the same Media Access Control (MAC) address for all IP addresses. You will also notice that the intruder is using a somewhat static pair of source ports, 35964 and 35965.

Figure 8.4: Xmas Scan

Null Scan

The Null scan determines which ports are open by sending packets with invalid flag settings to a target device. It is considered a stealth scan because it may be able to bypass some firewalls and IDSs easier than the SYN scans. This Null scan sends packets with all flags turned off. Closed ports will respond with an RST/ACK and open ports will drop the packet and not respond. However, this type of scan will not work against systems running Microsoft Windows, Cisco, BSDI, HP/UX, MVS, and IRIX. They will all respond with RST/ACK packets, even from open ports.

In Figure 8.5, the attacker, 192.168.0.9, is sending packets to the target 192.168.0.99 with all flags turned off, as indicated by the empty brackets []. Most ports respond with an RST/ACK packet, however the highlighted packet for the https port never receives a response. This is an indication that the port is open and has dropped the packet. Notice that the intruder is using a somewhat static pair of source ports, 42294 and 42295.

Figure 8.5: Null Scan

Remote Access Trojans

The term trojan horse originally came from the Greek epic poem the Iliad, by Homer. In the story of the Trojan war, the Greeks left a large wooden horse as an apparent peace offering to the Trojans. Once the horse was brought inside the city walls of Troy, the Greek soldiers that were hiding inside of the hollow horse emerged and assisted in capturing the city. In the information security field, trojans are malicious programs that are often disguised as other programs such as jokes, games, network utilities, and sometimes even the trojan removal program itself! Trojans are often used to distribute backdoor programs without the victim being aware that they are being installed. Backdoors operate in a client-server architecture and allow the intruder to have complete control of a victim’s computer, remotely over the network. They give an intruder access to just about every function of the computer including logging keystrokes, activating the webcam, logging passwords, uploading and downloading files, and much, much more. They even have password protection and encryption features for intruders to protect the computers they own! There are hundreds, maybe even thousands, of trojan programs circulating the Internet, usually with many variations of the code. This makes them very difficult to detect with antivirus software.

In this section we will be using Scan2.log that was provided by the Honeynet Research Alliance as part of the Honeynet Project Scan of the Month challenge. Scan2.log is located on the accompanying CD-ROM in the /captures directory. We will also be using our own, lab-created backdoor packet captures called subseven_log and netbus_log, also located on the accompanying CD-ROM in the /captures directory.

SubSeven Legend

SubSeven Legend (also referred to as SubSeven) is one of the most common Windows backdoor trojans. It is an older program and most virus software can detect it, but there are many variations of it floating around the Internet. SubSeven is smart enough to notify the intruder, via Internet Relay Chat (IRC), e-mail, or some other method, that the victim computer is online. It runs over a TCP connection with a default port of 27374, although this port is configurable. SubSeven has numerous features that allow the intruder to completely control the victim computer.

Figure 8.6 shows a packet capture of a SubSeven Legend client-server interaction. SubSeven Legend is the anniversary edition of SubSeven. The intruder is running the client on 192.168.1.1, which is connected to the server on the victim computer at 192.168.1.200. You will notice that the server is running on the default port 27374 and data is being pushed between the client and server.

Figure 8.6: SubSeven Legend Backdoor Trojan

Using the Follow TCP Stream feature of Ethereal will show what is going on between the SubSeven server and client. Figure 8.7 shows the connection day and time and the version of the SubSeven server. Next, it shows that the intruder performed a directory listing of C:\, and downloaded the file secret.txt. However, the data for this file is obscured.

Figure 8.7: SubSeven Client-Server Interaction

NetBus

The NetBus backdoor trojan is also one of the older and more common Windows backdoor trojans. It is easily detectable using antivirus software, but like SubSeven, many variations exist. It runs over a TCP connection with default ports of 12345 and 12346, but is configurable. Like SubSeven it has numerous features that allow the intruder to completely control the victim computer.

Figure 8.8 shows a packet capture of a NetBus client-server interaction. The intruder is running the client on 192.168.1.1, which is connected to the server on the victim computer at 192.168.1.200. You will notice that the server is running on the default ports 12345 and 12346 and data is being pushed between the client and server. The two separate source ports indicate two distinct TCP connections.

Figure 8.8: NetBus Backdoor Trojan

Using the Follow TCP Stream feature of Ethereal will show what is going on between the NetBus server with the port 12345 and the client. Figure 8.9 shows the version of the NetBus server and also shows that the intruder downloaded the file C:\temp\secret.txt. Figure 8.10 shows the client revealing the contents of the downloaded file! This means that not only the intruder, but anyone else on the line with a sniffer, can read the contents of the file as it is transmitted.

Figure 8.9: NetBus Client-Server Interaction

Figure 8.10: NetBus Client-Server Content

RST.b

RST.b is a newer, less widely used, backdoor access trojan that affects various Linux platforms. The backdoor listens in promiscuous mode for User Datagram Protocol (UDP) packets to any port. To access the backdoor, the intruder sends a UDP packet containing the payload “DOM”. There is more information on this backdoor at www.qualys.com/alert/remoteshellb.html.

Figure 8.11 shows a packet capture of an intruder scanning for systems infected with the RST.b trojan. We filtered on UDP to focus in on the last nine UDP packets. The intruder uses different source IP addresses and random destination ports to prevent IDSs from detecting the scan. Because the RST.b trojan listens in promiscuous mode, it will respond to UDP packets, containing the “DOM” payload, on any port.

Figure 8.11: RST.b Backdoor Scan

Many people get confused over the difference between a virus, a worm, and a trojan. The terms tend to be used interchangeably, but they are really three very distinct entities. They each use different ways to infect computers, and each has different motivations behind its use.

A virus is a program that can infect files by attaching to them, or replacing them, without the knowledge of the user. A virus can execute itself, and replicate itself to other files within the system. To do this, it often attaches to executable files, known as host files. Viruses travel from computer to computer when users transmit infected files or share storage media, such as a floppy disk. Viruses may be benign or malicious. A benign virus does not have any destructive behavior; it presents more of an annoying or inconvenient behavior, such as displaying messages on the computer at certain times. A benign virus still consumes valuable memory, CPU time, and disk space. Malignant viruses are the most dangerous because they can cause widespread damage, such as altering software and data, removing files or erasing the entire system. However, there are no viruses that can physically damage your computer hardware. There are several types of viruses, including the following:

File infector A virus that attaches to an executable file.
Boot sector A virus that places code in the boot sector of a computer so that it is executed every time the computer is booted.
Master boot record A virus that infects the first physical sector of all disks.
Multi-partite A virus that will use a number of infection methods.
Macro A virus that attaches itself to documents in the form of macros.

A trojan is a program that is covertly hiding another, potentially malicious, program. The trojan is often created to appear as something fun or beneficial, such as a game or helpful utility. However, when a user executes the program, the hidden malicious program is also executed without the user’s knowledge. The malicious program is then running in memory and could be controlling backdoor access for the intruder, or destroying system files or data. A trojan could also contain a virus or a worm. Trojans do not replicate or propagate themselves; they are often spread by unknowing users who open an e-mail attachment to execute a file downloaded from the Internet.

A worm is a program much like a virus that has the added functionality of being able to replicate itself without the use of a host file. With a worm, you don’t have to receive an infected file, or use an infected floppy to become infected; the worm does this all on its own. A worm actively replicates itself and propagates itself throughout computer networks. Not only will a worm consume valuable system resources, it can also consume network bandwidth while it is propagating or attempting to propagate.

Dissecting Worms

Throughout the past few years we have seen not only an increase in worm activity, but also an increase in the severity of worm attacks on systems and networks. Internet worms are becoming faster, smarter, and stealthier. Most worms attack vulnerabilities in software for which patches have been readily available for quite some time before the exploit appeared. Complex worms are beginning to emerge that have the ability to exploit several vulnerabilities and propagate in a number of different ways. This makes reverse engineering and defending against the worm more difficult. This section will explore three well-known worms: SQL Slammer, Code Red, and Ramen.

SQL Slammer Worm

The SQL Slammer worm began propagating on the Internet on January 25, 2003. It exploits a vulnerability in the Resolution Service of Microsoft SQL Server 2000 and Microsoft Desktop Engine (MSDE) 2000. It is also known as the W32.Slammer worm, Sapphire worm, and W32.SQLExp.Worm. It is known as the fastest spreading worm, and infected most vulnerable systems within 10 minutes. As the worm propagated and compromised more systems, the Internet showed significant signs of degradation.

The SQL Slammer worm exploits a stack buffer overflow vulnerability that allows for the execution of arbitrary code. Once a system is compromised, the worm will attempt to propagate itself by sending 376-byte packets to randomly chosen IP addresses on UDP port 1434. All vulnerable systems that are discovered will become infected and also begin to scan for more vulnerable systems. With this type of exponential growth, no wonder it spread so fast! This type of propagation leads to a lot of other problems including performance issues, crashed systems, and denial of service. Details on the SQL Slammer worm including the patch, instructions on applying ingress and egress filtering, and recovery from a compromised system can be found in the CERT Advisory at www.cert.org/advisories/CA-2003-04.html.

The Scan3.log file, provided by the Honeynet Research Alliance as part of the Honeynet Project Scan of the Month challenge, shows evidence of the SQL Slammer worm attempting propagation. Scan3.log is located on the accompanying CD-ROM in the /captures directory. After you open the packet capture in Ethereal, apply the UDP filter with destination port 1434, and you will see the Slammer scan traffic, as shown in Figure 8.12. You will notice that there are 55 packets from random source addresses that are sending a UDP packet to port 1434. The UDP packet also has a length of 384 bytes, which is the 376 bytes of data plus the 8-byte header. All of the packets are incoming to the target 172.16.134.191, and none are going out, which lets us know the system is not compromised; it is just the target of the randomly generated IP addresses on other compromised systems. You will also notice that each of the packets contains data, and although it is a bit scrambled you can make out the various parts of the exploit code such as: ws2_32.dll, kerne32.dll, GetTickCount, socket, and send to.

Figure 8.12: SQL Slammer Propagation Attempt

Code Red Worm

The Code Red worm was originally discovered on July 16, 2001, and since then there have been many variants including Code Red II and III. The worm infects Microsoft Windows NT, 2000, and beta versions of XP that are running IIS 4.0 and 5.0 Web servers. Code Red exploits a known buffer overflow vulnerability in the IIS Indexing services IDQ.DLL file. Details on the Code Red worm including the patches, workarounds, and recovery from a compromised system can be found in the CERT Advisory at www.cert.org/advisories/_CA-2001-19.html.

SQL Slammer has been the fastest spreading worm to date. A detailed analysis of the spread of the SQL Slammer worm can be found at www.caida.org/analysis/security/sapphire. There are several key attributes of the worm that allowed it to spread at such an alarming rate. These are outlined as follows:

Random scanning The random scanning of the worm allowed for initial exponential growth.
Simple and fast scanner The worm could scan as fast as the compromised computer could transmit packets or the network could deliver them.
Small size The SQL Slammer worm was only 376 bytes.
UDP The use of a single UDP packet allowed for efficient propagation because the connection does not have to wait for a response.

The propagation of the Slammer worm caused worldwide disruption in approximately 10 minutes. Fast-spreading Internet worms are a significant milestone in computer security, and a reality that should be met with all available countermeasures.

The Code Red worm operates in 3 stages, which are time sensitive: propagation, denial of service, and sleep. Although there are many variations, the general pattern of behavior is as follows:

Propagation mode This stage takes place from the 1st to the 19th of the month. An infected system will randomly generate IP addresses and attempt to connect to them on HyperText Transfer Protocol (HTTP) port 80. If a system is discovered and is vulnerable, the exploit code will be sent via an HTTP GET request and the web page of the server will be defaced. The original worm defaced web pages by displaying “Welcome to www.worm.com! Hacked By Chinese!” However, some new variations will not deface the web page. The worm places a file, C:\notworm, on the system to signal that it has been infected. This way, if the system gets infected again, the worm will go into an infinite sleep state. If the c:\notworm file does not exist, then this is the first time this system has been infected, and it will create new threads to continue the propagation scanning. This propagation activity will continue until the 20th of the month.
Denial of Service mode This stage begins on the 20th and lasts until the 27th. In this stage, the worm will attempt to packet-flood a specific IP address that is designated in the code by sending large amounts of data to HTTP port 80 of the target. The first target was originally the Whitehouse website at 198.137.240.91. By directing the flood to the IP address instead of the DNS host name, it was easy for Whitehouse.gov system administrators to change the IP, thus making the flood ineffective.
Sleep This stage causes the worm to enter a sleep state from the 28th until the end of the month. It will remain in memory, but will not be active, until the cycle repeats on the 1st

The CodeRed_Stage1 capture, Figure 8.13, shows the Code Red exploit and propagation in action. The CodeRed_Stage1 file is located on the accompanying CD-ROM in the /captures directory. The Code Red capture files were provided by L. Christopher Paul and can also be downloaded from www.bofh.sh/_CodeRed. This capture was lab-generated to show the various Code Red stages, so timestamps may not reflect the proper dates for the various stages. The worm spreads from the system 192.168.1.1 and infects the vulnerable target 192.168.1.105. The newly compromised system then begins scanning random IP addresses for open HTTP port 80. A definite giveaway in this capture is packet number 4, “GET /default.ida?NNNNNNNNN…”, which is the exploit for Code Red. The random HTTP port 80 scanning that begins at packet number 12 should also alert you to something strange. This isn’t typical web surfing because none of the targets are responding.

Figure 8.13: Code Red Stage 1 – Infection and Propagation

Figure 8.14 shows the “Follow TCP Stream” output of the initial exploit. Notice the exploit in the HTTP GET request at the beginning, and the checking of the of C:\notworm file, and web page defacement at the end.

Figure 8.14: Code Red Exploit Output

The CodeRed_Stage2 capture, Figure 8.15, shows the denial of service mode of the worm. The CodeRed_Stage2 capture file is located on the accompanying CD-ROM in the /captures directory. The infected server, 192.168.1.105 is attempting to flood the Whitehouse web server at 198.137.240.91. Since this was performed in a lab environment, the actual denial of service was not accomplished.

Figure 8.15: Code Red Stage 2 – Denial of Service

Ramen Worm

The Ramen worm is a collection of tools that can exploit several known vulnerabilities and can self-propagate. The original CERT Incident Note, posted on January 18, 2001, can be found at www.cert.org/incident_notes/IN-2001-01.html. Ramen targets Red Hat Linux 6.2 and Red Hat Linux 7.0 servers with vulnerable versions of the following:

wu-ftpd This program runs on TCP port 21 and vulnerable versions contain a format string input validation error in the site_exec() function.
rpc.statd This program runs on UDP port 111 and vulnerable versions contain format string input validation errors in the syslog() function.
Lprng This program runs on TCP port 515 and vulnerable versions contain format string input validation errors in the syslog() function.

Once a host is compromised, the Ramen tools are copied into a directory called /usr/src/.poop. They are started and controlled by a series of shell scripts. Some of the important characteristics of the Ramen worm include the following:

The webpage is defaced by replacing the index.html file. The new web page consists of the phrase “Hackers looooooooooooooooove noodles” and a picture of a package of Ramen noodles.
E-mail is sent to gb31337@yahoo.com and gb31337@hotmail.com with the text “Eat Your Ramen!”.
The tcpwrappers access control list (ACL) is disabled by removing the /etc/hosts.deny file.
The file /usr/src/.poop/myip contains the IP address of the local system.
The file /etc/rc.d/rc.sysinit is modified to include a startup script that initiates scanning and exploitation.
A new program called asp is added, which creates a listener on TCP port 27374. This port is used to send the ramen.tgz toolkit file to other compromised systems. That is also the port that SubSeven uses. Coincidence? It is unclear why the author would want to use an already well-known port, since most IDSs should have been configured to alert activity on that port.
The user names ftp and anonymous are added to /etc/ftpusers to disable anonymous FTP (File Transfer Protocol). By disabling anonymous FTP, this part of the worm code is actually fixing the vulnerability that it used to exploit the system!
The rpd.statd and rpc.rstatd services are terminated and the /sbin/rpc.statd and /usr/sbin/rpc.statd files are deleted. However, there is no service called rpc.rstatd.
The lpd service is terminated and the /usr/sbin/lpd system file is deleted.

Once the system has been modified, the Ramen worm begins scanning and exploiting the vulnerable systems that it finds. The worm generates random class B IP addresses to scan. It will then send packets with the SYN and FIN flags set and with a source and destination port of 21. Once a vulnerable system is compromised the following actions occur:

The /usr/src/.poop directory is created on the victim.
The ramen.tgz toolkit is copied to the new directory and to the /tmp directory. The /tmp directory is where the toolkit is stored so that it can be copied out to new vulnerable systems.
The ramen.tgz toolkit is unarchived in the /usr/src/.poop directory and the initial shell script is started. The system is now fully compromised and will begin scanning for new vulnerable systems.

The ramenattack.gz packet capture was downloaded from www.whitehats.com/library/worms/ramen. Here you will find a very detailed analysis of the Ramen worm by Max Vision, called “Ramen Internet Worm Analysis” as well as the ramen.tgz source code. The ramen attack.gz capture file is also located on the accompanying CD-ROM in the /captures directory. Ethereal will automatically uncompress the file when you open it.

We will step through the various parts of the packet capture to show how the Ramen worm works.

In Figure 8.16, the infected system 192.168.0.23 is performing a SYN/FIN scan on the 10.0.0.0/24 Class B network. It receives a SYN/ACK from the target system at 10.0.0.23.

Figure 8.16: Ramen Work Propagation Scanning
Next, in packet 26, the worm connects to the system to grab the FTP banner and determine if the system is a Red Hat 6.2 or 7.0 server. The banner that the Red Hat 6.2 server returns is as follows:
```
220 test2.whitehats.com FTP server (Version wu-2.6.0(1) Mon Feb 28 10:30:36 EST 2000) ready.
 221 You could at least say goodbye.
```
Next, the wu-ftp and rpc.statd exploits are launched against the potential target. The wu-ftp attempt begins at packet 137 and is unsuccessful, but the rpc.statd exploit succeeds. Figure 8.17 shows the payload of the rpc.statd exploit. Notice the padding of “90 90 90 90…” and the trailing “/bin/sh” that will execute a command shell. You will also notice in packet 289 that once the SYN/FIN scan is finished scanning the target 10.0.0.0/24 range it sends a SYN/FIN packet to 10.9.9.9 from port 31337. This represents the packet that is sent to www.microsoft.de when the scan is complete. Since the worm was activated and analyzed in a lab environment 10.9.9.9 was chosen to represent www.microsoft.de.

Figure 8.17: Ramen Worm rpc.statd Exploit
You will also notice in packet 290 that a connection is made with the port 39168 on the target system. The rpc.statd exploit created a backdoor on the victim on this port and it is now used to initiate the transfer of the worm and execute it. It also sends an e-mail to accounts at Hotmail and Yahoo. The output from this transfer is shown in Figure 8.18.

Figure 8.18: Ramen Worm Execution
The last connection you will see, beginning in packet 297 in Figure 8.17, is the actual transfer of the Ramen toolkit that was initiated in previous script. The new compromised system connects back to the attacker at port 27374 to download a copy of the worm.
The worm is now executing on the victim and will begin scanning for new vulnerable hosts.

Overall, the Ramen worm is easy to detect, especially since it uses a well-known Trojan port for the worm transfer. It contains unexplained and inefficient code and makes no attempt to be stealthy. There are also several places where its functionality could be optimized. However, this is a worm that exploits several different vulnerabilities and self-propagates. The security community should definitely watch out for more worms with these capabilities.

Note

A day-zero, or alternately a zero-day attack, is an exploit on a vulnerability that is not yet known about and for which there is no patch.

Summary

Analyzing real-world packet captures is both a science and an art. A high traffic network segment can present the analyzer with thousands of packets containing hundreds of connections, sessions, and protocols. Ethereal’s built-in features such as TCP session reconstruction, display filters, and packet colorization help simplify the process of analyzing data. However, as with any skill, you must practice, practice, practice. Constantly analyzing network data will help you quickly assess what is normal and what is unusual behavior. If you don’t have the ability to analyze your own network traffic data, participate in the Honeynet Project Scan of the Month challenges. These challenges cover network traffic analysis, as well as malicious code, exploits, and methodology.

You should also become familiar with reading and interpreting hexadecimal output. This will come in handy when you are analyzing day-zero attacks and you may have to implement your own custom signature. Intrusion detection systems often match a signature on the content of a packet in hexadecimal format.

In this chapter we presented several different types of packet captures and the processes used to analyze the data. You should have an understanding of the types of activity to look for in a packet capture and how to identify various types of network traffic. Combining this skill with the network troubleshooting methodology presented in Chapter 2 will help you to detect, analyze, and respond quickly to the next major worm outbreak.

Solutions Fast Track

Scanning

Network scanning is used to detect open ports and services on systems.
A TCP Connect scan completes the TCP 3-way handshake and is easily logged and detected.
SYN scans were once used as stealthy scanning techniques; however most firewalls and IDSs can now detect these types of scans.
Xmas scans are ineffective against Microsoft operating systems because they will respond with an RST from all ports, even if they are open.
A Null scan sends packets with all flags turned off. Closed ports will respond with an RST/ACK and open ports will just drop the packet.

Remote Access Trojans

Remote access backdoor programs are often delivered to unsuspecting users within a trojan program.
Remote access backdoors operate in a client-server architecture, allowing the intruder complete control over the compromised system.
SubSeven can notify the intruder, via IRC, e-mail, or some other method, that the victim computer is online.
NetBus is an older Windows backdoor trojan that is easily detected by antivirus software, but like SubSeven, many variations exist.
The RST.b trojan listens in promiscuous mode and will respond to UDP packets, containing the “DOM” payload, on any port.

Dissecting Worms

Internet worms are becoming increasingly fast and complex.
The SQL Slammer worm uses UDP to accomplish its fast propagation.
The original Code Red worm operated in 3 stages: propagation, denial of service, and sleep.
The Ramen worm is a collection of tools that can exploit several known vulnerabilities in the wu-ftpd, rpc.statd, and lprng utilities.

Frequently Asked Questions

The following Frequently Asked Questions, answered by the authors of this book, are designed to both measure your understanding of the concepts presented in this chapter and to assist you with real-life implementation of these concepts. To have your questions about this chapter answered by the author, browse to www.syngress.com/solutions and click on the “Ask the Author” form. You will also gain access to thousands of other FAQs at ITFAQnet.com.

1.	Why is it that when I right-click on some of my packets the “Follow TCP Stream” options is grayed out?
2.	Can I use Ethereal to discover a trojan that is being sent to someone on my network?
3.	Can I use Ethereal to discover a virus that is being sent to someone on my network?
4.	Are there network activities that will falsely resemble network scanning attacks?

Answers

1.	The underlying protocol that you are trying to reconstruct does not use TCP for its connection method. It may use the connectionless UDP method for its transmission.
2.	No, Ethereal can only be used to discover the active use of the backdoor access program that the trojan installs. To Ethereal, or any network analyzer, the transmission of the trojan will appear to be a regular executable file.
3.	No, like a trojan, the transmission of a virus will look like a regular executable or some other type of file. Ethereal will not be able to tell that the file is infected.
4.	Yes, there are lots of activities that will resemble network scans. A client program that is automatically searching for a server at startup may continue to send TCP SYN packets to the target address. Often multiple and rapid TCP connection that are associated with FTP and HTTP downloads also resemble network scan attacks and trigger alarms.

Часть 9: Разработка Ethereal

The fact that Ethereal is open source and distributed under the General Public License (GPL) allows many individuals to contribute to the overall success of the project. With developers throughout the world contributing for several years, Ethereal has become a viable tool for many organizations.

Ethereal developers have contributed new functionalities as well as features to the growing number of tools included in the Ethereal distribution. This includes the console-based version of Ethereal named Tethereal, as well as a number of other tools that are part of the Ethereal distribution.

The main Ethereal application is a Graphical User Interface (GUI) application utilizing components of GNU’s Not UNIX (GNU) Image Manipulation Program called GIMP. The latest version of the GIMP Toolkit is now called GTK+. GTK+ is the official name of the toolkit but most developers refer to it as GTK. Although the name implies that GNU owns GTK, this is not the case. GTK is maintained as a separate entity at www.gtk.org. Ethereal uses the GTK library and functions for its GUI implementation. New features often require modifications to the GUI. This might include new menu items or modifications to existing menu selections. The core of the application includes the main window, menus, utility functions, etc.

The components of Ethereal that dissect packet structures are called protocol dissectors. These components are individual source code modules that instruct the main Ethereal application on how to dissect a specific type of protocol. The dissector can be complex or simple based on the protocol that is being dissected. Most of the contributions to the Ethereal project are either new dissectors or enhancements to existing ones.

By utilizing the concepts within this chapter, you should be able to grasp the basic steps to become a contributor to the Ethereal project. Many users and developers worldwide would benefit from your efforts and welcome anything you might want contribute.

Prerequisites for Developing Ethereal

The first step in the development process is to acquire the Ethereal source. You can download many different distributions from the Ethereal website, such as the currently released source code or the last nightly backup of the source code. You can also utilize the Concurrent Versions System (CVS) to keep up to date throughout your development process. CVS is the most risky, compared to released versions of Ethereal, because you are compiling code that hasn’t been fully tested. Generally, however, the CVS code is of very high quality.

Even if you have an issue with the current CVS code, you can generally get one of the members of the Ethereal mailing list (ethereal-dev@ethereal.com) to make a quick change to resolve the issue. CVS gives you access to code changes as they are checked into the master build. It is the most up–to-date, but can contain unidentified bugs. Please keep in mind that the CVS distribution can be and is routinely updated as well. You might develop with the current released code and then find out that a specific function you are working with has changed. Instructions for utilizing the latest builds and CVS can also be found at the www.ethereal.com website.

Before you can add to or modify Ethereal, you must be able to build the application from source. To build from source you will need to acquire additional libraries and tools. Ethereal is a multiplatform application, meaning that it can run on many different operating systems. You will need to be able to build on the particular operating system that you will be developing on.

Because of the wide range of development on the Ethereal project, there may already be work in progress on a specific feature or protocol dissector. The Ethereal developer mailing list (ethereal-dev@ethereal.com.) is a good way to determine if work is already being done in a specific area. Questions can be posted to the ethereal-dev mailing list before you start work on a specific protocol dissector or feature. You can consult the Ethereal website for more information on the available mailing lists at www.ethereal.com.

It is also important to understand that Ethereal is developed and built using a number of different programming languages. This includes many UNIX-based programs and shell scripts. For example, several modules within Ethereal are written in python and Perl. Although it may not be necessary for you to be proficient in each programming language, you might find times where you need to understand enough about the language to make a simple change. A majority of the code base for Ethereal is ANSI-C. The requirement for ANSI-C is due to the portability of the code to multiple operating system platforms. Special care should be taken when writing in C to use only those functions that are defined as ANSI-C and are portable. You should be able to use just about any C compiler with the Ethereal source. This would include GNU C Compiler (gcc) on Linux, as well as Microsoft Visual C++ on Windows.

Skills

To build a new dissector or modify the main application, you will need to be able to program in C. However, please keep in mind that modifications to existing dissectors may require you to be knowledgeable in another language.

Before starting any work you need to read the portability section 1.1.1 of the README.developer document contained in the doc directory of the source distribution. The word portability is used in reference to the steps a developer should take to ensure that Ethereal source can be compiled on all of the supported operating systems. For example, you wouldn’t want to use a function that only exists on a win32 platform. This would cause Ethereal source to not compile or build correctly on the other supported operating systems. Typically, when a program is written to one operating system platform and then made to run on a different platform, the process is called porting. This is where the name portability is derived from.

Modifications to the Ethereal GUI will require some knowledge of GTK. The GTK website at www.gtk.org, contains online and downloadable tutorials for programming in GTK.

Contributions to the Ethereal project come from many different levels of developers. Some are novices while others might be considered to be experts. However, the overall Ethereal project is maintained by a group of highly experienced developers. New additions and or contributions are first reviewed by this group and then incorporated into the source distribution following any necessary changes. In some cases, the individual who reviews the changes might make a recommendation to the original developer for a specific change, or in other cases they may make the changes themselves.

Tools/Libraries

In most cases, you will need the developer kit for access to necessary libraries. A developer kit is different from the normal binary distribution. Generally, the developer package includes the compiled binaries for the operating system it was built for. For example, since Ethereal utilizes the GTK libraries for its GUI implementation, you will need to ensure that you have the developer kit for GTK. You will also need to make sure that you download the correct developer kit for the operating system that you are going to develop on. It is important to try to use the latest released version of the developer kit if possible. Although you might be able to build Ethereal with an older set of libraries, the results of the application running might not be as expected. However, in some cases this might not be an option. Some operating systems only support certain versions of support libraries. In general, you can consult the Ethereal developer mailing list or the developer section of the www.ethereal.com website.

Win32 ports of the required libraries are not necessarily located at their respective project site. For example, the win32 port for the libpcap library is called WinPcap. The following web pages list places where you can look for Win32 library ports. The www.ethereal.com/distribution/win32/development web page contains most of what you will need, but if you want to build with GTK 2.x you will need additional library packages not listed on the Ethereal website. Refer to the web pages located at www.gimp.org/~tml/gimp/win32.for GTK 2.x information and access to the Win32 ports.

When building Ethereal, you will need the GTK and GLIB libraries. Ethereal can be built using the older GTK 1.2, 1.3, or the newer GTK 2.x versions. The newer 2.x versions of GTK add more font control and have a better look and feel. These libraries can be downloaded from www.gtk.org. The installation chapter in this book identifies some of these issues when installing on Solaris and Red Hat distributions.

The console version of Ethereal, called Tethereal, only requires the GLIB libraries. If you will only be building the Tethereal application, you will not need GTK.

If you will be building with packet capture support in Ethereal or Tethereal, you will need to make sure that you have the libpcap libraries from: www.tcpdump.org. Without packet capture support, users of the compiled program will only be able to view packet trace files. They will not be able to perform new packet captures. Win32 developers will need the WinPcap libraries instead of libpcap. These can be downloaded from http://winpcap.polito.it/.

The following is a list of libraries needed to build Ethereal. Remember that you will need to download the developer kit to acquire the necessary libraries for your operating system. Some packages are optional and can be linked to add additional features. UNIX/Linux operating systems will detect the installed libraries by the automake process. Automake will identify the library packages that can be included when you build Ethereal. On Win32 based computers the config.nmake file should be modified to define what libraries that you wish to include in the build process. These libraries will then be added to the final binary during the linker process of the build.

glib Low-level core library for GTK (required).
gettext GNU language conversion (required by glib).
libiconv Character set conversion library (required by glib).
GTK GIMP toolkit for creating graphical user interfaces (required for Ethereal build).
libpcap Packet capture library for UNIX/Linux-based operating systems.
WinPcap Packet capture library for Win32 based operating systems (optional).
ADNS GNU Advanced DNS client library (optional) adds DNS lookup support.
net-snmp Simple Network Management Protocol (SNMP) library (optional) adds SNMP support.
pcre Perl Compatible Regular Expressions library (optional) adds Perl expression filters.
zlib File compression library (optional) adds compressed file support.

If you will be building with GTK version 1.2 or 1.3, no additional libraries are needed for GTK. Otherwise, when building with GTK 2.x you will need the following additional libraries:

atk Accessibility toolkit (required).
pango Internalization of text (required).

Windows users must choose to either attempt to build from within cygwin using gcc or with a Win32-based compiler such as Microsoft’s Visual C++ (MSVC++). They will also need to download a number of additional libraries. The default location specified in the Ethereal distribution for the libraries on Win32 is C:\ethereal-win32-libs. You should download and extract each required library to this location. Ethereal’s scripts will then locate the libraries at build time. Otherwise, you will need to modify the config.nmake file located in the main distribution directory to point to the correct location for each library.

Tools that you might need are specific to the operating system in which you need them to run. The Ethereal compile and build process utilizes a number of script files. These scripts will require a number of tools to run successfully. Most of the tools have their roots in the UNIX/Linux operating systems. To compile and build Ethereal on non-UNIX-based operating systems you will need to have access to similar tools.

Windows users will also need to install cygwin. Cygwin is a Linux-like environment for Windows-based computers. It gives both a Linux Application Program Interface (API) emulator as well as a set of Linux-based tools. These tools are what allow the scripts utilized by Ethereal during the build process to work on Windows-based computers. Cygwin can be downloaded and installed from www.cygwin.com.

Windows users will also need to download Python. Python can be downloaded and installed from www.python.org/.

Most UNIX and Linux-based operating systems will include a C compiler and many of the required tools needed to build Ethereal.

The following is a list of tools needed to compile and build Ethereal:

Cygwin Provides UNIX/Linux tools for Win32 developers. This is not needed for UNIX/Linux.
Perl Needed for all operating systems.
pod2man Part of Perl.
pod2html Part of Perl.
Python Needed for all operating systems.
Flex Needed for all operating systems.
Bison Needed for all operating systems.

Detailed instructions for building the Ethereal binaries from source are included in the INSTALL file, located in the main source directory. Chapter 3 of this book also outlines the build process on RedHat Linux.

Building on Windows-Based Operating Systems

Detailed instructions for building the Ethereal binaries from source are included in the file README.win32, located in the main source directory. This file includes instructions on building on both MSVC++ and Cygwin.It is also important to use CMD.EXE and not COMMAND.COM when attempting to build Ethereal. The program CMD.EXE provides long name support whereas the older COMMAND.COM is limited to 8.3 file naming conventions. Ethereal’s source contains long named files and is not supported with command.com.

Windows users may need to update or change the default environment variables for their compiler to locate additional support libraries. For example, when building Ethereal, the wiretap source must include header files for winsock support. It is important that the build process can locate the correct include files. Validate that the following user environment variables are defined correctly:

Include
Lib

It’s important to also make sure that cygwin is located in the user path environment variable to locate the necessary cygwin executables during the build process. These executables are the Windows equivalent of necessary UNIX/Linux binaries. For example bison.exe is the equivalent of its UNIX/Linux counterpart bison.

Ethereal Design

The Ethereal source distribution envelopes a main source directory and several subdirectories. The main source directory contains the following important source files:

config.nmake This file instructs Ethereal where to locate libraries during the build.
Makefile.nmake This is the script for making the Ethereal binaries on Win32.
Makefile.am Automake configuration file for UNIX/Linux.
cleanbld.bat File for switching between platforms.
configure File for UNIX/Linux build and install.
idl2eth.sh Shell script for creating Ethereal dissector for Interface Definition Language (IDL) files.
INSTALL UNIX/Linux installation instructions.
make-xxx Script files to build support modules.
packet-xxx Protocol dissectors.
README Associated readme files for multiple platforms.
tap-xxx Protocol taps.
xxxx Remaining files contain utility functions for Ethereal/Tethereal.

In Figure 9.1, you can see a breakdown of the directories contained in the Ethereal distribution.

Figure 9.1: Main Directory

aclocal-fallback and aclocal-missing

The aclocal-fallback and aclocal-missing directories are used to store information used by automake on UNIX/Linux-based systems.

debian

The debian directory is used for compatibility with debian Linux-based operating systems. These files are not under packaging because the debian tools require that the debian directory to be at the top-level directory of a source package.

doc

Contained within the doc directory are many text documents to assist you in the development process. They are provided in the following list:

README.design This document provides some useful information on the core structure of Ethereal.
README.developer This is the main document to assist in the development of new protocol dissectors. Also included are helpful design pointers, a sample template and potential problems.
README.idl2eth Refer to this document when you desire to build a dissector from an IDL file.
README.plug-ins Documentation for utilizing the plug-in interface of Ethereal.
README.regression Steps for testing and regressing new dissectors. This file provides a template with which you can test for regressions in packet decodes. The file is structured as a makefile that can be utilized after modifying the core Ethereal code or a dissector to ensure that Ethereal operates correctly.
README.tapping Detailed information on the tapping system built into Ethereal.
README.tvbuff Tvbuff is the main structure for dissectors to access and display data. It also performs checks on the data to trap for errors in the data stream to prevent stack and buffer overflows. This document describes the proper use of the tvbuff functions and data structure.
README.xml-output Tethereal provides a mechanism to output data in XML/PDML (Product Data Markup Language) format. This document outlines what this capability provides.

epan

The epan directory contains most of the utility and global functions used within dissectors. The subdirectory dfilter contains source for display filter functionality. The ftypes subdirectory contains source that define the different data types that are utilized in the data type logic (see Figure 9.2).

Figure 9.2: epan Directory

gtk

Contained within the gtk directory are the source files for the main Ethereal application. This includes the main GUI as well as the menu and toolbar. Basically, any of the Ethereal source that needs to access the GUI will reside within this directory.

help

The help directory will hold the source files that are used to build the content for the help menu dialogs. These are built during compile time and linked into the Ethereal binary file.

image

The icons and bitmaps linked into the Ethereal binary are stored in the image directory, as shown in Figure 9.3. The custom icons are stored in the toolbar subdirectory and are in X PixMap (XPM) format. The XPM file format is used to create icons and bitmaps for X-Windows-based operating systems.

Figure 9.3: Image Directory

packaging

The packaging directory contains the necessary scripts and files to generate a binary distribution, as shown in Figure 9.4. Currently supported distributions include the Nullsoft Scriptable Installation System (NSIS) to generate a Windows installation package or the RedHat Package Manager (rpm) and System V Release 4 (svr4) to generate Linux and UNIX installation packages.

Figure 9.4: Packaging Directory

plugins

A number of dissectors have been written to interface with Ethereal through the plugin interface, as shown in Figure 9.5. For detailed information on how to create a plug-in, refer to the README.plugins document in the doc directory.

Figure 9.5: Plugins Interface

tools

Ethereal’s source distribution contains several tools in this directory. In the tools directory the EtherealXML.py file is a python script to read Tethereal-generated PDML files. The lemon directory contains the Lemon tool, which will generate C source files based on a supplied template, as shown in Figure 9.6. Lemon is a parser generator for C or C++ that does the same job as bison and yacc, but Lemon provides more flexibility and does a better job of eliminating common errors. It also runs much faster then the other tools, is reentrant, and is thread-safe.

Figure 9.6: Lemon Directory

wiretap

The wiretap directory is the core capture file support library, which provides the support to read and write different capture file formats. For information on how to add or modify the capture file types supported by Ethereal, refer to the README.developer document located in the wiretap directory.

Developing a Dissector

A protocol dissector is most commonly written in C, although there are components of Ethereal that build C source from Python scripts, IDL files, and even Perl scripts. These files are named after the protocol they are meant to dissect. For example, a protocol dissector for a protocol called myprot would be named packet-myprot.c. These files are located in the main source directory. Some dissectors have been implemented as plug-ins. The advantage of a plug-in is that it does not require a complete recompile of the whole Ethereal source during development. However, even plug-ins start out as a packet-xxx.c source file. This section discusses the necessary steps for creating a standard packet-xxx.c dissector.

Step 1 – Copy the Template

There are several steps that must be completed to integrate a new dissector into Ethereal. The first step is the comments, as seen in the following code. Remember that Ethereal is open source, so the main comment identifies not only that you did the work to create the dissector, but also includes information on the original contributor of Ethereal and the GPL.

/* packet-PROTOABBREV.c
  * Routines for PROTONAME dissection
  * Copyright 2000, YOUR_NAME <YOUR_EMAIL_ADDRESS>
  *
  * $Id: README.developer,v 1.86 2003/11/14 19:20:24 guy Exp $

It is important that your editor saves files in the proper format. Ethereal source is composed of UNIX-style files. The source file should not contain lines that end in carriage return, line feeds (CR/LF). Lines of text should be terminated only by the line feed character. If you are programming on non-UNIX-based computers you will need to make sure that your editor supplies the correct end of line formatting. Otherwise, you will need to reformat the source files prior to submitting them back to the ethereal-dev mailing list.

*
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
  * Copyright 1998 Gerald Combs
  *
  * Copied from WHATEVER_FILE_YOU_USED (where "WHATEVER_FILE_YOU_USED"
  * is a dissector file; if you just copied this from README.developer,
  * don't bother with the "Copied from" - you don't even need to put
  * in a "Copied from" if you copied an existing dissector, especially
  * if the bulk of the code in the new dissector is your code)
  * 
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
  * as published by the Free Software Foundation; either version 2
  * of the License, or (at your option) any later version.
  * 
  * This program is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  * GNU General Public License for more details.
  * 
  * You should have received a copy of the GNU General Public License
  * along with this program; if not, write to the Free Software
  *  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  */

When working with the template, you need to replace certain text with your information. For example, for line 1, you would replace packet-PROTOABBREV.c to packet-myprot.c. Change line 2 (PROTONAME) to indicate the protocol your dissector is meant to decode. Line 3 should be modified with the copyright date, your name, and your e-mail address. Note that since Ethereal is open source, this is your claim to ownership of the submitted code. This doesn’t keep other developers from modifying your code, but it does limit other people from taking ownership of your work. Once you contribute your code to the Ethereal project it becomes part of the GPL-licensed codebase and you will be added to the growing list of Ethereal contributors. Line 5 of the comment is important to the CVS system, as it identifies the current file ID and revision. This line is modified when source code is checked in and out of the CVS system. Make sure you do not remove this line. Finally, line 11 should be modified to document the source of your information used to build the dissector. If this information is not available or cannot be disclosed, then this section can be omitted. The rest of the comments should remain intact to reflect the original author, Gerald Combs, and the GPL information.

Step 2 Define the Includes

The next portion of the template, as seen in the following code, defines the includes for this source program. Includes are needed for global functions that this dissector calls. Ethereal defines a number of global functions that can be used within your protocol dissector. You might also need to include standard header files from your compiler or standard library. For example, string.h is a standard header file for string functions.

#ifdef HAVE_CONFIG_H
 # include "config.h"
 #endif
 
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 
 #include <glib.h>
 
 #ifdef NEED_SNPRINTF_H
 # include "snprintf.h"
 #endif
 
 #include <epan/packet.h>
 #include "packet-PROTOABBREV.h"

Output variables are set or passed to the C pre-processor to determine specific includes that might be needed to perform the build under specific conditions. For example, the HAVE_CONFIG_H include is only processed by make if this value is true. On Linux-based operating systems, autoconf generates output variables that may define even more output variables based on the build environment. Please refer to www.gnu.org/software/autoconf for more information.

Ethereal includes a large number of functions that can be used within your protocol dissector. To use these functions you must include the header file for the source that contains the defined function. One of the hard parts in utilizing the global functions provided by Ethereal is identifying the ones available for use. Let’s say that you have an Internet Protocol (IP) address that you would like to display. You could manually format a display string or you could use the built-in global function. But where is the global function? The following list displays some of the most common includes that define the global functions that might be needed by your dissector:

prefs.h Structure and functions for manipulating system preferences.
reassemble.h Structure and functions for reassembly of packet fragments.
tap.h Functions for utilizing the built-in tap interface.
epan/column-utils Functions for manipulating the summary window column data.
epan/conversation.h Functions for tracking conversations (Request to Reply).
epan/int-64bit.h Functions for manipulating 64-bit integers.
epan/plugins.h Functions for plug-in support.
epan/resolve.h Functions for resolving addresses to names.
epan/strutil.h Common string functions.
epan/to_str.h Functions for string conversion.
epan/tvbuff.h Testy Virtual Buffer (TVBUFF). A method used by dissectors to access packet data.
epan/value_string.h Functions to locate strings based on numeric values.

The following structures may contain information important for your dissector.
epan/column-info.h Structure of summary window column data.
epan/framedata.h Structure of frame data.
epan/packet-info Structure of packet information.

There are many more functions and structures defined in the Ethereal source. In some cases you will need to research available functions by analyzing other packet-xxx.c dissectors. Most of the utility functions you will need will be located in the epan directory.

static void dissect_my_protocol();

Step 3 Create the Function to Register

The next step in the development of a protocol dissector is to create the function to register your dissector with Ethereal.

/* Register the protocol with Ethereal
 
 /* this format is required because a script is used to build the C function
    that calls all the protocol registration.
 */
 
 void
 proto_register_PROTOABBREV(void)
 {
 
 /* Setup list of header fields  See Section 1.6.1 for details */
       static hf_register_info hf[] = {
             { &hf_PROTOABBREV_FIELDABBREV,
                   { "FIELDNAME",               "PROTOABBREV.FIELDABBREV",
                   FIELDTYPE, FIELDBASE, FIELDCONVERT, BITMASK,
                   "FIELDDESCR" }
             },
       };
 
 /* Setup protocol subtree array */
       static gint *ett[] = {
               &ett_PROTOABBREV,
        };
 
 /* Register the protocol name and description */
        proto_PROTOABBREV = proto_register_protocol("PROTONAME",
             "PROTOSHORTNAME", "PROTOABBREV");
 
 /* Required function calls to register the header fields and subtree used */
        proto_register_field_array(proto_PROTOABBREV, hf, array_length(hf));
        proto_register_subtree_array(ett, array_length(ett));

It is important that the proto_register_xxx function is left justified as shown in the template. The scripts used to register protocol dissectors are make-reg-dotc and make-reg-dotc.py. These scripts parse all of the packet-xxx files to build a list of all dissectors to be registered with the Ethereal engine. If this function does not meet the proper syntax requirements, the scripts will fail to register your new dissector. The file that is generated by the scripts is called register.c and is located in the main Ethereal source directory. This file should not be edited manually since it is recreated each time you compile and build Ethereal.

The first part of the proto_register_myprot function sets up the hf array fields of the dissection. Although these are not required for packet dissection, they are recommended to take advantage of the full-featured display filter capabilities of Ethereal. Each item that is defined within the hf array will be an individual item that can be filtered upon within Ethereal. For example, ip.src is an element within the packet-ip dissector. A user can enter a display filter of ip.src==10.10.0.1. If the ip.src element was not defined, then this would be an invalid filter.

{ &hf_ip_src,
 { "Source", "ip.src", FT_IPv4, BASE_NONE, NULL, 0x0,
       "", HFILL }},

The next part of the registration process will be to define the array for the sub-tree called ett. The ett variables keep track of the state of the tree branch in the GUI protocol tree, for example, whether the tree branch is open (expanded) or closed. We register the protocols short and long names with Ethereal by calling the proto_register_protocol function (this causes the protocol to be displayed in the Enabled Protocols window). The final step is to register the hf and ett arrays with the proto_register_field_arry and proto_register_subtree_array

That’s all it takes to register an available dissector with Ethereal. But, how would Ethereal know when to pass the data stream from a specific type of packet to this new dissector? Ethereal now needs to have the dissector instruct Ethereal when it should be called. For example, suppose we are writing a dissector to decode packets that are being transported on top of Transmission Control Protocol (TCP) with a port of 250. We need to instruct Ethereal to pass all packets that meet the criteria to our dissector.

Step 4 Instruct Ethereal

void
 proto_reg_handoff_PROTOABBREV(void)
 {
       dissector_handle_t PROTOABBREV_handle;
 
       PROTOABBREV_handle = create_dissector_handle(dissect_PROTOABBREV,
           proto_PROTOABBREV);
       dissector_add("PARENT_SUBFIELD", ID_VALUE, PROTOABBREV_handle);

The proto_reg_handoff_xxx function is used to instruct Ethereal when to call our dissector. The function create_dissector_handle passes the function that Ethereal will call to dissect the packets and the proto_xxx value that we registered as our protocol in the proto_register_protocol function. The dissector_add function allows us to specify the criteria that will trigger Ethereal to pass the packet to our dissector. PARENT_SUBFIELD allows us to specify the element within the parent dissector that we will trigger off of. For our example of TCP port 250, we would just set this value to tcp.port. We would then set the ID_VALUE to 250. Ethereal will then automatically pass data to our dissector by calling the function defined in create_dissector_handle if the value of tcp.port equals 250.

void
 proto_reg_handoff_myprot(void)
 {
       dissector_handle_t myprot_handle;
 
       myprot_handle = create_dissector_handle(dissect_myprot,
           proto_myprot);
       dissector_add("tcp.port", 250, myprot_handle);
 }

Step 5 Create the Dissector

Now we must create our dissector. We will need to create the function that we registered with Ethereal for our packet dissection. In our example we called this function dissect_myprot. Ethereal will pass our function three data structures—tvb, pinfo, and tree. The tvb structure will be used to extract and decode the data contained in each element of the packet. The pinfo structure gives us specific information about the packet based on information that has previously been dissected by other processes. For example, the pinfo structure tells us which packet number this packet relates to. It also contains flags for processing fragmented packets or multiple dissections. Finally, the tree structure gives us a pointer to the memory location of the GUI displayed data in the decode window. For our example this would be a pointer to a memory location in the GUI display to the location of the data just below the TCP protocol section. This is the starting point where our dissected data will be displayed in the decode pane. See Figure 9.7

Figure 9.7: Dissector Data Displayed in the Decode Window

Our decode data will start immediately after the TCP section. We now can start decoding the packet. In some cases we want to grab information from the data stream into a local variable so that we can make logical decisions based upon its value. To acquire data from the packet we use tvb_get_xxx functions. For example, let’s assume that the first byte in the packet is an unsigned integer that will contain the value of 0 for a request packet or a value of 1 for a reply packet. We can first define our variable and then use a tvb_get_guint8 function to get the data from the packet.

guint request_reply;
 request_reply = tvb_get_guint8(tvb, 0);

The variable request_reply now contains the value of the first byte in the data stream. The parameters passed to the tvb_get_xxx functions vary but all will take the pointer to your local tvb and an offset. In many cases it makes sense to create a variable for the offset value and then increment that variable after making each tvb call.

guint request_reply, offset = 0;
 request_reply = tvb_get_guint8(tvb, offset);

Ethereal utilizes a lower-case format for all syntax. The C language is case-sensitive and the variable RequestReply is a different variable than one named requestreply. The preferred syntax when writing source for Ethereal is to use all lower-case characters and separate words with the underscore character. For our example, it was request_reply. It is strongly recommended that you follow this requirement. It allows all of the Ethereal code to have the same look and feel.

tvb_get Functions

There are a number of tvb_get_xxx functions. These allow you retrieve data from the packet data stream based on the type of data you need to acquire. For example, you may need x number of bytes or you may need a 4-byte value. You may also find that the data in the data stream is in the wrong order. For example, you are expecting the value for a “long” to be returned as 0001 but instead it is returned as 1000. There are two types of each tvb_get_xxx function to allow you to get the data from the datastream in the endianess you need. Endianess refers to the pattern for byte ordering in native types, such as integers. There are only two main patterns, big endian and little endian, and these describe which end of a multibyte integer appears in the lowest address byte of the integer. Big endian means the most significant byte comes first, and little endian means the least significant byte comes first. The following illustrates each pattern for integer 0x87654321. Please refer to the README.tvbuff and the README.developer documents located in the docs directory.

Value Types Used by Ethereal

Ethereal utilizes a number of common value definitions. These are defined in the README.tvbuff and the README.developer documents located in the doc directory. Different development environments will refer to value types by different names. Ethereal provides a common set of value types to allow for easier portability between operating systems. The following is a brief listing of the most common:

guint8 (1-byte value)

guint16 (2-byte value)

guint32 (4-byte value)

guint64 (8-byte value)

guint8* (pointer to a byte value)

gchar* (pointer to a character string)

Now we want to display in the decode pane whether this is a request or reply packet. We do this with the proto_tree_add_xxx functions. In our example we only want to display in the decode window a message indicating if this is a request or reply packet.

if (request_reply==0)
        proto_tree_add_text(tree, tvb, offset, 1, "Request-(%d) ",      
             request_reply);
 else
        proto_tree_add_text(tree, tvb, offset, 1, "Reply-(%d) ", 
             request_reply);

The proto_tree_add_text function requires the following parameters.

tree Pointer to the protocol tree.
tvb The tvbuff to mark as the source data.
offset The offset in the tvb is where the data is located.
1 The length of the value, in bytes, in the tvb.
Request Packet (%d) The printf type format for displaying the data.
request_reply The data value to be displayed via the printf format.

You might ask why the tvbuff information gets passed to the proto_tree_add_xxx function. We already have extracted the information into our variable request_reply. The tvbuff parameters tell Ethereal the portion of the data in the hex display pane to highlight when this value is selected in the decode pane. Also note that the tvbuff starts at the beginning of the data passed to your dissector. For example, when getting data from the tvbuff, the byte with an offset of 0 is the first byte of the packet data that is related to your protocol. The previous packet data that was decoded by a higher-level dissector is not accessible. This ensures that the data seen by your dissector only pertains to the protocol dissection you are attempting to accomplish.

There is one problem with this example. If we utilize the proto_tree_add__text function then this value is not a filterable element. So, if the user wanted to create a filter for all request packets in our dissector, they would not be able to. We could rewrite the example to utilize the hf array and make the request_reply value a filterable item.

if (request_reply==0)
        proto_tree_add_item(tree, hf_request, tvb, offset, 1, FALSE);
 else
        proto_tree_add_item(tree, hf_reply, tvb, offset, 1, FALSE);

Although this example will now allow the user to filter on the request or reply condition, this is not the most efficient use of the proto_tree_add_xxx functions. Since the value is already stored there is no reason to force the dissector to reread the data. The proto_tree_add_uint function can be used to display the data already stored in our request_reply variable. If the value had not already been stored in a variable, the proto_tree_add_item function would be the most efficient to use.

if (request_reply==0)
                 proto_tree_add_uint(tree, hf_request, tvb, offset, 1,
                     request_reply);
 else
                 proto_tree_add_uint(tree, hf_reply, tvb, offset, 1,
                     request_reply);

If we change the proto_tree_add_text to proto_tree_add_item, then we utilize an hf element for displaying the data in the decode window. We now need to add the hf_request and hf_reply variables to the hf array.

You must first declare the hf variables at the top of the source file after your include statements.

static int hf_request = -1;
 static int hf_reply = -1;

Now we just add the element information to the hf arrary.

{ &hf_request,
   { "Reqeust Packet", "myprot.request",
   FT_UINT8, BASE_DEC, NULL, 0x0,
   "", HFILL }},
 
 { &hf_reply,
   { "Reply Packet", "myprot.reply",
   FT_UINT8, BASE_DEC, NULL, 0x0,
   "", HFILL }},

With these changes, if the user would like to filter on all request packets in the myprot dissector, they enter the filter of myprot.request. Any packet that meets the request_reply value of 0 will contain an array element of myprot.request. Reply packets will contain an element of myprot.reply. Figure 9.8 shows an example of how a user might enter a display filter to force Ethereal to only display the packets for our new dissector.

Figure 9.8: Sample Display Filter

The real work of the dissector begins here. You will need to go through the logic of each type of packet that the dissector will decode. You should utilize the tvb_get_xxx functions to get data you need to evaluate as well as the proto_tree_add_xxx functions to display information in the decode window.

But, there is one more important step that we have not considered at this point. The summary pane, as shown in Figure 9.9, allows the user to browse quickly through the packet trace without having to look at each packet decode. This window allows you to display brief but important information relative to the packet. Typically, most developers will provide summary data on request packets and only error information on reply packets. The col_set_str function allows you to set the value of the data within any of the displayed summary window columns.

Figure 9.9: Summary Pane

There are many variations of the proto_tree_add_xxx functions. The proto_tree_add_item is the most versatile because it allows the format of the data to be defined in the hf array. If you attempt to pass the wrong data types to any of the proto_tree_add_xxx functions, a runtime error will be displayed and Ethereal will halt. This error processing allows Ethereal to trap for errors instead of allowing memory to be overrun or corrupted. It is good practice to utilize the hf array even if you do not want the end user to be able to filter on a specific item in the decode. For these conditions you can specify that the element is hidden so that the end user will not know of its definition. For detailed information on all of the different proto_tree_add_xxx types and the format of the hf array, refer to the README.developer document in the doc directory.

In the following code example we see the check_col() and col_set_str() functions. These functions are just a subset of the column functions available.

if (check_col(pinfo->cinfo, COL_PROTOCOL))
     col_set_str(pinfo->cinfo, COL_PROTOCOL, "MYPROT");

Note that the first thing we do is to evaluate whether the column data exists. If it doesn’t exist, then we cannot write to the column data structure. This is an important step since without this check you could potentially write to undefined memory. We then make the col_set_str function call to set the value of the protocol column “COL_PROTOCOL” to our protocol name “MYPROT”.

if (request_reply==0)
 {
     proto_tree_add_item(tree, hf_request, tvb, offset, 1, FALSE);
     if (check_col(pinfo->cinfo, COL_INFO))
         col_set_str(pinfo->cinfo, COL_INFO, "Request– ");
 }
 else
 {
     proto_tree_add_item(tree, hf_reply, tvb, offset, 1, FALSE);
     if (check_col(pinfo->cinfo, COLINFO))
         col_set_str(pinfo->cinfo, COL_INFO, "Reply– ");
 }

We now want to set the summary column to reflect if this is a request or reply packet. We do this the same way we did for the protocol column, by using the col_set_str function. Note that we still perform the check to validate that the column information is valid. Later in our dissector we can append information to the info column by using the col_append_str function.

Step 6 Pass Payloads

The final thing your dissector should do is to pass on any payload that might be remaining to be dissected by additional dissectors. This handoff of the payload data is what each of the lower level dissectors performs to allow entry points for further dissection. For example, the TCP dissector decodes the TCP header information but the remaining payload is dissected by different higher-level dissectors. In some cases you may not need to pass on payload data, but it is recommended that your dissector look at the remaining data in the packet and pass it on if there is anything else to dissect. In some cases your dissector may contain a data payload that can’t be actually dissected. In this case if you have remaining data in the packet structure that needs to be decoded by another dissector or as payload information, the remaining data should be displayed in some manner. The passing of the remaining payload back to Ethereal will automatically be displayed as [Data] if no further dissection can be performed. For example, there is no defined lower dissector to handle the decoding of the remaining data. If the remaining data is payload for your dissector then utilize the proto_tree_add_item and pass a -1 as the length parameter. Ethereal will then mark all of the remaining data in the packet as the defined proto_tree_add_item. The following information is extracted from the README.developer document located in the doc directory.

An example from packet-ipx.c –
 
 void
 dissect_ipx(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
 {
    tvbuff_t        *next_tvb;
    int             reported_length, available_length;
 
    /* Make the next tvbuff */
    next_tvb = tvb_new_subset(tvb, IPX_HEADER_LEN, -1, -1);
 
 /* call the next dissector */
    dissector_next(next_tvb, pinfo, tree);

You’ve just learned how to create a simple dissector. In the next section, we will discuss how to modify the files used to build Ethereal so that it can be compiled into the rest of the project. Before you start major work on your dissector you should first make sure that the build process will complete with your new dissector included. This will also validate that your registration is working and that Ethereal passes your dissector the packet data as expected. Under the “Advanced Topics” section of this chapter, we will explore some of the more complex issues you may encounter when creating a protocol dissector.

Running a Dissector

To add a new dissector to the Ethereal project you will need to modify some of the scripts used to manage the build process. The scripts that have to be changed will depend on the operating system that you are developing on. When developing on a UNIX/Linux-based operating system you will need to change the Makefile.am to add your new dissector. On Windows based operating systems you will need to modify the Makefile.nmake script.

DISSECTOR_SRC = \
     packet-aarp.c \
     packet-acap.c \
     packet-afp.c  \
     packet-afs.c  \

Both files contain the same structure to define the new dissector. Add your dissector to the DISSECTOR_SRC section of the file. When you build Ethereal this section is parsed and each dissector is compiled and linked into the main Ethereal binary.

Once you have successfully built Ethereal with your modifications you should go back and analyze your code. Places where you have not commented on what you are doing should be commented on if they are not obvious. This allows you and others to look at the code at a later date and determine what that particular section is doing. Also take note of any warnings reported by your compiler and try to resolve them. Generally, this might be improper data type casts or unused variable definitions.

After you have completed the cleaning up of the code and you are satisfied with its functionality, please contribute your changes back to the Ethereal project by sending a patch to the ethereal-dev mailing list. For changes to existing files it is recommended that the changes are sent as a patch to the existing file in CVS. It is also important that you consult with the proper individuals before you submit any proprietary information back to the Ethereal distribution. Remember that Ethereal is released under GPL and your submissions should be made under the same license agreement.

If you are working with a CVS distribution you can perform an update by issuing the following command:

cvs update –Pd

Then you should generate a patch with the command:

cvs diff –u packet-myprot.c >packet-myprot.c.diff

If the file you need to send is a new dissector, you should send the complete source file packet-myprot.c and a patch to both the Makefile.nmake and Makefile.am. Attempting to perform a CVS diff on your new dissector will not generate any information if your source does not exist in the CVS distribution. Your initial contribution will be a complete copy of the source. Future modifications should be submitted in patch form by generating a CVS diff file.

The Dissection Process

When does your dissector get called? When Ethereal reads a packet via the wiretap library it performs the following steps:

The frame data is passed to the function epan_dissect_run().
The function epan_dissect_run() defines the frame, column, and data pointers and calls the function dissect_packet().
The dissect_packet() function creates the topmost tvbuff and then calls the dissect_frame() function.
The dissect_frame() function dissects the frame data and displays in the decode pane of the GUI the frame information for the packet. For example, the arrival time, frame number, or frame length.
The dissect_frame() funtion then calls the dissector_try_port() to see if there are any protocol dissectors to dissect the next part of the tvbuff. In the example shown in Figure 9.7, we see in the decode pane that we are passed to the Ethernet packet type dissector. This would be dissect_eth_common() function.
The dissect_eth_common() function then decodes and displays the Ethernet header in the decode pane of the Ethereal GUI. Several different functions could be called at this point based on the Ethernet frame type. But once the Ethernet frame type has been decoded the remaining tvbuff is passed to the core Ethereal function dissector_try_port() again.
The dissector_try_port() function again looks to see if there is another dissector registered for the remaining tvbuff.
This process of decoding each layer of the packet continues, header by header, until we reach our protocol dissector. Ethereal calls each dissector, that dissector processes its data, then the dissector creates a new tvbuff and sends it back to dissector_try_port(). In our example we saw that myprot would eventually be the payload of a TCP packet. Ethereal would continue each dissection until the TCP dissector was processed. At this point dissector_try_port() would see that we are registered for TCP port 250.
Finally, the dissector_try_port() function calls our dissector myprot.
Once our dissector has completed its work it passes any remaining tvbuff back again. The process continues until either there is no more data or no more registered dissectors for the remaining data. Once this happens the next frame is read from the packet trace file.

Advanced Topics

The previous section discussed the basic information necessary to create a simple dissector. But, as your dissector becomes more complex you will need to implement more advanced features. Ethereal provides many different mechanisms to assist you in making your dissector display and decode packet data in a more informative manner. In this section we will look at some of the more complex tasks that you may want to incorporate into your packet-xxx dissector.

We will also take a quick look at modifying the Ethereal GUI. This process will require you to acquire some knowledge of GTK and some of its features and mechanisms. Since Ethereal’s GUI is generated by using the GTK libraries, you will find that it makes calls to functions that are not included in the Ethereal distribution. These functions are part of the GTK binaries that you downloaded in the GTK developer kit. Documentation on these functions are available at the GTK website at www.gtk.org.

Finally, this section includes a short description of the tap and plug-in implementations in Ethereal. Taps will allow you to build tools that acquire real-time data from Ethereal. The plugin interface will allow you to convert a packet-xxx dissector into a plug-in that can be loaded and unloaded.

It is important to realize that your dissector can be called multiple times. Every time a display or color filter gets applied to a packet trace, Ethereal will re-dissect the data again. When the user clicks on an item in the decode pane the dissector is again called to dissect that specific packet. Your dissector should evaluate the fd.flags.visited flag in the pinfo data structure to determine if it needs to perform work that has not been performed. Otherwise, you may overwrite data that is necessary to properly decode your packets, for example, adding new conversations into a conversation list that already exists. You should construct your dissector to take into consideration if the initial dissection has already been completed.

Dissector Considerations

When you compose a dissector you may need to consider several factors. If the protocol that needs dissection runs on top of a connection-oriented protocol, you might need to track the request reply packets to ensure they match. Connection-oriented protocols generally guarantee delivery. The underlying protocol will retransmit packets if they are not acknowledged by their peer. So how do you handle retransmissions? Your dissector may also need to handle payloads that exceed the maximum packet size. The actual payload may span several packets and your dissector needs to defragment the data. There are also situations where you might want to store information either in the form of a memory value or across loading of the application. You will most likely encounter at least one of these conditions. This section is meant to provide some advanced topics to help you overcome and develop a way to handle these situations.

Creating Sub-trees

Many times the decoded data should be branched to a separate sub-tree. This practice allows users to see important summary information in the decode window and allow them to expand specific sections of the decode window to see more detail. For example, we may want to branch at a sub-level or a particular item that might contain more data or attributes then you want to normally display (see Figures 9. 10 and Figure 9.11).

Figure 9.10: Closed Item in Decode Pane

Figure 9.11: Expanded Item in Decode Pane

The user can now click on the Entry Information field within the decode window to expand the item and get more detailed information. Sub-trees are easily implemented with the proto_tree functions.

proto_item        *subitem;
 proto_tree        *subtree;
 
 subitem = proto_tree_add_text(tree, tvb, offset, -1, "Some Description");
 subtree = proto_item_add_subtree(subitem, ett_myprot);
 proto_tree_add_item(subtree, hf_myvalue, tvb, offset, 4, FALSE);
 proto_item_set_end(subitem, tvb, offset);

The first step is to declare the proto_item and proto_tree variables.

The proto_tree_add_text function allows us to create a label. This is only one of many good uses of the proto_tree_add_text function. In this example, we pass the tree pointer that was given to us when our dissector was called. We also pass the tvb, offset, and length to the function so that when the user highlights the label in the decode window the remaining packet data will be highlighted. The -1 tells proto_tree_add_text that the length is all remaining data starting from the beginning offset. Finally, the label is passed to the function to describe what this sub-tree actually contains. We could branch from an actual element within the decode window as well instead of creating a label. To do this we could replace the proto_tree_add_text with a different proto_tree_add function. Once the label has been created in the original tree a new item pointer is returned in our sub-item variable.

The next function, proto_item_add_subtree, sets up the sub-tree in the display. It creates the sub-tree so that when we later perform another proto_tree_add function, we can reference the new sub-tree pointer.

The next call is to the proto_tree_add_item function. We pass the pointer for our new sub-tree in this function. This actually places the new element beneath the expandable label we created before. The value will not be viewable in the decode window until the sub-tree label is clicked on and expanded.

The final step in this example is to set the overall length of the proto_tree_add_item with the proto_item_set_end function. This is used when the length of the value being set is unknown. If you are working with items of known length, this function call is not necessary.

Many times you may want to create several branches of sub-trees. To do this, create multiple proto_items and proto_tree pointers. We would create sub-tree 1 and then sub-tree 2, but reference sub-tree 1 as the source tree. A visual display of the multi-level tree view can be seen in Figure 9.12.

                item1 = proto_tree_add_text(tree, tvb, offset, -1, 
                      "Selector Option");
                 tree1 = proto_item_add_subtree(item1, ett_myprot);
                 number_of_items = tvb_get_ntohl(tvb, offset);
                 proto_tree_add_uint(tree, hf_num_objects, tvb, offset, 4,                  
                       number_of_items);
                 foffset += 4;
                 for (i = 1 ; i <= number_of_items; i++ )
                 {
                     item2 = proto_tree_add_text(tree1, tvb, offset, -1,
                           "Option - %u", i);
                     tree2 = proto_item_add_subtree(item2, ett_myprot);
                 }

Figure 9.12: Visual Display of Multi-level Tree View

Bitfields

In some cases you may have a value that represents specific information based on what bits are set within the value. Bitfields give the user a visual display of each bit and whether they are enabled within the value, as shown in Figure 9.13.

Figure 9.13: Visual Display of Bits

Bitfields are implemented through the use of the hf array elements. The following code is an example of the calling function that builds the subtree and summary data.

flags = tvb_get_guint8(tvb, offset);
 strcpy(flags_str, "");
 sep = " (";
 if (flags & FLAG1) {
    strcat(flags_str, sep);
    strcat(flags_str, "Flag 1");
    sep = ",";
 }
 if (flags & FLAG2) {
    strcat(flags_str, sep);
    strcat(flags_str, "Flag 2");
    sep = ",";
 }
 if (flags_str[0] != '\0')
    strcat(flags_str, ")");
 ti = proto_tree_add_uint_format(tree, hf_flags,
      tvb, offset, 1, flags, "Flags: 0x%04x%s", flags,
      flags_str);
 flags_tree = proto_item_add_subtree(ti, ett_myprot);

The first step is to acquire the value from the tvbuff into the value flags. We then build our initial string and then compare the value of flags with our defined flag bits. If they match, we combine the string with the flag information. Once our summary string has been built we just create our sub-tree and display the data. We now need to display each of the valid bits in a bit view.

proto_tree_add_item(flags_tree, hf_flag_1,
     tvb, offset, 1, FALSE);
 proto_tree_add_item(flags_tree, hf_flag_2,
     tvb, offset, 1, FALSE);
 
 { &hf_flag_1,
   { "Flag 1", "myprot.flag.1",
    FT_BOOLEAN, 8, NULL, FLAG1,
    "Is Flag one set? ", HFILL }},
 { &hf_flag_2,
   { "Flag 2", "myprot.flag.2",
   FT_BOOLEAN, 8, NULL, FLAG2,
   "Is Flag two set? ", HFILL }},

We display the bitfields by calling the proto_tree_add_item function with reference to our new sub-tree and the bitfield hf element names. Then, in the hf array, we define our new values. The key here is parameters 3, 4, and 6. Parameter 3 declares that this is a Boolean value. This means that we will evaluate this as a true or false condition. Parameter 4 declares that we will display 8 bits. Parameter 6 declares the actual value of the bitmask. You can substitute this value with the explicit mask. In our example, flag 1’s value might be 0x01 and flag 2 might be 0x02.

Unicode Strings

Many times you will run into situations where the actual data contained in the packet might contain Unicode data. Unicode data is normally seen in the hex data window as a two-byte value. For example you might see:

57 00 6f 00 72 00 6b 00 73 00 74 00 61 00 74 00 69 00 6f 00 6e 00
 W     o     r     k     s     t     a     t     i     o     n

When processing the data, most string conversion utilities will see the second byte of the multi-byte character as a terminating null. You might find that you need to parse the string to acquire single byte character strings. Many of the main string functions within Ethereal now perform this process for you but you might find that you have a situation that requires you to manually perform the conversion. Several dissectors include functions to convert multi-byte character strings to single byte strings. The following code is an example extracted from packet-ncp2222.inc:

static void
 uni_to_string(char * data, guint32 str_length, char *dest_buf)
 {
         guint32 i;
         guint16 c_char;
         guint32 length_remaining = 0;
 
         length_remaining = str_length;
         dest_buf[0] = '\0';        
         if(str_length == 0)
         {
                 return;
         }
         for ( i = 0; i < str_length; i++ )
         {
                 c_char = data[i];
                 if (c_char<0x20 || c_char>0x7e)
                 {
                         if (c_char != 0x00)
                         { 
                                 c_char = '.';
                                 dest_buf[i] = c_char & 0xff;
                         }
                         else
                         {
                                 i--;
                                 str_length--;
                         }
                 }
                 else
                 {
                         dest_buf[i] = c_char & 0xff;
                 }
                 length_remaining--;
                 
                 if(length_remaining==0)
                 {
                         dest_buf[i+1] = '\0';
                         return;
                 }        
         }
         dest_buf[i] = '\0';
         return;
 }

Conversations

Ethereal conversations are a key component of many protocol dissectors. Each dissector that needs to track conversations will define and maintain their own conversation table. The conversation table gives the dissector the ability to track request and reply packets. You might ask why you would need to track the conversation. What if there is no information contained in the reply packets that identify which request the reply was for? In this case we would need to store the original request packet in memory so that when the reply packet is found we can decode it. For example, the NetWare Core Protocol (NCP) protocol only defines a sequence number on the request packet. But, each request reply sequence is a unique session. Running on top of TCP or Internetwork Packet Exchange (IPX), the request packet will be made from a specific address with a unique port/socket. If we match these conversation components then we can logically assume that the reply packet is a response to the original request. Unfortunately, these may not come in the proper order in a packet trace. The conversation list saves each request conversation within our conversation list. When we encounter a reply packet, we perform a lookup in the conversation list to determine which request the reply matches. If no originating request packet is found, we should display a message in the decode window that the packet could not be decoded due to no request packet being found. Section 2.2.7 of the README.developer document located in the doc directory provides basic skeleton code to setup a conversation table.

Some important steps should not be missed when using conversations lists. This includes the initialization function and the cleanup function that have to be placed in the protocol register routine. Many dissectors include conversation lists. If, after reviewing the section in the README.developer document, you still need a clearer example, refer to other dissectors that utilize this capability.

Packet Retransmissions

Packet retransmissions are common on busy networks. Your dissector should be able to handle such an occurrence if it is going to attempt to handle fragmented packets. If your dissector or protocol does not process fragmented packets, your dissector can treat these packets as normal packets. In most cases a simple conversation list can check for the occurrence of a request packet but if nothing triggers your dissector, it might be a duplicate entry. You may also find that you need to manage another memory table to track a retransmitted packet. However, in other cases, the lower-level protocol might have already detected the retransmissions.

The packet information structure pinfo can provide information for the status of the current packet being decoded. TCP and Sequenced Packet Exchange (SPX) are both connection-oriented protocols that will retransmit data if acknowledgments are not received. Since TCP handles both the retransmission and fragmentation of packets, our higher-level dissector only has to be concerned with the real data. However, in the case of SPX, the higher-level dissector has to trap for retransmissions if it is handling packet fragmentation. The next section discusses how the SPX dissector passes this information on to the higher-level dissectors. It is important for you to understand that a retransmission is a common occurrence on many networks. Your dissector should be able to determine if a packet is a retransmission or a normal packet. In some cases you may choose not to dissect retransmitted packets and just identify the original packet. Just remember that a retransmission can occur at any time. It may consist of a complete packet or an individual fragment.

Passing Data Between Dissectors

The pinfo->private_data element can be used to pass a pointer to a memory table with information regarding the specific packet being decoded. You should first define a structure in your lower level dissector that will hold the information. The following information was extracted from packet-ipx.h and packet-ipx.c:

/*
  * Structure passed to SPX subdissectors, containing information from
  * the SPX header that might be useful to the subdissector.
  */
 typedef struct {
        gboolean eom;              /* end-of-message flag in SPX header */
        guint8    datastream_type;     * datastream type from SPX header */
 } spx_info;

Then we update the structure and save it to pinfo.

static void
 dissect_spx(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
 {
       spx_info      spx_info;
 
              /*
              * Pass information to subdissectors.
              */
              spx_info.eom = conn_ctrl & SPX_EOM;
              spx_info.datastream_type = datastream_type;
              pinfo->private_data = &spx_info;

Now, in the higher-level dissector we can retrieve this information. This information was extracted from the source file packet-ndps.c:

static void
 ndps_defrag(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
 {
     spx_info            *spx_info;
 
     /* Get SPX info from SPX dissector */
     spx_info = pinfo->private_data;

The higher-level dissector can now utilize the information from the lower level dissector to perform logical operations on the packet data.

Saving Preference Settings

It is often important for the user to determine how the protocol dissector might handle specific features of your dissector. For example, the packet fragmentation code can be enabled or disabled by the end user under the protocol preferences dialog. To implement a user configurable setting that will be either used during runtime or saved across multiple loads of Ethereal, you should add the ability to utilize the system preference file.

ldap_module = prefs_register_protocol(proto_ldap, NULL);
 prefs_register_bool_preference(ldap_module, "desegment_tcp",
     "Desegment all LDAP messages spanning multiple TCP segments",
     "Whether the LDAP dissector should desegment message",
     &ldap_desegment);

This code goes into the proto_register_xxx routine. It creates a new entry in the preference files with the value of the referenced variable myprot_desegment. The following is an example of the entry created in the preference file. Figure 9.14 is an example of how the value will look to the end user when they go to the preferences option in Ethereal and select your protocol. We used the LDAP protocol dissector as our example.

# Whether the LDAP dissector should desegment messages
 # TRUE or FALSE (case-insensitive).
 ldap.desegment: TRUE

Figure 9.14: Example of LDAP Preference

In other cases you may need to keep information relating to a specific packet decode. It is best to utilize a conversation table to handle this type of condition.

Packet Fragmentation

Packet fragmentation can be handled at many different protocol layers. TCP already includes packet reassembly. If your dissector needs to do additional packet reassembly then you can utilize the reassembly functions defined in Ethereal. A good example of how to handle packet reassembly by TCP is located in section 2.7 of the README.developer document in the doc directory. It covers how to handle the packet reassembly when your dissector is running on top of TCP or User Datagram Protocol (UDP).

The files packet-ncp2222.inc, packet-atalk.c, and packet-clnp.c all give examples of how to defragment messages that are fragmented within the protocol you are dissecting. The logic involved in defragmented packets can be very complicated. You will find yourself spending many hours troubleshooting and fine-tuning the defragmentation function.

Value Strings

You will also find times when you read a specific value from the packet datastream that could be defined by many different descriptions based on the value. You will want to present a string to the user indicating what the value actually means. An example of this might be an error return value in a reply packet. The numerical value will indicate which error was being returned. The section 1.7.1 in the README.developer document located in the doc directory lists the match_strval and the val_to_str functions. The first step is to create the array of values.

static const value_string my_values[] = {
        { 0x00000000, "Value 1" ),
        { 0x00000001, "Value 2" },
        { 0x00000002, "Value 3" },
        { 0, NULL }
 };

It is important to note the final line in the value string of [0, NULL]. This is the termination record for the value_string function. If this is omitted then Ethereal will continually scan memory and may possible generate a bounds error.

You can now utilize the match_strval or val_to_str functions to process the value.

valuestr = match_strval(value2, my_values);

But, you can simplify this process even further by utilizing the VALS capability of the hf arrary.

{ &hf_valuestr,
 { "This is my value", "myprot.valuestr",
    FT_UINT8, BASE_DEC, VALS(my_values), 0x0,
   "My value string", HFILL }}

This way we can just utilize the simple tvb_get and proto_tree_add _functions.

value2 = tvb_get_guint8(tvb, 1);
 proto_tree_add_uint(tree, hf_valuestr, tvb, 1, 1, value2);

The same feature can be utilized to display true or false value strings in the decode pane of the GUI, for example, if you wanted to display “Yes” or “No” based on a true or false value.

     typedef struct true_false_string {
           char    *true_string;
           char    *false_string;
      } true_false_string;

Value strings are very important for processing return values that might contain a large number of error codes. The value string gives you the ability to process all of the possible values and return a specific string to identify the actual error. Without this information the end user is forced to research the returned value to look up the return value. In some cases the value may not really indicate a problem, but by providing the string to the end user you will eliminate much frustration and make your dissector even more valuable. Figure 9.15 shows an example of data displayed in the decode pane when utilizing a value string to return a string based on the return value.

Figure 9.15: Example of Value String Display

The Ethereal GUI

The Ethereal GUI is created through calls to the GTK library. When you develop for the Ethereal GUI you must consider compatibility issues for other builds of Ethereal. This means that you must program for both GTK version 1.2 and versions 2.x. Some of the GTK functions work in both versions but others need to be programmed specifically for the version that Ethereal is built with. The README.developer document located in the doc directory does not contain any information on the modifications to the GUI. As a reference you should use the GTK website at www.gtk.org as well as other GUI code located in the GTK directory.

The Item Factory

The main menu for Ethereal is created via a GTK item factory. The following information is extracted from the gtk/menu.c source file included in the Ethereal source distribution:

/* This is the GtkItemFactoryEntry structure used to generate new menus.
        Item 1: The menu path. The letter after the underscore indicates an
                accelerator key once the menu is open.
        Item 2: The accelerator key for the entry
        Item 3: The callback function.
        Item 4: The callback action.  This changes the parameters with
                which the function is called.  The default is 0.
        Item 5: The item type, used to define what kind of an item it is.
                Here are the possible values:
 
                NULL               -> "<Item>"
                ""                 -> "<Item>"
                "<Title>"          -> create a title item
                "<Item>"           -> create a simple item
                "<ImageItem>"       -> create an item holding an image (gtk2)
                "<StockItem>"       -> create an item holding a stock image (gtk2)
                "<CheckItem>"      -> create a check item
                "<ToggleItem>"     -> create a toggle item
                "<RadioItem>"      -> create a radio item
                <path>              -> path of a radio item to link against
                "<Separator>"      -> create a separator
                "<Tearoff>"        -> create a tearoff separator (gtk2)
                "<Branch>"          -> create an item to hold sub items (optional)
                "<LastBranch>"     -> create a right justified branch
        Item 6: extra data needed for ImageItem and StockItem (gtk2)
     */

The set_menu_sensitivity function enables and disables the availability of menu items based on a specified condition. Generally, you will only need to modify the Ethereal menu if you are creating a tool or making a change to some other portion of the GUI.

When the item factory option is selected, the function listed in Item 3 will be called. In GTK, callback functions are what get called when an item is selected.

Using GTK

When an item is selected, GTK passes a handle to the active selection. These are called widgets in GTK.

void
 my_widget(GtkWidget *w _U_, gpointer d _U_)
 {
    GtkWidget     *main_vb
    GtkTooltips   *tooltips;
 #if GTK_MAJOR_VERSION < 2
    GtkAccelGroup *accel_group;
 #endif

When our menu item is selected, GTK passes us the GTK widget pointer and data structure. We then create a new GTK widget for our window.

The GtkTooltips is a value that allows us to store information that will be displayed when the user places his or her mouse pointer over a GTK widget. For example, suppose that we have a button on our window that (when clicked) will change the current display filter to one of our choosing. Although the size of the button only allows us to label it as “Filter”, we can define a tool tip that provides a more detailed description of the button’s function.

The GtkAccelGroup is necessary for GTK version 1.2. It allows for accelerator keys to be used on the keyboard to access menu items.

  if (mywindow_w != NULL) {
     /* There's already a "My Window" dialog box; reactivate it. */
     reactivate_window(mywindow_w);
     return;
   }
 
   mywindow = dlg_window_new("Ethereal: My Window");
   SIGNAL_CONNECT(mywindow_w, "destroy", mywindow_destroy_cb, NULL);
 
   tooltips = gtk_tooltips_new ();
 
 #if GTK_MAJOR_VERSION < 2
   /* Accelerator group for the accelerators (or, as they're called in
      Windows and, I think, in Motif, "mnemonics"; Alt+<key> is a mnemonic,
      Ctrl+<key> is an accelerator). */
   accel_group = gtk_accel_group_new();
   gtk_window_add_accel_group(GTK_WINDOW(mywindow_w), accel_group);
 #endif

We first check to make sure our window is not already open. If it is, then we reactivate it. If it is not, then we create a new dialog window. When you create the new window you should create a callback handler to take care of the window being closed by the user clicking the exit button in the upper right-hand corner of the dialog box. The SIGNAL_CONNECT function tells GTK what to do when the specified signal occurs. In this case it is the destroy signal that we are trapping for.

Finally, we initialize the tooltips. Notice that we only perform the accelerator group from GTK version 1.2. Accelerator keys in GTK 2.x are defined when creating the item. We will see this later.

  /* Container for each row of widgets */
   main_vb = gtk_vbox_new(FALSE, 3);
   gtk_container_border_width(GTK_CONTAINER(main_vb), 5);
   gtk_container_add(GTK_CONTAINER(mywindow_w), main_vb);
   gtk_widget_show(main_vb);

The first step is to create our main window. Next, we create a box on the new window. The gtk_vbox_new creates the new box that we will add to our window. The gtk_container_border_width defines the border for our window. The gtk_container_add now adds our new box to the main window. Finally, the gtk_widget_show forces GTK to paint the information to the screen. The following demonstrates the creation of an OK button on the main_vb window.

  /* Button row: OK button */
   bbox = gtk_hbutton_box_new();
   gtk_button_box_set_layout (GTK_BUTTON_BOX (bbox), GTK_BUTTONBOX_END);
   gtk_button_box_set_spacing(GTK_BUTTON_BOX(bbox), 5);
   gtk_container_add(GTK_CONTAINER(main_vb), bbox);
   gtk_widget_show(bbox);
 
 #if GTK_MAJOR_VERSION < 2
   ok_bt = gtk_button_new_with_label ("OK");
 #else
   ok_bt = gtk_button_new_from_stock(GTK_STOCK_OK);
 #endif
   SIGNAL_CONNECT(ok_bt, "clicked", capture_prep_ok_cb, cap_open_w);
   GTK_WIDGET_SET_FLAGS(ok_bt, GTK_CAN_DEFAULT);
   gtk_box_pack_start (GTK_BOX (bbox), ok_bt, TRUE, TRUE, 0);
   gtk_widget_grab_default(ok_bt);
   gtk_widget_show(ok_bt);

The first section of this code creates a new horizontal button box, adds it to the main_vb window, and forces GTK to paint the new box.

We then check the GTK version and create the new button depending on the version of GTK. Note that GTK version 2.x allows us to specify the icon used for this button. This is how you can create custom icons and incorporate them into Ethereal. We register the callback function for GTK to use when the button is clicked, register the button as the default button, and finally paint the button on the screen.

You can also register widget data to a widget so that when it is selected then the data associated to the widget gets passed to the calling function. For example, in the gtk/find_dlg.c file, a number of defines are set to identify the buttons within the find window.

/* Capture callback data keys */
 #define E_FIND_FILT_KEY       "find_filter_te"
 #define E_FIND_BACKWARD_KEY   "find_backward"

Next, the keys are registered as data to the dialog with the object_set_data function.

  OBJECT_SET_DATA(find_frame_w, E_FIND_FILT_KEY, filter_text_box);
   OBJECT_SET_DATA(find_frame_w, E_FIND_BACKWARD_KEY, backward_rb);

Finally, when the find_frame_w is selected, the callback function can access the values of the attached buttons by calling the object_get_data function.

  filter_te = (GtkWidget *)OBJECT_GET_DATA(parent_w, E_FIND_FILT_KEY);
   backward_rb = (GtkWidget *)OBJECT_GET_DATA(parent_w, E_FIND_BACKWARD_KEY);

The GTK website contains many examples and a window builder tool that you can download and experiment with. To program in GTK you must know the static defines for predefined items like GTK_STOCK_XXX and GTK_CAN_DEFAULT. All of this information is available from the GTK website.

TAPS

Ethereal implements a tap system to allow for real-time statistics during packet captures. These can also be used by tools that register to the tap interface and command Ethereal to redissect a saved packet capture file. The tap system is documented in the README.tapping document located in the doc directory. Also in the main source directory you will find a number of tap-xxx files you can use for a reference on the tap interface. The file gtk/endpoint_talkers_table.c can be used for an example of how to implement a TAP inside of an included tools menu option.

You implement the tap interface in two steps. The first step is to install the tap into the protocol dissector you would like to get information from. The second step is to add the tap listener to your application. Many of the protocol dissectors included in Ethereal already contain taps. Most likely you will only need to create your tap listener and perform the work you need to do. If you find that a tap is not installed in the protocol you need, the process is simple through the use of only a few lines of code. Please refer to the README._tapping for more information.

Plug-ins

Ethereal also supports the implementation of protocol dissectors as plug-ins. Plug-ins are preferred by some developers because they can be developed and debugged without having to rebuild the whole Ethereal distribution. You can compile and build your plug-in and then copy the binary to the plugins directory under the name of your plug-in. Ethereal ships with a number of plug-ins and each can be loaded or unloaded depending on whether they are installed prior to launching Ethereal. The plugin interface mimics the dissector interface. In fact, plug-ins are first developed as a normal dissector. Then, additional code is added to make the dissector a plug-in. The key part of developing a plug-in is the plugin_init and plugin_address_table_init functions to register the plug-in with Ethereal. The file README.plugins located in the doc directory outlines the steps you need to take to generate a plug-in dissector for Ethereal.

Summary

This chapter has outlined some of the most important parts of developing in Ethereal. There are several kinds of components to which you can contribute:

Protocol Dissectors
Plug-ins
The Ethereal GUI
Tools

This chapter went into great detail documenting the proper steps to take when creating a dissector. By consulting the README.developer document in the doc directory, you can cut and paste a template to help you get started. However, since the document does not clearly define each step necessary in the development process, this chapter attempts to provide these steps in a logical order. You first modify the header and the include statements. We then register the protocol dissector. Finally, create the dissector code to actually decode the data. The important factor in the decode section is to utilize the hf array in the register function so that elements can be filtered upon.

This chapter also covered several advanced topics including a basic guide to GTK programming. Many of the topics covered will be experienced by someone creating a protocol dissector. Handling of the advanced topic issues correctly can eliminate many hours of unnecessary work and research. After debugging your work, make sure you go back and cleanup as much of the code as possible. Insert comments to make the code clear. In addition, make sure you remove unused variable definitions. If possible, clean up any remaining warnings displayed in the compile process by your compiler. Finally, please contribute your modifications back to the Ethereal project by e-mailing a patch to the ethereal-dev mailing list. Again, make certain that any information that you contribute back to Ethereal is not going to violate any proprietary claims. Ethereal is released under the GPL and all contributions should be consistent with this licensing agreement.

Solutions Fast Track

Prerequisites for Developing Ethereal

The Ethereal source must be obtained before you can start any new development. You have the option of downloading different types of download packages. The Ethereal website, www.ethereal.com, has links to download previous versions, the current version, nightly backups, and CVS code.
The requirements for Windows based computers are different from UNIX/Linux based computers. Windows based computers require additional tools to emulate the UNIX/Linux environment.
To build Ethereal, a number of libraries and tools will need to be used. There are several libraries that are optional depending on whether you decide to add a specific feature.
Ethereal can be compiled and run on a number of operating systems. For this reason you must ensure that you program in ANSI C for portability between all of the supported platforms.
Before you start any work on Ethereal, make sure you can compile and link Ethereal into its executable binary form.

Ethereal Design

The main directory of the source distribution is the primary location of protocol dissectors, protocol taps, and dissector code.
The GTK directory is used to store the GUI source used in Ethereal. You will find the main application as well as the toolbar and menu source in this directory.
Most of the utility functions for Ethereal are located in the epan directory. These functions include conversion functions as well as tvb and column functions.
The doc directory of the distribution is where you will locate most of the documentation that is shipped with the Ethereal source. This is a great resource to anyone wanting to develop in Ethereal.

Developing a Dissector

Before you start any Ethereal development, make sure you can build the Ethereal executable.
The first step in developing a dissector is to utilize the template provided in the README.developer document.
It is important to consider the GPL and other factors when modifying the header comments from the template. Note that this is where you need to add your personal information so you can receive credit for your work.
Global Ethereal functions are provided to ease the development of dissectors.
Registering your protocol dissector is a necessary process so that Ethereal knows when to pass packet data on to your dissector.
The hf array provides the mechanism to incorporate display and color filters.
Using tvb_get_xxx functions to access data for the frame. The data passed to your dissector does not include the data that has already been decoded by other dissectors.
Using the proto_tree functions allow you to print to the decode pane of the Ethereal GUI.
One of the most important steps a dissector should do is to pass any remaining packet data back to Ethereal. This way future dissectors can be written to dissect the remaining packet data.

Advanced Topics

Creating sub-trees allows you to display data in a more informative way in the decode pane of the GUI. Users needing more detailed information can expand the item to view the details.
Ethereal provides a mechanism to display bitfields in a graphical view. This allows the user to see from the bit display what the actual fields represent.
Many dissectors must be able to handle unicode strings. Unicode strings present a challenge to normal string processing because of their 2 byte width.
There are situations that require you to have the ability to track request and reply packet pairs. Ethereal provides the conversation list functions to keep specific information of a source packet so that it can be matched to a reply packet.
Packet retransmissions are a normal occurrence on most networks. It is important that Ethereal protocol dissectors can handle this type of condition. The use of conversation lists can help in this process.
Users should have the ability to configure different components in Ethereal. This includes the ability to turn on or off a feature within your protocol dissector. The preference files give you a place to store values so your dissector can retrieve them the next time Ethereal is active.
During the processing of data within a packet, you may need to know certain information from another dissector. Ethereal provides a mechanism to pass data between dissectors with the pinfo->private_data pointer.
Fragmentation occurs when the payload of a packet exceeds the actual size of the packet. The protocol will break the payload into pieces and then send each one within a fragment. The destination device will then collect all of the fragments and reassemble the original payload. Dissectors need to have the ability to process these packet fragments. Ethereal utilizes several de-fragment functions to track and reassemble fragmented data.
There are many times within the packet data that the number displayed is a user-friendly string to define the value. Most gerror codes are returned as numerical values but the number itself means little to the end user. Value strings give you the ability to convert numerical values to a meaningful message.
Ethereal’s GUI utilizes the GTK item factory for creating and manipulating its menu items. Adding a new menu item is a quick process by adding new items to the item factory.
If you plan to develop or modify any of the Ethereal GUI you will need to become familiar with GTK programming and its rich set of functions. The GTK website provides documentation and examples on proper ways of writing to the GTK library: www.gtk.org.
Ethereal provides a mechanism to receive real-time data. Tools can utilize the tap system to gather information from a live capture or from an existing packet trace.
Packet dissectors do not have to be compiled into the Ethereal source. The plugin interface provides a mechanism to convert your dissector from the packet-xxx type source to a plugin. Plugins can be compiled quicker and can be added and removed prior to launching the Ethereal executable.

Frequently Asked Questions

1.	How does Ethereal know when a dissector should be called?
2.	Where do you locate the design document for developing Ethereal?
3.	How do you pass information from one dissector to another?
4.	How do I know what functions are provided by Ethereal?
5.	Can I build Ethereal with Microsoft Visual C++?
6.	Where can I find more information on programming the GUI?

Answers

1.	The dissector_add function defines the condition in which the dissector should be called.
2.	There really isn’t a design document, but the README.developer document and the other documents contained in the doc directory contain useful information.
3.	By using the pinfo->private_data to pass a pointer to the other dissectors data.
4.	We have tried to list many of the common ones within this chapter, but for a complete listing you should look at the header files of the source for all exports. Exports are the mechanism that allows you to define the public functions that will be available to the rest of the application. Functions that are not exported are limited in visibility to the module in which they are defined. Although they may be limited in their visibility, it is important that you do not create a function within your dissector that might conflict with a public function that has been exported. This is one of the reasons why you should declare your private functions as static unless you plan to export the function for use with other Ethereal modules.
5.	Yes, you just need to make sure you have all of the required libraries and tools. It is important to realize that building under Microsoft Visual C++ does not include using the visual studio environment. Building Ethereal utilizes the command line interface and you build Ethereal.exe with nmake.exe. Ethereal does not include any visual studio workspace or configuration files to be used with the visual studio GUI. To build Ethereal under Microsoft Visual C++ you open a CMD window and then navigate to the main source directory of Ethereal. Finally you execute nmake with the syntax – nmake –f makefile.nmake.
6.	The GTK website has development tutorials and examples at www.gtk.org

Appendix: Supported Protocols

This section lists the 400+ protocols, by description, that are supported by Ethereal protocol decoders. The display fields, field values, and elongated descriptions of each protocol can be found on the accompanying CD-ROM in the /filters folder of Chapter 5.

Ethereal 0.10.0a provides 483 protocol keywords. This list shows the protocol names and descriptions.

aal1 ATM AAL1

aal3_4 ATM AAL3/4

aarp AppleTalk Address Resolution Protocol

acap Application Configuration Access Protocol

acn ACN

afp AppleTalk Filing Protocol

afs Andrew File System (AFS)

ah Authentication Header

aim AOL Instant Messenger

ajp13 Apache JServ Protocol v1.3

alcap AAL type 2 signaling protocol - Capability set 1 (Q.2630.1)

ans Intel ANS probe

ansi_637_tele ANSI IS-637-A (SMS) Teleservice Layer

ansi_637_trans ANSI IS-637-A (SMS) Transport Layer

ansi_683 ANSI IS-683-A (OTA (Mobile))

ansi_a_bsmap ANSI A-I/F BSMAP

ansi_a_dtap ANSI A-I/F DTAP

ansi_map ANSI Mobile Application Part

aodv Ad hoc On-demand Distance Vector Routing Protocol

arcnet ARCNET

arp Address Resolution Protocol

artnet Art-Net

asap Aggregate Server Access Protocol

ascend Lucent/Ascend debug output

asf Alert Standard Forum

asn1 ASN.1 decoding

asp AppleTalk Session Protocol

atm ATM

atp AppleTalk Transaction Protocol packet

atsvc Microsoft Task Scheduler Service

auto_rp Cisco Auto-RP

bacapp Building Automation and Control Network APDU

bacnet Building Automation and Control Network NPDU

bacp PPP Bandwidth Allocation Control Protocol

bap PPP Bandwidth Allocation Protocol

beep Blocks Extensible Exchange Protocol

bfdcontrol Bi-directional Fault Detection Control Message

bgp Border Gateway Protocol

bicc Bearer Independent Call Control

bofl Wellfleet Breath of Life

bootp Bootstrap Protocol

bootparams Boot Parameters

bossvr DCE/RPC BOS Server

brdwlk Boardwalk

browser Microsoft Windows Browser Protocol

bssap BSSAP/BSAP

bssgp BSS GPRS Protocol

budb DCE/RPC BUDB

butc DCE/RPC BUTC

bvlc BACnet Virtual Link Control

cbcp PPP Callback Control Protocol

ccp PPP Compression Control Protocol

CCSDS CCSDS

cdp Cisco Discovery Protocol

cdpcp PPP CDP Control Protocol

cds_clerkserver CDS Clerk Server Calls

cds_solicit DCE/RPC CDS Solicitation

cflow Cisco NetFlow

cgmp Cisco Group Management Protocol

chap PPP Challenge Handshake Authentication Protocol

chdlc Cisco HDLC

cldap Connectionless Lightweight Directory Access Protocol

clearcase Clearcase NFS

clnp ISO 8473 CLNP ConnectionLess Network Protocol

cltp ISO 8602 CLTP ConnectionLess Transport Protocol

comp_data PPP Compressed Datagram

conv DCE/RPC Conversation Manager

cops Common Open Policy Service

cosine CoSine IPNOS L2 debug output

cotp ISO 8073 COTP Connection-Oriented Transport Protocol

cpfi Cross Point Frame Injector

cpha Check Point High Availability Protocol

cprpc_server DNS Control Program Server

cups Common Unix Printing System (CUPS) Browsing Protocol

data Data

dccp Distributed Checksum Clearinghouse Protocol

dce_dfs DCE DFS Calls

dce_update DCE/RPC UpServer

dcerpc DCE RPC

ddp Datagram Delivery Protocol

ddtp Dynamic DNS Tools Protocol

dec_stp DEC Spanning Tree Protocol

dfs Microsoft Distributed File System

dhcpv6 DHCPv6

diameter Diameter Protocol

distcc Distcc Distributed Compiler

dlsw Data Link SWitching

dns Domain Name Service

dnsserver Windows 2000 DNS

docsis DOCSIS 1.1

docsis_bpkmattr DOCSIS Baseline Privacy Key Management Attributes

docsis_bpkmreq DOCSIS Baseline Privacy Key Management Request

docsis_bpkmrsp DOCSIS Baseline Privacy Key Management Response

docsis_dsaack DOCSIS Dynamic Service Addition Acknowledge

docsis_dsareq DOCSIS Dynamic Service Addition Request

docsis_dsarsp DOCSIS Dynamic Service Addition Response

docsis_dscack DOCSIS Dynamic Service Change Acknowledgement

docsis_dscreq DOCSIS Dynamic Service Change Request

docsis_dscrsp DOCSIS Dynamic Service Change Response

docsis_dsdreq DOCSIS Dynamic Service Delete Request

docsis_dsdrsp DOCSIS Dynamic Service Delete Response

docsis_map DOCSIS Upstream Bandwidth Allocation

docsis_mgmt DOCSIS Mac Management

docsis_regack DOCSIS Registration Acknowledge

docsis_regreq DOCSIS Registration Requests

docsis_regrsp DOCSIS Registration Responses

docsis_rngreq DOCSIS MAP Messages

docsis_rngrsp DOCSIS Ranging Response

docsis_tlv DOCSIS Appendix C TLV’s

docsis_uccreq DOCSIS Upstream Channel Change Request

docsis_uccrsp DOCSIS Upstream Channel Change Response

docsis_ucd DOCSIS Upstream Channel Descriptor

docsis_vsif DOCSIS Vendor Specific Endodings

drsuapi Microsoft Directory Replication Service

dsi Data Stream Interface

dtsprovider DCE Distributed Time Service Provider

dtsstime_req DCE Distributed Time Service Local Server

dvmrp Distance Vector Multicast Routing Protocol

eap Extensible Authentication Protocol

eapol 802.1x Authentication

echo Echo

edonkey eDonkey Protocol

eigrp Enhanced Interior Gateway Routing Protocol

els FC Extended Link Svc

enc OpenBSD Encapsulating Device

enip EtherNet/IP (Industrial Protocol)

enttec ENTTEC

epm DCE/RPC Endpoint Mapper

epm4 DCE/RPC Endpoint Mapper4

esis ISO 9542 ESIS Routing Information Exchange Protocol

esp Encapsulating Security Payload

eth Ethernet

etherip Ethernet over IP

fc Fiber Channel

FCdNS Fiber Channel Name Server

fcct Fiber Channel Common Transport

fcip FCIP

fcp Fibre Channel Protocol for SCSI

fcs FC Fabric Configuration Server

fcsp Fiber Channel Security Protocol

fddi Fiber Distributed Data Interface

fix Financial Information eXchange Protocol

fldb DCE/RPC FLDB

fr Frame Relay

frame Frame

ftp File Transfer Protocol (FTP)

ftp-data FTP Data

ftserver FTServer Operations

fw1 Checkpoint FW-1

FZS Fibre Channel Fabric Zone Server

giop General Inter-ORB Protocol

giop-coseventcomm Coseventcomm Dissector Using GIOP API

giop-cosnaming Cosnaming Dissector Using GIOP API

gmrp GARP Multicast Registration Protocol

gnutella Gnutella Protocol

gprs_ns GPRS Network service

gre Generic Routing Encapsulation

gryphon DG Gryphon Protocol

gsm_a_bssmap GSM A-I/F BSSMAP

gsm_a_dtap GSM A-I/F DTAP

gsm_a_rp GSM A-I/F RP

gsm_map GSM Mobile Application Part

gsm_sms GSM SMS TPDU (GSM 03.40)

gss-api Generic Security Service Application Program Interface

gtp GPRS Tunneling Protocol

gvrp GARP VLAN Registration Protocol

h1 Sinec H1 Protocol

h225 H225

h245 H245

h261 ITU-T Recommendation H.261

h263 ITU-T Recommendation H.263 RTP Payload header (RFC2190)

h4501 H4501

hclnfsd Hummingbird NFS Daemon

hpext HP Extended Local-Link Control

hsrp Cisco Hot Standby Router Protocol

http Hypertext Transfer Protocol

hyperscsi HyperSCSI

iapp Inter-Access-Point Protocol

ib Interbase

icap Internet Content Adaptation Protocol

icl_rpc DCE/RPC ICL RPC

icmp Internet Control Message Protocol

icmpv6 Internet Control Message Protocol v6

icp Internet Cache Protocol

icq ICQ Protocol

igap Internet Group Membership Authentication Protocol

igmp Internet Group Management Protocol

igrp Cisco Interior Gateway Routing Protocol

ilmi ILMI

imap Internet Message Access Protocol

initshutdown Remote Shutdown

ip Internet Protocol

ipcomp IP Payload Compression

ipcp PPP IP Control Protocol

ipfc IP Over FC

ipmi Intelligent Platform Management Interface

ipp Internet Printing Protocol

ipv6 Internet Protocol Version 6

ipv6cp PPP IPv6 Control Protocol

ipx Internetwork Packet eXchange

ipxmsg IPX Message

ipxrip IPX Routing Information Protocol

ipxsap Service Advertisement Protocol

ipxwan IPX WAN

irc Internet Relay Chat

isakmp Internet Security Association and Key Management Protocol

iscsi iSCSI

isdn ISDN

isis ISO 10589 ISIS InTRA Domain Routing Information Exchange Protocol

isl Cisco ISL

isns iSNS

isup ISDN User Part

iua ISDN Q.921-User Adaptation Layer

jabber Jabber XML Messaging

kadm5 Kerberos Administration

kerberos Kerberos

klm Kernel Lock Manager

kpasswd MS Kpasswd

krb5rpc DCE/RPC Kerberos V

l2tp Layer 2 Tunneling Protocol

lacp Link Aggregation Control Protocol

lane ATM LAN Emulation

lanman Microsoft Windows Lanman Remote API Protocol

lapb Link Access Procedure Balanced (LAPB)

lapbether Link Access Procedure Balanced Ethernet (LAPBETHER)

lapd Link Access Procedure, Channel D (LAPD)

laplink Laplink

lcp PPP Link Control Protocol

ldap Lightweight Directory Access Protocol

ldp Label Distribution Protocol

llap LocalTalk Link Access Protocol

llc Logical-Link Control

lmi Local Management Interface

lmp Link Management Protocol (LMP)

lpd Line Printer Daemon Protocol

lsa Microsoft Local Security Architecture

lsa_ds Microsoft Local Security Architecture (Directory Services)

lwapp LWAPP Encapsulated Packet

lwapp-cntl LWAP Control Message

lwapp-l3 LWAPP Layer 3 Packet

lwres Light Weight DNS RESolver (BIND9)

m2pa MTP2 Peer Adaptation Layer

m2tp MTP 2 Transparent Proxy

m2ua MTP 2 User Adaptation Layer

m3ua MTP 3 User Adaptation Layer

mailslot SMB MailSlot Protocol

malformed Malformed Packet

mapi Microsoft Exchange MAPI

mbtcp Modbus/TCP

mdshdr MDS Header

megaco MEGACO

messenger Microsoft Messenger Service

mgcp Media Gateway Control Protocol

mgmt DCE/RPC Remote Management

mip Mobile IP

mipv6 Mobile IPv6

mmse MMS Message Encapsulation

mount Mount Service

mp PPP Multilink Protocol

mpeg1 RFC 2250 MPEG1

mpls MultiProtocol Label Switching Header

mplscp PPP MPLS Control Protocol

mrdisc Multicast Router DISCovery protocol

msdp Multicast Source Discovery Protocol

msnip MSNIP: Multicast Source Notification of Interest Protocol

msnms MSN Messenger Service

msproxy MS Proxy Protocol

mtp2 Message Transfer Part Level 2

mtp3 Message Transfer Part Level 3

mtp3mg Message Transfer Part Level 3 Management

mysql MySQL Protocol

nbdgm NetBIOS Datagram Service

nbipx NetBIOS over IPX

nbns NetBIOS Name Service

nbp Name Binding Protocol

nbss NetBIOS Session Service

ncp NetWare Core Protocol

ndmp Network Data Management Protocol

ndps Novell Distributed Print System

netbios NetBIOS

netlogon Microsoft Windows Logon Protocol

nfs Network File System

nfsacl NFSACL

nfsauth NFSAUTH

nisplus NIS+

nispluscb NIS+ Callback

nlm Network Lock Manager Protocol

nlsp NetWare Link Services Protocol

nmpi Name Management Protocol over IPX

nntp Network News Transfer Protocol

nspi NSPI

ntlmssp NTLM Secure Service Provider

ntp Network Time Protocol

null Null/Loopback

oamaal ATM OAM AAL

ospf Open Shortest Path First

oxid DCOM OXID Resolver

pap PPP Password Authentication Protocol

pcli Packet Cable Lawful Intercept

pcnfsd PC NFS

per Packed Encoding Rules (ASN.1 X.691)

pflog OpenBSD Packet Filter log file

pflog-old OpenBSD Packet Filter log file, pre 3.4

pgm Pragmatic General Multicast

pim Protocol Independent Multicast

pipe SMB Pipe Protocol

pop Post Office Protocol

portmap Portmap

ppp Point-to-Point Protocol

pppmux PPP Multiplexing

pppmuxcp PPPMux Control Protocol

pppoed PPP-over-Ethernet Discovery

pppoes PPP-over-Ethernet Session

pptp Point-to-Point Tunneling Protocol

prism Prism

q2931 Q.2931

q931 Q.931

q933 Q.933

qllc Qualified Logical Link Control

quake Quake Network Protocol

quake2 Quake II Network Protocol

quake3 Quake III Arena Network Protocol

quakeworld QuakeWorld Network Protocol

radius Radius Protocol

ranap Radio Access Network Application Part

raw Raw packet data

raw_sip Session Initiation Protocol (SIP as raw text)

rdm RDM

remact DCOM Remote Activation

rep_proc AFS (4.0) Replication Server call declarations

rip Routing Information Protocol

ripng RIPng

rlogin Rlogin Protocol

rmcp Remote Management Control Protocol

rmi Java RMI

rmp HP Remote Maintenance Protocol

roverride Remote Override interface

rpc Remote Procedure Call

rpc_browser RPC Browser

rpc_netlogon Microsoft Network Logon

rpl Remote Program Load

rpriv Privilege Server Operations

rquota Remote Quota

rs_acct DCE/RPC RS_ACCT

rs_attr Registry Server Attributes Manipulation Interface

rs_bind DCE/RPC RS_BIND

rs_misc DCE/RPC RS_MISC

rs_pgo DCE Name Service

rs_plcy RS Interface Properties

rs_prop_acct DCE/RPC RS_PROP_ACCT

rs_repadm Registry server administration operations.

rs_replist DCE/RPC Repserver Calls

rs_unix DCE/RPC RS_UNIX

rsec_login Remote sec_login preauth interface.

rsh Remote Shell

rstat RSTAT

rsvp Resource ReserVation Protocol (RSVP)

rsync RSYNC File Synchroniser

rtcfg RTCFG

rtcp Real-time Transport Control Protocol

rtmp Routing Table Maintenance Protocol

rtnet RTNET

rtp Real-Time Transport Protocol

rtpevent RFC 2833 RTP Event

rtsp Real Time Streaming Protocol

rwall Remote Wall Protocol

rx RX Protocol

sadmind SADMIND

samr Microsoft Security Account Manager

sap Session Announcement Protocol

sb3 Fiber Channel Single Byte Command

sccp Signaling Connection Control Part

sccpmg Signaling Connection Control Part Management

scsi SCSI

sctp Stream Control Transmission Protocol

sdlc Synchronous Data Link Control (SDLC)

sdp Session Description Protocol

sebek SEBEK - Kernel Data Capture

secidmap DCE Security ID Mapper

serialization Java Serialization

ses ISO 8327-1 OSI Session Protocol

sflow InMon sFlow

sgimount SGI Mount Service

short Short Frame

sip Session Initiation Protocol

skinny Skinny Client Control Protocol

slarp Cisco SLARP

slimp3 SliMP3 Communication Protocol

sll Linux cooked-mode capture

smb SMB (Server Message Block Protocol)

smpp Short Message Peer to Peer

smtp Simple Mail Transfer Protocol

smux SNMP Multiplex Protocol

sna Systems Network Architecture

sna_xid Systems Network Architecture XID

snaeth SNA-over-Ethernet

snmp Simple Network Management Protocol

socks Socks Protocol

sonmp Nortel SONMP

spnego Spnego

spnego-krb5 SPNEGO-KRB5

spoolss Microsoft Spool Subsystem

spray SPRAY

spx Sequenced Packet eXchange

srvloc Service Location Protocol

srvsvc Microsoft Server Service

sscop SSCOP

ssh SSH Protocol

ssl Secure Socket Layer

stat Network Status Monitor Protocol

statnotify Network Status Monitor CallBack Protocol

stp Spanning Tree Protocol

stun Simple Traversal of UDP Through NAT

sua SS7 SCCP-User Adaptation Layer

svcctl Microsoft Service Control

swils Fiber Channel SW_ILS

syslog Syslog message

t38 T38

tacacs TACACS

tacplus TACACS+

tapi Microsoft Telephony API Service

tcap Transaction Capabilities Application Part

tcp Transmission Control Protocol

tds Tabular Data Stream

telnet Telnet

teredo TEREDO Tunneling IPv6 over UDP through NATs

tftp Trivial File Transfer Protocol

time Time Protocol

tkn4int DCE/RPC TokenServer Calls

tns Transparent Network Substrate Protocol

tpcp Alteon - Transparent Proxy Cache Protocol

tpkt TPKT

tr Token-Ring

trmac Token-Ring Media Access Control

tsp Time Synchronization Protocol

tzsp Tazmen Sniffer Protocol

ubikdisk DCE/RPC FLDB UBIK TRANSFER

ubikvote DCE/RPC FLDB UBIKVOTE

ucp Universal Computer Protocol

udp User Datagram Protocol

udpencap UDP Encapsulation of IPsec Packets

unreassembled Un-reassembled Fragmented Packet

v120 Async data over ISDN (V.120)

vines_arp Banyan Vines ARP

vines_echo Banyan Vines Echo

vines_frp Banyan Vines Fragmentation Protocol

vines_icp Banyan Vines ICP

vines_ip Banyan Vines IP

vines_ipc Banyan Vines IPC

vines_llc Banyan Vines LLC

vines_rtp Banyan Vines RTP

vines_spp Banyan Vines SPP

vj PPP VJ Compression

vlan 802.1q Virtual LAN

vrrp Virtual Router Redundancy Protocol

vtp Virtual Trunking Protocol

wap-wsp Wireless Session Protocol

wap-wsp-wtp Wireless Transaction Protocol

wap-wtls Wireless Transport Layer Security

wbxml WAP Binary XML

wccp Web Cache Coordination Protocol

wcp Wellfleet Compression

whdlc Wellfleet HDLC

who Who

winreg Microsoft Registry

wkssvc Microsoft Workstation Service

wlan IEEE 802.11 wireless LAN

wlan_mgt IEEE 802.11 wireless LAN management frame

wlancap AVS WLAN Capture header

x.25 X.25

x.29 X.29

x11 X11

xdmcp X Display Manager Control Protocol

xot X.25 over TCP

xyplex Xyplex

yhoo Yahoo Messenger Protocol

ymsg Yahoo YMSG Messenger Protocol

ypbind Yellow Pages Bind

yppasswd Yellow Pages Password

ypserv Yellow Pages Service

ypxfr Yellow Pages Transfer

zebra Zebra Protocol

zip Zone Information Protocol

Оставьте свой комментарий !

Ваше имя:

Комментарий:

Оба поля являются обязательными

Автор	Комментарий к данной статье

Часть 8: Real World Packet Captures

Introduction

Scanning

TCP Connect Scan

SYN Scan

Xmas Scan

Null Scan

Remote Access Trojans

SubSeven Legend

NetBus

RST.b

Dissecting Worms

SQL Slammer Worm

Code Red Worm

Ramen Worm

Summary

Solutions Fast Track

Scanning

Remote Access Trojans

Dissecting Worms

Frequently Asked Questions

Часть 9: Разработка Ethereal

Prerequisites for Developing Ethereal

Skills

Tools/Libraries

Ethereal Design

aclocal-fallback and aclocal-missing

debian

doc

epan

gtk

help

image

packaging

plugins

tools

wiretap

Developing a Dissector

Step 1 – Copy the Template

Step 2 Define the Includes

Step 3 Create the Function to Register

Step 4 Instruct Ethereal

Step 5 Create the Dissector

Step 6 Pass Payloads

Running a Dissector

The Dissection Process

Advanced Topics

Dissector Considerations

Creating Sub-trees

Bitfields

Unicode Strings

Conversations

Packet Retransmissions

Passing Data Between Dissectors

Saving Preference Settings

Packet Fragmentation

Value Strings

The Ethereal GUI

The Item Factory

Using GTK

TAPS

Plug-ins

Summary

Solutions Fast Track

Prerequisites for Developing Ethereal

Ethereal Design

Developing a Dissector

Advanced Topics

Frequently Asked Questions

Appendix: Supported Protocols