

                L   I   B   N   E   T   D   U   D   E


	      The NETwork DUmp data Displayer and Editor
                      Packet Manipulation Library

                    Connection State Tracker Plugin

                     http://netdude.sourceforge.net
         Christian Kreibich <christian.kreibich-AT-cl.cam.ac.uk>

------------------------------------------------------------------------

This plugin implements control blocks for connections running over IP.
The semantics of "connection" depend on the transport protocol: the
plugin models TCP connection endpoints using a TCP connection state
machine, UDP and other protocols are supported by a timeout mechanism.
The plugin provides connection tables to store and retrieve connections
conveniently.

Here's an API overview. The generic handle for connections are instances
of LND_ConnIDs, with specialised versions for TCP (LND_TCPConn), UDP
(LND_UDPConn) and IP (LND_IPConn). You can cast all of those into
LND_ConnIDs, and also go vice-versa by looking at the proto field in
the LND_ConnID to determine what to cast into. LND_TCPConn connections
are tracked using a simplified connection state machine, whose states
can be found in the LND_TCPState enum. Keep in mind that this is a
state machine modeling both connection end points at the same time.

Whenever possible, you should use the API in the libnd_conn_XXX family.
These delegate to the appropriate class of connection. The API for
TCP, UDP, and IP connections may be partially hidden in the future.

You create new connections by passing a packet belonging to that
connection to libnd_conn_new(), and release it using libnd_conn_free().

The source and destination of a connection can be obtained using
libnd_conn_get_src() and libnd_conn_get_dst(). These will always
return IP addresses, and port numbers when applicable (i.e., for
TCP and UDP connections for now).

The state associated with a connection is updated using
libnd_conn_update() -- what this means depends on the type of the
connection. The concept of a dead connection is generally supported
and the state can be queried using libnd_conn_is_dead(). For TCP,
the concept of state is more fine-grained and can be checked using

  libnd_tcpconn_state_get()
  libnd_tcpconn_state_get_string()

  libnd_tcpconn_handshake_seen()
  libnd_tcpconn_teardown_seen()
  libnd_tcpconn_timeout_pending()
  libnd_tcpconn_is_dead()

Arbitrary data can be associated with, queried from, and removed from
a connection using the following:

  libnd_conn_data_set()
  libnd_conn_data_get()
  libnd_conn_data_remove()

You remain ownership over the data items you hook into those connections.
The identifiers are copied internally so you need not pass string
duplicates.

The plugin also provides a hashtable for multiple connections. Lookups
in this table use LND_Packets as a key, the lookup is thus direction-
independent. The hashtable is managed using

  libnd_conn_table_new()
  libnd_conn_table_free()

The tables understand two different policies of connection management:
dead connections that are still in the table can be ignored when queried
and upon item iteration, or reported. The former is useful when you want
to assemble state for possibly multiple connections with the same identifier,
the latter is useful when you always remove dead connections from the
table anyway. Connection removal is not done automatically, this is up
to you. You specify an initial policy when creating the table, and can
switch it at any time using libnd_conn_table_[get|set]_policy().

Item management is done using

  libnd_conn_table_add(),
  libnd_conn_table_lookup(),
  libnd_conn_table_remove(),

Items in the table can be iterated in two ways:

  libnd_conn_table_foreach()

iterates over all items in the table in a sequence implied by the current
table structure (i.e. essentially walking each overflow chain sequentially).
The hash table implements move-to-front, so repeated lookups of the same
connection are O(1). The most and least recently used connections in the
connection table can be obtained using

  libnd_conn_table_get_oldest()
  libnd_conn_table_get_youngest()

and you can iterate over the connections in most-recently-used and least-
recently-used order using

  libnd_conn_table_foreach_newest()
  libnd_conn_table_foreach_oldest()

No size limit is enforced on the connection table. You can easily do 
this yourself though if required, by checking the connection table size
using

  libnd_conn_table_size()

and selecting elements from the table for eviction as desired, until the
table size is below your desired threshold again.

You can tweak the timeout settings globally, if you so desire. Have a
look at the libnd_conntrack_* constants defined in libnd_conntrack.h.

That's it. For an example of using this API, have a look at the sources
of the libnetdude traffic analyzer plugin ("Traffic-Analyzer"), the
TCP Filter plugin ("TCP-Filter"), or the flow demultiplexer ("Demux").

To build this plugin, do the following:

- run ./autogen.sh.
- run ./configure, adding --enable-debugging for debugging output.
- run make install.

This plugin has no dependancies, i.e., you don't need to have other
plugins installed to use it.

------------------------------------------------------------------------
  Yet another SRG production -- http://www.cl.cam.ac.uk/Research/SRG/
------------------------------------------------------------------------
