path: root/doc/ethereal-tut.mgp

#!/usr/bin/X11/mgp -o -g 1028x776-1026-772
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Copyright, 2000, Richard Sharpe, richard.sharpe@linuxworld.com
%%
%% This presentation is free material; 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 material 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 material; if not, write to the Free Software
%% Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
%%
%% If you make any changes or improvements, please consider contributing 
%% them back to the ethereal team or the author.
%%
%deffont "standard" xfont "comic sans ms-medium-r"
%deffont "thick" xfont "arial black-medium-r"
%deffont "typewriter" xfont "courier new-bold-r"
%%
%% Default settings per each line numbers.
%%
%default 1 leftfill, size 8, fore "yellow", back "black", font "thick"
%default 1 bgrad 0 0 128 0 1 "lightblue" "cyan" "blue" "darkblue" "black" 
%default 2 size 7, vgap 10, prefix "       "
%default 3 size 2, bar "gray70", vgap 10
%default 4 size 5, fore "white", vgap 30, prefix " ", font "standard"
%%
%% Default settings that are applied to TAB-indented lines.
%%
%tab 1 size 4, vgap 95, prefix "             ", icon box "red" 50
%tab 2 size 4, vgap 95, prefix "                 ", icon arc "yellow" 50
%tab 3 size 3, vgap 95, prefix "                       ", icon delta3 "white" 40 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page
%nodefault, bgrad 0 0 128 0 1 "lightblue" "cyan" "blue" "darkblue" "black"
%tfont "comic sans ms-medium-r"


%center, size 4
%image "ethereal-logo-small.png"

%size 7, font "standard"
Developing an Ethereal Dissector

%size 7, font "standard"
A tutorial on Open Source Software

%size 4, font "standard"
by Richard Sharpe

%% You may add the following here, if you like ...
%%size 4, font "standard"
%%Presented by YOUR NAME HERE

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Agenda


	My involvement with Ethereal
	Overview of Ethereal
	Developing a dissector
	The AUTH/IDENT dissector
	Advanced topics
	Resources


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

My involvement with Ethereal


	Needed a Linux/Unix packet analysis program
	Found Ethereal in late 1998
		Very few application protocols at that stage
	Developed a number of dissectors in 1999 and 2000
		POP, TFTP, FTP, Telnet, SMB, SMTP, BXXP
	Helped with various bits of infrastructure and ideas

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Overview of Ethereal


	What is Ethereal
	Genesis of Ethereal
	Protocols it understands
	Features
	Platforms it runs on
	Tools it uses
	Uses for Ethereal
	Future of Ethereal

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

What is Ethereal


	Open source packet capture and analysis program
		GPL'd
	Based on GTK+
	Uses libpcap
	Developed by a world-wide team
	Being used by standards groups
	Supports many protocols

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page
%%nodefault, bgrad 0 0 128 0 1 "lightblue" "cyan" "blue" "darkblue" "black"

What is Ethereal
%%system "/root/ethereal-latest/ethereal -m 9x15 -n -r /root/captures/w95-logon-off-nt.cap" -1
%%system "xterm -fn 12x24 -e more /root/ethereal-latest/packet-bxxp.c &" 

%center
%image "ethereal-shot.png"

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Genesis of Ethereal


	Started in 1998 by Gerald Combs
		Needed a GUI-based packet analysis program
		Wrote his own, using GTK+
	Quickly gained a following
		Guy Harris, Gilbert Ramirez, Laurent Deniel
		Jun-ichiro itojun Hagino, Hannes Boehm, 
		Richard Sharpe, Jeff Foster, ... 
	Currently, Version 0.8.13?

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Protocols it understands


	Any UNIX/Linux network device
	IP, IPX, NetBEUI, X.25, HDLC, ...
	ICMP, IGMP, TCP, UDP, OSPF, ...
	Many application layer protocols
	138+

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Features


	Read and write many capture file formats
		libpcap, NetMon, snoop, NetXRay, ...
	Filter packets during capture
	Filter packets during display
	View all packet details code handles
	Follow TCP streams
	Print packets, etc ...

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Platforms it runs on


	Any version of UNIX with:
		GTK+
		libpcap
	Linux, FreeBSD, ...
	Windows 9X, NT, 2000


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page 

