################################################################################

____ _ _

| _ \ _ __ ___ | |_ ___ ___ ___ | |

| |_) | '__/ _ | __/ _ \ / __/ _ | |

| __/| | | () | || () | (| () | |

|| || _/ ___/ __/|_|

== A Simple ASCII Header Generator for Network Protocols ==

################################################################################

Written by:

Luis MartinGarcia.

-> E-Mail: luis.mgarc@gmail.com

-> WWWW: http://www.luismg.com

-> GitHub: https://github.com/luismartingarcia

################################################################################

TABLE OF CONTENTS

0x01 Introduction............................................................. 0x02 Downloading Protocol...................................................... 0x03 Installing Protocol...................................................... 0x04 Running Protocol......................................................... |_ 0x04.1 Displaying Existing Protocols...................................... |_ 0x04.2 Displaying Custom Protocols........................................ | |_ 0x04.2.1 Field Lists................................................. | |_ 0x04.2.2 Options..................................................... |_ 0x04.3 Command-line Options............................................... 0x05 Examples................................................................. 0x06 Contact, Support and Bug Reporting.......................................

0x01 - INTRODUCTION

Protocol is a simple command-line tool that serves two purposes:

• Provide a simple way for engineers to have a look at standard network protocol headers, directly from the command-line, without having to google for the relevant RFC or for ugly header image diagrams.

• Provide a way for researchers and engineers to quickly generate ASCII RFC-like header diagrams for their own custom protocols.

0x02 - DOWNLOADING PROTOCOL

The latest version of protocol is available via GitHub. It can be downloaded directly from the following website clicking on the button "Download ZIP".

https://github.com/luismartingarcia/protocol

Alternatively, the code can be checked out using GIT, running the following command:

git clone https://github.com/luismartingarcia/protocol.git

If prompted for a username and password, don't enter any, just hit Enter.

Documentation and extra information is always available through the following site:

http://www.luismg.com/protocol

0x03 - INSTALLING PROTOCOL

Protocol can be installed by running the included setup.py script as follows:

setup.py install

Note that in order to install Protocol, root or administrative privileges are required. On GNU/Linux systems, it can be installed as follows:

sudo ./setup.py install

0x04 - RUNNING PROTOCOL

Once installed, Protocol can be run from the command line. The syntax is the following:

protocol <EXISTING_PROTOCOL_NAME(S)>

or

protocol <CUSTOM_PROTOCOL_SPECIFICATION(S)>

The following subsections describe each approach.

0x04.1 Displaying Existing Protocols

The first approach lets users print ASCII headers for existing network protocols. In particular, the following protocols are available.

"ethernet"            : Ethernet
"8021q"               : IEEE 802.1q
"dot1q"               : IEEE 802.1q
"tcp"                 : Transmission Control Protocol (TCP)
"udp"                 : User Datagram Protocol (TCP)
"ip"                  : Internet Protocol (IP), version 4.
"ipv6"                : Internet Protocol (IP), version 6.
"icmp"                : Internet Control Message Protocol (ICMP)
"icmp-destination":   : ICMP Destination Unreachable
"icmp-time"           : ICMP Time Exceeded
"icmp-parameter"      : ICMP Parameter Problem
"icmp-source"         : ICMP Source Quench
"icmp-redirect"       : ICMP Redirect
"icmp-echo"           : ICMP Echo Request/Reply
"icmp-timestamp"      : ICMP Timestamp Request/Reply
"icmp-information"    : ICMP Information Request/Reply
"icmpv6"              : Internet Control Message Protocol for IPv6 (ICMPv6)
"icmpv6-destination"  : ICMPv6 Destination Unreachable
"icmpv6-big"          : ICMPv6 Packet Too Big
"icmpv6-time"         : ICMPv6 Time Exceeded
"icmpv6-parameter"    : ICMPv6 Parameter Problem
"icmpv6-echo"         : ICMPv6 Echo Request/Reply
"icmpv6-rsol"         : ICMPv6 Router Solicitation
"icmpv6-radv"         : ICMPv6 Router Advertisement
"icmpv6-nsol"         : ICMPv6 Neighbor Solicitation
"icmpv6-nadv"         : ICMPv6 Neighbor Advertisement
"icmpv6-redirect"     : ICMPv6 Redirect

One or more of the protocols listed above can be printed. Here are a few examples:

protocol tcp
protocol dot1q
protocol tcp udp
protocol ipv6 icmpv6 icmpv6-redirect

Note that protocol names don't need to be fully specified, as long as there is no ambiguity. For example 'protocol et' is equivalent to 'protocol ethernet'. Whenever there is ambiguity (e.g. 'protocol icmpv6-r', a list of possible options will be displayed.

$ protocol icmpv6-r
Ambiguous protocol specifier 'icmpv6-r'. Did you mean any of these?
  icmpv6-radv
  icmpv6-redirect
  icmpv6-rsol

0x04.1 Displaying Custom Protocols

Apart from already existing protocols, Protocol can represent any arbitrary protocol headers. In order to do that, instead of specifying the name of an existing protocol, a custom protocol specification may be supplied. Such specification must follow a simple but specific syntax:

"<LIST_OF_FIELDS>[?OPTIONS]"

Where [LIST_OF_FIELDS] is a comma-separated list of protocol field names and lengths (expressed in bits), and [?OPTIONS] is an optional part that allows users to specify format modifiers for the ASCII header. Note that if any of the field names contains spaces, the protocol specification must be enclosed in double quotes.

0x04.2.1 Field Lists

The most important part of a protocol specification are field lists. This
is just a comma-separated list of name:length tuples, where name represents
the text that describes the protocol field and can contain any character,
except for '?' and length is an integer greater than zero, representing the
number of bits the field takes in the header. Here are a few examples:

Type:8,Code:8,Checksum:16,Message Body:64
Source Port:16,Destination Port:16,Length:16,Checksum:16

Note that there is no whitespace after the commas. This is a restriction
that must be respected.

Also, note that field lengths don't need to align to the length of the
line. If a particular field is too long, Protocol will just wrap it to the
next line. Here are some examples:

$ protocol "Source:16,TTL:8,Reserved:40"
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|             Source            |      TTL      |               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+               +
|                            Reserved                           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


$ protocol "Source:16,Reserved:40,TTL:8"
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|             Source            |                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+               +-+-+-+-+-+-+-+-+
|                    Reserved                   |      TTL      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

$ protocol "Reserved:32,Target Address:128"
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                            Reserved                           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
+                                                               +
|                                                               |
+                         Target Address                        +
|                                                               |
+                                                               +
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

0x04.2.2 Options

Once the list of fields has been specified, users may optionally pass
formatting options to contro