14. Dissector

14.1. Utilities

haka.dissector.new{...} → dissector
Parameters:
  • name (string) – Dissector name.
  • type (Dissector) – Dissector type
Returns:
  • dissector (Class) – Created dissector. This object is a class that can be extended to implements the needed functions and properties.

Create a new dissector.

haka.dissector.pcall(dissector, f)
Parameters:
  • dissector (Dissector) – Dissector to protect.
  • f (function) – Function to call.

Protected call for a function inside a dissector context.

haka.dissector.opposite_direction(dir) → other_dir
Parameters:
  • dir (string) – Direction 'up' or 'down'.
Returns:
  • other_dir (string) – Other direction.

Utility function to get the other direction.

14.2. Dissector types

object Dissector

Dissector object.

<Dissector>.state

Instance of the state machine. This field is only present if the dissector sub-class has a field named state_machine and another one named auto_state_machine which evaluate to true.

Dissector:register_event(name, continue[, signal[, options]])
Parameters:
  • name (string) – Name of the event.
  • continue (function) – Continuation function.
  • signal (function) – Signaling function.
  • options (table) – List of options.

Register a new event for the dissector.

continue(self) → valid
Parameters:
Returns:
  • valid (boolean) – Should the event trigger continue.

This function tests if the other listener on this events should be evaluated.

signal(f, options, ...)
Parameters:
  • f (function) – Listener function.
  • options (table) – List of options from the event.
  • ... – Extra parameters that should be passed to the listener.

Signaling function used when a listener need to be called.

<Dissector>.name
Type:string

Name of the dissector.

<Dissector>:trigger(event, ...)
Parameters:
  • event (string) – Event name to trigger.
  • ... – Parameters to pass to the event.

Trigger an event.

abstract <Dissector>:drop()

Drop the dissector instance. It can be a packet or an flow depending on the dissector type.

abstract <Dissector>:error()

Called whenever an error is raised when inside the context of this dissector. The default implementation will do a <Dissector>.drop().

<Dissector>:continue()

Function that abort if the dissector no longer requires processing.

abstract <Dissector>:can_continue() → continue
Returns:
  • continue (boolean) – false is the dissector no longer requires processing.

Function that check if the dissector no longer requires processing.

abstract <Dissector>:next_dissector()

Get the next dissector to use.

14.2.1. Packet

dissector haka.helper.PacketDissector
Extends:Dissector 

Basic packet dissector.

event PacketDissector.receive_packet(pkt)
Parameters:

Event that is triggered whenever a new packet is received.

event PacketDissector.send_packet(pkt)
Parameters:

Event that is triggered just before sending the packet to the upper layer.

PacketDissector.receive(prev)
Parameters:
  • prev (Dissector) – Previous dissector object.

Function called to dissect a packet from data comming from another dissector.

abstract <PacketDissector>:send()

Send the packet.

abstract <PacketDissector>:inject()

Inject the packet.

14.2.2. Encapsulated packet

dissector haka.helper.EncapsulatedPacketDissector
Extends:PacketDissector 

Packet dissector that is build above another packet payload (ICMP over IP for instance).

abstract <EncapsulatedPacketDissector>:parse_payload(pkt, payload)
Parameters:
  • pkt (Dissector) – Parent dissector packet.
  • payload (vbuffer) – Payload to be parsed by this dissector.

Parse the payload coming from the previous dissector packet.

abstract <EncapsulatedPacketDissector>:create_payload(pkt, payload, init)
Parameters:
  • pkt (Dissector) – Parent dissector packet.
  • payload (vbuffer) – Payload to be parsed by this dissector.
  • init – Initialization field for the packet.

Build a new payload.

abstract <EncapsulatedPacketDissector>:forge_payload(pkt, payload)
Parameters:
  • pkt (Dissector) – Parent dissector packet.
  • payload (vbuffer) – Payload to be parsed by this dissector.

Called when the packet is about to be send.

14.2.3. Flow

dissector haka.helper.FlowDissector
Extends:Dissector 

Dissector for a flow (multiple packets). An example is HTTP for instance.

Dissector:register_streamed_event(name, continue[, options])
Parameters:
  • name (string) – Name of the event.
  • continue (function) – Continuation function.
  • signal (function) – Signaling function.
  • options (table) – List of options.

Register a new event for the dissector. This event will support the streamed option (see FlowDissector.stream_wrapper()).

FlowDissector.connections
Type:table

Table of connections to instanciate when the dissector is created.

<FlowDissector>:streamed(f, stream, current, ...)
Parameters:
  • f (function) – Function to execute.
  • stream (vbuffer_stream) – Stream.
  • current (vbuffer_iterator) – Current position in the stream.
  • ... – Parameters that are given to f.

Execute a function in streamed mode. In this mode, Haka will use coroutine to execute it in a thread like environement. It allows the function to block waiting for available data on the stream.

This function is mainly used as the signal function for event based on stream.

FlowDissector.stream_wrapper(f, options, self, stream, current, ...)
Parameters:
  • f (function) – Listener function.
  • options (table) – List of options from the event.
  • self (FlowDissector) – Current dissector
  • stream (vbuffer_stream) – Stream.
  • current (vbuffer_iterator) – Current position in the stream.
  • ... – Parameters that are given to f.

Usage:

HttpDissector:register_event('request_data', nil, haka.dissector.FlowDissector.stream_wrapper)
<FlowDissector>:get_comanager(stream) → manager
Parameters:
Returns:

Retreived the stream coroutine manager for a given stream.

<FlowDissector>:select_next_dissector(dissector)
Parameters:

Enable a dissector on the current flow.

14.3. Examples

For dissector examples, check the supported Haka dissectors.