1 Protocol Dissection in XML Format
2 =================================
4 Copyright (c) 2003 by Gilbert Ramirez <gram@alumni.rice.edu>
7 Ethereal has the ability to export its protocol dissection in an
8 XML format, tshark has similar functionality by using the "-Tpdml"
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:
15 http://analyzer.polito.it/30alpha/docs/dissectors/PDMLSpec.htm
17 A related XML format, the Packet Summary Markup Language (PSML), is
18 also defined by the Analyzer group to provide packet summary information.
19 The PSML format is not documented in a publicly-available HTML document,
20 but its format is simple. Ethereal can export this format too. Some day it
21 may be added to tshark so that "-Tpsml" would produce PSML.
23 One wonders if the "-T" option should read "-Txml" instead of "-Tpdml"
24 (and in the future, "-Tpsml"), but if tshark was required to produce
25 another XML-based format of its protocol dissection, then "-Txml" would
30 The PDML that wireshark produces is known not to be loadable into Analyzer.
31 It causes Analyzer to crash. As such, the PDML that wireshark produces
32 is be labled with a version number of "0", which means that the PDML does
33 not fully follow the PDML spec. Furthemore, a creator attribute in the
34 "<pdml>" tag gives the version number of [t]ethereal that produced the PDML.
35 In that way, as the PDML produced by wireshark matures, but still does not
36 meet the PDML spec, scripts can make intelligent decisions about how to
37 best parse the PDML, based on the "creator" attribute.
39 A PDML file is delimited by a "<pdml>" tag.
40 A PDML file contains multiple packets, denoted by the "<packet>" tag.
41 A packet will contain multiple protocols, denoted by the "<proto>" tag.
42 A protocol might contain one or more fields, denoted by the "<field>" tag.
44 A pseudo-protocol named "geninfo" is produced, as is required by the PDML
45 spec, and exported as the first protocol after the opening "<packet>" tag.
46 Its information comes from ethereal's "frame" protocol, which servers
47 the similar purpose of storing packet meta-data. Both "geninfo" and
48 "frame" protocols are provided in the PDML output.
53 <pdml version="0" creator="ethereal/0.9.17">
55 The creator is "ethereal" (i.e., the "ethereal" engine. It will always say
56 "ethereal", not "tshark") version 0.9.17.
61 "<proto>" tags can have the following attributes:
63 name - the display filter name for the protocol
64 showname - the label used to describe this protocol in the protocol
65 tree. This is usually the descriptive name of the protocol,
66 but it can be modified by dissectors to include more data
68 pos - the starting offset within the packet data where this
70 size - the number of octets in the packet data that this protocol
75 "<field>" tags can have the following attributes:
77 name - the display filter name for the field
78 showname - the label used to describe this field in the protocol
79 tree. This is usually the descriptive name of the protocol,
80 followed by some represention of the value.
81 pos - the starting offset within the packet data where this
83 size - the number of octets in the packet data that this field
85 value - the actual packet data, in hex, that this field covers
86 show - the representation of the packet data ('value') as it would
87 appear in a display filter.
89 Some dissectors sometimes place text into the protocol tree, without using
90 a field with a field-name. Those appear in PDML as "<field>" tags with no
91 'name' attribute, but with a 'show' attribute giving that text.
93 Many dissectors label the undissected payload of a protocol as belonging
94 to a "data" protocol, and the "data" protocol usually resided inside
95 that last protocol dissected. In the PDML, The "data" protocol becomes
96 a "data" field, placed exactly where the "data" protocol is in wireshark's
97 protocol tree. So, if wireshark would normally show:
111 In PDML, the "Data" protocol would become another field under HTTP:
132 <field name="data" value="........."/>
140 This is a python module which provides some infrastructor for
141 Python developers who wish to parse PDML. It is designed to read
142 a PDML file and call a user's callback function every time a packet
143 is constructed from the protocols and fields for a single packet.
145 The python user should import the module, define a callback function
146 which accepts one argument, and call the parse_fh function:
148 ------------------------------------------------------------
151 def my_callback(packet):
154 fh = open(xml_filename)
155 EtherealXML.parse_fh(fh, my_callback)
157 # Now that the script has the packet data, do someting.
158 ------------------------------------------------------------
160 The object that is passed to the callback function is an
161 EtherealXML.Packet object, which corresponds to a single packet.
162 EtherealXML Provides 3 classes, each of which corresponds to a PDML tag:
164 Packet - "<packet>" tag
165 Protocol - "<proto>" tag
166 Field - "<field>" tag
168 Each of these classes has accessors which will return the defined attributes:
177 Protocols and fields can contain other fields. Thus, the Protocol and
178 Field class have a "children" member, which is a simple list of the
179 Field objects, if any, that are contained. The "children" list can be
180 directly accessed by calling users. It will be empty of this Protocol
181 or Field contains no Fields.
183 Furthemore, the Packet class is a sub-class of the PacketList class.
184 The PacketList class provides methods to look for protocols and fields.
185 The term "item" is used when the item being looked for can be
186 a protocol or a field:
188 item_exists(name) - checks if an item exists in the PacketList
189 get_items(name) - returns a PacketList of all matching items
194 Generally, parsing XML is slow. If you're writing a script to parse
195 the PDML output of tshark, pass a read filter with "-R" to tshark to
196 try to reduce as much as possible the number of packets coming out of tshark.
197 The less your script has to process, the faster it will be.
199 'tools/msnchat' is a sample Python program that uses EtherealXML to parse PDML.
200 Given one or more capture files, it runs tshark on each of them, providing
201 a read filter to reduce tshark's output. It finds MSN Chat conversations
202 in the capture file and produces nice HTML showing the conversations. It has
203 only been tested with capture files containing non-simultaneous chat sessions,
204 but was written to more-or-less handle any number of simultanous chat