Best way to document a packet protocol

Question

I often find myself in the situation of wanting to write a breakdown of the protocol that some program (either my own or some other by reading its code or RCE) uses for its network communication, but there is just no standard on how to document the structure of packets in those.

What I usually do is to write the protocol documentation with Markdown and specify packet structures like this:

[uint32 size] [uint32 command] [var parameters]

However, I am looking for a convenient and standardized way of solving this.

Answer 1

One good protocol documentation I found was HTTP Specification by IETF. It may not satisfy all your requirements but is a good place to start.

Answer 2

If you are working with fixed structures (versus dynamic strings) I like tables. You can quickly see size, offsets and usage.

For dynamic structures, I typically use a structure like definition.

It is worth noting an offset from last known fixed position. It makes it easier when debugging streams or writing test cases for code.

Answer 3

Unfortunately, there is no good standard solution, as you can see by reading the various RFC. Most of them simply use ASCII art to show the layout of packets. A solution I like is the pseudo-code of RFC 5246, for instance:

struct {
      uint8 major;
      uint8 minor;
  } ProtocolVersion;

  enum {
      change_cipher_spec(20), alert(21), handshake(22),
      application_data(23), (255)
  } ContentType;

There have been many attempts to improve things.

Michael Richardson suggested me a proposal he wrote several years ago, PAX PDL - a non-procedural packet description language, which was apparently not a success.

On an IETF mailing list, Bob Braden mentioned that this problem is quite old in the IETF and suggests reading the RFC 31, the first one discussing the issue. Apparently, the proposed form was used only once, in RFC 88.

Answer 4

There are a variety of types of protocols, and as a result a variety of types of documentation. From my perspective, the important thing is to know what messages can be exchanged, how they are formed, and what state machine the protocol follows, which is to say what the states are, what possible inputs, outputs, and side-effects exist, and what events cause what behavior.

One very well-written specification is RFC 1661, which defines PPP.