Tools it uses


	GTK+ 1.2.6+, Glib
	libpcap
	autogen, automake, bison, flex, GCC

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Uses for Ethereal


	Learning about protocols
	Network troubleshooting
	Developing new implementations
	Capturing passwords

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Example ... Why is RADIUS failing

%center
%image "ethereal-radius.png"

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Future of Ethereal


	Version 1.0 early 2001
	Version 2.0 redeveloped
		Apply all the lessons we have learned
		Separate packet dissecting from display
			Provide a library to be use separately
	Use SNMP to capture from RMON packet probes
	Developer documentation
	Improve user documentation
	Automatic generation of dissectors?

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Developing a dissector


	Obtaining the source code
	Other packages you need
	Unpack source and prepare to build
	Structure of the source code
	Your dissector
	Summary information vs tree view
	When your dissector is called
	Routines you will need to use
	Using tvb versus the (packet) frame buffer
	A walk through a dissector

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Obtaining the source code


	Download from www.ethereal.com
		Not the latest code
		But it will compile
	Get access to the CVS tree
		Latest, possibly buggy code
		May not compile
		May be undergoing serious change


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Other packages you need


	libpcap
	GTK+ 1.2.6+
	GLIB 1.2.6+
	automake, autoconf
	make
	gcc
	bison/yacc, flex/lex
	Perl
	Python

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Unpack your source and prepare to build


%size 4, font "typewriter"
     tar zxvf ethereal-0.8.x.tar.gz

%size 4, font "typewriter"
     cd ethereal-0.8.x

%size 4, font "typewriter"
     ./configure  # may need autogen.sh

%size 4, font "typewriter"
     # Fix up any problems

%size 4, font "typewriter"
     make

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Structure of the source code


	ethereal-0.x.y
		All the dissectors, packet-xxx.c
		Much of the support code
	ethereal-0.x.y/gtk
		Contains main.c
		Contains the GUI code
	ethereal-0.x.y/wiretap
		Code to deal with capture file formats

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Structure, cont


	ethereal-0.x.y/doc
		Documentation and scripts for generating docs
	ethereal-0.x.y/plugins
		Plugins and support code
	ethereal-0.x.y/others...
		A few other directories

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Your dissector


	Create packet-xxx.c in top level directory
	Copy an existing dissector and modify
		eg, packet-pop.c
		not a good choice if you need to keep state between packets
	Must have a dissect_xxx entry point
	Use build-dissector.pl to build a TCP/UDP dissector
	Can decode as much or as little as you want

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Summary information vs tree view


	Must produce two types of information
		Summary information in the top pane
		Protocol tree information in the middle and lower panes


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Summary vs tree view, cont


	One dissector used for both!
		If called with a tree argument, must provide protocol tree info
		If called without a tree argument, only need to provide summary
	Your protocol may require you to decode whole packet in either case!

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

When your dissector is called


	Called by the protocol below you
		Eg, packet-tcp.c, etc
	Once, on first pass, for every packet that is yours
		Mainly, summary info wanted this time around
		If filter specified, full decode needed
		If color filter in effect, full decode needed
	Everytime user clicks on one of your packets in the summary pane	
	If a rescan is needed
		Once, again, for every packet that is yours

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Routines you will need to use


	Registration routines
	Summary info display
	Protocol tree display
	Packet access routines (macros)
	TVB routines
	Utility routines

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Registration routines


	Registering initialization callbacks
		Create a bxxp_init_protocol routine
	Registering your dissection routines
		Create proto_register_xxx routine
		Call dissector_add
		Create proto_reg_handoff_xxx
	Registering filter information
	Registering preference information

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Summary info display


	check_col
		Checks if a column is needed
	col_add_[f]str
		Adds a string or a formatted string


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Protocol tree display


	proto_item_add_subtree
		Adds a new subtree to the protocol tree
	proto_tree_add_xxx[_format]
		Adds an item to the subtree for display and searching
	proto_tree_add_xxx_hidden
		Adds an item to the subtree for searching only
	proto_item_set_len
		Sets the length for an item
	proto_tree_add_notext & proto_tree_set_text
		Adds an item without text
		Later add the text

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Packet access routines (macros)


	Accessing information in the frame data
	Only needed if you are not using TVB
	Extracting information with correct endianness
		Big endian
			pntohs, pntohl
		Little endian
			pletohs, pletohl
	Avoids unaligned access traps on RISC architectures as well

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

