doc/README.xml-output

   1 Protocol Dissection in XML Format
   2 =================================
   3 $Id$
   4 Copyright (c) 2003 by Gilbert Ramirez <gram@alumni.rice.edu>
   5
   6
   7 Wireshark has the ability to export its protocol dissection in an
   8 XML format, tshark has similar functionality by using the "-Tpdml"
   9 option.
  10
  11 The XML that wireshark produces follows the Packet Details Markup
  12 Language (PDML) specified by the group at the Politecnico Di Torino
  13 working on Analyzer. The specification can be found at:
  14
  15 http://analyzer.polito.it/30alpha/docs/dissectors/PDMLSpec.htm
  16
  17 That URL is not functioning any more, but a copy can be found at:
  18
  19 http://gd.tuwien.ac.at/.vhost/analyzer.polito.it/docs/dissectors/PDMLSpec.htm
  20
  21 A related XML format, the Packet Summary Markup Language (PSML), is
  22 also defined by the Analyzer group to provide packet summary information.
  23 The PSML format is not documented in a publicly-available HTML document,
  24 but its format is simple. Wireshark can export this format too. Some day it
  25 may be added to tshark so that "-Tpsml" would produce PSML.
  26
  27 One wonders if the "-T" option should read "-Txml" instead of "-Tpdml"
  28 (and in the future, "-Tpsml"), but if tshark was required to produce
  29 another XML-based format of its protocol dissection, then "-Txml" would
  30 be ambiguous.
  31
  32 PDML
  33 ====
  34 The PDML that wireshark produces is known not to be loadable into Analyzer.
  35 It causes Analyzer to crash. As such, the PDML that wireshark produces
  36 is be labeled with a version number of "0", which means that the PDML does
  37 not fully follow the PDML spec. Furthermore, a creator attribute in the
  38 "<pdml>" tag gives the version number of wireshark/tshark that produced the PDML.
  39 In that way, as the PDML produced by wireshark matures, but still does not
  40 meet the PDML spec, scripts can make intelligent decisions about how to
  41 best parse the PDML, based on the "creator" attribute.
  42
  43 A PDML file is delimited by a "<pdml>" tag.
  44 A PDML file contains multiple packets, denoted by the "<packet>" tag.
  45 A packet will contain multiple protocols, denoted by the "<proto>" tag.
  46 A protocol might contain one or more fields, denoted by the "<field>" tag.
  47
  48 A pseudo-protocol named "geninfo" is produced, as is required by the PDML
  49 spec, and exported as the first protocol after the opening "<packet>" tag.
  50 Its information comes from wireshark's "frame" protocol, which serves
  51 the similar purpose of storing packet meta-data. Both "geninfo" and
  52 "frame" protocols are provided in the PDML output.
  53
  54 The "<pdml>" tag
  55 ================
  56 Example:
  57         <pdml version="0" creator="wireshark/0.9.17">
  58
  59 The creator is "wireshark" (i.e., the "wireshark" engine. It will always say
  60 "wireshark", not "tshark") version 0.9.17.
  61
  62
  63 The "<proto>" tag
  64 =================
  65 "<proto>" tags can have the following attributes:
  66
  67         name - the display filter name for the protocol
  68         showname - the label used to describe this protocol in the protocol
  69                 tree. This is usually the descriptive name of the protocol,
  70                 but it can be modified by dissectors to include more data
  71                 (tcp can do this)
  72         pos - the starting offset within the packet data where this
  73                 protocol starts
  74         size - the number of octets in the packet data that this protocol
  75                 covers.
  76
  77 The "<field>" tag
  78 =================
  79 "<field>" tags can have the following attributes:
  80
  81         name - the display filter name for the field
  82         showname - the label used to describe this field in the protocol
  83                 tree. This is usually the descriptive name of the protocol,
  84                 followed by some representation of the value.
  85         pos - the starting offset within the packet data where this
  86                 field starts
  87         size - the number of octets in the packet data that this field
  88                 covers.
  89         value - the actual packet data, in hex, that this field covers
  90         show - the representation of the packet data ('value') as it would
  91                 appear in a display filter.
  92
  93 Some dissectors sometimes place text into the protocol tree, without using
  94 a field with a field-name. Those appear in PDML as "<field>" tags with no
  95 'name' attribute, but with a 'show' attribute giving that text.
  96
  97 Many dissectors label the undissected payload of a protocol as belonging
  98 to a "data" protocol, and the "data" protocol usually resided inside
  99 that last protocol dissected. In the PDML, The "data" protocol becomes
 100 a "data" field, placed exactly where the "data" protocol is in wireshark's
 101 protocol tree. So, if wireshark would normally show:
 102
 103 +-- Frame
 104 |
 105 +-- Ethernet
 106 |
 107 +-- IP
 108 |
 109 +-- TCP
 110 |
 111 +-- HTTP
 112     |
 113     +-- Data
 114
 115 In PDML, the "Data" protocol would become another field under HTTP:
 116
 117 <packet>
 118         <proto name="frame">
 119         ...
 120         </proto>
 121
 122         <proto name="eth">
 123         ...
 124         </proto>
 125
 126         <proto name="ip">
 127         ...
 128         </proto>
 129
 130         <proto name="tcp">
 131         ...
 132         </proto>
 133
 134         <proto name="http">
 135         ...
 136                 <field name="data" value="........."/>
 137         </proto>
 138 </packet>
 139
 140
 141
 142 tools/WiresharkXML.py
 143 ====================
 144 This is a python module which provides some infrastructure for
 145 Python developers who wish to parse PDML. It is designed to read
 146 a PDML file and call a user's callback function every time a packet
 147 is constructed from the protocols and fields for a single packet.
 148
 149 The python user should import the module, define a callback function
 150 which accepts one argument, and call the parse_fh function:
 151
 152 ------------------------------------------------------------
 153 import WiresharkXML
 154
 155 def my_callback(packet):
 156         # do something
 157
 158 # If the PDML is stored in a file, you can:
 159 fh = open(xml_filename)
 160 WiresharkXML.parse_fh(fh, my_callback)
 161
 162 # or, if the PDML is contained within a string, you can:
 163 WiresharkXML.parse_string(my_string, my_callback)
 164
 165 # Now that the script has the packet data, do something.
 166 ------------------------------------------------------------
 167
 168 The object that is passed to the callback function is an
 169 WiresharkXML.Packet object, which corresponds to a single packet.
 170 WiresharkXML Provides 3 classes, each of which corresponds to a PDML tag:
 171
 172         Packet   - "<packet>" tag
 173         Protocol - "<proto>" tag
 174         Field    - "<field>" tag
 175
 176 Each of these classes has accessors which will return the defined attributes:
 177
 178         get_name()
 179         get_showname()
 180         get_pos()
 181         get_size()
 182         get_value()
 183         get_show()
 184
 185 Protocols and fields can contain other fields. Thus, the Protocol and
 186 Field class have a "children" member, which is a simple list of the
 187 Field objects, if any, that are contained. The "children" list can be
 188 directly accessed by code using the object. The "children" list will be
 189 empty if this Protocol or Field contains no Fields.
 190
 191 Furthermore, the Packet class is a sub-class of the PacketList class.
 192 The PacketList class provides methods to look for protocols and fields.
 193 The term "item" is used when the item being looked for can be
 194 a protocol or a field:
 195
 196         item_exists(name) - checks if an item exists in the PacketList
 197         get_items(name) - returns a PacketList of all matching items
 198
 199
 200 General Notes
 201 =============
 202 Generally, parsing XML is slow. If you're writing a script to parse
 203 the PDML output of tshark, pass a read filter with "-R" to tshark to
 204 try to reduce as much as possible the number of packets coming out of tshark.
 205 The less your script has to process, the faster it will be.
 206
 207 'tools/msnchat' is a sample Python program that uses WiresharkXML to parse
 208 PDML. Given one or more capture files, it runs tshark on each of them,
 209 providing a read filter to reduce tshark's output. It finds MSN Chat
 210 conversations in the capture file and produces nice HTML showing the
 211 conversations. It has only been tested with capture files containing
 212 non-simultaneous chat sessions, but was written to more-or-less handle any
 213 number of simultaneous chat sessions.