PDML Specification

PDML Specification
http://www.nbee.org/doku.php?id=netpdl:pdml_specification

The PDML language is a very simple language that keeps the information related to a decoded packet. PDML stands for Packet Details Markup Language and it is strongly related to NetPDL. This language is used by a NetPDL engine that understands the NetPDL Visualization Extension to create a detailed view of each packet. 

A detailed view of a packet is an XML file that contains all the most important information related to protocols and fields that are contained in one packet (e.g. the protocols, all the field names and their values, and more). The PDML specification is a way to organize this information. A PDML document lists all the packets contained in a capture file, detailing the most important information for every protocol that has been found in the packet and for each field that has been decoded within the protocol. 

Structure of a PDML document
The PDML document is delimited by the <pdml> and </pdml> tags. This tag contains a set of <packet> elements, which contains decoded packets. 

The <pdml> element can have the following attributes: 

Attribute Description 
version (optional) The version of the PDML specification. 
creator (optional) The creator of the current PDML file. For instance, any file created by the NetBee library has creator=“NetBee”. 
dissectors (optional) The date (in format dd-mm-yyyy) of the last update of the NetPDL protocol database that was used to create the current PDML file. 

The <packet> element has the following attributes: 

Attribute Description 
num (required) The number of the current packet within the capture. For instance, a value of “1” means that this is the first packet of the capture, and so on. 
len (required) The total length (in bytes) of the packet. 
caplen (required) The captured length (in bytes), i.e. the length of portion of the packet that has been captured. 
timestamp (required) The timestamp (according to the UNIX struct timeval structure) of the packet. This is the only field that has a non integer (float) value. 

An example of PDML document looks like: 

  <pdml>
    <packet>
      ...
    </packet>

    <packet>
      ...
    </packet>
    ...
  </pdml>Detailing the content of a packet: the <proto> element
A <packet> element can have one or more <proto> elements. The <proto> element keeps the name of one protocol and it has the following attributes: 

Attribute Description 
name (required) It contains the content of the name Field Visualization Variable that is associated to the current protocol. For instance, this means that this attribute contains the same string present in the name attribute of the originating <protocol> of the NetPDL document. 
longname (optional) It contains the content of the longname Field Visualization Variable that is associated to the current protocol. For instance, this means that this attribute contains the same string present in the longname attribute of the corresponding <protocol> of the NetPDL document. 
size (required) It contains the content of the size Field Visualization Variable that is associated to the current protocol. For instance, this means that this attribute contains the size (in bytes) of the headers of the current protocol. 
pos (required) It contains the content of the pos Field Visualization Variable that is associated to the current protocol. For instance, this means that this attribute contains the starting position (in bytes) of the headers of the current protocol. 

A <proto> element must have one or more <field> child elements. 

Detailing the content of a field: the <field> element
The <field> element contains the information related to a single field. Only NetPDL <field> elements can create a PDML <field> element. In case of a decoded field, there is no ambiguity concerning the field size or the number (and the type) of fields present in the protocol header. Therefore the PDML does not have the complexity of NetPDL because it does not have to manage variable fields, loops, conditional primitives, and more. 

The <field> element can have several attributes. These attributes correspond to the Field Visualization Variables that are associated to the current field. Supported attributes are the following: name, longname, value, showvalue, size, pos, mask, showmap and showdtl. For more details about their meaning, please check the appropriate section of the NetPDL Visualization Extension. Only the name, value, size and pos attributes are compulsory. However, note that it is not possible to recreate the complete dumped packet by parsing the PDML description. 

<field> elements can be nested. This is the case of a field that has some other subfield: a NetPDL <bitfield> field might create a nested tree of <field>. This is an example, extracted from the definition of the IP header that has some <bitfield> fields: 

NetPDL definition: 

  <protocol name="IP" longname="IPv4 (Internet Protocol version 4)">

    <format>
      <fields>
        <field type="fixed" name="verhlen" longname="Version and header Length">
          <field type="bit" name="ver" longname="Version" mask="F0"/>
          <field type="bit" name="hlen" longname="Header length" mask="0F"/>
        </field>

      ...Generated PDML fragment: 

    <proto name="IP" pos="15" longname="IPv4 (Internet Protocol version 4)" size="20">
      <field name="verhlen" pos="15" showvalue="45" longname="Version and header Length" size="1" value="45">
        <field mask="F0" name="ver" pos="15" showvalue="4" longname="Version" size="0" value="45" />
        <field mask="0F" name="hlen" pos="15" showvalue="5" longname="Header length" size="0" value="45" />

      </field>
      ...Example: an ICMP packet
This example shows a ICMP packet on an Ethernet network. This packet is made up of a geninfo protocol, then Ethernet, IP and ICMP. The example shows both the showdtl and showmap optional attributes (used, for example, to print detailed information about MAC addresses), and it shows also nested <field> elements (for example in case of the IP Flags and Fragment Offset field). 