TVB routines


	tvb_xxx
		Routines to access data from the packet
	tvb_length_remaining(tvb, offset)
		Find out how many bytes remain in the packet

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Utility routines


	format_text
		Formats packet data for display in the detail pane

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Using TVB vs the frame buffer


	Original dissectors accessed the packet/frame buffer
	Too many coders did not check that chars were available
	Many crashes due to poor code
	Testy Virtializable Buffers introduced
		Protect Ethereal from bad coding
		However, few dissectors converted to using TVB

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

A walk through a dissector...


%%system "...more etc ..."
	Walk through packet-pop.c comparing code to what Ethereal displays

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

The AUTH/IDENT dissector


	Overview of the AUTH/IDENT dissector
	Discussion of the AUTH/IDENT dissector
	Other files you need to modify
	Building the dissector

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Overview of the AUTH/IDENT dissector


%center, size 4
%image "rfc1413.png"

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Discussion of the AUTH/IDENT dissector


	Simple dissector needed here
	All dissection decisions based on packet content alone
	Must check port numbers for client or server side
	Small amount of code plus a couple of support routines
	Some registration code required

%page

Create the dissector...


	Hack away until done...

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Other files you need to modify


	Makefile.common
		Add your source code module to DISSECTOR_SOURCES
	Rerun configure

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Building the dissector


%size 4, font "typewriter"
      make: make

%size 4, font "typewriter"
      test

%size 4, font "typewriter"
      fix

%size 4, font "typewriter"
      goto make
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Advanced topics


	Preferences
	Display filters
	Keeping state
	Conversations
	Per-frame state
	Missing frames
	Changing the GUI


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Preferences


	Allow you to manage preferences
	Kept in ~/.ethereal/preferences
	You provide a callback routine
		proto_reg_handoff_xxx
	Register your preferences in proto_register_xxx
		Fields
		Types
		Description
		They appear in the preferences panel


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Preferences, cont


%center, image "eth-prefs.png"

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Preferences, the code


	prefs_register_module
		Registers the module and a handoff routine
	prefs_register_xxx_preference
		Registers a preferences field, its type, name, description, etc


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Display filters


	Allow users to search the capture file for interesting items
	Supported by registering field items to the protocol tree
		proto_register_field_array
	Field items can be displayable or hidden

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Keeping state


	Sometimes you want to keep state information
		You need information from past frames to make sense of the current frame
	Two mechanisms that work hand in hand
		Conversations
			Focussed around TCP connections
		Per-frame data
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Conversations


	Conversations allow you to keep state information
		Source & dest IP and port numbers
	Search for the conversation on each frame
		Create one if it does not exist
	Best used on the first pass through all the packets

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Per-frame state


	State can be kept:
		Per-frame
		Per-protocol
	Best used in conjunction with conversations
	Accumulate information on first pass
		Add it to per-frame data as you go
	Always check for per-frame data first
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Missing and or duplicate frames


	Your dissector must tolerate missing frames, segments, etc
	Can be missing for a variety of reasons
		Did not capture enough packets/frames
		Multiple paths through the internet
	Your dissector must also tolerate duplicate segments
		Retransmissions
		Capturing on loopback under Linux
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Changing the GUI


	All the GUI code is kept in ethereal-x.y.z/gtk
	Mostly callbacks from GTK+ objects
	Add what you need
	Discuss it with the team first

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Resources


	The Ethereal web site
		www.ethereal.com

	The Ethereal user's guide
		www.ns.aus.com/ethereal/user-guide/book1.html

	The GTK+ web site
		www.gtk.org

	Ethereal developers documentaion
		README.developer in doc directory
		README.tvbuff in doc directory

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Mailing lists


	ethereal-dev
	ethereal-announce
	ethereal-users
	ethereal-core
	Subscribe to them from www.ethereal.com