PDML Specification

The PDML language is a very simple language that has been defined to keep the information related to a decoded packet. PDML stands for Packet Details Markup Language and it is strongly related to the 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 the protocols and the fields that are contained into the packet (e.g. the protocols, all the field names and their values, and more). The PDML specification is a way to organize this information and it lists all the packets within a capture file, detailing the most important information for every protocol that has been found into the packet and for each field thathas 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 the decoded packet.

Both <pdml> and <packet> do not have attributes.

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 keeps the name of the field according the the NetPDL specification. In other words, its value is equal to the value of the name attribute of the corresponding <proto> element into the NetPDL document.
showname (required) It keeps the name of the field in a 'human readable' form according the the NetPDL specification. In other words, its value is equal to the value of the showname attribute of the corresponding <protol> element into the NetPDL document.
size (required) It keeps the size (in bytes) of the headers of the current protocol. It is calculated at run-time by the NetPDL decoding engine according to the field sizes.
For instance, the Ethernet header of an Ethernet packet will have size equal to 14 (the Ethernet header is 14 bytes long).
pos (required) It keeps the starting position (in bytes) of the headers of the current protocol. It is calculated at run-time by the NetPDL decoding engine according the sizes of the preceding protocols.
For instance the position of an Ethernet header of an Ethernet packet will be equal to 1 (this header starts at the first byte of the packet dump); if the packet contains an IP header, the value of the pos attribute related to that protocol will be "14".

Note: although this value can be derived by checking the size attribute of all the preceding protocols, this number is also provided. This could help a XSL template applied to the PDML file, which can have an easy way to print graphically each element.

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

Detailing the content of a field: the <field> element

The <field> element contains the information related to a single field. Only the fields that are included into the NetPDL Standard Fields Section can create a PDML <field> element. For instance, NetPDL uses the <loop> element to control how many times a group of fields has to be repeated, but it is not actually a field.

In case of a decoded field, there is no ambiguity concerning the field size or the number (and the type) of fields present into the protocol header. Therefore the PDML does not have all the complexity of the NetPDL because it does not have to manage variable fields, loops, "if" conditions, and more.

The <field> element can have the following attributes:

Attribute Description
name (required) It keeps the name of the field according the the NetPDL specification. In other words, its value is equal to the value of the name attribute of the corresponding field of the NetPDL description.
showname (required) It keeps the name of the field in a 'human readable' form according the the NetPDL specification. In other words, its value is equal to the value of the showname attribute of the corresponding field of the NetPDL description. 
value (required) It keeps the field value as an hex string. In other words, the content of the value attribute in case of a 16 bit field whose value is 0800 (hex) is the string "0800".
unmaskedvalue (optional) This attribute is used only if the length of the current field is not an integer number of bytes. For instance, a field which is 4-bit wide belongs to this category. In this case, the size attribute is misleading because this size refers to the 'parent' field defined into the NetPDL specification. For instance, this attribute is used for PDML fields that derive from a <bit> field of the NetPDL specification, which must always be included within a <masked> field (that is the 'parent' field).

The unmaskedvalue attribute keeps the value of the field supposing that its length is equal to the parent field. For instance, a <masked> field with length equal to 1 byte, split in 2 <bit> fields of 4 bits each, will originate two <field> in the PDML description that have the unmaskedvalue attribute equal to the value of the <masked> field as a whole.

This attribute is required only for fields that derive from <bit> fields; in the other cases it can be omitted.
This attribute is used to speed up the reassembling of the hexadecimal dump of the packet starting from the PDML file.
show (required) It keeps the field value in a "printable" form. In other words, the content of the value attribute depends on the showsep, showgrp and showtype attributes of the corresponding field in the NetPDL description. For instance, let us suppose a 48 bit field (like the MAC address) described with the following attributes in the NetPDL language: 
    <... showtype="hex" showgrp="3" showsep="-">

If the field value is "ffffffffffff" (which is stored into the attribute value), the content of the show attribute will be "ffffff-ffffff". See the Standard Visualization Attributes Section in the NetPDL Visualization Extension for more details.
hide (optional) It tells the visualization engine if the field must be shown or not. This may be used in case of a field that contains a value that is meaningful when decoding data, but it is not significant when printing it. The PDML will contain this field (which can be used to re-create the hex dump of the packet), but it should not be shown on screen. Allowed values are:
  • no (default): the field should be shown on screen.
  • yes: the field is present in the packet, but it should not be shown on screen.
size (required) It keeps the size (in byte) of the current field. It is calculated at run-time by the NetPDL decoding engine (since the size of some fields, like the <variable> one, cannot be known a priori). It is equivalent to the same attribute defined for the <proto> element.
pos (required) It keeps the starting position (in byte) of the current field. It is calculated at run-time by the NetPDL decoding engine according to the size of all the preceding protocols / fields. It is equivalent to the same attribute defined for the <proto> element.
showmap (optional) There are some fields whose value can be associated with some meaning. For instance, the field code of an ICMP packet can be associated with the type of ICMP message: Echo Request, Echo Reply, and more. The showmap attribute keeps this kind of association: the value of this attribute will be a literal string that indicates the meaning of this field.

