Wireshark Developer's Guide 24295 for Wireshark 0.99.
Wireshark Developer's Guide: 24295 for Wireshark 0.99.7 by Ulf Lamping Copyright © 2004-2007 Ulf Lamping Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 or any later version published by the Free Software Foundation. All logos and trademarks in this document are property of their respective owner.
Table of Contents Preface ............................................................................................................. viii 1. Foreword .............................................................................................. viii 2. Who should read this document? ................................................................. ix 3. Acknowledgements .................................................................................... x 4. About this document ..........................
Wireshark Developer's Guide 3.3.3. Buildbot Snapshots ..............................................................24 3.3.4. Released sources .................................................................25 3.4. Update the Wireshark sources ...........................................................26 3.4.1. ... with Anonymous Subversion access .....................................26 3.4.2. ... from zip files ...................................................................26 3.5. Build Wireshark ...
Wireshark Developer's Guide 4.11. Subversion (SVN) client (optional) ..................................................61 4.11.1. UNIX or Win32 Cygwin: svn ...............................................61 4.11.2. Win32 native: svn ..............................................................61 4.12. Subversion (SVN) GUI client (optional) ...........................................62 4.12.1. UNIX or Win32 Cygwin: rapidSVN, subcommander ................62 4.12.2. Win32 native: TortoiseSVN .................
Wireshark Developer's Guide 6.4. Capture Files .................................................................................91 6.5. Dissect packets ..............................................................................92 7. Introduction .............................................................................................94 7.1. Source overview ............................................................................94 7.2. Coding styleguides ..........................................
Preface 1. Foreword This book tries to give you a guide to start your own experiments into the wonderful world of Wireshark development. Developers who are new to Wireshark often have a hard time getting their development environment up and running. This is especially true for Win32 developers, as a lot of the tools and methods used when building Wireshark are much more common in the UNIX world than on Win32.
Preface 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 explain the usage of Wireshark in general. Please refer the Wireshark User's Guide about Wireshark usage. By reading this book, you will learn how to develop Wireshark. It will hopefully guide you around some common problems that frequently appear for new (and sometimes even advanced) developers of Wireshark.
Preface 3. Acknowledgements The authors would like to thank the whole Wireshark team for their assistance. In particular, the authors would like to thank: • Gerald Combs, for initiating the Wireshark project. • Guy Harris, for many helpful hints and his effort in maintaining the various contributions on the mailing lists.
Preface 4. About this document This book was developed by Ulf Lamping. It is written in DocBook/XML. You will find some specially marked parts in this book: This is a warning! You should pay attention to a warning, as otherwise data loss might occur. This is a note! A note will point you to common mistakes and things that might not be obvious. This is a tip! Tips will be helpful for your everyday work developing Wireshark.
Preface 5. Where to get the latest copy of this document? The latest copy of this documentation can always be found at: http://www.wireshark.org/docs/ in PDF (A4 and US letter), HTML (single and chunked) and CHM format.
Preface 6. Providing feedback about this document Should you have any feedback about this document, please send it to the authors through wiresharkdev[AT]wireshark.org.
Preface xiv
Part I. Wireshark Build Environment Part I. Wireshark Build Environment The first part describes how to set up the tools, libraries and source needed to generate Wireshark, and how to do some typical development tasks. Part II. Wireshark Development The second part describes how the Wireshark sources are structured and how to change the sources (e.g. adding a new dissector).
Chapter 1. Introduction 1.1. Introduction This chapter will provide you with information about Wireshark development in general.
Introduction 1.2. What is Wireshark? Well, if you want to start Wireshark development, you might already know what Wireshark is doing. If not, please have a look at the Wireshark User's Guide, which will provide a lot of general information about it.
Introduction 1.3. Platforms Wireshark runs on Wireshark currently runs on most UNIX platforms and various Windows platforms. It requires GTK+, GLib, libpcap and some other libraries in order to run. As Wireshark is developed in a platform independent way and uses libraries (such as the GTK+ GUI library) which are available for a lot of different platforms, it's thus available on a wide variety of platforms.
Introduction • Suse Linux 1.3.3. Microsoft Windows Thanks to the Win32 API, development on all Windows platforms will be done in a very similar way. All Windows platforms referred to as Win32, Win or Windows may be used with the same meaning. Older Windows versions are no longer supported by Wireshark. As Windows CE differs a lot compared to the other Windows platforms mentioned, Wireshark will not run on Windows CE and there are no plans to support it.
Introduction 1.4. Development and maintenance of Wireshark Wireshark was initially developed by Gerald Combs. Ongoing development and maintenance of Wireshark is handled by the Wireshark team, a loose group of individuals who fix bugs and provide new functionality. There have also been a large number of people who have contributed protocol dissectors to Wireshark, and it is expected that this will continue.
Introduction with Wireshark. So if Wireshark is updated (which is done often), you can get a new Wireshark version from the website and your changes will already be included without any effort for you. The Wireshark source code and binary kits for some platforms are all available on the download page of the Wireshark website: http://www.wireshark.org/download/.
Introduction 1.5. Releases and distributions The officially released files can be found at: http://www.wireshark.org/download/. A new Wireshark version is released after significant changes compared to the last release are completed or a serious security issue is encountered. The typical release schedule is about every 4-8 weeks (although this may vary). There are two kinds of distributions: binary and source; both have their advantages and disadvantages. 1.5.1.
Introduction 1.6. Automated Builds (Buildbot) The Wireshark Buildbot automatically rebuilds Wireshark on every change of the source code repository and indicates problematic changes. This frees the developers from repeating (and annoying) work, so time can be spent on more interesting tasks. 1.6.1. Advantages • Recognizing (cross platform) build problems - early. Compilation problems can be narrowed down to a few commits, making a fix much easier. • "Health status" overview of the sources.
Introduction 1.7. Reporting problems and getting help If you have problems, or need help with Wireshark, there are several places that may be of interest to you (well, beside this guide of course). 1.7.1. Website You will find lot's of useful information on the Wireshark homepage at http://www.wireshark.org. 1.7.2. Wiki The Wireshark Wiki at http://wiki.wireshark.org provides a wide range of information related to Wireshark and packet capturing in general.
Introduction wireshark-announce This mailing list will inform you about new program releases, which usually appear about every 4-8 weeks. wireshark-users This list is for users of Wireshark. People post questions about building and using Wireshark, others (hopefully) provide answers. wireshark-dev This list is for Wireshark developers. People post questions about the development of Wireshark, others (hopefully) provide answers. If you want to start developing a protocol dissector, join this list.
Introduction and after it, if there are some), so others may find the build step where things go wrong. Please don't give something like: "I get a warning when compiling x" as this won't give any direction to look at. Don't send large files! Do not send large files (>100KB) to the mailing lists, just place a note that further data is available on request. Large files will only annoy a lot of people on the list who are not interested in your specific problem.
Introduction 13
Chapter 2. Quick Setup 2.1. UNIX: Installation All the tools required are usually installed on a UNIX developer machine. If a tool is not already installed on your system, you will typically use the installation package from your distribution (by your favourite package manager: aptitude, yum, synaptics, ...). If an install package is not available, or you have a reason not to use it (maybe because it's simply too old), you can install that tool from source code.
Quick Setup 2.2. Win32: Step-by-Step Guide A quick setup guide for Win32 with recommended configuration. Warning! Unless you know exactly what you are doing, you should strictly follow the recommendations! 2.2.1. Install Microsoft C compiler and Platform SDK You need to install: 1. C compiler: Download(474MB) and install "Visual C++ 2005 Express Edition" 2. Platform SDK : Download(420MB) and install Platform SDK Server 2003 R2 Install MSVC the usual way. Don't forget to install vcvars32.
Quick Setup • Utils/patch • Web/wget After clicking the Next button several times, the setup will then download and install the selected packages (this may take a while). Why this is recommended: Cygwin's bash version is required, as no native Win32 version is available. As additional packages can easily be added, the perl and alike packages are also used. 2.2.3. Install Python Get the python 2.4 installer from: http://python.
Quick Setup c. 2. i. URL of repository: " tp://anonsvn.wireshark.org/wireshark/trunk/" ii. Checkout directory: "C:\wireshark" ht- d. TortoiseSVN might ask you to create this directory - say yes e. TortoiseSVN starts downloading the sources f. if the download fails you may be behind a restrictive firewall, see Section 3.3, “Obtain the Wireshark sources”for alternative download methods Edit config.nmake: edit the settings in C:\wireshark\config.nmake, especially: a.
Quick Setup Warning! You will need the Wireshark sources and some tools (nmake, bash) installed, before this verification is able to work. Enter at the command line (cmd.exe, not Cygwin's bash!): > nmake -f Makefile.
Quick Setup Now it's time to build Wireshark ... 1. If you've closed cmd.exe in the meantime, prepare cmd.exe again 2. nmake -f Makefile.nmake all to build Wireshark 3. wait for Wireshark to compile - this may take a while! 4. run C:\wireshark\wireshark-gtk2\wireshark.exe and check if it starts 5. check Help/About if it shows your "private" program version, 0.99.4-myprotocol123 - you might run a release version previously installed! e.g.
Quick Setup 20
Chapter 3. Work with the Wireshark sources 3.1. Introduction This chapter will explain how to work with the Wireshark source code. It will show you how to: • get the source • compile the source • submit changes • ... However, this chapter will not explain the source file contents in detail, such as where to find a specific functionality. This is done in Section 7.1, “Source overview”.
Work with the Wireshark sources 3.2. The Wireshark Subversion repository Subversion is used to keep track of the changes made to the Wireshark source code. The Wireshark source code is stored inside Wireshark project's Subversion repository located at a server at the wireshark.org domain. To qoute the Subversion book about "What is Subversion?": “Subversion is a free/open-source version control system. That is, Subversion manages files and directories over time.
Work with the Wireshark sources http://anonsvn.wireshark.org/viewvc/viewvc.cgi/.
Work with the Wireshark sources 3.3. Obtain the Wireshark sources There are several ways to obtain the sources from Wireshark's Subversion server. Anonymous Subversion access is recommended! It can make your life much easier, compared to updating your source tree by using any of the zip file methods mentioned below. Subversion handles merging of changes into your personal source tree in a very comfortable and quick way. So you can update your source tree several times a day without much effort.
Work with the Wireshark sources source code change is committed. These snapshots can be found at: http:/ / www.wireshark.org/ download/automated/src/. If anonymous Subversion access isn't possible, e.g. if the connection to the server isn't possible because of a corporate firewall, the sources can be obtained by downloading the buildbot snapshots.
Work with the Wireshark sources 3.4. Update the Wireshark sources After you've obtained the Wireshark sources for the first time, you might want to keep them in sync with the sources at the Subversion repository. Take a look at the buildbot first! As development evolves, the Wireshark sources are compilable most of the time - but not always. You may take a look at the Section 1.6, “Automated Builds (Buildbot)” first, to see if the sources are currently in a good shape. 3.4.1. ...
Work with the Wireshark sources 3.5. Build Wireshark The sources contain several documentation files, it's a good idea to look at these files first. So after obtaining the sources, tools and libraries, the first place to look at is doc/ README.developer, here you will get the latest infos for Wireshark development for all supported platforms.
Work with the Wireshark sources other files in the root directory.
Work with the Wireshark sources 3.6. Run generated Wireshark Tip! An already installed Wireshark may interfere with your newly generated version in various ways. If you have any problems getting your Wireshark running the first time, it might be a good idea to remove the previously installed version first. XXX - add more info here.
Work with the Wireshark sources 3.7. Debug your generated Wireshark See the above info on running Wireshark. XXX - add more info here. 3.7.1. Win32 native XXX - add more info here.
Work with the Wireshark sources 3.8. Make changes to the Wireshark sources As the Wireshark developers are working on many different platforms, a lot of editors are used to develop Wireshark (emacs, vi, Microsoft Visual Studio and many many others). There's no "standard" or "default" development environment.
Work with the Wireshark sources 3.9. Contribute your changes If you have finished changing the Wireshark sources to suit your needs, you might want to contribute your changes back to the Wireshark community. You gain the following benefits by contributing your improvements: • It's the right thing to do. Other people who find your contributions useful will appreciate them, and you will know that you have helped people in the same way that the developers of Wireshark have helped you.
Work with the Wireshark sources tool to find the right place(s) to change in the existing sources. 3.9.2. Generate a patch There are several ways to generate patches. The preferred way is to generate them from an updated Subversion tree, since it avoids unnecessary integration work. 3.9.2.1. Using the svn command-line client svn diff [changed_files] > svn.diff Use the command line svn client to generate a patch in the required format from the changes you've made to your working copy.
Work with the Wireshark sources temporary files which might be otherwise included in the diff. After doing the diff, you should edit the foo.diff file and remove unnecessary things, like your private changes to the config.nmake file. Table 3.1. Some useful diff options Option Purpose -N Add new files when used in conjuction with -r. -r Recursively compare any subdirectories found. -u Output unified context. --strip-trailing-cr Strip trailing carriage return on input.
Work with the Wireshark sources The core maintainers have done a lot of work fixing bugs and making code compile on the various platforms Wireshark supports. To ensure Wireshark's source code quality, and to reduce the workload of the core maintainers, there are some things you should think about before submitting a patch. Warn! Ignoring the code requirements will make it very likely that your patch will be rejected! • Follow the Wireshark source code style guide.
Work with the Wireshark sources • You don't get any reponse to your patch (even after a few days or so). Possible reason: your patch might simply get lost, as all core maintainers were busy at that time and forgot to look at your patch. Simply send a mail asking if the patch was forgotten or if someone is still looking at it.
Work with the Wireshark sources 3.10. Apply a patch from someone else Sometimes you need to apply a patch to your private source tree. Maybe because you want to try a patch from someone on the developer mailing list, or you want to check your own patch before submitting. Warning! If you have problems applying a patch, make sure the line endings (CR/NL) of the patch and your source files match. 3.10.1. Using patch Given the file "new.
Work with the Wireshark sources "missing" subdirectory. For "cvs diff -c" or "cvs diff -u" diffs, there's a Python script "cvsdiff-fix.py" in the "tools" directory in the Wireshark source tree; it will fix up those lines in "cvs diff" output. It reads its standard input by default, or can be given a file name on the command line, and writes to the standard output, so if you're typing at a command interpreter that does piping, you could do something such as python tools/cvsdiff.
Work with the Wireshark sources 3.11. Add a new file to the Subversion repository The "usual" way to commit new files is described in Section 3.9, “Contribute your changes”. However, the following might be of interest for the "normal" developer as well. Note! This action is only possible/allowed by the Wireshark core developers who have write access to the Subversion repository. It is put in here, to have all information in one place.
Work with the Wireshark sources 3.12. Binary packaging Delivering binary packages, makes it much easier for the end-users to install Wireshark on their target system. This section will explain how the binary packages are made. 3.12.1. Debian: .deb packages The Debian Package is built using dpkg-buildpackage, based on information found in the source tree under debian. See http://www.debian-administration.org/articles/336 for a more in-depth discussion of the build process.
Work with the Wireshark sources Tip! Please be patient while the compression is done, it will take some time (a few minutes!) even on fast machines. If everything went well, you will now find something like: wireshark-setup-0.99.7.exe in the packaging/nsis directory.
Work with the Wireshark sources 42
Chapter 4. Tool Reference 4.1. Introduction This chapter will provide you with information about the various tools needed for Wireshark development. None of the tools mentioned in this chapter is needed to run Wireshark, they are only needed to build it. Most of these tools have their roots on UNIX like platforms, but Win32 ports are also available.
Tool Reference 4.2. Win32: Cygwin Cygwin provides a lot of UNIX based tools on the Win32 platform. It uses a UNIX emulation layer which might be a bit slower compared to the native Win32 tools, but at an acceptable level. The installation and update is pretty easy and done through a single (web based) setup.exe.
Tool Reference 4.3. GNU compiler toolchain (UNIX or Win32 Cygwin) 4.3.1. gcc (GNU compiler collection) Win32: Warn! Using Cygwin gcc to compile Wireshark is "EXPERT ONLY" and therefore NOT recommended. If you really want to try it anyway, see: http://wiki.wireshark.org/Development/CygwinGCC for some details! The GCC C compiler is available for most of the UNIX-like platforms and as the Devel/gcc package from the Cygwin setup.
Tool Reference debuggers), so you have to install GDB first. It is available for many UNIX-like platforms and as the ddd package from the Cygwin setup. If GNU DDD isn't already installed or available as a package for your platform, you can get it at: http://www.gnu.org/software/ddd/. 4.3.4. make (GNU Make) Win32 Note! Although some effort is made to use make from the Cygwin environment, the mainline is still using Microsoft Visual Studio's nmake.
Tool Reference 4.4. Microsoft compiler toolchain (Win32 native) To compile Wireshark on Windows using the Microsoft C/C++ compiler, you'll need: 1. C compiler (cl.exe) 2. Linker (link.exe) 3. Make (nmake.exe) 4. C runtime headers and libraries (e.g. stdio.h, msvcrt.lib) 5. Windows platform headers and libraries (e.g. windows.h, WSock32.lib) 6. HTML help headers and libraries (htmlhelp.h, htmlhelp.lib) 4.4.1.
Tool Reference Visual Stu- Yes dio 6.0 Commercial Visual Stu- Yes dio .NET (2002) Commercial MSVC6 1 Microsoft Visual Studio\VC98\Bi n\vcvars32.b at MSVC2002 Microsoft Visual Studio .NET\Vc7\bi n\vcvars32.b at 1 No 2 Visual Stu- Yes dio .NET 2003 Commercial MSVC2003 Microsoft Visual Studio .NET 2003\Vc7\bi n\vcvars32.
Tool Reference .NET Frame- No work SDK version 1.0a Free Down(104MB load) DOTNET10 Mican't build crosoft.NET\ setup 4 FrameworkSDK\Bin\corv ars.bat .NET Frame- No work SDK Version 1.1 5 Free Down(106MB load) .NET Frame- No work 2.0 SDK 5 Free Down(363MB load) DOTNET20 Mivcrecrosoft.NET\ dist_x86.exe SDK\v2.0\Bi 3 n\sdkvars.bat Windows No SDK for Windows Vista and Free Down- No 2 (1188M loadB) - Free DownDOTNET11 Mican't build load crosoft.NET\ setup 4 (420MB) SDK\v1.1\Bi n\sdkvars.
Tool Reference 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 2003 EULA explicitly forbids linking with GPL'ed programs. This belief is probably due to an improper interpretation of the Visual Studio 2003 Toolkit EULA, which places redistribution restrictions only on SOURCE CODE SAMPLES which accompany the toolkit. 2.
Tool Reference Visual Studio 2008 Express Edition (Code Name "Orcas") After correct installation of the toolchain, typing at the command line prompt (cmd.exe): > cl should result in something like: Microsoft (R) 32-bit C/C++ Optimizing Compiler Version 12.00.8804 for 80x86 Copyright (C) Microsoft Corp 1984-1998. All rights reserved. usage: cl [ option... ] filename... [ /link linkoption... However, the version string may vary. 4.4.4. nmake.
Tool Reference on the users machine. MSVC6 was using msvcrt.dll, which is already available on all recent windows systems - no need to redistribute anything. Starting with MSVC7, it is necessary to ship the C runtime DLL (msvcr.dll) together with the application installer somehow, as that DLL is possibly not available on the target system. Note! The files to redistribute must be mentioned in the redist.
Tool Reference smallest package). As MSVC2005EE and DOTNET20 doesn't provide the folder "Microsoft.VC80.CRT" they use method 3. You'll have to download a vcredist_x86.exe from Microsoft that matches your compiler version. The best way to determine this version is to open one of the generated manifest files (e.g. wireshark.exe.manifest) and look for the version of the Microsoft.VC80.CRT entry. • 8.0.50608.0, from: "Microsoft Visual C++ 2005" (and probably the Express Edition as well): http:/ / www.
Tool Reference Both files are part of the Platform SDK (standalone PSDK or MSVC since 2002). If you still use MSVC 6, you can get them from the "HTML Help Workshop" mentioned above. The related settings in config.nmake depend on the MSVC variant you use: • MSVC 6: if the "HTML Help Workshop" is installed, set HHC_DIR to its directory • > MSVC 6: set HHC_DIR to use it (the actual value doesn't matter in this case) 4.4.9. Debugger Well, using a good debugger can save you a lot of development time.
Tool Reference 4.5. bash The bash shell is needed to run several shell scripts. 4.5.1. UNIX or Win32 Cygwin: GNU bash The bash shell is available for most of the UNIX-like platforms and as the bash package from the Cygwin setup. If bash isn't already installed or available as a package for your platform, you can get it at: http:// www.gnu.org/software/bash/bash.html. After correct installation, typing at the bash command line prompt: $ bash --version should result in something like: GNU bash, version 3.1.
Tool Reference 4.6. python Python is an interpreter based programming language. The homepage of the python project is: http:// python.org/. Python is used to generate some source files. Python version 2.2 and above should be working fine. 4.6.1. UNIX or Win32 Cygwin: python Python is available for most of the UNIX-like platforms and as the python package from the Cygwin setup If Python isn't already installed or available as a package for your platform, you can get it at: http:// www.python.org/.
Tool Reference 4.7. perl Perl is an interpreter based programming language. The homepage of the perl project is: http:/ / www.perl.com. Perl is used to convert various text files into usable source code. Perl version 5.6 and above should be working fine. 4.7.1. UNIX or Win32 Cygwin: perl Perl is available for most of the UNIX-like platforms and as the perl package from the Cygwin setup. If perl isn't already installed or available as a package for your platform, you can get it at: http:/ / www.perl.com/.
Tool Reference 4.8. sed Sed it the streaming editor. It makes it easy for example to replace specially marked texts inside a source code file. The Wireshark build process uses this to stamp version strings into various places. 4.8.1. UNIX or Win32 Cygwin: sed Sed is available for most of the UNIX-like platforms and as the sed package from the Cygwin setup. If sed isn't already installed or available as a package for your platform, you can get it at: http://directory.fsf.org/GNU/sed.
Tool Reference 4.9. yacc (bison) Bison is a free implementation of yacc. 4.9.1. UNIX or Win32 Cygwin: bison Bison is available for most of the UNIX-like platforms and as the bison package from the Cygwin setup. If GNU Bison isn't already installed or available as a package for your platform, you can get it at: http://www.gnu.org/software/bison/bison.html. After correct installation, typing at the bash command line prompt: $ bison --version should result in something like: bison (GNU Bison) 2.
Tool Reference 4.10. flex Flex is a free implementation of lexx. 4.10.1. UNIX or Win32 Cygwin: flex Flex is available for most of the UNIX-like platforms and as the flex package from the Cygwin setup. If GNU flex isn't already installed or available as a package for your platform, you can get it at: http://www.gnu.org/software/flex/. After correct installation, typing at the bash command line prompt: $ flex --version should result in something like: flex version 2.5.
Tool Reference 4.11. Subversion (SVN) client (optional) The Wireshark project uses its own Subversion (or short SVN) server to keep track of all the changes done to the source code. Details about the usage of Subversion in the Wireshark project can be found in Section 3.2, “The Wireshark Subversion repository”. If you want to work with the source code and are planning to commit your changes back to the Wireshark community, it is recommended to use a SVN client to get the latest source files.
Tool Reference 4.12. Subversion (SVN) GUI client (optional) Along with the traditional command-line client, several GUI clients are available for a number of platforms, see http://subversion.tigris.org/project_links.html. Keep Subversion program versions in sync! If you are working with both command line and GUI clients, keep the Subversion program versions in sync, at least the major/minor versions (e.g. 1.4). 4.12.1.
Tool Reference 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 needed for building Wireshark, but it's needed if you are going to commit your changes back to the Wireshark community. Note! The recommended way to build patches is using the Subversion client, see Section 4.11, “Subversion (SVN) client (optional)” for details. You will find more instructions in Section 3.9.2.
Tool Reference 4.14. patch (optional) The patch utility is used to merge a diff file into your own source tree. This tool is only needed, if you want to apply a patch (diff file) from someone else (probably from the developer mailing list) to try out in your own private source tree. Tip! Unless you are in the rare case needing to apply a patch to your private source tree, you won't need the patch tool installed. You will find more instructions in Section 3.
Tool Reference 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-like platforms and as the wget package from the Cygwin setup. You will only need wget, if you want to use the Win32 automated library download, see Section 5.3, “Win32: Automated library download” for details.
Tool Reference 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 UNIX-like platforms and as the unzip package from the Cygwin setup. You will only need unzip, if you want to use the Win32 automated library download, see Section 5.3, “Win32: Automated library download” for details.
Tool Reference 4.17. Win32: NSIS (optional) The NSIS (Nullsoft Scriptable Install System) is used to generate a wireshark-setup-.exe from all the files needed to be installed, including all required DLL's and such. To install it, simply download the latest released version (currently: 2.28) from http:/ / nsis.sourceforge.net and start the downloaded installer. You will need NSIS version 2 final or higher. You will find more instructions in Section 3.12.3, “Win32: NSIS .
Tool Reference 68
Chapter 5. Library Reference 5.1. Introduction Several libraries are needed to build / run Wireshark. Most of the libraries are split into three packages: 1. Runtime package: binaries (e.g. win32 DLL's) and alike 2. Developer package: documentation, header files and alike 3. Source package: library sources, usually not required to build Wireshark Tip! Win32: All required libraries for the MSVC generation are available at: http://anonsvn.wireshark.
Library Reference 5.2. Binary library formats Binary libraries are available in different formats, depending on the C compiler used to build it and of course the platform they were built for. 5.2.1. Unix If you have installed unix binary libraries on your system, they will match the C compiler. If not already installed, the libraries should be available as a package from the platform installer, or you can download and compile the source and then install the binaries. 5.2.2.
Library Reference 5.3. Win32: Automated library download 5.3.1. Initial download You can download/install all required libraries by using the setup target of the Makefile.nmake from the source package. Tip! It's a really good idea to use the Win32 automated library download to install the required libraries as it makes this download very easy. Note! Before you start the download, you must have installed both the required tools (see Chapter 4, Tool Reference) and also the Wireshark sources (see Section 3.
Library Reference 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 the WIRESHARK_LIBS dir won't be downloaded again. Remaining (outdated) zip files shouldn't do any harm.
Library Reference 5.4. GTK+ / GLib / GDK / Pango / ATK / GNU gettext / GNU libiconv The Glib library is used as a basic platform abstraction library, it's not related to graphical user interface (GUI) things. For a detailed description about GLib, see Section 7.3, “The GLib library”. The GTK and its dependent libraries are used to build Wireshark's GUI. For a detailed description of the GTK libraries, see Section 10.2, “The GTK library”.
Library Reference 5.5. Net-SNMP (optional) "Various tools relating to the Simple Network Management Protocol" 5.5.1. Unix If this library isn't already installed or available as a package for your platform, you can get it at: http://sourceforge.net/projects/net-snmp/. 5.5.2. Win32 MSVC Wireshark uses the source Net-SNMP distribution at http://sourceforge.net/projects/net-snmp/. libsnmp is compiled with the "libsnmp - Win32 Release" project using MSVC++ 6.0. A file called "README.
Library Reference 5.6. GNU adns (optional) "Advanced, easy to use, asynchronous-capable DNS client library and utilities." 5.6.1. Unix If this library isn't already installed or available as a package for your platform, you can get it at: http://www.gnu.org/software/adns/. 5.6.2. Win32 MSVC You can get the latest version at: http://adns.jgaa.
Library Reference 5.7. PCRE (optional) "Perl compatible regular expressions" 5.7.1. Unix If this library isn't already installed or available as a package for your platform, you can get it at: http://www.pcre.org/. 5.7.2. Win32 MSVC You can get the latest version at: http://gnuwin32.sourceforge.net/packages/pcre.
Library Reference 5.8. zlib (optional) "zlib is designed to be a free, general-purpose, legally unencumbered -- that is, not covered by any patents -- lossless data-compression library for use on virtually any computer hardware and operating system." 5.8.1. Unix If this library isn't already installed or available as a package for your platform, you can get it at: http://www.gzip.org/zlib/. 5.8.2. Win32 MSVC You can get the latest version at: http://gnuwin32.sourceforge.net/packages/zlib.
Library Reference 5.9. libpcap/WinPcap (optional) "packet capture library" 5.9.1. Unix: libpcap If this library isn't already installed or available as a package for your platform, you can get it at: http://www.tcpdump.org/. 5.9.2. Win32 MSVC: WinPcap You can get the "Windows packet capture library" at: http://www.winpcap.org/install/default.
Library Reference 5.10. GnuTLS (optional) The "GNU Transport Layer Security Library" is used to dissect SSL and TLS protocols (aka: HTTPS). 5.10.1. Unix If this library isn't already installed or available as a package for your platform, you can get it at: http://www.gnu.org/software/gnutls/download.html. 5.10.2. Win32 MSVC We roll our own version using: http://josefsson.
Library Reference 5.11. Gcrypt (optional) The "Gcrypt Library" is Low-level encryption library and provides support for many ciphers, such as DES, 3DES, AES, Blowfish, and others.. 5.11.1. Unix If this library isn't already installed or available as a package for your platform, you can get it at: http://directory.fsf.org/security/libgcrypt.html. 5.11.2. Win32 MSVC Part of our homemade GnuTLS package.
Library Reference 5.12. Kerberos (optional) The Kerberos library is used to dissect Kerberos, sealed DCERPC and secureLDAP protocols. 5.12.1. Unix If this library isn't already installed or available as a package for your platform, you can get it at: http://web.mit.edu/Kerberos/dist/. XXX - Is it supported on *NIX at all? 5.12.2. Win32 MSVC You can get the latest version of KfW "Kerberos for Windows" at: http://web.mit.
Library Reference 5.13. LUA (optional) The LUA library is used to add scripting support to Wireshark. 5.13.1. Unix If this library isn't already installed or available as a package for your platform, you can get it at: http://www.lua.org/download.html. 5.13.2. Win32 MSVC You can get the latest version at: http://luaforge.
Library Reference 5.14. PortAudio (optional) The PortAudio library enables audio output for RTP streams. 5.14.1. Unix If this library isn't already installed or available as a package for your platform, you can get it at: http://www.portaudio.com/download.html. 5.14.2. Win32 MSVC You can get the latest version at: http://www.portaudio.com/download.
Library Reference 5.15. Win32: GTK WIMP (optional) for GTK 2.x only "GTK-Wimp ("Windows impersonator") is a GTK theme that blends well into the Windows desktop environment." GTK-Wimp can be used to get a native Look-and-Feel on WinXP machines, especially with the "coloured" WinXP theme. It will only take effect together with the GTK2 version of Wireshark. No changes to the Wireshark sources are needed, GTK-Wimp simply changes the way GTK2 displays the widgets (by changing the GTK2 default theme).
Library Reference 85
Part II. Wireshark Development (incomplete) Part I. Wireshark Build Environment The first part describes how to set up the tools, libraries and source needed to generate Wireshark, and how to do some typical development tasks. Part II. Wireshark Development The second part describes how the Wireshark sources are structured and how to change the sources (e.g. adding a new dissector).
Chapter 6. How Wireshark Works 6.1. Introduction This chapter will give you a short overview of how Wireshark works.
How Wireshark Works 6.2. Overview The following will give you a simplified overview of Wiresharks function blocks: Figure 6.1. Wireshark function blocks. The function blocks in more detail: GTK 1/2 Handling of all user input/output (all windows, dialogs and such). Source code can be found in the gtk directory.
How Wireshark Works Core Main "glue code" that holds the other blocks together. Source code can be found in the root directory. Epan Ethereal Packet ANalyzer (XXX - is this correct?) the packet analyzing engine. Source code can be found in the epan directory. • Protocol-Tree - Keep data of the capture file protocol information. • Dissectors - The various protocol dissectors in epan/ dissectors. • Plugins - Some of the protocol dissectors are implemented as plugins.
How Wireshark Works 6.3. Capturing packets Capturing will take packets from a network adapter, and save them to a file on your harddisk. To hide all the lowlevel machine dependent details from Wireshark, the libpcap/WinPcap (see Section 5.9, “libpcap/WinPcap (optional)”) library is used. This library provides a general purpose interface to capture packets from a lot of different network interface types (Ethernet, Token Ring, ...).
How Wireshark Works 6.4. Capture Files Wireshark can read and write capture files in its natural file format, the libpcap format, which is used by many other network capturing tools, e.g. tcpdump. In addition to this, as one of its strengths, Wireshark can read/write files in many different file formats of other network capturing tools. The wiretap library, developed together with Wireshark, provides a general purpose interface to read/ write all the file formats.
How Wireshark Works 6.5. Dissect packets While Wireshark is loading packets from a file, each packet is dissected. Wireshark tries to detect the packet type and gets as much information from the packet as possible. In this run though, only the information shown in the packet list pane is needed. As the user selects a specific packet in the packet list pane, this packet will be dissected again. This time, Wireshark tries to get every single piece of information and put it into the packet details pane.
How Wireshark Works 93
Chapter 7. Introduction 7.1. Source overview Wireshark consists of the following major parts: • Packet dissection - in the /epan/dissector and /plugin/* directory • File I/O - using Wireshark's own wiretap library • Capture - using the libpcap/winpcap library • User interface - using the GTK (and corresponding) libraries • Help - using an external webbrowser and GTK text output Beside this, some other minor parts and additional helpers exist.
Introduction 7.2. Coding styleguides The coding styleguides for Wireshark can be found in the "Code style" section of the file doc/ README.developer.
Introduction 7.3. The GLib library Glib is used as a basic platform abstraction library, it's not related to GUI things. To quote the Glib documentation: “GLib is a general-purpose utility library, which provides many useful data types, macros, type conversions, string utilities, file utilities, a main loop abstraction, and so on. It works on many UNIX-like platforms, Windows, OS/2 and BeOS. GLib is released under the GNU Library General Public License (GNU LGPL).
Introduction 97
Chapter 8. Packet capturing XXX - this chapter has to be reviewed and extended! 8.1. How to add a new capture type to libpcap The following is an excerpt from a developer mailing list mail, about adding ISO 9141 and 14230 (simple serial line card diagnostics) to Wireshark: For libpcap, the first thing you'd need to do would be to get DLT_ values for all the link-layer protocols you'd need.
Packet capturing 99
Chapter 9. Packet dissection 9.1. How it works Each dissector decodes its part of the protocol, and then hands off decoding to subsequent dissectors for an encapsulated protocol. So it might all start with a Frame dissector which dissects the packet details of the capture file itself (e.g. timestamps), passes the data on to an Ethernet frame dissector that decodes the Ethernet header, and then passes the payload to the next dissector (e.g. IP) and so on.
Packet dissection 9.2. Adding a basic dissector Let's step through adding a basic dissector. We'll start with the made up "foo" protocol. It consists of the following basic items. • A packet type - 8 bits, possible values: 1 - initialisation, 2 - terminate, 3 - data. • A set of flags stored in 8 bits, 0x01 - start packet, 0x02 - end packet, 0x04 - priority packet. • A sequence number - 16 bits. • An IP address. 9.2.1.
Packet dissection 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 those missing functions. Let's start with register function. First a call to proto_register_protocol that registers the protocol. We can give it three names that will be used for display in various places. The full and short name are used in e.g.
Packet dissection In order to compile this dissector and create a plugin a couple of support files are required, besides the dissector source in packet-foo.c: • Makefile.am - This is the UNIX/Linux makefile template • Makefile.common - This contains the file names of this plugin • Makefile.nmake - This contains the Wireshark plugin makefile for Windows • moduleinfo.h - This contains plugin version info • moduleinfo.nmake - This contains DLL version info for Windows • packet-foo.
Packet dissection FALSE we'll ignore for now. After this change, there should be a label in the detailed display for the protocol, and selecting this will highlight the remaining contents of the packet. Now let's go to the next step and add some protocol dissection. For this step we'll need to construct a couple of tables that help with dissection. This needs some changes to proto_register_foo. First a couple of statically declare arrays. Example 9.5. Registering data structures.
Packet dissection } Now the dissection is starting to look more interesting. We have picked apart our first bit of the protocol. One byte of data at the start of the packet that defines the packet type for foo protocol. The proto_item_add_subtree call has added a child node to the protocol tree which is where we will do our detail dissection. The expansion of this node is controlled by the ett_foo variable. This remembers if the node should be expanded or not as you move between packets.
Packet dissection proto_tree_add_item(foo_tree, proto_tree_add_item(foo_tree, proto_tree_add_item(foo_tree, proto_tree_add_item(foo_tree, hf_foo_pdu_type, tvb, offset, 1, FALSE); offset += 1; hf_foo_flags, tvb, offset, 1, FALSE); offset += 1; hf_foo_sequenceno, tvb, offset, 2, FALSE); offset += 2; hf_foo_initialip, tvb, offset, 4, FALSE); offset += 4; This dissects all the bits of this simple hypothetical protocol.
Packet dissection }, { &hf_foo_endflag, { "FOO PDU End Flags", "foo.flags.end", FT_BOOLEAN, 8, NULL, FOO_END_FLAG, NULL, HFILL } }, { &hf_foo_priorityflag, { "FOO PDU Priority Flags", "foo.flags.priority", FT_BOOLEAN, 8, NULL, FOO_PRIORITY_FLAG, NULL, HFILL } }, ...
Packet dissection arly we append this data to the base of our dissecting tree.
Packet dissection 9.3. How to handle transformed data Some protocols do clever things with data. They might possibly encrypt the data, or compress data, or part of it. If you know how these steps are taken it is possible to reverse them within the dissector. As encryption can be tricky, let's consider the case of compression. These techniques can also work for other transformations of data, where some step is required before the data can be examined.
Packet dissection 9.4. How to reassemble split packets Some protocols have times when they have to split a large packet across multiple other packets. In this case the dissection can't be carried out correctly until you have all the data. The first packet doesn't have enough data, and the subsequent packets don't have the expect format. To dissect these packets you need to wait until all the parts have arrived and then start the dissection. 9.4.1.
Packet dissection • The provided packet info. • The sequence number of the fragment stream. There may be several streams of fragments in flight, and this is used to key the relevant one to be used for reassembly. • The msg_fragment_table and the msg_reassembled_table are variables we need to declare. We'll consider these in detail later. • msg_num is the packet number within the sequence. • The length here is specified as the rest of the tvb as we want the rest of the packet data.
Packet dissection { fragment_table_init(&msg_fragment_table); reassembled_table_init(&msg_reassembled_table); } First a couple of hash tables are declared, and these are initialised in the protocol initialisation routine. Following that, a fragment_items structure is allocated and filled in with a series of ett items, hf data items, and a string tag. The ett and hf values should be included in the relevant tables like all the other variables your protocol may use.
Packet dissection &ett_msg_fragment, &ett_msg_fragments ... These hf variables are used internally within the reassembly routines to make useful links, and to add data to the dissection. It produces links from one packet to another - such as a partial packet having a link to the fully reassembled packet. Likewise there are back pointers to the individual packets from the reassembled one. The other variables are used for flagging up errors. 9.4.2.
Packet dissection whenever a message has been reassembled. The parameters tvb, pinfo and tree are just handed over to tcp_dissect_pdus(). The 4th parameter is a flag to indicate if the data should be reassebled or not. This could be set according to a dissector preference as well. Parameter 5 indicates how much data has at least to be available to be able to determine the length of the foo message. Parameter 6 is a function pointer to a method that returns this length.
Packet dissection 9.5. How to tap protocols Adding a Tap interface to a protocol allows it to do some useful things. In particular you can produce protocol statistics from the tap interface. A tap is basically a way of allowing other items to see whats happening as a protocol is dissected. A tap is registered with the main program, and then called on each dissection. Some arbritary protocol specific data is provided with the routine that can be used. To create a tap, you first need to register a tap.
Packet dissection 9.6. How to produce protocol stats Given that you have a tap interface for the protocol, you can use this to produce some interesting statistics (well presumably interesting!) from protocol traces. This can be done in a separate plugin, or in the same plugin that is doing the dissection. The latter scheme is better, as the tap and stats module typically rely on sharing protocol specific data, which might get out of step between two different plugins.
Packet dissection In this case we create a new tree node, to handle the total packets, and as a child of that we create a pivot table to handle the stats about different packet types. Example 9.24.
Packet dissection 9.7. How to use conversations Some info about how to use conversations in a dissector can be found in the file doc/ README.developer chapter 2.2.
Packet dissection 119
Chapter 10. User Interface 10.1. Introduction Wireshark can be "logically" separated into the backend (dissecting of protocols, file load/save, capturing, ...) and the frontend (the user interface). However, there's currently no clear separation between these two parts (no clear API definition), but this might change in the future. The following frontends are currently maintained by the Wireshark development team: • Wireshark, GTK 1.x based • Wireshark, GTK 2.
User Interface 10.2. The GTK library Wireshark is based on the GTK toolkit, see: http://www.gtk.org for details. GTK is designed to hide the details of the underlying GUI in a platform independent way. As this is appreciated for a multiplatform tool, this has some drawbacks, as it will result in a somewhat "non native" look and feel. GTK is available for a lot of different platforms including, but not limited to: Unix/Linux, Mac OS X and Win32.
User Interface 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 stable too) • more dependencies compared to 1.x, see below GTK 2.x depends on the following libraries: • GObject (Object library. Basis for GTK and others) • GLib (A general-purpose utility library, not specific to graphical user interfaces.
User Interface mentation at: http://gtk.org/api/. Several mailing lists are available about GTK development, see http://gtk.org/mailinglists.html, the gtk-app-devel-list may be your friend. There's no Win32 specific GTK mailing list. If you want to post a Win32 specific problem (e.g. a problem in the GtkFileChooser dialog) and you are sure that it's really Win32 specific, you could send it to GIMPwin-users at http://www.gimp.org/mail_lists.html.
User Interface 10.3. GUI Reference documents Although the GUI development of Wireshark is platform independent, the Wireshark development team tries to follow the GNOME Human Interface Guidelines (HIG) where appropriate. This is the case, because both GNOME and Wireshark are based on the GTK+ toolkit and the GNOME HIG is excellently written and easy to understand. For further reference, see the following documents: • GNOME Human Interface Guidelines at: http://developer.gnome.
User Interface 10.4. Adding/Extending Dialogs This is usually the main area for contributing new user interface features. XXX: add the various functions from gtk/dlg_utils.
User Interface 10.5. Widget naming It seems to be common sense to name the widgets with some descriptive trailing characters, like: • xy_lb = gtk_label_new(); • xy_cb = gtk_checkbox_new(); • XXX: add more examples However, this schema isn't used at all places inside the code.
User Interface 10.6. Common GTK programming pitfalls There are some common pitfalls in GTK programming. 10.6.1. Usage of gtk_widget_show() / gtk_widget_show_all() When a GTK widget is created it will be hidden by default. In order to show it, a call to gtk_widget_show() has to be done. It isn't necessary to do this for each and every widget created. A call to gtk_widget_show_all() on the parent of all the widgets in question (e.g.
User Interface 128
Appendix A. This Document's License (GPL) As with the original licence and documentation distributed with Wireshark, this document is covered by the GNU General Public Licence (GNU GPL). If you haven't read the GPL before, please do so. It explains all the things that you are allowed to do with this code and documentation. GNU GENERAL PUBLIC LICENSE Version 2, June 1991 Copyright (C) 1989, 1991 Free Software Foundation, Inc.
This Document's License (GPL) either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you". Activities other than copying, distribution and modification are not covered by this License; they are outside its scope.
This Document's License (GPL) The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable.
This Document's License (GPL) Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation. 10.
This Document's License (GPL) Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (which makes passes at compilers) written by James Hacker. , 1 April 1989 Ty Coon, President of Vice This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library.
