Concept |  Packet |  Mapper |  Network |  Procotol language |  Utilities |  Launching |  FAQ 

The best way to understand how this language works is to study the examples distributed with GASP. This documentation is a reference guide and not a tutorial.

Lexical elements
comment #.* any characters following a diese is part of a comment
name [A-Za-z0-9_]+ a name is formed of alphanumerics, the first character must be letter
string .* the string notation use the same syntax as the strings in C.
expression byte(.bit)? | '.*' an expression if either a position (byte offset, dot, bit offset) or a complex expression (using the same syntax as C expressions)

The absolute position in bit in calculated as 8*byte+bit, so you can use values greater than 8 for the bit part.

Content of a file .pro
protocol A file is a list of protocols
?protocol ...?

Definition of a protocol
protocol name = { The name will be the one used to create the mapper
  size = expression The total size. Use '%computedsize' to let GASP compute it when the size is variable.
  spec = string A free text the user can consult when requesting help about the protocol. Use it for example to indicate some references.
  nextlayer = expression ?, expression, ...? Specify a list of possible next layer protocol. This information is used by the decodefrom command to automatically construct a stack of protocols.
The first match will deternime the protocol to use next.
To return the textual representation of a field to match the name of a known protocol, use the '%string(fieldName)' expression.
  list of fields The list of all the fields composing the protocol.
}

Definition of a field
field name @ (offset, size) = { The name will be the one used in the configure command.
The offset and size are expressions. An expression is any C expression, with all the operators defined in C.

The offset can use one of the meta-values :

  1. '%field(fieldName)' to reference the offset of an already defined field.
  2. '%data(offset,size)' to reference some data in the packet memory. The offset and .
  3. '%seek(offset,size)' to reference the offset of an already defined field.
  4. '%follows' to tell GASP to put this field immediatly after the previous one. This is used with variable length fields.

The size can use the same meta-values expect '%follows' which is replaced by '%size' the let GASP compute the size of the field.

  type = type The type of the field. See below for a list of supported types.
  help = string The string returned to user when using the help command.
  default = expression A default value which is used to initialize the field.
The special values '%address_ethernet' and '%address_ip' can be used to get the actual Ethernet and IP addresses of the host running GASP.
}

Definition of an array of fixed size elements
fieldarray name @ (offset, size) = { The offset is the offset of the beginning of the array. The size is the size of one element.
  nbelements = expression Indicates the number of entries in the array. An error is returned if you try to access an element outside the range 0..nbelements-1.
  type = type Same as a simple field.
  help = string Same as a simple field.
  default = expression Same as a simple field.
}

Definition of an array of variable size elements
fieldvariablearray name @ (offset, size) = { The offset is the offset of the beginning of the array. The size is the total size allocated for all the elements.
  type = type Same as a simple field.
  help = string Same as a simple field.
  default = expression Same as a simple field.
}

 

Table of supported types
Empty type
none An empty type. Do nothing when you write a value, returns nothing when trying to read through it.  
Integer
integer An integer value. The integer of 4, 8, 16 and 32 bits have special optimized routines for read/write. The access to integer at random offset and of random size is less efficient.
Reading: return a signed integer.
Writing: you can use decimal, hexadecimal (prefix 0x) or octal (prefix 0) values.
  1234
-56
0xABCD
0777
length Integer value with a special meaning : compute the length of all the data forming the packet after the mapper.
Reading: return a signed integer.
Writing: you can use decimal, hexadecimal (prefix 0x) or octal (prefix 0) values. Use the length command to automatically set the field to its correct value.
 
checksum(ip)
checksum(tcp)
checksum(udp)
Integer value with a special meaning : compute a checksum using the specified algorithm.
Reading: return a signed integer.
Writing: you can use decimal, hexadecimal (prefix 0x) or octal (prefix 0) values. Use the checksum command to automatically set the field to its correct value.
 
Strings
string(fixed) A string of fixed size.
Reading: return a string.
Writing: give a string as argument. If the string is too long to fit in the fixed size, it is truncated. If the string is too short, the remaing space is fill with 0.
  "toto"
"\t tab"
"new\nline"
string(c) A string terminated with a 0, as in the C language.
Reading: return a string.
Writing: give a string as argument. The string fill all the space for the field. The following data will be moved if necessary.
  "toto"
"\t tab"
"new\nline"
string(dns) A string representing the name of a machine as defined in the DNS protocol. The compression of string is supported.
Reading: return a string.
Writing: give a string as argument. The string fill all the space for the field. The following data will be moved if necessary.
  "host.domain.country"
"1.2.3.4.inaddr-arpa"
string(user, ending) A string with a user-defined matching string as termination. The 'string(c)' is a special case with ending = "\0".
Reading: return a string.
Writing: give a string as argument. The string fill all the space for the field. The following data will be moved if necessary.
 
Lists
list {
   value short long
   ...
}
Describe a list of know values. Each value is associated with a short and a long description. The values are directly stored in an array for the best runtime performance.
Reading: returns the short description or an integer if the value doesn't map to a know value. Use getraw to get the numerical value and getverbose to get the long description.
Writing: accepts the short description as input or any form of number.
 
sparelist {
   value short long
   ...
}
Same as above, but stores data more efficiently when the list if not composed of contiguous values. There is a small runtime penality as the program must lookup for the value.  
samelist(name) Use this type to indicate that the field is using the same list as an other field. The type share the data with the field given in name.  
Flags
list {
   mask name off on
   ...
}
Describes a list of flags. Each flag is define by a mask, its name, and a long description for the clear and set states.
Reading: returns a list of flags names prefixed by '-' is the flag is cleared and '+' if it is set. Use getraw to get the numerical value and getverbose to get a long description.
Writing: needs a list of flags to change. '+name' or 'name' means 'set the flag' and '-name' means 'clear the flag'. Any flag not mentionned in the list is left unmodified.
  {+a -b +e}
Addresses
address_ethernet An ethernet address represented as 6 bytes separated by columns. is a special case with ending = "\0".
Reading: return a string.
Writing: expect 6 bytes separated by columns.
  12:34:56:78:9A:BC
address_ip An IP address. The resolution uses the DNS services.
Reading: returns the hostname. Use getraw to obtain the dotted value and getverbose to get the fully qualified name.
Writing: any form accepted by a DNS request will work.
  1.2.3.4
host
host.domain
Structures
record {
   sybtype(size)
   ...
}
Allows to group severals basic types in one. The subtype must be a valid type and the size is the size of the subtype inside the total side of the field.
The subtype are simply appended.
A record can't contain variable lengh types.
Reading: returns a list of the values of the subtypes.
Writing: a list of values rescpecting the input conventing for each subtype.
 
mapper(name) For complex types, use an other mapper to decode/encode it.
Reading: same as the mapper used.
Writing: same as the mapper used.
 
switch(expression) {
   v1-v2 type
   v1,v2 type
   ...
   default type
}
Handles dynamic typing. The type used to read/write the value is determined at run-time using the value of the given expression. This value is matched against a list of possible value. Is none is matched, a default type can be specified.
The matching values can be multiple and contain ranges.
Reading: same as the matched type.
Writing: same as the matched type.
 


Copyright © 2000 Laurent Riesterer.
Last modified on Mar 2, 2000.