Protocol parsers (PDF, DFF, IFF)

Protocol parsers (PDF, DFF, IFF and others)

Analyzer uses three external parsers that are used to make the protocol parsing/decoding working.

Analyzer executes these parser automatically when

user changes the source files (for example the protocol definition, in menu' Setup/Protocol Definition)
at launch time (Analyzer controls automatically the coherence of object files with the corresponding source file).

All parsers show an error message is shown if the number of parameters is wrong or it is not possible to open a file; the parser generates no output file and returns a value different from '0' when the parsed file contains some error.

Protocol Definition (PDF: Protocol Definition Format)

PDF file (Protocol Definition Format) defines protocols supported by analysis engine and it is a normal text file. This files is used to:

describe the format of each packet (for example: IP has a first field that is 4-bits long called "version", then another 4-bits field called "Header_length", and so on)
explain how these protocols have to be demultiplexed (for example: if an IP packet contains code "17" in the "protocol" field, next protocol will be UDP)

This parser is launched by Analyzer when the user either sets or modify this configuration file. This parser can be launched manually as well:

 pdreader FILE.PDF OUTPUT_FILE.PDO

Output file is a "pseudo-code" object file that is used by Query to interpret and decode packets. On other words, Query has a virtual machine in which this object file is executed; Query has to be able to execute these commands and to provide a "friendly" environment for this code.

Protocols will be described in a text file with a particular C-like language (case insensitive), with a small set of data types. Fields definition is given by type + name.

The supported data types are:

BYTE(8) int (0,255)
WORD(16) int (0,65535)
DWORD(32) int (-2147483648,2147483648)

Names format is: a character (or '_') followed by less then 50 alphanumerical types. A field can contain sub fields obtained masking some indicated bits.

field BYTE 01110010
    sub field BIT (2,5) ; this notation means that BIT is given by the
                          bits 2,3,4,5 of BYTE so BIT has the value 1100

A protocol definition starts with the word 'PROTOCOL', followed by a fields series and expressions which ends with 'ENDPR'.

More information about PDF grammar can be found looking at the grammar page.

Display Definition (DFF: Description File Format, IFF: Index File Format)

These files define what has to be displayed on the Analyzer main window: DFF file defines the complete description of the protocol, whereas IFF describes a brief description of the protocol. DFF output (with a proper formatting) can be seen in the Analyzer's second window (the one on the left), while IFF output can be seen in the first window (the one on the top).

There are two different files for the display definition because of the different requirements of them: the top window has limited space so that only the most important information have to be printed (for example IP source and destination address). The left window has more space, so that everything can be printed (for example header length, fragment offset, ...).

This parser can be launched either by Analyzer or manually. In the latter case the syntax is:

ddreader INPUT.xFF OUTPUTFILE.xFP OBJECT.PDO

where the latter if the PDO file previously generated.

xFF parser creates an object file as well: this object file is executed by the analysis engine (Query) and it works after the PDO file finishes its job. In fact the PDO file decodes the packet and set appropriate values for all the protocol fields defined in there. As soon as a protocol has been completely decoded, the analysis engine executes the corresponding DFO and IFO code in order to define how this protocol has to be displayed. Therefore protocols names and protocol fields must have the same name in the PDF, DFF and IFF files and they are mapped by the Query virtual machine in somewhat "global" variables that are created by the PDO and they are accessed by the DFO(IFO as well.

DFF/IFF files share the same parser (case insensitive), therefore they share the same C-like syntax used to define the display definition.

The language has the following characteristics:

variables: they are defined by a type and a name, the definitions are done in the function and the types can be:
- BYTE(8) int (0,255)
- WORD(16) int (0,65535)
- DWORD(32) int (-2147483648,2147483648)
the variables are even initiated at 0. The names are: a letter or the type '_' followed by less then 50 alphanumerical type
arrays: they are defined with the word 'ARRAY'; they are a DWORD vector limited to 65535 elements; it is not possible make multidimensional arrays; the array does not immediately occupy the necessary memory to reach the max size, but it grows when the user asks to enter in not yet lodged places. It is convenient to immediately enter in the max array position, so the array doesn't grow in more steps. The array scope is global; it is definable only out of the functions and the access to it is like in C. It is not initiated.
functions: they must return a value. Return value will be '0' in absence of an explicit return instruction. A function is defined by a type, a name and a parameters list. The parameters are passed by value and not by reference. There are not pointers so a function cannot delegate an other function to change the value of variable. To do this, you can use array which has global scope. Recursive functions are allowed.

structured constructions: the xFF files accept all C constructions except the switch statement. Here it is a constructions description:

if '(' expression ')' instruction	If expression is different from 0 then instruction is executed
if '(' expression ')' instruction1 else instruction2	If expression is different from 0 instruction1 is executed instead instruction2
do '{' instructions '}' while '(' expression ')'	The instructions are executed. If expression is different from 0 the instructions are executed again.
while '('expression ')''{'instructions '}'	If expression is different from 0 the instructions are executed, then expression is calculated again.
for '(' expression1 ';' expression2 ';' expression3 ')' instruction	Expression1 is calculated. If expression2 is true then instruction is executed.Expression3 is calculated. Expression3 is calculated again.

instructions:
- CONTINUE: it resumes the structured construction as in C.
- BREAK: it breaks the most internal structured construction (doesn't work in if).
- TITLE '(' string ')': show the string as a title
- PRINTF '(' string ',' expressions_list ')': print a string using the format options (look at printf() page). The paging command are like those of the function C printf - %d for int, %u for unsignedint,%s for character.
- PRINTF '(' string ')': print a string like printf do. Paging command are not available.
- APRINT '(' string ',' name ')': print a vector like a for cycle. It has paging command as printf.
- CLEAR '(' name ')':cancel a vector. All the elements values will be lost. The vector memory is completely settled free.
- RETURN expression: goes out from the current function and returns a value.
- RESETLOG '('expression')', RESETLOG '('expression', 'expression')', RESETLOG '('expression', 'expression', 'expression')' : this instruction can be invoked using three different formats. It is used to modify the bytes intervals which are automatically associated, by Query, to the packets fields. Look at resetlog utilization for further information.

Further information about these are available in the page which describe the class which implement the virtual machine which parses the relative objects files.

You can have more information about DFF and IFF format looking at:

the grammar page.