<pdml>
  <packet num="4" len="74" caplen="74" timestamp="963585313.991300">
    <proto name="Ethernet" pos="1" longname="Ethernet 802.3" size="14">
      <field name="dst" pos="1" showvalue="000629-992da3" showdtl="000629-992da3 Unicast address (Vendor IBM RISC6000 system)" showmap="IBM RISC6000 system" longname="MAC Destination" size="6" value="000629992da3" />
      <field name="src" pos="7" showvalue="00e01e-ec3c84" showdtl="00e01e-ec3c84 Unicast address (Vendor Cisco)" showmap="Cisco" longname="MAC Source" size="6" value="00e01eec3c84" />
      <field name="type-length" pos="13" showvalue="0800" longname="Ethertype" size="2" value="0800" />

    </proto>
    <proto name="IP" pos="15" longname="IPv4 (Internet Protocol version 4)" size="20">
      <field name="verhlen" pos="15" showvalue="45" longname="Version and header Length" size="1" value="45">
        <field mask="F0" name="ver" pos="15" showvalue="45" longname="Version" size="0" value="4" />
        <field mask="0F" name="hlen" pos="15" showvalue="45" showdtl="20 (field value = 5)" longname="Header length" size="0" value="5" />
      </field>

      <field name="tos" pos="16" showvalue="00" longname="Type of service" size="1" value="00" />
      <field name="tlen" pos="17" showvalue="60" longname="Total length" size="2" value="003c" />
      <field name="identification" pos="19" showvalue="1094" longname="Identification" size="2" value="0446" />
      <field name="ffo" pos="21" showvalue="0000" longname="Flags and Fragment offset" size="2" value="0000">
        <field mask="8000" name="unused" pos="21" showvalue="0" longname="Unused" size="0" value="0000" />
        <field mask="4000" name="df" pos="21" showvalue="0" longname="Don't fragment" size="0" value="0000" />

        <field mask="2000" name="mf" pos="21" showvalue="0" longname="More fragments" size="0" value="0000" />
        <field mask="1FFF" name="foffset" pos="21" showvalue="0" showdtl="0 (field value = 0)" longname="Fragment offset" size="0" value="0000" />
      </field>
      <field name="ttl" pos="23" showvalue="127" longname="Time to live" size="1" value="7f" />
      <field name="nextp" pos="24" showvalue="1" longname="Next protocol" size="1" value="01" />
      <field name="hchecksum" pos="25" showvalue="d9bf" longname="Header Checksum" size="2" value="d9bf" />

      <field name="src" pos="27" showvalue="130.192.16.81" longname="Source address" size="4" value="82c01051" />
      <field name="dst" pos="31" showvalue="192.168.10.2" longname="Destination address" size="4" value="c0a80a02" />
    </proto>
    <proto name="ICMP" pos="35" longname="ICMP (Internet Control Message Protocol)" size="40">
      <field name="type" pos="35" showvalue="8" showmap="Echo Reply" longname="Type" size="1" value="08" />
      <field name="code" pos="36" showvalue="0" longname="Code" size="1" value="00" />

      <field name="checksum" pos="37" showvalue="245c" longname="Checksum" size="2" value="245c" />
      <field name="echoreply" pos="39" longname="Echo Reply" size="36">
        <field name="identifier" pos="39" showvalue="512" longname="Identifier" size="2" value="0200" />
        <field name="seqn" pos="41" showvalue="9984" longname="Sequence number" size="2" value="2700" />
        <field name="data" pos="43" showvalue="abcdefghijklmnopqrstuvwabcdefghi" longname="Padding Data" size="32" value="6162636465666768696a6b6c6d6e6f7071727374757677616263646566676869" />
      </field>

    </proto>
  </packet>
</pdml>An example of a default detailed view
A tool that wants to display a detailed view of the packet might use the following algorithm (in pseudo-code): 

  if exist(showdtl_attrib)
    print(longname_attrib, " = ", showdtl_attrib);
  else
    if exist(showmap_attrib)
      print(longname_attrib, " = ", showvalue_attrib, " (", showmap_attrib, ")" );
    else
      print(longname_attrib, " = ", showvalue_attrib)This pseudo-code shows how the information present into the PDML document can be used: if a detailed view is available (showdtl attribute), we can use that value for printing the field. Otherwise, we can print the field name (in “human” form by using the longname attribute) and its value (in “human” form by using the showvalue attribute); additionally, if the showmap attribute is available, we can print that attribute as well. 

Other attributes (like pos and size) can be used to enlighten the bytes corresponding to the current field in a dump view of the packet, i.e. a view in which only the hexadecimal dump of the packet is given. 

Relationship between NetPDL and PDML
The relationship between NetPDL and PDML is rather simple. The detailed view originates from the directives contained in the <showtemplate> element in the NetPDL visualization extension. For this element to be applied, the packet decoding has to be completed, i.e. Field Visualization Variables must be associated to all NetPDL fields. 

The procedure for creating the detailed view involves the execution of the directives present in the <showtemplate> NetPDL element, and coping the value of the required field/attributes from the NetPDL engine to the PDML document. 

XML Schema Definition
The XML schema definition of the PDML language can be found at the XSD Schema Page. 

Language license
The license of the PDML language can be found at the Language License Page.