Wireshark Developer's Guide24295 for Wireshark 0.99.7Ulf Lamping,
3. AcknowledgementsThe authors would like to thank the whole Wireshark team for their assistance. In particular, the au-thors would like to thank:• Ge
Part II. Wireshark Development(incomplete)Part I. Wireshark Build EnvironmentThe first part describes how to set up the tools, libraries and source ne
Chapter 6. How Wireshark Works6.1. IntroductionThis chapter will give you a short overview of how Wireshark works.87
6.2. OverviewThe following will give you a simplified overview of Wiresharks function blocks:Figure 6.1. Wireshark function blocks.The function blocks
Core Main "glue code" that holds the other blocks together. Sourcecode can be found in the root directory.Epan Ethereal Packet ANalyzer (XXX
6.3. Capturing packetsCapturing will take packets from a network adapter, and save them to a file on your harddisk.To hide all the lowlevel machine de
6.4. Capture FilesWireshark can read and write capture files in its natural file format, the libpcap format, which isused by many other network captur
6.5. Dissect packetsWhile Wireshark is loading packets from a file, each packet is dissected. Wireshark tries to detectthe packet type and gets as muc
How Wireshark Works93
Chapter 7. Introduction7.1. Source overviewWireshark consists of the following major parts:• Packet dissection - in the /epan/dissector and /plugin/*
7.2. Coding styleguidesThe coding styleguides for Wireshark can be found in the "Code style" section of the file doc/README.developer.Introd
4. About this documentThis book was developed by Ulf Lamping.It is written in DocBook/XML.You will find some specially marked parts in this book:This
7.3. The GLib libraryGlib is used as a basic platform abstraction library, it's not related to GUI things.To quote the Glib documentation: “GLib
Introduction97
Chapter 8. Packet capturingXXX - this chapter has to be reviewed and extended!8.1. How to add a new capture type to libpcapThe following is an excerpt
Packet capturing99
Chapter 9. Packet dissection9.1. How it worksEach dissector decodes its part of the protocol, and then hands off decoding to subsequent dissectorsfor
9.2. Adding a basic dissectorLet's step through adding a basic dissector. We'll start with the made up "foo" protocol. It consists
Next a dissector reference that we'll initialise later.Now we have the basics in place to interact with the main program, we had better fill in t
In order to compile this dissector and create a plugin a couple of support files are required, besidesthe dissector source in packet-foo.c:• Makefile.
FALSE we'll ignore for now.After this change, there should be a label in the detailed display for the protocol, and selecting thiswill highlight
}Now the dissection is starting to look more interesting. We have picked apart our first bit of the pro-tocol. One byte of data at the start of the pa
5. Where to get the latest copy of thisdocument?The latest copy of this documentation can always be found at: http://www.wireshark.org/docs/ inPDF (A4
proto_tree_add_item(foo_tree, hf_foo_pdu_type, tvb, offset, 1, FALSE); offset += 1;proto_tree_add_item(foo_tree, hf_foo_flags, tvb, offset, 1, FALSE);
},{ &hf_foo_endflag,{ "FOO PDU End Flags", "foo.flags.end",FT_BOOLEAN, 8,NULL, FOO_END_FLAG,NULL, HFILL }},{ &hf_foo_prior
arly we append this data to the base of our dissecting tree.Packet dissection108
9.3. How to handle transformed dataSome protocols do clever things with data. They might possibly encrypt the data, or compress data,or part of it. If
9.4. How to reassemble split packetsSome protocols have times when they have to split a large packet across multiple other packets. Inthis case the di
• The provided packet info.• The sequence number of the fragment stream. There may be several streams of fragments inflight, and this is used to key t
{fragment_table_init(&msg_fragment_table);reassembled_table_init(&msg_reassembled_table);}First a couple of hash tables are declared, and thes
&ett_msg_fragment,&ett_msg_fragments...These hf variables are used internally within the reassembly routines to make useful links, and toadd d
whenever a message has been reassembled.The parameters tvb, pinfo and tree are just handed over to tcp_dissect_pdus(). The 4thparameter is a flag to i
9.5. How to tap protocolsAdding a Tap interface to a protocol allows it to do some useful things. In particular you can pro-duce protocol statistics f
6. Providing feedback about this documentShould you have any feedback about this document, please send it to the authors through wireshark-dev[AT]wire
9.6. How to produce protocol statsGiven that you have a tap interface for the protocol, you can use this to produce some interestingstatistics (well p
In this case we create a new tree node, to handle the total packets, and as a child of that we create apivot table to handle the stats about different
9.7. How to use conversationsSome info about how to use conversations in a dissector can be found in the file doc/README.developer chapter 2.2.Packet
Packet dissection119
Chapter 10. User Interface10.1. IntroductionWireshark can be "logically" separated into the backend (dissecting of protocols, file load/save
10.2. The GTK libraryWireshark is based on the GTK toolkit, see: http://www.gtk.org for details. GTK is designed to hidethe details of the underlying
Disadvantages:• not available on all platforms (compared to version 1.x)• maybe a bit less stable compared to version 1.x (but should be production st
mentation at: http://gtk.org/api/.Several mailing lists are available about GTK development, see http://gtk.org/mailinglists.html, thegtk-app-devel-li
10.3. GUI Reference documentsAlthough the GUI development of Wireshark is platform independent, the Wireshark developmentteam tries to follow the GNOM
10.4. Adding/Extending DialogsThis is usually the main area for contributing new user interface features.XXX: add the various functions from gtk/dlg_u
Prefacexiv
10.5. Widget namingIt seems to be common sense to name the widgets with some descriptive trailing characters, like:• xy_lb = gtk_label_new();• xy_cb =
10.6. Common GTK programming pitfallsThere are some common pitfalls in GTK programming.10.6.1. Usage of gtk_widget_show() /gtk_widget_show_all()When a
User Interface128
Appendix A. This Document's License(GPL)As with the original licence and documentation distributed with Wireshark, this document iscovered by the
either verbatim or with modifications and/or translated into anotherlanguage. (Hereinafter, translation is included without limitation inthe term &quo
The source code for a work means the preferred form of the work formaking modifications to it. For an executable work, complete sourcecode means all t
Each version is given a distinguishing version number. If the Programspecifies a version number of this License which applies to it and "anylater
Yoyodyne, Inc., hereby disclaims all copyright interest in the program`Gnomovision' (which makes passes at compilers) written by James Hacker.<
Part I. Wireshark BuildEnvironmentPart I. Wireshark Build EnvironmentThe first part describes how to set up the tools, libraries and source needed to
Chapter 1. Introduction1.1. IntroductionThis chapter will provide you with information about Wireshark development in general.2
1.2. What is Wireshark?Well, if you want to start Wireshark development, you might already know what Wireshark is do-ing. If not, please have a look a
1.3. Platforms Wireshark runs onWireshark currently runs on most UNIX platforms and various Windows platforms. It requiresGTK+, GLib, libpcap and some
• Suse Linux1.3.3. Microsoft WindowsThanks to the Win32 API, development on all Windows platforms will be done in a very similarway. All Windows platf
Wireshark Developer's Guide:24295 for Wireshark 0.99.7by Ulf LampingCopyright © 2004-2007 Ulf LampingPermission is granted to copy, distribute an
1.4. Development and maintenance ofWiresharkWireshark was initially developed by Gerald Combs. Ongoing development and maintenance ofWireshark is hand
with Wireshark. So if Wireshark is updated (which is done often), you can get a new Wiresharkversion from the website and your changes will already be
1.5. Releases and distributionsThe officially released files can be found at: http://www.wireshark.org/download/. A new Wiresharkversion is released a
1.6. Automated Builds (Buildbot)The Wireshark Buildbot automatically rebuilds Wireshark on every change of the source code re-pository and indicates p
1.7. Reporting problems and getting helpIf you have problems, or need help with Wireshark, there are several places that may be of interestto you (wel
wireshark-announce This mailing list will inform you about new program releases, whichusually appear about every 4-8 weeks.wireshark-users This list i
and after it, if there are some), so others may find the build step where things go wrong. Pleasedon't give something like: "I get a warning
Introduction13
Chapter 2. Quick Setup2.1. UNIX: InstallationAll the tools required are usually installed on a UNIX developer machine.If a tool is not already install
2.2. Win32: Step-by-Step GuideA quick setup guide for Win32 with recommended configuration.Warning!Unless you know exactly what you are doing, you sho
• Utils/patch• Web/wgetAfter clicking the Next button several times, the setup will then download and install the selectedpackages (this may take a wh
c.i. URL of repository: " ht-tp://anonsvn.wireshark.org/wireshark/trunk/"ii. Checkout directory: "C:\wireshark"d. TortoiseSVN migh
Warning!You will need the Wireshark sources and some tools (nmake, bash) installed, beforethis verification is able to work.Enter at the command line
Now it's time to build Wireshark ...1. If you've closed cmd.exe in the meantime, prepare cmd.exe again2. nmake -f Makefile.nmake all to buil
Quick Setup20
Chapter 3. Work with the Wiresharksources3.1. IntroductionThis chapter will explain how to work with the Wireshark source code. It will show you how t
3.2. The Wireshark Subversion repositorySubversion is used to keep track of the changes made to the Wireshark source code. The Wiresharksource code is
http://anonsvn.wireshark.org/viewvc/viewvc.cgi/.Of special interest might be the subdirectories:• trunk - the very latest source files• releases - the
3.3. Obtain the Wireshark sourcesThere are several ways to obtain the sources from Wireshark's Subversion server.Anonymous Subversion access is r
source code change is committed. These snapshots can be found at: http:/ / www.wireshark.org/download/automated/src/.If anonymous Subversion access is
Table of ContentsPreface ... viii1. Foreword
3.4. Update the Wireshark sourcesAfter you've obtained the Wireshark sources for the first time, you might want to keep them in syncwith the sour
3.5. Build WiresharkThe sources contain several documentation files, it's a good idea to look at these files first.So after obtaining the sources
other files in the root directory.Work with the Wireshark sources28
3.6. Run generated WiresharkTip!An already installed Wireshark may interfere with your newly generated version invarious ways. If you have any problem
3.7. Debug your generated WiresharkSee the above info on running Wireshark.XXX - add more info here.3.7.1. Win32 nativeXXX - add more info here.Work w
3.8. Make changes to the Wireshark sourcesAs the Wireshark developers are working on many different platforms, a lot of editors are used todevelop Wir
3.9. Contribute your changesIf you have finished changing the Wireshark sources to suit your needs, you might want to contrib-ute your changes back to
tool to find the right place(s) to change in the existing sources.3.9.2. Generate a patchThere are several ways to generate patches. The preferred way
temporary files which might be otherwise included in the diff. After doing the diff, you should editthe foo.diff file and remove unnecessary things, l
The core maintainers have done a lot of work fixing bugs and making code compile on the variousplatforms Wireshark supports.To ensure Wireshark's
3.3.3. Buildbot Snapshots ...243.3.4. Released sources ...
• You don't get any reponse to your patch (even after a few days or so). Possible reason: yourpatch might simply get lost, as all core maintainer
3.10. Apply a patch from someone elseSometimes you need to apply a patch to your private source tree. Maybe because you want to try apatch from someon
"missing" subdirectory.For "cvs diff -c" or "cvs diff -u" diffs, there's a Python script "cvsdiff-fix.py"
3.11. Add a new file to the SubversionrepositoryThe "usual" way to commit new files is described in Section 3.9, “Contribute your changes”.H
3.12. Binary packagingDelivering binary packages, makes it much easier for the end-users to install Wireshark on their tar-get system. This section wi
Tip!Please be patient while the compression is done, it will take some time (a fewminutes!) even on fast machines.If everything went well, you will no
Work with the Wireshark sources42
Chapter 4. Tool Reference4.1. IntroductionThis chapter will provide you with information about the various tools needed for Wireshark devel-opment.Non
4.2. Win32: CygwinCygwin provides a lot of UNIX based tools on the Win32 platform. It uses a UNIX emulation layerwhich might be a bit slower compared
4.3. GNU compiler toolchain (UNIX or Win32Cygwin)4.3.1. gcc (GNU compiler collection)Win32: Warn!Using Cygwin gcc to compile Wireshark is "EXPERT
4.11. Subversion (SVN) client (optional) ...614.11.1. UNIX or Win32 Cygwin: svn ...
debuggers), so you have to install GDB first. It is available for many UNIX-like platforms and asthe ddd package from the Cygwin setup.If GNU DDD isn&
4.4. Microsoft compiler toolchain (Win32native)To compile Wireshark on Windows using the Microsoft C/C++ compiler, you'll need:1. C compiler (cl.
Visual Stu-dio 6.0Yes Commercial1No2MSVC6 MicrosoftVisual Stu-dio\VC98\Bin\vcvars32.bat-Visual Stu-dio .NET(2002)Yes Commercial1MSVC2002 MicrosoftVisu
.NET Frame-work SDKversion 1.0aNo Free Down-(104MBload)Free Down-load(420MB)DOTNET10 Mi-crosoft.NET\Frame-workS-DK\Bin\corvars.batcan't buildsetu
using newer versions of Visual Studio. This FUD essentially stems from two misconceptions:1. Unfortunately, it is believed by many that the Microsoft
Visual Studio 2008 Ex-press Edition(Code Name "Orcas")After correct installation of the toolchain, typing at the command line prompt (cmd.ex
on the users machine.MSVC6 was using msvcrt.dll, which is already available on all recent windows systems - no need toredistribute anything. Starting
smallest package). As MSVC2005EE and DOTNET20 doesn't provide the folder "Mi-crosoft.VC80.CRT" they use method 3. You'll have to d
Both files are part of the Platform SDK (standalone PSDK or MSVC since 2002). If you still useMSVC 6, you can get them from the "HTML Help Worksh
4.5. bashThe bash shell is needed to run several shell scripts.4.5.1. UNIX or Win32 Cygwin: GNU bashThe bash shell is available for most of the UNIX-l
6.4. Capture Files ...916.5. Dissect packets ...
4.6. pythonPython is an interpreter based programming language. The homepage of the python project is: http://python.org/. Python is used to generate
4.7. perlPerl is an interpreter based programming language. The homepage of the perl project is: http:/ /www.perl.com. Perl is used to convert various
4.8. sedSed it the streaming editor. It makes it easy for example to replace specially marked texts inside asource code file. The Wireshark build proc
4.9. yacc (bison)Bison is a free implementation of yacc.4.9.1. UNIX or Win32 Cygwin: bisonBison is available for most of the UNIX-like platforms and a
4.10. flexFlex is a free implementation of lexx.4.10.1. UNIX or Win32 Cygwin: flexFlex is available for most of the UNIX-like platforms and as the fle
4.11. Subversion (SVN) client (optional)The Wireshark project uses its own Subversion (or short SVN) server to keep track of all thechanges done to th
4.12. Subversion (SVN) GUI client (optional)Along with the traditional command-line client, several GUI clients are available for a number ofplatforms
4.13. diff (optional)Diff is used to get a file of all differences between two source files/trees (sometimes called a patch).The diff tool isn't
4.14. patch (optional)The patch utility is used to merge a diff file into your own source tree. This tool is only needed, ifyou want to apply a patch
4.15. Win32: GNU wget (optional)GNU wget is used to download files from the internet using the command line.GNU wget is available for most of the UNIX
Preface1. ForewordThis book tries to give you a guide to start your own experiments into the wonderful world of Wire-shark development.Developers who
4.16. Win32: GNU unzip (optional)GNU unzip is used to, well, unzip the zip files downloaded using the wget tool.GNU unzip is available for most of the
4.17. Win32: NSIS (optional)The NSIS (Nullsoft Scriptable Install System) is used to generate a wireshark-setup-<version>.exefrom all the files
Tool Reference68
Chapter 5. Library Reference5.1. IntroductionSeveral libraries are needed to build / run Wireshark. Most of the libraries are split into three pack-ag
5.2. Binary library formatsBinary libraries are available in different formats, depending on the C compiler used to build it andof course the platform
5.3. Win32: Automated library download5.3.1. Initial downloadYou can download/install all required libraries by using the setup target of the Makefile
toplevel, which are the files downloaded the last time(s).Also note that as wget will download only the missing (updated) files, existing zip files in
5.4. GTK+ / GLib / GDK / Pango / ATK / GNUgettext / GNU libiconvThe Glib library is used as a basic platform abstraction library, it's not relate
5.5. Net-SNMP (optional)"Various tools relating to the Simple Network Management Protocol"5.5.1. UnixIf this library isn't already inst
5.6. GNU adns (optional)"Advanced, easy to use, asynchronous-capable DNS client library and utilities."5.6.1. UnixIf this library isn't
2. Who should read this document?The intended audience of this book is anyone going into the development of Wireshark.This book is not intended to exp
5.7. PCRE (optional)"Perl compatible regular expressions"5.7.1. UnixIf this library isn't already installed or available as a package f
5.8. zlib (optional)"zlib is designed to be a free, general-purpose, legally unencumbered -- that is, not covered by anypatents -- lossless data-
5.9. libpcap/WinPcap (optional)"packet capture library"5.9.1. Unix: libpcapIf this library isn't already installed or available as a pa
5.10. GnuTLS (optional)The "GNU Transport Layer Security Library" is used to dissect SSL and TLS protocols (aka: HT-TPS).5.10.1. UnixIf this
5.11. Gcrypt (optional)The "Gcrypt Library" is Low-level encryption library and provides support for many ciphers, suchas DES, 3DES, AES, Bl
5.12. Kerberos (optional)The Kerberos library is used to dissect Kerberos, sealed DCERPC and secureLDAP protocols.5.12.1. UnixIf this library isn&apos
5.13. LUA (optional)The LUA library is used to add scripting support to Wireshark.5.13.1. UnixIf this library isn't already installed or availabl
5.14. PortAudio (optional)The PortAudio library enables audio output for RTP streams.5.14.1. UnixIf this library isn't already installed or avail
5.15. Win32: GTK WIMP (optional) for GTK 2.xonly"GTK-Wimp ("Windows impersonator") is a GTK theme that blends well into the Windows des
Library Reference85
Commentaires sur ces manuels