How to add a custom link-layer dissector to Wireshark

In this how-to article, we will discuss the main techniques on how to add a custom link-layer dissector to Wireshark. This article can be used by anyone for any custom protocol and is also applicable to dissecting custom frame data by Wireshark when using the EMBEDnet “Protocol Emulation Tool Kit”

Reference: “Protocol Emulation Took Kit User guide” on how to create live frame captures when using Wireshark with LUA scripts.

Anything not covered in this how-to is left upto the reader to research.

General assumptions:

• All frame data is custom and does not reference an existing link-layer protocol
• Frame data can be directed to Wireshark using a standard pcap format live via pipes or sometime later using stored pcap file.

There are several methods on how-to write Wireshark dissectors, two of the most common are: compiled “C” dissector and LUA script. Here, we will be using LUA scripts to implement our custom link-layer dissector.

Some of the key points with custom dissectors are:

1. A custom dissector needs to define its own dissector table. Most other dissectors, like those that use UDP frame data, reference a preexisting link-layer protocol, like Ethernet, or IEEE 802.15.4.
2. User defined link layers are referenced in Wireshark within the range: 147-162 DLT_USER0-DLT_USER15
3. A custom dissector needs to be manually registered in Wireshark whereas pre-configured link-layer based dissectors do not require manual registration.

The general process for creating a custom dissector is:

1. Find an example dissector as a base to modify and create your new dissector. Just do a www search on “Wireshark LUA scripts”. An example lua script will be provided as a reference below.
2. Reference the LUA script documentation as needed.
3. Use your frame header structure as a reference when creating the output format for the dissector.
4. Step through your header structure data and specify the output format for each structure member within the LUA script.
5. Make sure that the LUA script is complete.
6. Test the LUA script.

Our example dissector will be based on the following packet structure:

[UINT8:size][UINT8:dest][UINT8:src][UINT8:seq][UINT8:data-0..data-n][UINT8:chksum]

Here is our example.lua script. Free free to copy this for your own use.

Note how the custom dissector table is created and referenced within the script and the custom link-layer 147 is used.

DissectorTable.new(“example-table”)

example_protocol.fields = { message_length,dest,src,seq,cont }

function example_protocol.init()

DissectorTable.get(“example-table”):add(147, example_protocol)

end

function example_protocol.dissector(buffer, pinfo, tree)

length = buffer:len()

if length == 0 then return end

— these are the column displayed in wireshark.

— to add/remove columns, rt click on the column and edit

— add the column data here, reference pinfo for available data types

pinfo.cols.protocol = example_protocol.name

pinfo.cols.dst = buffer(1,1):uint()

pinfo.cols.src = buffer(2,1):uint()

pinfo.cols.net_dst = buffer(4,1):uint()

local subtree = tree:add(example_protocol, buffer(), “Tpeer Protocol Data”)

subtree:add_le(message_length, buffer(0,1))

subtree:add_le(dest, buffer(1,1))

subtree:add_le(src, buffer(2,1))

subtree:add_le(seq, buffer(3,1))

subtree:add_le(cont, buffer(4,1))

end

— for custom protocols not based on an existing dissector protocol:

— need to add protocol to: wireshark: edit->preferences->protocols->DLT_USER->new->Payload protocol=”protocol name”

— where protocol name is name from arg1 of Proto() definition above

table = DissectorTable.get(“example-table”)

table:add(147, example_protocol)

Registering the custom dissector in wireshark:

1. Navigate to: Edit->Preferences->Protocols->DSLT_USER->Edit->new

2. Select the DLT user value that matches the DTL used in the LUA script:(147)

3. Set Payload protocol = First string argument of the Proto() LUA call.

4. Example: in example.lua, example_protocol = Proto(“example”, “example protocol”)

5. Use “example” as the Payload protocol

Now, if example.lua is used, frame data generated from the “Protocol Emulator Tool Kit” can be dissected using this script and wireshark will display the dissected frame data. Wireshark filters may also be applied to the frame data capture session.