doc/README.heuristic

   1 $Revision$
   2 $Date$
   3 $Author$
   4
   5
   6 This file is a HOWTO for Wireshark developers. It describes how Wireshark
   7 heuristic protocol dissectors work and how to write them.
   8
   9 This file is compiled to give in depth information on Wireshark.
  10 It is by no means all inclusive and complete. Please feel free to send
  11 remarks and patches to the developer mailing list.
  12
  13
  14 Prerequisites
  15 -------------
  16 As this file is an addition to README.developer, it is essential to read
  17 and understand that document first.
  18
  19
  20 Why heuristic dissectors?
  21 -------------------------
  22 When Wireshark "receives" a packet, it has to find the right dissector to
  23 start decoding the packet data. Often this can be done by known conventions,
  24 e.g. the Ethernet type 0x0800 means "IP on top of Ethernet" - an easy and
  25 reliable match for Wireshark.
  26
  27 Unfortunately, these conventions are not always available, or (accidentally
  28 or knowingly) some protocols don't care about those conventions and "reuse"
  29 existing "magic numbers / tokens".
  30
  31 For example TCP defines port 80 only for the use of HTTP traffic. But, this
  32 convention doesn't prevent anyone from using TCP port 80 for some different
  33 protocol, or on the other hand using HTTP on a port number different than 80.
  34
  35 To solve this problem, Wireshark introduced the so called heuristic dissector
  36 mechanism to try to deal with these problems.
  37
  38
  39 How Wireshark uses heuristic dissectors?
  40 ----------------------------------------
  41 While Wireshark starts, heuristic dissectors (HD) register themselves slightly
  42 different than "normal" dissectors, e.g. a HD can ask for any TCP packet, as
  43 it *may* contain interesting packet data for this dissector. In reality more
  44 than one HD will exist for e.g. TCP packet data.
  45
  46 So if Wireshark has to decode TCP packet data, it will first try to find a
  47 dissector registered directly for the TCP port used in that packet. If it
  48 finds such a registered dissector it will just hand over the packet data to it.
  49
  50 In case there is no such "normal" dissector, WS will hand over the packet data
  51 to the first matching HD. Now the HD will look into the data and decide if that
  52 data looks like something the dissector "is interested in". The return value
  53 signals WS if the HD processed the data (so WS can stop working on that packet)
  54 or if the heuristic didn't match (so WS tries the next HD until one matches -
  55 or the data simply can't be processed).
  56
  57 Note that it is possible to configure WS through preference settings so that it
  58 hands off a packet to the heuristic dissectors before the "normal" dissectors
  59 are called. This allows the HD the chance to receive packets and process them
  60 differently than they otherwise would be. Of course if no HD is interested in
  61 the packet, then the packet will ultimately get handed off to the "normal"
  62 dissector as if the HD wasn't involved at all. As of this writing, the DCCP,
  63 SCTP, TCP, TIPC and UDP dissectors all provide this capability via their
  64 "Try heuristic sub-dissectors first" preference, but none of them have this
  65 option enabled by default.
  66
  67 Once a packet for a particular "connection" has been identified as belonging
  68 to a particular protocol, Wireshark should then be set up to always directly
  69 call the dissector for that protocol. This removes the overhead of having
  70 to identify each packet of the connection heuristically.
  71
  72
  73 How do these heuristics work?
  74 -----------------------------
  75 It's difficult to give a general answer here. The usual heuristic works as follows:
  76
  77 A HD looks into the first few packet bytes and searches for common patterns that
  78 are specific to the protocol in question. Most protocols starts with a
  79 specific header, so a specific pattern may look like (synthetic example):
  80
  81 1) first byte must be 0x42
  82 2) second byte is a type field and can only contain values between 0x20 - 0x33
  83 3) third byte is a flag field, where the lower 4 bits always contain the value 0
  84 4) fourth and fifth bytes contain a 16 bit length field, where the value can't
  85    be larger than 10000 bytes
  86
  87 So the heuristic dissector will check incoming packet data for all of the
  88 4 above conditions, and only if all of the four conditions are true there is a
  89 good chance that the packet really contains the expected protocol - and the
  90 dissector continues to decode the packet data. If one condition fails, it's
  91 very certainly not the protocol in question and the dissector returns to WS
  92 immediately "this is not my protocol" - maybe some other heuristic dissector
  93 is interested!
  94
  95 Obviously, this is *not* 100% bullet proof, but it's the best WS can offer to
  96 its users here - and improving the heuristic is always possible if it turns out
  97 that it's not good enough to distinguish between two given protocols.
  98
  99
 100 Heuristic Code Example
 101 ----------------------
 102 You can find a lot of code examples in the Wireshark sources, e.g.:
 103 grep -l heur_dissector_add epan/dissectors/*.c
 104 returns 132 files (Feb 2013).
 105
 106 For the above example criteria, the following code example might do the work
 107 (combine this with the dissector skeleton in README.developer):
 108
 109 XXX - please note: The following code examples were not tried in reality,
 110 please report problems to the dev-list!
 111
 112 --------------------------------------------------------------------------------------------
 113 static dissector_handle_t PROTOABBREV_handle;
 114
 115 static void
 116 dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data _U_)
 117 {
 118     /* Dissection ... */
 119
 120     return;
 121 }
 122
 123
 124 static gboolean
 125 dissect_PROTOABBREV_heur(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data)
 126 {
 127 ...
 128
 129     /* 1) first byte must be 0x42 */
 130     if ( tvb_get_guint8(tvb, 0) != 0x42 )
 131         return (FALSE);
 132
 133     /* 2) second byte is a type field and only can contain values between 0x20-0x33 */
 134     if ( tvb_get_guint8(tvb, 1) < 0x20 || tvb_get_guint8(tvb, 1) > 0x33 )
 135         return (FALSE);
 136
 137     /* 3) third byte is a flag field, where the lower 4 bits always contain the value 0 */
 138     if ( tvb_get_guint8(tvb, 2) & 0x0f )
 139         return (FALSE);
 140
 141     /* 4) fourth and fifth bytes contains a 16 bit length field, where the value can't be longer than 10000 bytes */
 142     /* Assumes network byte order */
 143     if ( tvb_get_ntohs(tvb, 3) > 10000 )
 144         return (FALSE);
 145
 146     /* Assume it's your packet ... */
 147
 148     /*   specify that dissect_PROTOABBREV is to be called directly from now on for packets for this "connection" ... */
 149     conversation = find_or_create_conversation(pinfo);
 150     conversation_set_dissector(conversation, PROTOABBREV_handle);
 151
 152     /*   and do the dissection */
 153     dissect_PROTOABBREV(tvb, pinfo, tree, data);
 154
 155     return (TRUE);
 156 }
 157
 158
 159 void
 160 proto_reg_handoff_PROTOABBREV(void)
 161 {
 162     PROTOABBREV_handle = create_dissector_handle(dissect_PROTOABBREV,
 163                                                  proto_PROTOABBREV);
 164
 165     /* register as heuristic dissector for both TCP and UDP */
 166     heur_dissector_add("tcp", dissect_PROTOABBREV_heur, proto_PROTOABBREV);
 167     heur_dissector_add("udp", dissect_PROTOABBREV_heur, proto_PROTOABBREV);
 168
 169 #ifdef OPTIONAL
 170     /* It's possible to write a dissector to be a dual heuristic/normal dissector */
 171     /*  by also registering the dissector "normally".                             */
 172     dissector_add_uint("ip.proto", IP_PROTO_PROTOABBREV, PROTOABBREV_handle);
 173 #endif
 174 }
 175
 176
 177 Please note, that registering a heuristic dissector is only possible for a
 178 small variety of protocols. In most cases a heuristic is not needed, and
 179 adding the support would only add unused code to the dissector.
 180
 181 TCP and UDP are prominent examples that support HDs, as there seems to be a
 182 tendency to reuse known port numbers for new protocols. But TCP and UDP are
 183 not the only dissectors that provide support for HDs.  You can find more
 184 examples by searching the Wireshark sources as follows:
 185 grep -l register_heur_dissector_list epan/dissectors/packet-*.c
 186 returns 38 files (Feb 2013).
 187