libtcpedit Design


Notice: Just like libtcpedit, this document is actively being developed. If you have any thoughts or ideas, please leave a comment below.

Project Goals

  1. A real library that other projects can use
  2. Thread safe. That means use of context variables and no globals
  3. Plugin architecture allows other people to easily add functionality
    • Multiple plugin groups (DLT/Layer2, Layer 3 and Layer 4-7)
    • Provide developer templates for creating new plugins
    • Plugins must be bi-directional. Must be able to read and write.
  4. Should expose a consistent API
  5. Provide user option parsing for applications using GNU Autogen/Autoops?

DLT/Layer 2

One of the most complicated parts of the code is converting pcap files and their packets from one DLT type to another. An example might be packets captured using the Linux any interface which uses DLT_LINUX_SLL and a pseudo-header which you want to send out an ethernet interface. This requires two things:

  1. Changing the DLT type to DLT_EN10MB
  2. Rewriting the pseudo-header to be a valid 802.3 ethernet header

The key thing here is that DLT types and the layer 2 header are tightly coupled, but we obviously can't initially support all DLT/layer 2 types. Hence we need to make sure that we make it easy to add additional DLT/L2 support.


  1. Easy to add support for future DLT types.
  2. Support converting one DLT type to another.
  3. Easy to add additional packet editing functionality.
    • Editing above Layer 2 should be DLT independant.
  4. Need to have good documentation


  1. Different DLT's have different framing/sizes (must make room for larger headers)
  2. Different DLT's have different layer 2 address types. Some have no L2 addresses at all.
  3. Some DLT's are missing important information
  4. Some DLT's have assumed L3 typing or don't support certain packet types.
  5. Problem is n*(n-1) which is O(n2)

Internal Processing

For each pcap file we need to know:

  1. Source DLT type
  2. Destination DLT type
  3. Missing information not found in source DLT
  4. Extra L2 data (VLAN tags?, wifi signal data, etc)

For each packet we need to know:

  1. Direction of packet (primary or secondary)
  2. User specified field overrides (specific to each destination DLT)

Using that information, we can rewrite the packet according to the rules in the tcpedit context.


After looking at the above, it's pretty clear to me that supporting DLT's really needs to be done via plugins. Plugins should provide:

  1. Input method to convert existing packet header to a tcpedit internal data structure for source parsing
  2. Output method to convert tcpedit internal data structure to a packet header
  3. Declaration of what field types they provide in input mode (ethernet src, dst addresses, HDLC address, proto type, etc)
  4. Declaration of what field types they require in output mode (same name space as above)
  5. AutoGen AutoOpts stubs to:
    1. Generate specific CLI arguments for:
      • Required fields when missing source or destination address
      • Optional fields such as ethernet VLAN tag info
    2. Method to parse above options


  1. All protocol plugins register
  2. User selects:
    • Output DLT
    • DLT field overrides if any
  3. User DLT field overrides passed to DLT encoder
  4. Source pcap DLT is read
  5. Sanity check is preformed to make sure source DLT + user options == required destination DLT fields
  6. Main Loop:
    • Packet is read
    • Packet is passed to source DLT decoder
    • Decoder fills out tcpedit internal data structure (tcpeditdlt_t)
    • tcpeditdlt_t is passed to destination DLT encoder
    • DLT Decoder returns new L2 header
    • Packet is rebuilt
    • L3 and above is processed
    • Packet is written


  • Output: Ethernet
    • Add VLAN Tag
    • Delete VLAN Tag
    • Edit VLAN Tag
    • Edit Src/Dest? MAC address


  • Output: Cisco HDLC
    • Edit destination address
    • Edit control value


  • Output: User defined type
    • Edit libpcap DLT type value
    • Layer 2 header

Decoder (input only) plugins

  • IEEE 802.11 (ieee80211)
  • 802.11 w/ Radiotap (radiotap)
  • BSD Loopback (null)
  • Loopback (loop)
  • Linux Cooked SLL (linuxsll)
  • Raw (raw)

Last modified 10 years ago Last modified on 01/18/09 19:56:01