From Gerhard Gappmeier: I have added a new chapter about tcp_dissect_pdu
[obnox/wireshark/wip.git] / docbook / wsdg_src / WSDG_chapter_dissection.xml
1 <!-- WSDG Chapter Dissection -->
2 <!-- $Id$ -->
3
4 <chapter id="ChapterDissection">
5   <title>Packet dissection</title>
6   <!-- Julian Onions additions -->
7   <section id="ChDissectWorks">
8         <title>How it works</title>
9         <para>
10         Each dissector decodes it's part of the protocol, and then hand off
11         decoding to subsequent dissectors for an encapsulated protocol.
12         </para>
13         <para>
14         So it might all start with a Frame dissector which dissects the packet details 
15         of the capture file itself (e.g. timestamps), passes the data on to an 
16         Ethernet frame dissector that decodes the Ethernet header, 
17         and then passes the payload to the next dissector (e.g. IP) and so on. 
18         At each stage, details of the packet will be decoded and displayed.
19         </para>
20         <para>
21         Dissection can be implemented in two possible ways. One is to have a dissector
22         module compiled into the main program, which means its always available.
23         Another way is to make a plugin (a shared library/DLL) that registers itself
24         to handle dissection. - XXX add a special explanation section for this?
25         </para>
26   </section>
27
28   <section id="ChDissectAdd">
29         <title>Adding a basic dissector</title>
30         <para>
31         Lets step through adding a basic dissector. We'll start with the made up
32         "foo" protocol. It consists of the following basic items.
33         </para>
34         <itemizedlist>
35         <listitem><para>
36         A packet type - 8 bits, possible values: 1 - initialisation, 2 - terminate, 3 - data.
37         </para></listitem>
38         <listitem><para>
39         A set of flags stored in 8 bits, 0x01 - start packet, 0x02 - end packet, 0x04 - priority packet.
40         </para></listitem>
41         <listitem><para>
42         A sequence number - 16 bits.
43         </para></listitem>
44         <listitem><para>
45         An IP address.
46         </para></listitem>
47         </itemizedlist>
48         <section id="ChDissectSetup">
49         <title>Setting up the dissector</title>
50            <para>
51                 The first decision you need to make is if this dissector will be a 
52                 built in dissector, included in the main program, or a plugin.
53            </para>
54            <para>
55                 Plugins are the easiest to write initially as they don't need
56                 write permission on the main code base. So lets start with that.
57                 With a little care, the plugin can be made to run as a built in
58                 easily too - so we haven't lost anything.
59            </para>
60            <example><title>Basic Plugin setup.</title>
61            <programlisting>
62            <![CDATA[
63 #ifdef HAVE_CONFIG_H
64 # include "config.h"
65 #endif
66
67 #include <gmodule.h>
68 #include <epan/packet.h>
69 #include <epan/prefs.h>
70
71 /* forward reference */
72 void proto_register_foo();
73 void proto_reg_handoff_foo();
74 void dissect_foo(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree);
75
76 /* Define version if we are not building Wireshark statically */
77 #ifndef ENABLE_STATIC
78 G_MODULE_EXPORT const gchar version[] = "0.0";
79 #endif
80
81 static int proto_foo = -1;
82 static int global_foo_port = 1234;
83 static dissector_handle_t foo_handle;
84
85 #ifndef ENABLE_STATIC
86 G_MODULE_EXPORT void
87 plugin_register(void)
88 {
89         /* register the new protocol, protocol fields, and subtrees */
90         if (proto_foo == -1) { /* execute protocol initialization only once */
91                 proto_register_foo();
92         }
93 }
94
95 G_MODULE_EXPORT void
96 plugin_reg_handoff(void){
97         proto_reg_handoff_foo();
98 }
99 #endif]]>
100            </programlisting>
101            </example>
102         <para>
103         Lets go through this a bit at a time. First we have some boiler plate
104         include files. These will be pretty constant to start with. Here we also
105         pre-declare some functions that we'll be writing shortly.
106         </para>
107         <para>
108         Next we have a section surrounded by #ifdef ENABLE_STATIC. This is what
109         makes this a plugin rather than a built in dissector.
110         </para>
111         <para>
112         The version is a simple string that is used to report on the version of this
113         dissector. You should increase this number each time you make changes that you
114         need to keep track of.
115         </para> 
116         <para>
117         Next we have an int that is initialised to -1 that records our protocol.
118         This will get updated when we register this plugin with the main program.
119         We can use this as a handy way to detect if we've been initialised yet.
120         Its good practice to make all variables and functions that aren't exported
121         static to keep name space pollution. Normally this isn't a problem unless your
122         dissector gets so big it has to span multiple files.
123         </para>
124         <para>
125         Then a global variable which contains the UDP port that we'll assume we are dissecting traffic for.
126         </para>
127         <para>
128         Next a dissector reference that we'll initialise later.
129         </para>
130         <para>
131         Next, the first plugin entry point. The function plugin_register() is called
132         when the plugin is loaded and allows you to do some initialisation stuff,
133         which will include communicating with the main program what you're plugins
134         capabilities are.
135         </para>
136         <para>
137         The plugin_reg_handoff routine is used when dissecting sub protocols. As our
138         hypothetical protocol will be hypothetically carried over UDP then we will
139         need to do this.
140         </para>
141         <para>
142         Now we have the basics in place to interact with the main program, we had
143         better fill in those missing functions. Lets start with register function.
144         </para>
145            <example><title>Plugin Initialisation.</title>
146    <programlisting>
147    <![CDATA[
148 void
149 proto_register_foo(void)
150 {
151         module_t *foo_module;
152
153         if (proto_foo == -1) {
154                 proto_foo = proto_register_protocol (
155                         "FOO Protocol",         /* name */
156                         "FOO",          /* short name */
157                         "foo"           /* abbrev */
158                         );
159         }
160         foo_module      = prefs_register_protocol(proto_foo, proto_reg_handoff_foo);
161 }]]>    
162    </programlisting></example>
163         <para>
164         First a call to proto_register_protocol that
165         registers the protocol. We can give it three names that
166         will be used in various places to display it.
167         - XXX explain where, this can be confusing
168         </para>
169         <para>
170         Then we call the preference register function. At the moment we have
171         no specific protocol preferences so this will be all that we need.
172         This takes a function parameter which is our handoff function.
173         I guess we'd better write that next.
174         </para>
175            <example><title>Plugin Handoff.</title>
176    <programlisting>
177    <![CDATA[
178 void
179 proto_reg_handoff_foo(void)
180 {
181         static int Initialized=FALSE;
182
183         if (!Initialized) {
184                 foo_handle = create_dissector_handle(dissect_foo, proto_foo);
185                 dissector_add("udp.port", global_foo_port, foo_handle);
186         }
187 }]]>    
188    </programlisting></example>
189         <para>
190         What's happening here? We are initialising the dissector if it hasn't
191         been initialised yet. 
192         First we create the dissector. This registers a routine 
193         to be called to do the actual dissecting.
194         Then we associate it with a udp port number
195         so that the main program will know to call us when it gets UDP traffic on that port.
196         </para>
197         <para>
198         Now at last we finally get to write some dissecting code. For the moment we'll
199         leave it as a basic placeholder.
200         </para>
201            <example><title>Plugin Dissection.</title>
202    <programlisting>
203    <![CDATA[
204 static void
205 dissect_foo(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
206 {
207
208         if (check_col(pinfo->cinfo, COL_PROTOCOL))
209                 col_set_str(pinfo->cinfo, COL_PROTOCOL, "FOO");
210         /* Clear out stuff in the info column */
211         if(check_col(pinfo->cinfo,COL_INFO)){
212                 col_clear(pinfo->cinfo,COL_INFO);
213         }
214 }]]>    
215    </programlisting></example>
216         <para>
217         This function is called to dissect the packets presented to it.
218         The packet data is held in a special buffer referenced here as tvb.
219         We shall become fairly familiar with this as we get deeper into the details
220         of the protocol.
221         The packet info structure contains general data about the protocol, and we
222         can update information here.
223         The tree parameter is where the detail dissection takes place.
224         </para>
225         <para>
226         For now we'll do the minimum we can get away with. 
227         The first two lines check to see if the Protocol column is being displayed in
228         the UI. If it is, we set the text of this to our protocol, so everyone
229         can see its been recognised.
230         The only other thing we do is to clear out any data in the INFO column
231         if its being displayed. 
232         </para>
233         <para>
234         At this point we should have a basic dissector ready to compile and install.
235         It doesn't do much at present, than identify the protocol and label it.
236         Compile the dissector to a dll or shared library, and copy it into the plugin
237         directory of the installation. To finish this off a Makefile of some sort will be 
238         required. A Makefile.nmake for Windows platforms and a Makefile.am for unix/linux
239         types.
240         </para>
241
242            <example><title>Makefile.nmake for Windows.</title>
243    <programlisting>
244    <![CDATA[
245 include ..\..\config.nmake
246
247 ############### no need to modify below this line #########
248
249 CFLAGS=/DHAVE_CONFIG_H /I../.. /I../../wiretap $(GLIB_CFLAGS) \
250         /I$(PCAP_DIR)\include -D_U_="" $(LOCAL_CFLAGS)
251
252 LDFLAGS = /NOLOGO /INCREMENTAL:no /MACHINE:I386 $(LOCAL_LDFLAGS)
253
254 !IFDEF ENABLE_LIBWIRESHARK
255 LINK_PLUGIN_WITH=..\..\epan\libwireshark.lib
256 CFLAGS=/DHAVE_WIN32_LIBWIRESHARK_LIB /D_NEED_VAR_IMPORT_ $(CFLAGS)
257
258 OBJECTS=foo.obj 
259
260 foo.dll foo.exp foo.lib : $(OBJECTS) $(LINK_PLUGIN_WITH)
261         link -dll /out:foo.dll $(LDFLAGS) $(OBJECTS) $(LINK_PLUGIN_WITH) \
262         $(GLIB_LIBS)
263
264 !ENDIF
265
266 clean:
267         rm -f $(OBJECTS) foo.dll foo.exp foo.lib *.pdb
268
269 distclean: clean
270
271 maintainer-clean: distclean]]>  
272    </programlisting></example>
273    <example><title>Makefile.am for unix/linux.</title>
274    <programlisting>
275    <![CDATA[
276 INCLUDES = -I$(top_srcdir)
277
278 plugindir = @plugindir@
279
280 plugin_LTLIBRARIES = foo.la
281 foo_la_SOURCES = foo.c moduleinfo.h
282 foo_la_LDFLAGS = -module -avoid-version
283 foo_la_LIBADD = @PLUGIN_LIBS@
284
285 # Libs must be cleared, or else libtool won't create a shared module.
286 # If your module needs to be linked against any particular libraries,
287 # add them here.
288 LIBS =
289
290 CLEANFILES = \
291         foo \
292         *~
293
294 EXTRA_DIST = \
295         Makefile.nmake
296 ]]>     
297    </programlisting></example>
298    </section>
299
300         <section id="ChDissectDetails">
301         <title>Dissecting the details of the protocol</title>
302            <para>
303            Now we have our basic dissector up and running, lets do something with it.
304            The simplest thing to do to start with is to just label the payload.
305            This will allow us to set up some of the parts we will need.
306            </para>
307            <para>
308            The first thing we will do is to build a subtree to decode our results into.
309            This helps to keep things looking nice in the detailed display.
310            Now the dissector is called in two different cases. In one case
311            it is called to get a summary of the packet, in the other case it is
312            called to look into details of the packet. These two cases can be
313            distinguished by the tree pointer. If the tree pointer is NULL, then
314            we are being asked for a summary. If it is non null, we can pick apart
315            the protocol for display. So with that in mind, lets enhance our dissector.
316            </para>
317            <example><title>Plugin Packet Dissection.</title>
318    <programlisting>
319    <![CDATA[
320 static void
321 dissect_foo(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
322 {
323
324         if (check_col(pinfo->cinfo, COL_PROTOCOL))
325                 col_set_str(pinfo->cinfo, COL_PROTOCOL, "FOO");
326         /* Clear out stuff in the info column */
327         if(check_col(pinfo->cinfo,COL_INFO)){
328                 col_clear(pinfo->cinfo,COL_INFO);
329         }
330         
331         if (tree) { /* we are being asked for details */
332                 proto_item *ti = NULL;
333                 ti = proto_tree_add_item(tree, proto_foo, tvb, 0, -1, FALSE);
334         }
335 }]]>    
336    </programlisting></example>
337         <para>
338         What we're doing here is adding a subtree to the dissection.
339         This subtree will hold all the details of this protocol and so not clutter
340         up the display when not required.
341         </para>
342         <para>
343         We are also marking the area of data that is being consumed by this
344         protocol. In our cases its all that has been passed to us, as we're assuming
345         this protocol does not encapsulate another.
346         Therefore, we add the new tree node with proto_tree_add_item, adding
347         it to the passed in tree, label it with the protocol, use the passed in
348         tvb buffer as the data, and consume from 0 to the end (-1) of this data.
349         The FALSE we'll ignore for now.
350         </para>
351         <para>
352         After this change, there should be a label in the detailed display for the protocol,
353         and selecting this will highlight the remaining contents of the packet.
354         </para>
355         <para>
356         Now lets go to the next step and add some protocol dissection.
357         For this step we'll need to construct a couple of tables that help with dissection.
358         This needs some changes to proto_register_foo. First a couple of statically
359         declare arrays.
360         </para>
361            <example><title>Plugin Registering data structures.</title>
362    <programlisting>
363    <![CDATA[
364 static hf_register_info hf[] = {
365         { &hf_foo_pdu_type,
366         { "FOO PDU Type",           "foo.type",
367         FT_UINT8, BASE_DEC, NULL, 0x0,
368         "", HFILL }
369         },
370
371 };
372
373
374 /* Setup protocol subtree array */
375 static gint *ett[] = {
376         &ett_foo,
377 };
378 ]]>     
379    </programlisting></example>
380         <para>
381         Then, after the registration code, we register these arrays.
382         </para>
383            <example><title>Plugin Registering data structures.</title>
384    <programlisting>
385    <![CDATA[
386
387         proto_register_field_array(proto_foo, hf, array_length(hf));
388         proto_register_subtree_array(ett, array_length(ett));
389 ]]>     
390    </programlisting></example>
391         <para>
392         The variables hf_foo_pdu_type and ett_foo also need to be declared
393         somewhere near the top of the file.
394         </para>
395            <example><title>Plugin data structure globals.</title>
396    <programlisting>
397    <![CDATA[
398 static int hf_foo_pdu_type = -1;
399
400 static gint ett_foo = -1;
401 ]]>     
402    </programlisting></example>
403         <para>
404         Now we can enhance the protocol display with some detail.
405         </para>
406            <example><title>Plugin starting to dissect the packets.</title>
407    <programlisting>
408    <![CDATA[
409         if (tree) { /* we are being asked for details */
410                 proto_item *ti = NULL;
411                 proto_tree *foo_tree = NULL;
412
413                 ti = proto_tree_add_item(tree, proto_foo, tvb, 0, -1, FALSE);
414                 foo_tree = proto_item_add_subtree(ti, ett_foo);
415                 proto_tree_add_item(foo_tree, hf_foo_pdu_type, tvb, 0, 1, FALSE);
416         }
417 ]]>     
418    </programlisting></example>
419         <para>
420         Now the dissection is starting to look more interesting. We have picked apart
421         our first bit of the protocol. One byte of data at the start of the packet
422         that defines the packet type for foo protocol.
423         </para>
424         <para>
425         The proto_item_add_subtree call has added a child node to the protocol tree
426         which is where we will do our detail dissection. The expansion of this
427         node is controlled by the ett_foo variable. This remembers if the node should
428         be expanded or not as you move between packets.
429         All subsequent dissection will be added to this tree, as you can see from the next call.
430         A call to proto_tree_add_item in the foo_tree, this time using the 
431         hf_foo_pdu_type to control the formatting of the item. The pdu type
432         is one byte of data, starting at 0. We assume it is in network order,
433         so that is why we use FALSE. Although for 1 byte there is no order issues
434         its best to keep right.
435         </para>
436         <para>
437         If we look in detail at the hf_foo_pdu_type declaration in the static array
438         we can see the details of the definition.
439         </para>
440         <itemizedlist>
441         <listitem><para>
442         hf_foo_pdu_type - the index for this node.
443         </para></listitem>
444         <listitem><para>
445         FOO PDU Type - the label for this item.
446         </para></listitem>
447         <listitem><para>
448         foo.type - this is the filter string. It enables us to type constructs such
449         as foo.type=1 into the filter box.
450         </para></listitem>
451         <listitem><para>
452         FT_UNIT8 - this specifies this item is an 8bit unsigned integer.
453         This tallies with our call above where we tell it to only look at one byte.
454         </para></listitem>
455         <listitem><para>
456         BASE_DEC - for an integer type, this tells it to be printed as a decimal
457         number. It could be BASE_HEX or BASE_OCT if that made more sense.
458         </para></listitem>
459         </itemizedlist>
460         <para>
461         We'll ignore the rest of the structure for now.
462         </para>
463         <para>
464         If you install this plugin and try it out, you'll see something that begins to look
465         useful. 
466         </para>
467         <para>
468         Now lets finish off dissecting the simple protocol. We need to add a few
469         more variables to the hf array, and a couple more procedure calls.
470         </para>
471            <example><title>Plugin wrapping up the packet dissection.</title>
472    <programlisting>
473    <![CDATA[
474 static int hf_foo_flags = -1;
475 static int hf_foo_sequenceno = -1;
476 static int hf_foo_initialip = -1;
477 ...
478         { &hf_foo_flags,
479         { "FOO PDU Flags",           "foo.flags",
480         FT_UINT8, BASE_HEX, NULL, 0x0,
481         "", HFILL }
482         },
483         { &hf_foo_sequenceno,
484         { "FOO PDU Sequence Number",           "foo.seqn",
485         FT_UINT16, BASE_DEC, NULL, 0x0,
486         "", HFILL }
487         },
488         { &hf_foo_initialip,
489         { "FOO PDU Initial IP",           "foo.initialip",
490         FT_IPv4, BASE_NONE, NULL, 0x0,
491         "", HFILL }
492         },
493 ...
494                 gint offset = 0;
495
496                 ti = proto_tree_add_item(tree, proto_foo, tvb, 0, -1, FALSE);
497                 foo_tree = proto_item_add_subtree(ti, ett_foo);
498                 proto_tree_add_item(foo_tree, hf_foo_pdu_type, tvb, offset, 1, FALSE); offset += 1;
499                 proto_tree_add_item(foo_tree, hf_foo_flags, tvb, offset, 1, FALSE); offset += 1;
500                 proto_tree_add_item(foo_tree, hf_foo_sequenceno, tvb, offset, 2, FALSE); offset += 2;
501                 proto_tree_add_item(foo_tree, hf_foo_initialip, tvb, offset, 4, FALSE); offset += 4;
502
503 ]]>     
504    </programlisting></example>
505    <para>
506    This dissects all the bits of this simple hypothetical protocol. We've introduced a new 
507    variable offset into the mix to help keep track of where we are in the packet dissection.
508    With these extra bits in place, the whole protocol is now dissected. 
509    </para>
510    </section>
511    <section><title>Improving the dissection information</title>
512    <para>
513    We can certainly improve the display of the proto with a bit of extra data.
514    The first step is to add some text labels. Lets start by labelling the packet types.
515    There is some useful support for this sort of thing by adding a couple of extra things.
516    First we add a simple table of type to name.
517    </para>
518            <example><title>Naming the packet types.</title>
519    <programlisting>
520    <![CDATA[
521 static const value_string packettypenames[] = {
522         { 1, "Initialise" },
523         { 2, "Terminate" },
524         { 3, "Data" },
525         { 0, NULL }
526 };
527 ]]>     
528    </programlisting></example>
529    <para>
530    This is a handy data structure that can be used to look up value to names.
531    There are routines to directly access this lookup table, but we don't need to
532    do that, as the support code already has that added in. We just have to give 
533    these details to the appropriate part of data, using the VALS macro.
534    </para>
535            <example><title>Adding Names to the protocol.</title>
536    <programlisting>
537    <![CDATA[
538         { &hf_foo_pdu_type,
539         { "FOO PDU Type",           "foo.type",
540         FT_UINT8, BASE_DEC, VALS(packettypenames), 0x0,
541         "", HFILL }
542         },
543 ]]>     
544    </programlisting></example>
545     <para>
546     This helps in deciphering the packets, and we can do a similar thing for the
547     flags structure. For this we need to add some more data to the table though.
548     </para>
549            <example><title>Adding Flags to the protocol.</title>
550    <programlisting>
551    <![CDATA[
552 #define FOO_START_FLAG  0x01
553 #define FOO_END_FLAG            0x02
554 #define FOO_PRIORITY_FLAG       0x04
555
556 static int hf_foo_startflag = -1;
557 static int hf_foo_endflag = -1;
558 static int hf_foo_priorityflag = -1;
559 ...
560         { &hf_foo_startflag,
561         { "FOO PDU Start Flags",           "foo.flags.start",
562         FT_BOOLEAN, 8, NULL, FOO_START_FLAG,
563         "", HFILL }
564         },
565         { &hf_foo_endflag,
566         { "FOO PDU End Flags",           "foo.flags.end",
567         FT_BOOLEAN, 8, NULL, FOO_END_FLAG,
568         "", HFILL }
569         },
570         { &hf_foo_priorityflag,
571         { "FOO PDU Priority Flags",           "foo.flags.priority",
572         FT_BOOLEAN, 8, NULL, FOO_PRIORITY_FLAG,
573         "", HFILL }
574         },
575 ...
576         proto_tree_add_item(foo_tree, hf_foo_flags, tvb, offset, 1, FALSE);
577         proto_tree_add_item(foo_tree, hf_foo_startflag, tvb, offset, 1, FALSE);
578         proto_tree_add_item(foo_tree, hf_foo_endflag, tvb, offset, 1, FALSE);
579         proto_tree_add_item(foo_tree, hf_foo_priorityflag, tvb, offset, 1, FALSE); offset += 1;
580 ]]>     
581    </programlisting></example>
582    <para>
583    Some things to note here. For the flags, as each bit is a different flag, we use
584    the type FT_BOOLEAN, as the flag is either on or off. Second, we include the flag
585    mask in the 7th field of the data, which allows the system to mask the relevant bit.
586    We've also changed the 5th field to 8, to indicate that we are looking at an 8 bit 
587    quantity when the flags are extracted. Then finally we add the extra constructs
588    to the dissection routine. Note we keep the same offset for each of the flags.
589    </para>
590    <para>
591    This is starting to look fairly full featured now, but there are a couple of other
592    things we can do to make things look even more pretty. At the moment our dissection
593    shows the packets as "Foo Protocol" which whilst correct is a little uninformative.
594    We can enhance this by adding a little more detail.
595    First, lets get hold of the actual value of the protocol type. We can use the handy
596    function tvb_get_guint8 to do this.
597    With this value in hand, there are a couple of things we can do.
598    First we can set the INFO column of the non-detailed view to show what sort of 
599    PDU it is - which is extremely helpful when looking at protocol traces.
600    Second, we can also display this information in the dissection window.
601    </para>
602            <example><title>Enhancing the display.</title>
603    <programlisting>
604    <![CDATA[
605 static void
606 dissect_foo(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
607 {
608         guint8 packet_type = tvb_get_guint8(tvb, 0);
609
610         if (check_col(pinfo->cinfo, COL_PROTOCOL))
611                 col_set_str(pinfo->cinfo, COL_PROTOCOL, "FOO");
612         /* Clear out stuff in the info column */
613         if(check_col(pinfo->cinfo,COL_INFO)){
614                 col_clear(pinfo->cinfo,COL_INFO);
615         }
616         if (check_col(pinfo->cinfo, COL_INFO)) {
617                 col_add_fstr(pinfo->cinfo, COL_INFO, "Type %s",
618                            val_to_str(packet_type, packettypenames, "Unknown (0x%02x)"));
619         }
620
621         if (tree) { /* we are being asked for details */
622                 proto_item *ti = NULL;
623                 proto_tree *foo_tree = NULL;
624                 gint offset = 0;
625
626                 ti = proto_tree_add_item(tree, proto_foo, tvb, 0, -1, FALSE);
627                 proto_item_append_text(ti, ", Type %s",
628                         val_to_str(packet_type, packettypenames, "Unknown (0x%02x)"));
629                 foo_tree = proto_item_add_subtree(ti, ett_foo);
630                 proto_tree_add_item(foo_tree, hf_foo_pdu_type, tvb, offset, 1, FALSE); offset += 1;
631 ...
632 ]]>
633    </programlisting></example>
634    <para>
635    So here, after grabbing the value of the first 8 bits, we use it with one of the
636    built in utility routines val_to_str, to lookup the value. If the value isn't 
637    found we provide a fallback which just prints the value in hex. 
638    We use this twice, once in the INFO field of the columns - if its displayed, and
639    similarly we append this data to the base of our dissecting tree.
640    </para>
641
642    </section>
643   </section>
644
645   <section id="ChDissectTransformed">
646         <title>How to handle transformed data</title>
647         <para>
648         Some protocols do clever things with data. They might possibly 
649         encrypt the data, or compress data, or part of it. If you know
650         how these steps are taken it is possible to reverse them within the
651         dissector. 
652         </para>
653         <para> 
654         As encryption can be tricky, lets consider the case of compression.
655         These techniques can also work for other transformations of data,
656         where some step is required before the data can be examined.
657         </para>
658         <para> 
659         What basically needs to happen here, is to identify the data that
660         needs conversion, take that data and transform it into a new stream,
661         and then call a dissector on it.
662         Often this needs to be done "on-the-fly" based on clues in the packet.
663         Sometimes this needs to be used in conjunction with other techniques,
664         such as packet reassembly. The following shows a technique to
665         achieve this effect.
666         </para>
667            <example><title>Decompressing data packets for dissection.</title>
668    <programlisting>
669    <![CDATA[
670         guint8 flags = tvb_get_guint8(tvb, offset); offset ++;
671         if (flags & FLAG_COMPRESSED) { /* the remainder of the packet is compressed */
672                 guint16 orig_size = tvb_get_ntohs(tvb, offset); offset += 2;
673                 guchar *decompressed_buffer; /* Buffers for decompression */
674                 decompressed_buffer = (guchar*) g_malloc (orig_size);
675                 decompress_packet (tvb_get_ptr(tvb, offset, -1), tvb_length_remaining(tvb, offset),
676                                 decompressed_buffer, orig_size);
677                 /* Now re-setup the tvb buffer to have the new data */
678                 next_tvb = tvb_new_real_data(decompressed_buffer, orig_size, orig_size);
679                 tvb_set_child_real_data_tvbuff(tvb, next_tvb);
680                 add_new_data_source(pinfo, next_tvb, "Decompressed Data");
681                 tvb_set_free_cb(next_tvb, g_free);
682         } else {
683                 next_tvb = tvb_new_subset(tvb, offset, -1, -1);
684         }
685         offset = 0;
686         /* process next_tvb from here on */
687 ]]>
688    </programlisting></example>
689         <para>
690         The first steps here are to recognise the compression. In this case
691         a flag byte alerts us to the fact the remainder of the packet is compressed.
692         Next we retrieve the original size of the packet, which in this case
693         is conveniently within the protocol. If its not, it may be part of the 
694         compression routine to work it out for you, in which case the logic would
695         be different.
696         </para>
697         <para>
698         So armed with the size, a buffer is allocated to receive the uncompressed
699         data using g_malloc, and the packet is decompressed into it.
700         The tvb_get_ptr function is useful to get a pointer to the raw data of 
701         the packet from the offset onwards. In this case the 
702         decompression routine also needs to know the length, which is
703         given by the tvb_length_remaining function.
704         </para>
705         <para>
706         Next we build a new tvb buffer from this data, using the tvb_new_real_data
707         call. This data is a child of our original data, so we acknowledge that
708         in the next call to tvb_set_child_real_data_tvbuff. 
709         Finally we add this data as a new data source, so that
710         the detailed display can show the decompressed bytes as well as the original.
711         One procedural step is to add a handler to free the data when its no longer needed.
712         In this case as g_malloc was used to allocate the memory, g_free is the appropriate
713         function.
714         </para>
715         <para> 
716         After this has been set up the remainder of the dissector can dissect the
717         buffer next_tvb, as its a new buffer the offset needs to be 0 as we start
718         again from the beginning of this buffer. To make the rest of the dissector
719         work regardless of whether compression was involved or not, in the case that
720         compression was not signaled, we use the tvb_new_subset to deliver us
721         a new buffer based on the old one but starting at the current offset, and
722         extending to the end. This makes dissecting the packet from this point on
723         exactly the same regardless of compression.
724         </para>
725   </section>
726   <section id="ChDissectReassemble">
727         <title>How to reassemble split packets</title>
728         <para>
729         Some protocols have times when they have to split a large packet across
730         multiple other packets. In this case the dissection can't be carried out correctly
731         until you have all the data. The first packet doesn't have enough data,
732         and the subsequent packets don't have the expect format.
733         To dissect these packets you need to wait until all the parts have
734         arrived and then start the dissection.
735         </para>
736           <section id="ChDissectReassembleUdp">
737                 <title>How to reassemble split UDP packets</title>
738                 <para>
739                 As an example, lets examine a protocol that is layered on
740                 top of UDP that splits up its own data stream.
741                 If a packet is bigger than some given size, it will be split into
742                 chunks, and somehow signaled within its protocol.
743                 </para>
744                 <para>
745                 To deal with such streams, we need several things to trigger
746                 from. We need to know that this packet is part of a multi-packet 
747                 sequence. We need to know how many packets are in the sequence.
748                 We also need to know when we have all the packets.
749                 </para>
750                 <para>
751                 For this example we'll assume there is a simple in-protocol
752                 signaling mechanism to give details. A flag byte that signals
753                 the presence of a multi-packet sequence and also the last packet, 
754                 followed by an ID of the sequence and a packet sequence number.
755                 </para>
756                 <programlisting>
757 <![CDATA[
758 msg_pkt ::= SEQUENCE {
759         .....
760         flags ::= SEQUENCE {
761                 fragment        BOOLEAN,
762                 last_fragment   BOOLEAN,
763         .....
764         }
765         msg_id  INTEGER(0..65535),
766         frag_id INTEGER(0..65535),
767         .....
768 }
769 ]]>
770                 </programlisting>
771            <example><title>Reassembling fragments - Part 1</title>
772    <programlisting>
773    <![CDATA[
774 #include <epan/reassemble.h>
775    ...
776 save_fragmented = pinfo->fragmented;
777 flags = tvb_get_guint8(tvb, offset); offset++;
778 if (flags & FL_FRAGMENT) { /* fragmented */
779         tvbuff_t* new_tvb = NULL;
780         fragment_data *frag_msg = NULL;
781         guint16 msg_seqid = tvb_get_ntohs(tvb, offset); offset += 2;
782         guint16 msg_num = tvb_get_ntohs(tvb, offset); offset += 2;
783
784         pinfo->fragmented = TRUE;
785         frag_msg = fragment_add_seq_check(tvb, offset, pinfo,
786                 msg_seqid, /* ID for fragments belonging together */
787                 msg_fragment_table, /* list of message fragments */
788                 msg_reassembled_table, /* list of reassembled messages */
789                 msg_num, /* fragment sequence number */
790                 tvb_length_remaining(tvb, offset), /* fragment length - to the end */
791                 flags & FL_FRAG_LAST); /* More fragments? */
792 ]]>
793    </programlisting></example>
794         <para>
795         We start by saving the fragmented state of this packet, so we can restore it later.
796         Next comes some protocol specific stuff, to dig the fragment data
797         out of the stream if it's present. Having decided it is present, we 
798         let the function fragment_add_seq_check do its work.
799         We need to provide this with a certain amount of data.
800         </para>
801         <itemizedlist>
802         <listitem><para>
803         The tvb buffer we are dissecting.
804         </para></listitem>
805         <listitem><para>
806         The offset where the partial packet starts.
807         </para></listitem>
808         <listitem><para>
809         The provided packet info.
810         </para></listitem>
811         <listitem><para>
812         The sequence number of the fragment stream. There may be several 
813         streams of fragments in flight, and this is used to key the 
814         relevant one to be used for reassembly.
815         </para></listitem>
816         <listitem><para>
817         The msg_fragment_table and the msg_reassembled_table are variables
818         we need to declare. We'll consider these in detail later.
819         </para></listitem>
820         <listitem><para>
821         msg_num is the packet number within the sequence. 
822         </para></listitem>
823         <listitem><para>
824         The length here is specified as the rest of the tvb as we want the rest of the packet data. 
825         </para></listitem>
826         <listitem><para>
827         Finally a parameter that signals if this is the last fragment or not.
828         This might be a flag as in this case, or there may be a counter in the
829         protocol.
830         </para></listitem>
831         </itemizedlist>
832            <example><title>Reassembling fragments part 2</title>
833            <programlisting>
834            <![CDATA[
835         new_tvb = process_reassembled_data(tvb, offset, pinfo,
836                 "Reassembled Message", frag_msg, &msg_frag_items,
837                 NULL, msg_tree);
838
839         if (frag_msg) { /* Reassembled */
840                 if (check_col(pinfo->cinfo, COL_INFO))
841                         col_append_str(pinfo->cinfo, COL_INFO, 
842                         " (Message Reassembled)");
843         } else { /* Not last packet of reassembled Short Message */
844                 if (check_col(pinfo->cinfo, COL_INFO))
845                         col_append_fstr(pinfo->cinfo, COL_INFO,
846                         " (Message fragment %u)", msg_num);
847         }
848
849         if (new_tvb) { /* take it all */
850                 next_tvb = new_tvb;
851         } else { /* make a new subset */
852                 next_tvb = tvb_new_subset(tvb, offset, -1, -1);
853         }
854 }
855 else { /* Not fragmented */
856         next_tvb = tvb_new_subset(tvb, offset, -1, -1);
857 }
858
859 .....
860 pinfo->fragmented = save_fragmented;
861         ]]>
862    </programlisting></example>
863            <para>
864            Having passed the fragment data to the reassembly handler, we can
865            now check if we have the whole message. If there is enough information, 
866            this routine will return the newly reassembled data buffer. 
867            </para>
868            <para>
869            After that, we add a couple of informative messages to the display
870            to show that this is part of a sequence. Then a bit of manipulation
871            of the buffers and the dissection can proceed.
872            Normally you will probably not bother dissecting further unless the 
873            fragments have been reassembled as there won't be much to find. Sometimes
874            the first packet in the sequence can be partially decoded though if you wish.
875            </para>
876            <para>
877            Now the mysterious data we passed into the fragment_add_seq_check.
878            </para>
879            <example><title>Reassembling fragments - Initialisation</title>
880            <programlisting>
881            <![CDATA[
882 static GHashTable *msg_fragment_table = NULL;
883 static GHashTable *msg_reassembled_table = NULL;
884
885
886 static void
887 msg_init_protocol(void)
888 {
889         fragment_table_init (&msg_fragment_table);
890         reassembled_table_init(&msg_reassembled_table);
891 }
892 ]]>
893    </programlisting></example>
894         <para>
895         First a couple of hash tables are declared, and these are initialised
896         in the protocol initialisation routine.
897         Following that, a fragment_items structure is allocated and filled 
898         in with a series of ett items, hf data items, and a string tag.
899         The ett and hf values should be included in the relevant tables like
900         all the other variables your protocol may use. The hf variables
901         need to be placed in the structure something like the following.
902         Of course the names may need to be adjusted.
903         </para>
904            <example><title>Reassembling fragments - Data</title>
905            <programlisting>
906            <![CDATA[
907 ...
908 static int hf_msg_fragments = -1;
909 static int hf_msg_fragment = -1;
910 static int hf_msg_fragment_overlap = -1;
911 static int hf_msg_fragment_overlap_conflicts = -1;
912 static int hf_msg_fragment_multiple_tails = -1;
913 static int hf_msg_fragment_too_long_fragment = -1;
914 static int hf_msg_fragment_error = -1;
915 static int hf_msg_reassembled_in = -1;
916 ...
917 static gint ett_msg_fragment = -1;
918 static gint ett_msg_fragments = -1;
919 ...
920 static const fragment_items msg_frag_items = {
921         /* Fragment subtrees */
922         &ett_msg_fragment,
923         &ett_msg_fragments,
924         /* Fragment fields */
925         &hf_msg_fragments,
926         &hf_msg_fragment,
927         &hf_msg_fragment_overlap,
928         &hf_msg_fragment_overlap_conflicts,
929         &hf_msg_fragment_multiple_tails,
930         &hf_msg_fragment_too_long_fragment,
931         &hf_msg_fragment_error,
932         /* Reassembled in field */
933         &hf_msg_reassembled_in,
934         /* Tag */
935         "Message fragments"
936 };
937 ...
938 static hf_register_info hf[] = 
939 {
940 ...
941 {&hf_msg_fragments,
942         {"Message fragments", "msg.fragments",
943         FT_NONE, BASE_NONE, NULL, 0x00, NULL, HFILL } },
944 {&hf_msg_fragment,
945         {"Message fragment", "msg.fragment",
946         FT_FRAMENUM, BASE_NONE, NULL, 0x00, NULL, HFILL } },
947 {&hf_msg_fragment_overlap,
948         {"Message fragment overlap", "msg.fragment.overlap",
949         FT_BOOLEAN, BASE_NONE, NULL, 0x00, NULL, HFILL } },
950 {&hf_msg_fragment_overlap_conflicts,
951         {"Message fragment overlapping with conflicting data",
952         "msg.fragment.overlap.conflicts",
953         FT_BOOLEAN, BASE_NONE, NULL, 0x00, NULL, HFILL } },
954 {&hf_msg_fragment_multiple_tails,
955         {"Message has multiple tail fragments",
956         "msg.fragment.multiple_tails", 
957         FT_BOOLEAN, BASE_NONE, NULL, 0x00, NULL, HFILL } },
958 {&hf_msg_fragment_too_long_fragment,
959         {"Message fragment too long", "msg.fragment.too_long_fragment",
960         FT_BOOLEAN, BASE_NONE, NULL, 0x00, NULL, HFILL } },
961 {&hf_msg_fragment_error,
962         {"Message defragmentation error", "msg.fragment.error",
963         FT_FRAMENUM, BASE_NONE, NULL, 0x00, NULL, HFILL } },
964 {&hf_msg_reassembled_in,
965         {"Reassembled in", "msg.reassembled.in",
966         FT_FRAMENUM, BASE_NONE, NULL, 0x00, NULL, HFILL } },
967 ...
968 static gint *ett[] = 
969 {
970 ...
971 &ett_msg_fragment,
972 &ett_msg_fragments
973 ...
974 ]]>
975    </programlisting></example>
976    <para>
977    These hf variables are used internally within the reassembly routines
978    to make useful links, and to add data to the dissection. It produces 
979    links from one packet to another - such as a partial packet having 
980    a link to the fully reassembled packet. Likewise there are back pointers
981    to the individual packets from the reassembled one.
982    The other variables are used for flagging up errors.
983    </para>
984         </section>
985         <section id="TcpDissectPdus">
986                 <title>How to reassemble split TCP Packets</title>
987                 <para>  
988                         A dissector gets a tvbuff_t pointer which holds the payload
989                         of a TCP packet. This payload contains the header and data
990                         of your application layer protocol.
991                 </para>
992                 <para>
993                         When dissecting an application layer protocol you cannot assume
994                         that each TCP packet contains exactly one application layer message.
995                         One application layer message can be split into several TCP packets.
996                 </para>
997                 <para>
998                         You also cannot assume the a TCP packet contains only one application layer message
999                         and that the message header is at the start of your TCP payload.
1000                         More than one messages can be transmitted in one TCP packet,
1001                         so that a message can start at an abitrary position.
1002                         
1003                 </para>
1004                 <para>
1005                         This sounds complicated, but there is a simple solution.
1006                         <methodname>tcp_dissect_pdus()</methodname> does all this tcp packet reassembling for you.
1007                         This function is implemented in <filename>epan/dissectors/packet-tcp.h</filename>.
1008                 </para>
1009                 <example>
1010                         <title>Reassembling TCP fragments</title>
1011                         <programlisting>
1012 <![CDATA[
1013 #ifdef HAVE_CONFIG_H
1014 # include "config.h"
1015 #endif
1016
1017 #include <gmodule.h>
1018 #include <epan/packet.h>
1019 #include <epan/emem.h>
1020 #include <epan/dissectors/packet-tcp.h>
1021 #include <epan/prefs.h>
1022
1023 ...
1024
1025 #define FRAME_HEADER_LEN 8
1026
1027 /* The main dissecting routine */
1028 static void dissect_foo(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
1029 {
1030     tcp_dissect_pdus(tvb, pinfo, tree, TRUE, FRAME_HEADER_LEN,
1031                      get_foo_message_len, dissect_foo_message);
1032 }
1033
1034 /* This method dissects fully reassembled messages */
1035 static void dissect_foo_message(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
1036 {
1037     /* TODO: implement your dissecting code */
1038 }
1039
1040 /* determine PDU length of protocol foo */
1041 static guint get_foo_message_len(tvbuff_t *tvb, int offset)
1042 {
1043     /* TODO: change this to your needs */
1044     return (guint)tvb_get_ntohl(tvb, offset+4); /* e.g. length is at offset 4 */
1045 }
1046
1047 ...
1048 ]]>
1049                         </programlisting>
1050                 </example>
1051                 <para>
1052                         As you can see this is really simple. Just call <function>tcp_dissect_pdus()</function> in
1053                         your main dissection routine and move you message parsing code into another function.
1054                         This function gets called whenever a message has been reassembled.
1055                 </para>
1056                 <para>
1057                         The parameters <parameter>tvb</parameter>, <parameter>pinfo</parameter> and <parameter>tree</parameter> 
1058                         are just handed over to <function>tcp_dissect_pdus()</function>.
1059                         The 4th parameter is a flag to indicate if the data should be reassebled or not. This could be set 
1060                         according to a dissector preference as well.
1061                         Parameter 5 indicates how much data has at least to be available to be able to determine the length 
1062                         of the foo message.
1063                         Parameter 6 is a function pointer to a method that returns this length. It gets called when at least 
1064                         the number of bytes given in the previous parameter is available.
1065                         Parameter 7 is a function pointer to your real message dissector.
1066                 </para>
1067         </section>
1068   </section>
1069   <section id="ChDissectTap">
1070         <title>How to tap protocols</title>
1071         <para>
1072         Adding a Tap interface to a protocol allows it to do some useful things.
1073         In particular you can produce protocol statistics from teh tap interface.
1074         </para>
1075         <para>
1076         A tap is basically a way of allowing other items to see whats happening as
1077         a protocol is dissected. A tap is registered with the main program, and
1078         then called on each dissection. Some arbritary protocol specific data
1079         is provided with the routine that can be used.
1080         </para>
1081         <para>
1082         To create a tap, you first need to register a tap. 
1083         A tap is registered with an integer handle, and registered 
1084         with the routine register_tap. This takes a string name
1085         with which to find it again.
1086         </para>
1087            <example><title>Initialising a tap</title>
1088            <programlisting>
1089            <![CDATA[
1090 #include <epan/tap.h>
1091
1092 static int foo_tap = -1;
1093
1094 struct FooTap {
1095         gint packet_type;
1096         gint priorty;
1097         ...
1098 };
1099 ...
1100         foo_tap = register_tap("foo");
1101 ]]>
1102    </programlisting></example>
1103         <para>
1104         Whilst you can program a tap without protocol specific data, it
1105         is generally not very useful. Therefore its a good idea
1106         to declare a structure that can be passed through the tap.
1107         This needs to be a static structure as it will be used after the
1108         dissection routine has returned. Its generally best to pick out some
1109         generic parts of the protocol you are dissecting into the tap data.
1110         A packet type, a priority, a status code maybe.
1111         The structure really needs to be included in a header file so
1112         that it can be included by other components that want to listen in
1113         to the tap.
1114         </para>
1115         <para>
1116         Once you have these defined, its simply a case of populating the
1117         protocol specific structure and then calling tap_queue_packet probably
1118         as the last part of the dissector.
1119         </para>
1120            <example><title>Calling a protocol tap</title>
1121            <programlisting>
1122            <![CDATA[
1123         static struct FooTap pinfo;
1124         
1125         pinfo.packet_type = tvb_get_guint8(tvb, 0);
1126         pinfo.priority = tvb_get_ntohs(tvb, 8);
1127            ...
1128         tap_queue_packet(foo_tap, pinfo, &pinfo);
1129 ]]>
1130    </programlisting></example>
1131         <para>  
1132         This now enables those interested parties to listen in on the details
1133         of this protocol conversation.
1134         </para>
1135   </section>
1136   <section id="ChDissectStats">
1137         <title>How to produce protocol stats</title>
1138         <para>
1139         Given that you have a tap interface for the protocol, you can use this
1140         to produce some interesting statistics (well presumably interesting!) from
1141         protocol traces.
1142         </para>
1143         <para>
1144         This can be done in a separate plugin, or in the same plugin that is 
1145         doing the dissection. The latter scheme is better, as the tap and stats
1146         module typically rely on sharing protocol specific data, which might get out
1147         of step between two different plugins.
1148         </para>
1149         <para> 
1150         Here is a mechanism to produce statistics from the above TAP interface.
1151         </para>
1152            <example><title>Initialising a stats interface</title>
1153            <programlisting>
1154            <![CDATA[
1155 /* register all http trees */
1156 static void register_foo_stat_trees(void) {
1157         stats_tree_register("foo","foo","Foo/Packet Types", 
1158                 foo_stats_tree_packet, foo_stats_tree_init, NULL );
1159 }
1160 #ifndef ENABLE_STATIC
1161 //G_MODULE_EXPORT const gchar version[] = "0.0";
1162
1163 G_MODULE_EXPORT void plugin_register_tap_listener(void)
1164 {
1165         register_foo_stat_trees();
1166 }
1167
1168 #endif
1169 ]]>
1170    </programlisting></example>
1171         <para>
1172         Working from the bottom up, first the plugin interface entry point is defined,
1173         plugin_register_tap_listener. This simply calls the initialisation function
1174         register_foo_stat_trees.
1175         </para>
1176         <para>
1177         This in turn calls the stats_tree_register function, which takes
1178         three strings, and three functions.
1179         </para>
1180         <orderedlist>
1181         <listitem><para>
1182         This is the tap name that is registered.
1183         </para></listitem>
1184         <listitem><para>
1185         An abbreviation of the stats name.
1186         </para></listitem>
1187         <listitem><para>
1188         The name of the stats module. A '/' character can be used to make sub menus.
1189         </para></listitem>
1190         <listitem><para>
1191         The function that will called to generate the stats.
1192         </para></listitem>
1193         <listitem><para>
1194         A function that can be called to initialise the stats data.
1195         </para></listitem>
1196         <listitem><para>
1197         A function that will be called to clean up the stats data.
1198         </para></listitem>
1199         </orderedlist>
1200         <para>
1201         In this case we only need the first two functions, as there is nothing specific to clean up.
1202         </para>
1203            <example><title>Initialising a stats session</title>
1204            <programlisting>
1205            <![CDATA[
1206 static const guint8* st_str_packets = "Total Packets";
1207 static const guint8* st_str_packet_types = "FOO Packet Types";
1208 static int st_node_packets = -1;
1209 static int st_node_packet_types = -1;
1210
1211 static void foo_stats_tree_init(stats_tree* st) {
1212         st_node_packets = stats_tree_create_node(st, st_str_packets, 0, TRUE);  
1213                 st_node_packet_types = stats_tree_create_pivot(st, st_str_packet_types, st_node_packets);
1214 }
1215 ]]>
1216    </programlisting></example>
1217         <para>
1218         In this case we create a new tree node, to handle the total packets,
1219         and as a child of that we create a pivot table to handle the stats about 
1220         different packet types.
1221         </para>
1222            <example><title>Generating the stats</title>
1223            <programlisting>
1224            <![CDATA[
1225 static int foo_stats_tree_packet(stats_tree* st, packet_info* pinfo , epan_dissect_t* edt , const void* p) {
1226         struct FooTap *pi = (struct FooTap *)p;
1227         tick_stat_node(st, st_str_packets, 0, FALSE);
1228         stats_tree_tick_pivot(st, st_node_packet_types, 
1229                         val_to_str(pi->packet_type, msgtypevalues, "Unknown packet type (%d)"));
1230         return 1;
1231 }       
1232 ]]>
1233    </programlisting></example>
1234         <para>
1235         In this case the processing of the stats is quite simple.
1236         First we call the tick_stat_node for the st_str_packets packet node, to count
1237         packets.
1238         Then a call to stats_tree_tick_pivot on the st_node_packet_types subtree
1239         allows us to record statistics by packet type.
1240         </para>
1241   </section>
1242
1243   <section id="ChDissectConversation">
1244         <title>How to use conversations</title>
1245         <para>
1246         Some info about how to use conversations in a dissector can be 
1247         found in the file doc/README.developer.
1248         </para>
1249   </section>
1250
1251 </chapter>
1252 <!-- End of WSDG Chapter Dissection -->