[Firebird-devel] Wire protocol specification and wireshark dissector

[mark c. <mar...@ob...>]

Hi folks,

I've been working on fixing up the wireshark plugin for Firebird.  One 
of the things that would have really helped in this process would have 
been up-to-date documentation.  After reading what I could find, 
including Carlos Guzman Alvarez's paper, I decided that I would be best 
off parsing the xdr_protocol routine in protocol.cpp and generating the 
required wireshark code.  This I have done. As a byproduct, I have 
produced an HTML document that I have requested to be posted on 
http://www.firebirdnews.org. 

In order to do this, I needed to tag up the source code with some extra 
info - comments about the packet type (only for documentation) and field 
names (for documenation and wireshark). Here's a simple sample:

  //: Resquest information about a previously prepared statement
  case op_info_sql:
    info = &p->p_info;
    //: DatabaseHandle
    MAP(xdr_short, reinterpret_cast<SSHORT&>(info->p_info_object));
    //: IncarnationOfObject
    MAP(xdr_short, reinterpret_cast<SSHORT&>(info->p_info_incarnation));
    //: RequestBuffer
    MAP(xdr_cstring_const, info->p_info_items);
    //: ReplyBufferLength
    MAP(xdr_short, reinterpret_cast<SSHORT&>(info->p_info_buffer_length));
    DEBUG_PRINTSIZE(xdrs, p->p_operation);
    return P_TRUE(xdrs, p);

It would be possible to include the the field name in the MAP macro like 
this

case op_info_sql:
    info = &p->p_info;
    MAP("DatabaseHandle", xdr_short, 
reinterpret_cast<SSHORT&>(info->p_info_object));

which I think reads better. The MAP macro can ignore the extra parameter 
- executable code would not be affected.

How do you feel about including this in the production code?

There are some advantages:

    * better internal documentation
    * ability to generate a Wire Protocol spec (which seems to be asked
      for regularly)
    * ability to generate a wireshark dissector.

There are some disadvantages:

    * extra comments need to be added as the protocol changes
    * it may be necessary to split out some cases as, while their
      structure is the same, the field names are not. This will result
      in a small increase in code size but probably no increase in
      execution time.
    * opaque data structures need extra 'hints' in the comments.

If you like the idea, I'll merge my code with the latest protocol.cpp. 
If you don't, I'll delete it. ;-)

Of course, I'll make the parser/generator code available. It's written 
in Delphi but would be easy to port.

Regards,
Mark Chambers