This attribute is optional because usually a field does not have such a mapping. This attribute is present only if the corresponding field of the NetPDL description has the showmap attribute. In this case, this attribute keeps the result of the lookup performed by the showmap attribute in the NetPDL description. See the showmap Section of the NetPDL Visualization Extension for more details.
showdtl (optional) There are some fields that require a more detailed explanation about their value. For instance, a MAC address can be a unicast address (and then we would like to know the vendor of the NIC card) or a multicast /broadcast address. The showdtl is an attribute that specify which description has to be associated to this field in case the standard description (basically the value of the field) is not enough.

This attribute is optional because usually a field does not need such a detailed view. This attribute is present only if the corresponding field of the NetPDL description has the showdtl attribute. In this case, this attribute keeps the result of the template specified by the showdtl attribute in the NetPDL description. See the showdtl Section of the NetPDL Visualization Extension for more details.

<field> elements can be nested. This is the case of a field that has some other subfield: a  NetPDL <masked> field (but also a NetPDL <option>) will create a nested tree of <field>. For instance, the <field> element that corresponds to a <masked> element into the NetPDL description will be the parent element, while all the <bit> element of the NetPDL description will originate a set of child <field> elements into the PDML document. This is an example, extracted from the definition of the IP header that has some <masked> fields:

NetPDL definition:

  <proto name="IP" showname="IPv4 (Internet Protocol version 4)">
    <fields>
      <masked name="verhlen" showname="Version and header Length" showtype="hex">
        <bit name="ver" showname="Version" mask="F0"/>
        <bit name="hlen" showname="Header length" mask="0F"/>
      </masked>
      ...

Generated PDML fragment:

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

A special protocol: the geninfo protocol

A special protocol has been defined for the PDML language which aims to keep all the general information related to the packet.

This protocol has a list of "fake" fields that contain some general information such as the number of the current packet within the capture, the length of the packet, and so on. This protocol is modeled after a set of fields with a predefined name (listed in the table below), whose value attribute keeps the value of the given information. The name of the fields that are present in this protocol are the following:

Content of the name attribute Description
num (required) The content of the value attribute is the number of the current packet within the capture. For instance, a value of "1" in the value attribute means that this is the first packet of the capture, and so on.
len (required) The content of the value attribute is the total length (in bytes) of the packet.
caplen (required) The content of the value attribute is the captured length (in bytes), i.e. the length of portion of the packet that has been captured.
timestamp (required) The content of the value attribute is the timestamp (according to the UNIX struct timeval structure) of the packet. This is the only field that has a non integer (float) value.
The show attribute related to this element will contain the timestamp formatted in a "human" form, e.g. 16:35:13.991300.

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>
    <proto name="geninfo" pos="1" showname="General information" size="74">
      <field name="num" pos="1" show="4" showname="Number" size="74" value="4" />
      <field name="len" pos="1" show="74" showname="Packet Length" size="74" value="74" />
      <field name="caplen" pos="1" show="74" showname="Captured Length" size="74" value="74" />
      <field name="timestamp" pos="1" show="16:35:13.991300" showname="Captured Time" size="74" value="963585313.991300" />
    </proto>
    <proto name="Ethernet" pos="1" showname="Ethernet 802.3" size="14">
      <field name="dst" pos="1" show="000629-992da3" showdtl="000629-992da3 Unicast address (Vendor IBM RISC6000 system)" showmap="IBM RISC6000 system" showname="MAC Destination" size="6" value="000629992da3" />
      <field name="src" pos="7" show="00e01e-ec3c84" showdtl="00e01e-ec3c84 Unicast address (Vendor Cisco)" showmap="Cisco" showname="MAC Source" size="6" value="00e01eec3c84" />
      <field name="type-length" pos="13" show="0800" showname="Ethertype" size="2" value="0800" />
    </proto>
    <proto name="IP" pos="15" showname="IPv4 (Internet Protocol version 4)" size="20">
      <field name="verhlen" pos="15" show="45" showname="Version and header Length" size="1" value="45">
        <field mask="F0" name="ver" pos="15" show="4" showname="Version" size="0" value="4" />
        <field mask="0F" name="hlen" pos="15" show="5" showdtl="20 (field value = 5)" showname="Header length" size="0" value="5" />
      </field>
      <field name="tos" pos="16" show="00" showname="Type of service" size="1" value="00" />
      <field name="tlen" pos="17" show="60" showname="Total length" size="2" value="003c" />
      <field name="identification" pos="19" show="1094" showname="Identification" size="2" value="0446" />
      <field name="ffo" pos="21" show="0000" showname="Flags and Fragment offset" size="2" value="0000">
        <field mask="8000" name="unused" pos="21" show="0" showname="Unused" size="0" value="0" />
        <field mask="4000" name="df" pos="21" show="0" showname="Don't fragment" size="0" value="0" />
        <field mask="2000" name="mf" pos="21" show="0" showname="More fragments" size="0" value="0" />
        <field mask="1FFF" name="foffset" pos="21" show="0" showdtl="0 (field value = 0)" showname="Fragment offset" size="0" value="0000" />
      </field>
      <field name="ttl" pos="23" show="127" showname="Time to live" size="1" value="7f" />
      <field name="nextp" pos="24" show="1" showname="Next protocol" size="1" value="01" />
      <field name="hchecksum" pos="25" show="d9bf" showname="Header Checksum" size="2" value="d9bf" />
      <field name="src" pos="27" show="130.192.16.81" showname="Source address" size="4" value="82c01051" />
      <field name="dst" pos="31" show="192.168.10.2" showname="Destination address" size="4" value="c0a80a02" />
    </proto>
    <proto name="ICMP" pos="35" showname="ICMP (Internet Control Message Protocol)" size="40">
      <field name="type" pos="35" show="8" showmap="Echo Reply" showname="Type" size="1" value="08" />
      <field name="code" pos="36" show="0" showname="Code" size="1" value="00" />
      <field name="checksum" pos="37" show="245c" showname="Checksum" size="2" value="245c" />
      <field name="echoreply" pos="39" showname="Echo Reply" size="36">
        <field name="identifier" pos="39" show="512" showname="Identifier" size="2" value="0200" />
        <field name="seqn" pos="41" show="9984" showname="Sequence number" size="2" value="2700" />
        <field name="data" pos="43" show="abcdefghijklmnopqrstuvwabcdefghi" showname="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 could use the following algorithm (in pseudo-code):

  if exist(showdtl_attrib)
    print(showname_attrib, " = ", showdtl_attrib);
  else
    if exist(showmap_attrib)
      print(showname_attrib, " = ", show_attrib, " (", showmap_attrib, ")" );
    else
      print(showname_attrib, " = ", show_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 to print the field value. Otherwise, we can print the field name (in "human" form by using the showname attribute) and its value (in "human" form by using the show 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 quite complex. First of all we have to split the generation of the detailed view of the packet from the generation of the summary view.

Generation of the detailed view of the packet

This is not a one-pass procedure. In other words, the NetPDL Visualization Extension is used to create the first part of the PDML document. At the end of this phase, each element into the PDML document will be almost complete excluding its showdtl attribute. For instance, the procedure that creates the PDML attributes looks the following:

PDML <field> attribute Generation procedure
name Copied from the name attribute of the corresponding field into the NetPDL document.
show Generate from the value attribute, formatted according to the commands of the showtype, showgrp and showsep of the corresponding field into the NetPDL document.
value, pos, size They are the result of the decoding procedure of the NetPDL engine.
showname Copied from the showname attribute of the corresponding field into the NetPDL document.
showmap Copied from the appropriate item into the matching table specified into the NetPDL document.

The showdtl attribute comes the last. In fact, the procedure to generate the showdtl attribute into the PDML document makes use of some instructions that require to get the attributes already stored into th same PDML element. In other words, the NetPDL file could require to print the text "The field value is ", then putting the value of the field in readable format (i.e. the content of the show attribute of the PDML element), then the string "which corresponds to the command", then the value of the showmap attribute.

As you can see, the showdtl attribute makes use of the previously created attributes for its construction. Summarizing, the NetPDL decoding engine;

  1. creates the first part of the PDML document
  2. reads the so created document
  3. it executes the instructions contained into the <showdtl> element of the NetPDL
  4. it creates the final PDML document, containing the showdtl attribute as well.

A graphical view of the process is shown in the Figure below.

Here there is a brief explanation of the required steps.

  1. Some attributes are generated directly from the attributes contained into the NetPDL description (or with a small piece of elaboration, referring to showtype, showgrp and showsep attributes).
  2. The showmap tag triggers the scan of the corresponding <showmap> element, looking for the item that matches the current value of the field.
  3. The third step involves returning the value of the field (which is stored in the PDML document), required for resolving the correct matching item.
  4. Once the correct matching item has been located, its show attribute is copied into the PDML element.
  5. The showdtl attributes involves the scan of the corresponding <showdtl> element within the NetPDL document.
  6. The directives contained into the template require the access to some of the attributes already stored in the PDML gragment
  7. All these attributes are merged together according to the <showdtl> directives, and the result is returned into the showdtl attribute of the PDML document.

Generation of the Summary View of the packet

This procedure is simpler because it comes after the previous procedure. In other words, the PDML document is already complete when the NetPDL engine starts creating the summary view. This procedure looks like the one already described in the previous Section for the showdtl attribute: the NetPDL engine executes all the instructions contained into the <showsum> element and it copies the value of the required attributes of the PDML document, creating the summary view of the packet.