The classes and functions in this chapter allow Lua scripts to create new
protocols for Wireshark. Proto
protocol objects can have Pref
preferences,
ProtoField
fields for filterable values that can be displayed in a details
view tree, functions for dissecting the new protocol, and so on.
The dissection function can be hooked into existing protocol tables through
DissectorTables
so that the new protocol dissector function gets called by that
protocol, and the new dissector can itself call on other, already existing protocol
dissectors by retrieving and calling the Dissector
object. A Proto
dissector
can also be used as a post-dissector, at the end of every frame’s dissection, or
as a heuristic dissector.
A refererence to a dissector, used to call a dissector against a packet or a part of it.
Obtains a dissector reference by name.
The Dissector reference.
Gets a Lua array table of all registered Dissector names.
Note | |
---|---|
this is an expensive operation, and should only be used for troubleshooting. |
Since: 1.11.3
The array table of registered dissector names.
Calls a dissector against a given packet (or part of it).
Number of bytes dissected. Note that some dissectors always return number of bytes in incoming buffer, so be aware.
A table of subdissectors of a particular protocol (e.g. TCP subdissectors like http, smtp, sip are added to table "tcp.port").
Useful to add more dissectors to a table so that they appear in the Decode As… dialog.
Creates a new DissectorTable for your dissector’s use.
ftypes.UINT8
, ftypes.UINT16
,
ftypes.UINT24
, ftypes.UINT32
, or
ftypes.STRING
(defaults to ftypes.UINT32
).
base.NONE
, base.DEC
, base.HEX
,
base.OCT
, base.DEC_HEX
or base.HEX_DEC
(defaults to base.DEC
).
The newly created DissectorTable.
Gets a Lua array table of all DissectorTable names - i.e., the string names you can use for the first argument to DissectorTable.get().
Note | |
---|---|
this is an expensive operation, and should only be used for troubleshooting. |
Since: 1.11.3
The array table of registered DissectorTable names.
Gets a Lua array table of all heuristic list names - i.e., the string names you can use for the first argument in Proto:register_heuristic().
Note | |
---|---|
this is an expensive operation, and should only be used for troubleshooting. |
Since: 1.11.3
The array table of registered heuristic list names
Obtain a reference to an existing dissector table.
The DissectorTable.
Add a Proto
with a dissector function, or a Dissector
object, to the dissector table.
Proto
or a Dissector
).
Remove existing dissectors from a table and add a new or a range of new dissectors.
Since: 1.11.3
Proto
or a Dissector
).
Remove a dissector or a range of dissectors from a table
Proto
or a Dissector
).
Remove all dissectors from a table.
Since: 1.11.3
Proto
or a Dissector
).
Try to call a dissector from a table
Number of bytes dissected. Note that some dissectors always return number of bytes in incoming buffer, so be aware.
Try to obtain a dissector from a table.
The dissector handle if found.
nil if not found.
A preference of a Protocol.
Creates a boolean preference to be added to a Proto.prefs
Lua table.
Creates an (unsigned) integer preference to be added to a Proto.prefs
Lua table.
Creates a string preference to be added to a Proto.prefs
Lua table.
Creates an enum preference to be added to a Proto.prefs
Lua table.
Creates a range preference to be added to a Proto.prefs
Lua table.
The table of preferences of a protocol.
A new protocol in Wireshark. Protocols have more uses, the main one is to dissect a protocol. But they can also be just dummies used to register preferences for other purposes.
The newly created protocol.
Creates a Proto
object.
The new Proto
object.
Registers a heuristic dissector function for this Proto
protocol,
for the given heuristic list name.
When later called, the passed-in function will be given:
Tvb
object
Pinfo
object
TreeItem
object
The function must return true
if the payload is for it, else false
.
The function should perform as much verification as possible to ensure the payload is for it, and dissect the packet (including setting TreeItem info and such) only if the payload is for it, before returning true or false.
Since version 1.99.1, this function also accepts a Dissector object as the second argument,
to allow re-using the same Lua code as the function proto.dissector(...)
. In this case,
the Dissector must return a Lua number of the number of bytes consumed/parsed: if 0 is returned,
it will be treated the same as a false
return for the heuristic; if a positive or negative
number is returned, then the it will be treated the same as a true
return for the heuristic,
meaning the packet is for this protocol and no other heuristic will be tried.
Since: 1.11.3
Mode: Retrieve or assign.
The protocol’s dissector, a function you define.
When later called, the function will be given:
Tvb
object
Pinfo
object
TreeItem
object
Mode: Assign only.
The preferences changed routine of this dissector, a Lua function you define.
Mode: Assign only.
The init routine of this dissector, a function you define.
The called init function is passed no arguments.
A Protocol expert info field, to be used when adding items to the dissection tree.
Since: 1.11.3
Creates a new ProtoExpert
object to be used for a protocol’s expert information notices.
Since: 1.11.3
expert.group.CHECKSUM
,
expert.group.SEQUENCE
, expert.group.RESPONSE_CODE
,
expert.group.REQUEST_CODE
, expert.group.UNDECODED
,
expert.group.REASSEMBLE
, expert.group.MALFORMED
,
expert.group.DEBUG
, expert.group.PROTOCOL
,
expert.group.SECURITY
, expert.group.COMMENTS_GROUP
or expert.group.DECRYPTION
.
expert.severity.COMMENT
, expert.severity.CHAT
,
expert.severity.NOTE
, expert.severity.WARN
,
or expert.severity.ERROR
.
The newly created ProtoExpert
object.
A Protocol field (to be used when adding items to the dissection tree).
Creates a new ProtoField
object to be used for a protocol field.
ftypes.BOOLEAN
, ftypes.UINT8
,
ftypes.UINT16
, ftypes.UINT24
, ftypes.UINT32
, ftypes.UINT64
, ftypes.INT8
,
ftypes.INT16
, ftypes.INT24
, ftypes.INT32
, ftypes.INT64
, ftypes.FLOAT
,
ftypes.DOUBLE
, ftypes.ABSOLUTE_TIME
, ftypes.RELATIVE_TIME
, ftypes.STRING
,
ftypes.STRINGZ
, ftypes.UINT_STRING
, ftypes.ETHER
, ftypes.BYTES
,
ftypes.UINT_BYTES
, ftypes.IPv4
, ftypes.IPv6
, ftypes.IPXNET
, ftypes.FRAMENUM
,
ftypes.PCRE
, ftypes.GUID
, ftypes.OID
, ftypes.PROTOCOL
, ftypes.REL_OID
,
ftypes.SYSTEM_ID
, ftypes.EUI64
or ftypes.NONE
.
frametype.NONE
, frametype.REQUEST
, frametype.RESPONSE
,
frametype.ACK
or frametype.DUP_ACK
if field type is ftypes.FRAMENUM.
base.NONE
, base.DEC
,
base.HEX
, base.OCT
, base.DEC_HEX
, or
base.HEX_DEC
.
The newly created ProtoField
object.
Creates a ProtoField
of an unsigned 8-bit integer (i.e., a byte).
base.DEC
, base.HEX
or base.OCT
.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
of an unsigned 16-bit integer.
base.DEC
, base.HEX
or base.OCT
.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
of an unsigned 24-bit integer.
base.DEC
, base.HEX
or base.OCT
.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
of an unsigned 32-bit integer.
base.DEC
, base.HEX
or base.OCT
.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
of an unsigned 64-bit integer.
base.DEC
, base.HEX
or base.OCT
.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
of a signed 8-bit integer (i.e., a byte).
base.DEC
, base.HEX
or base.OCT
.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
of a signed 16-bit integer.
base.DEC
, base.HEX
or base.OCT
.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
of a signed 24-bit integer.
base.DEC
, base.HEX
or base.OCT
.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
of a signed 32-bit integer.
base.DEC
, base.HEX
or base.OCT
.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
of a signed 64-bit integer.
base.DEC
, base.HEX
or base.OCT
.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
for a frame number (for hyperlinks between frames).
base.NONE
is supported for framenum.
frametype.NONE
, frametype.REQUEST
, frametype.RESPONSE
, frametype.ACK
or frametype.DUP_ACK
.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
for a boolean true/false value.
base.NONE
is used for NULL-value).
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
of a time_t structure value.
base.LOCAL
, base.UTC
or base.DOY_UTC
.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
of a time_t structure value.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
of an unstructured type.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
of an IPv4 address (4 bytes).
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
of an IPv6 address (16 bytes).
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
of an Ethernet address (6 bytes).
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
of a floating point number (4 bytes).
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
of a double-precision floating point (8 bytes).
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
of a string value.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
of a zero-terminated string value.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
for an arbitrary number of bytes.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
for an arbitrary number of unsigned bytes.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
for a Globally Unique IDentifier (GUID).
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
for an ASN.1 Organizational IDentified (OID).
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
for a sub-protocol. Since 1.99.9.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
for an ASN.1 Relative-OID.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
for an OSI System ID.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Creates a ProtoField
for an EUI64.
A ProtoField
object to be added to a table set to the Proto.fields
attribute.
Make a Proto
protocol (with a dissector function) a post-dissector.
It will be called for every frame after dissection.
Note | |
---|---|
this impacts performance (default=false). |
Make the TCP-layer invoke the given Lua dissection function for each PDU in the TCP segment, of the length returned by the given get_len_func function.
This function is useful for protocols that run over TCP and that are
either a fixed length always, or have a minimum size and have a length
field encoded within that minimum portion that identifies their full
length. For such protocols, their protocol dissector function can invoke
this dissect_tcp_pdus()
function to make it easier to handle dissecting
their protocol’s messages (i.e., their protocol data unit (PDU)). This
function shouild not be used for protocols whose PDU length cannot be
determined from a fixed minimum portion, such as HTTP or Telnet.
Since: 1.99.2
Tvb
object of the PDU’s
Tvb
(possibly reassembled), (2) the Pinfo
object,
and (3) the TreeItem
object. The Lua function must
return a Lua number of the number of bytes read/handled,
which would typically be the Tvb:len()
.
Tvb
object of the PDU’s
Tvb
(possibly reassembled), (2) the Pinfo
object,
and (3) the TreeItem
object. The Lua function must
return a Lua number of the number of bytes read/handled,
which would typically be the Tvb:len()
.