Understanding PacketGen Structure

PacketGen uses 3 primary concepts:

• a packet is an object describing a network packet,
• a header is an object describing a network protocol,
• a type is a basic or composed type. A composed type is a type based on one or more others composed types or basic types.

Packets

PacketGen is packet centric, so sessions or fragmentation are not handled. Thus, a packet may not contain all data necessary to interpret it.

A packet (PacketGen::Packet class) is merely a container for headers. It also has a body to handle data of most inner protocol.

A packet consists of:

• an array containing headers (PacketGen::Packet#headers),
• a body (PacketGen::Packet#body, which is a shortcut to last header's body).

Packet class also provides methods to interact with packets:

• parsing packets from binary string,
• reading packets from PCAP and PCAP-NG files,
• writing packets to PCAP-NG files,
• capturing packets from a network interface,
• sending packets on wire,
• helpers methods to:
  • calculate all length and checksum fields among headers,
  • serialize packet to binary data,
  • encapsulate a packet in another one,
  • decapsulate some headers from a packet to a new packet.

Headers

Most of headers are based on BinStruct types. They contain attributes. Each attribute is defined from a type.

Some headers may contain others headers. Such headers should have a #body field to handle inner headers.

Some protocols use length and/or checksum attributes. To permit computation of these attributes at once through PacketGen::Packet#calc, these attributes should be named #length and #checksum, respectively.

Most of PacketGen header classes inherit from PacketGen::Header::Base class. This class implements minimal API needed to parse packets and add headers to packets.

Types

Basic types

Basic types are types used to construct headers or composed types. Basic types are listed in table below.

Type	Description
binStruct::Int8	8-bit integer
binStruct::Int8Enum	8-bit enumerated integer
binStruct::Int16, Int16be	16-bit big-endian integer
binStruct::Int16Enum, Int16beEnum	16-bit big-endian enumerated integer
binStruct::Int16le	16-bit little-endian integer
binStruct::Int16leEnum	16-bit little-endian enumerated integer
binStruct::Int32, Int32be	32-bit big-endian integer
binStruct::Int32Enum, Int32beEnum	32-bit big-endian enumerated integer
binStruct::Int32le	32-bit little-endian integer
binStruct::Int32leEnum	32-bit little-endian enumerated integer
binStruct::Int64, Int64be	64-bit big-endian integer
binStruct::Int64le	64-bit little-endian integer
binStruct::String	binary string
binStruct::CString	null-terminated string
binStruct::IntString	binary string prepended with its length

Composed Types

Composed types are some BinStruct/PacketGen default types built from basic ones. These types are commonly used to define headers:

Type	Description
BinStruct::Array	container for types. May contain multiple values of a single type
BinStruct::Struct	a container to concatenate multiple attributes of different types together
BinStruct::AbstractTLV	Type-Length-Value type
BinStruct::OUI	Organizationally Unique Identifier

Some headers also define commonly used types:

Type	Description
PacketGen::Header::Eth::MacAddr	Ethernet MAC address
PacketGen::Header::IP::Addr	IPv4 address
PacketGen::Header::IPv6::Addr	IPv6 address