Docbook2Wiki: Initial conversion from Docbook

2008-03-11T21:39:00Z

Initial conversion from Docbook

New page

{{Network Security Tools/TOC}}
Ettercap is a network analyzer that is free and open source. Advanced features such as ARP poisoning, packet filtering, and OS fingerprinting, along with support for password dissectors and plug-ins make Ettercap a powerful tool and a favorite among many network administrators. Ettercap has been known to compile on various Unix and Linux flavors, and has been successfully ported to run on Microsoft Windows operating systems.

This chapter introduces the concept of writing dissectors and plug-ins for Ettercap. Dissectors allow you to grab important information, such as usernames and passwords, that are transmitted over a network. For the purposes of understanding how to write a dissector, we will step through a dissector that captures and displays FTP usernames and passwords. Then, to demonstrate how to write an Ettercap plug-in, we will step through a plug-in that alerts the user when one host on the network attempts to establish a new TCP connection with another host.

== Installing and Using Ettercap ==

The latest Ettercap source code is available from ''http://ettercap.sourceforge.net/download.php''. Grab the latest tarball and compile Ettercap:

[notroot]$ '''tar zxvf ettercap-NG-x.y.z.tar.gz'''
[notroot]$ '''cd ettercap-NG-x.y.z'''
[notroot]$ '''./configure'''
[notroot]$''' make'''
[root]#''' make install'''

<div class="warning">
'''Warning'''

Make sure you obtain and install an Ettercap version that is equal to or greater than 0.7.0. Ettercap APIs of versions older than 0.7.0 differ significantly, and are no longer supported.
</div>

You can run Ettercap in console mode, curses mode, or GTK mode, the latter of which is shown in [[Network Security Tools/Modifying and Hacking Security Tools/Developing Dissectors and Plug-ins for the Ettercap Network Sniffer#networkst-CHP-2-FIG-1|Figure 2-1]].

<div id="networkst-CHP-2-FIG-1">
'''Figure 2-1. Ettercap in GTK mode'''

[[Image:Network Security Tools_I_2_tt84.png|Ettercap in GTK mode]]
</div>

Run <tt>ettercap -h</tt> to discover the plethora of options and features Ettercap provides. See the <tt>ettercap</tt> manpage for more details on available options and features.

<div class="tip">
'''Tip'''

The Ettercap web site consists of a publicly available message board dedicated to providing support in case you experience problems. Access the message board by visiting ''http://ettercap.sourceforge.net/forum/''.
</div>

== Writing an Ettercap Dissector ==

A ''dissector'' captures protocol-specific information from the network. Most Ettercap dissectors are designed to capture usernames and passwords transmitted over the network in real time. Here is an example of how to run Ettercap in console mode to sniff passwords:

[root]# '''ettercap --text --quiet'''

ettercap NG-0.7.0 copyright 2001-2004 ALoR & NaGA

Listening on en0... (Ethernet)
eth0 -> 00:0B:25:30:11:B 192.168.1.1 255.255.255.0

Privileges dropped to UID 65534 GID 65534...
0 plugins
39 protocol dissectors
53 ports monitored
6312 mac vendor fingerprint
1633 tcp OS fingerprint
2183 known services

Starting Unified sniffing...

Text only Interface activated...
Hit 'h' for inline help

FTP : 10.0.0.1:21 -> USER: john PASS: try4ndgu355m3!!

In the preceding example, the FTP dissector successfully sniffed the FTP password <tt>try4ndgu355m3!!</tt> of user <tt>john</tt> logged on to an FTP server running on host <tt>10.0.0.1</tt>.

In the following paragraphs, we will discuss the dissector responsible for capturing FTP usernames and passwords. First we will discuss the FTP authentication mechanism, followed by a detailed analysis of the FTP dissector source code.

=== Overview of FTP Authentication ===

This section discusses how FTP performs authentication. We need to understand this before we step through FTP dissector source code for Ettercap.

FTP is a plain-text protocol, and it uses no encryption. FTP servers listen on TCP port 21 by default. To authenticate with an FTP server, the client establishes a connection to TCP port 21 and expects a banner that is preceded with <tt>220</tt>:

220 Welcome to ftp.example.com

The banner string is irrelevant and can be changed by the FTP server administrator. By default, banner strings of some FTP servers provide the FTP server name and version number. With respect to the Ettercap dissector, we are concerned with only the <tt>220</tt> response code, which signifies that the FTP server is ready to serve further requests.

To authenticate with the FTP server, a client sends the <tt>USER</tt> command followed by the user's username:

USER john

If the FTP server is ready to authenticate the user, it responds with a <tt>331</tt> response code:

331 Please specify the password.

Next, the FTP client sends the <tt>PASS</tt> command followed by the user's password:

PASS try4ndgu355m3!!

If the supplied password is correct, the FTP server responds with a <tt>230</tt> response code:

230- Welcome to ftp.example.com
230 Login successful.

The outcome of a request to an FTP server depends mainly on the first digit of the three-digit response code. [[Network Security Tools/Modifying and Hacking Security Tools/Developing Dissectors and Plug-ins for the Ettercap Network Sniffer#networkst-CHP-2-TABLE-1|Table 2-1]] lists FTP response codes and their meanings, based on the first digit of the code.

<div id="networkst-CHP-2-TABLE-1">
'''Table 2-1. FTP response codes'''

{| border="1"
|-
! Response code !! Description
|-
|

1yz
| Positive preliminary reply
|-
|

2yz
| Positive completion reply
|-
|

3yz
| Positive intermediate reply
|-
|

4yz
| Transient negative completion reply
|}
</div>

Because FTP is a plain-text protocol, you can use a telnet client to connect to the FTP server and test the authentication mechanism. Here is an example:

[notroot]$ '''telnet ftp.example.com 21'''
Trying 192.168.1.2...
Connected to ftp.example.com.
Escape character is '^]'.
220 Welcome to ftp.example.com.

''' USER john'''

331 Please specify the password.
'''PASS try4ndgu355m3!!'''
230- Welcome to ftp.example.com
230 Login successful.

<div class="tip">
'''Tip'''

For more details on the FTP protocol, see RFC 959, available at ''http://www.faqs.org/rfcs/rfc959.html''.
</div>

=== The FTP Password Dissector ===

The FTP dissector's goal is to analyze FTP traffic on the network to obtain and display FTP usernames and passwords. The dissector, ''ec_ftp.c'', is located in the ''src/dissectors'' directory of the Ettercap source tree. The first few lines of the code use the <tt>include</tt> directive to include required header files for writing dissectors:

#include <ec.h>
#include <ec_decode.h>
#include <ec_dissect.h>
#include <ec_session.h>

Prototypes for defined functions are declared next. We will discuss these functions in the next few paragraphs.

FUNC_DECODER(dissector_ftp);
void ftp_init(void);

The <tt>ftp_init( )</tt> function adds an entry into appropriate Ettercap data structures by invoking the <tt>dissect_add( )</tt> function:

void _ _init ftp_init(void)
{
dissect_add("ftp", APP_LAYER_TCP, 21, dissector_ftp);
}

Note that the <tt>_ _init</tt> macro is defined in <tt>ec.h</tt> as:

#define _ _init _ _attribute_ _ ((constructor))

The <tt>_ _attribute_ _((constructor))</tt> directive causes all functions to be invoked before <tt>main( )</tt>. Therefore, the <tt>ftp_init( )</tt> function is automatically invoked when the <tt>ettercap</tt> executable is run. The <tt>dissect_add( )</tt> function should be called by every dissector because it is used to add an entry into <tt>dissect_list</tt>, a structure used by Ettercap to manage enabled dissectors. The function prototype for <tt>dissect_add( )</tt> is:

void dissect_add(char *name, u_int8 level, u_int32 port, FUNC_DECODER_PTR(decoder))

Parameters accepted by <tt>dissect_add( )</tt> are described in [[Network Security Tools/Modifying and Hacking Security Tools/Developing Dissectors and Plug-ins for the Ettercap Network Sniffer#networkst-CHP-2-TABLE-2|Table 2-2]].

<div id="networkst-CHP-2-TABLE-2">
'''Table 2-2. Parameters for dissect_add( )'''

{| border="1"
|-
! Parameter !! Description
|-
|

Name
| Name of dissector. This name is also used in the Ettercap configuration file located in ''share/etter.conf'' to enable or disable dissectors upon startup.
|-
|

Level
| Layer on which the dissector operates. Possible values are <tt>IFACE_LAYER</tt>, <tt>LINK_LAYER</tt>, <tt>NET_LAYER</tt>, <tt>PROTO_LAYER</tt>, <tt>APP_LAYER</tt>, <tt>APP_LAYER_TCP</tt>, and <tt>APP_LAYER_UDP</tt>.
|-
|

Port
| Port number on which the dissector operates.
|-
|

FUNC_DECODER_PTR(decoder)
| Pointer to "main" function of the dissector.
|}
</div>

Notice that the last parameter to <tt>dissect_add( )</tt> is <tt>dissector_ftp</tt>. This designates the <tt>dissector_ftp( )</tt> function as the entry point to the dissector code whenever traffic on TCP port 21 is captured. The <tt>FUNC_DECODER( )</tt> macro is used to define <tt>dissector_ftp</tt>:

FUNC_DECODER(dissector_ftp)

The <tt>FUNC_DECODER</tt> macro is just a wrapper around <tt>dissector_ftp</tt> that defines it as a pointer. This is useful because, as we previously noted, <tt>dissector_ftp</tt> is passed to <tt>dissect_add( )</tt>, whose last parameter accepts only a pointer to a function.

Because <tt>dissector_ftp( )</tt> is invoked every time a packet on TCP port 21 is captured, <tt>DECLARE_DISP_PTR_END( )</tt> is called to set <tt>ptr</tt> to point to the beginning of the data buffer, and <tt>end</tt> to point to the end of the buffer:

DECLARE_DISP_PTR_END(ptr, end);

Dissectors in Ettercap need to keep track of individual TCP connections. You initiate a TCP connection by sending a TCP packet with the <tt>SYN</tt> flag set, followed by a response TCP packet from the server that contains the <tt>SYN</tt> and <tt>ACK</tt> flags set. Therefore, the FTP dissector calls <tt>CREATE_SESSION_ON_SYN_ACK()</tt> , which creates a new session for the connection as soon as a packet with the <tt>SYN</tt> and <tt>ACK</tt> flags set is captured:

CREATE_SESSION_ON_SYN_ACK("ftp", s, dissector_ftp);

The first parameter to <tt>CREATE_SESSION_ON_SYN_ACK( )</tt> indicates the name of the dissector, which in our case is <tt>ftp</tt>. The second parameter to <tt>CREATE_SESSION_SYN</tt> <tt>_ACK( )</tt> is <tt>s</tt>, which is a pointer to the <tt>ec_session</tt> structure defined in ''ec_session.h''. This structure holds individual session data, and is therefore used to keep track of individual TCP connections.

The first TCP packet sent from the FTP server most likely contains the banner, including the 220 response code, and this is analyzed by calling the <tt>IF_FIRST_PACKET_FROM_SERVER()</tt> function. The <tt>IF_FIRST_PACKET_FROM_SERVER( )</tt> macro expects the block to end with <tt>ENDIF_FIRST_PACKET_FROM_SERVER( )</tt> :

IF_FIRST_PACKET_FROM_SERVER("ftp", s, ident, dissector_ftp)
{
DEBUG_MSG("\tdissector_ftp BANNER");

if (!strncmp(ptr, "220", 3))
{
PACKET->DISSECTOR.banner = strdup(ptr + 4);

if ( (ptr = strchr(PACKET->DISSECTOR.banner, '\r')) != NULL )
*ptr = '\0';
}
} ENDIF_FIRST_PACKET_FROM_SERVER(s, ident)

The <tt>ident</tt> parameter is a <tt>void</tt> pointer, and is assigned to a new session identifier of type <tt>struct dissect_ident</tt> . As the name suggests, <tt>ident</tt> is used to identify sessions. <tt>PACKET</tt> is a global structure of type <tt>struct packet_object</tt> . It holds the actual network packet data. (See ''ec_packet.h'' for the definition of <tt>packet_object</tt>.) Using <tt>strncmp()</tt> , the FTP dissector code looks for the string <tt>220</tt> within the first three characters pointed to by <tt>ptr</tt> because <tt>220</tt> is sent by an FTP server upon connect, followed by the FTP server banner. <tt>PACKET->DISSECTOR.banner</tt> is then set to the banner of the FTP server, which is basically everything after the <tt>220</tt> string. Next, <tt>strchr()</tt> is used to point <tt>ptr</tt> to the end of the banner by searching for the <tt>\r</tt> character.

The dissector makes sure to skip packets that contain no data. These packets are mainly <tt>ACK</tt> TCP packets that serve only as acknowledgments:

if (PACKET->DATA.len == 0)
return NULL;

The <tt>FROM_SERVER</tt> macro is used to skip all subsequent packets from the server. After having obtained the <tt>220</tt> server string and banner, we do not care about any data coming from the FTP server. From there on, the dissector is concerned only with username and password data that is transmitted to the server:

if (FROM_SERVER("ftp", PACKET))
return NULL;

Whitespace in the beginning of packet data is skipped:

while(*ptr == ' ' && ptr != end) ptr++;

If <tt>ptr</tt> points to <tt>end</tt>, there is no more data to analyze, so the dissector returns:

if (ptr == end)
return NULL;

The dissector uses <tt>strncasecmp()</tt> to look for the <tt>USER</tt> command sent by the FTP client to the server to capture the FTP username:

if (!strncasecmp(ptr, "USER ", 5))
{
DEBUG_MSG("\tDissector_FTP USER");

dissect_create_session(&s, PACKET, DISSECT_CODE(dissector_ftp));

ptr += 5;

SAFE_FREE(s->data);

s->data = strdup(ptr);
s->data_len = strlen(ptr);

if ( (ptr = strchr(s->data,'\r')) != NULL )
*ptr = '\0';

session_put(s);

return NULL;
}

The <tt>DEBUG_MSG( )</tt> macro prints the given string to a designated debug file if Ettercap is compiled with the <tt>--enable-debug</tt> option. If Ettercap is unable to write to the debug file, the message is printed to <tt>stderr</tt>, which causes most Unix and Linux shells to output to the console by default.

Note that the FTP dissector uses the session pointer(<tt>s</tt>) returned by <tt>CREATE_SESSION_SYN_ACK()</tt> to invoke <tt>IF_FIRST_PACKET_FROM_SERVER()</tt> , which requires a session pointer as its second parameter. However, the dissector creates a brand-new session in the preceding block when Ettercap is started after the FTP connection is established, in which case the banner and SYN+ACK packet would have already been sent and never been seen by the dissector.

The dissector advances <tt>ptr</tt> by 5 to skip the <tt>USER</tt> command followed by whitespace, so now <tt>ptr</tt> points to the username sent by the FTP client. The <tt>SAFE_FREE( )</tt> macro invokes <tt>free( )</tt> to free data only if the data is not <tt>null</tt>. The session pointer's <tt>data</tt> and <tt>data_len</tt> items are set to the username string contained in <tt>ptr</tt>, and its length. Next, <tt>session_put( )</tt> is invoked to store the session pointed to by <tt>s</tt>. This session is retrieved by the following <tt>if</tt> block, which attempts to capture the password sent by the FTP client. The <tt>strncasecmp()</tt> function compares the first five characters of <tt>ptr</tt> with the <tt>PASS</tt> string, which signifies that the FTP client has sent the user password to the server:

if ( !strncasecmp(ptr, "PASS ", 5) )
{
DEBUG_MSG("\tDissector_FTP PASS");

ptr += 5;

dissect_create_ident(&ident, PACKET, DISSECT_CODE(dissector_ftp));

if (session_get_and_del(&s, ident, DISSECT_IDENT_LEN) == -ENOTFOUND)
{
SAFE_FREE(ident);
return NULL;
}

if (s->data == NULL)
{
SAFE_FREE(ident);
return NULL;
}

PACKET->DISSECTOR.user = strdup(s->data);
PACKET->DISSECTOR.pass = strdup(ptr);

if ( (ptr = strchr(PACKET->DISSECTOR.pass, '\r')) != NULL )
*ptr = '\0';

session_free(s);
SAFE_FREE(ident);

DISSECT_MSG("FTP : %s:%d -> USER: %s PASS: %s\n", ip_addr_ntoa(&PACKET->L3.dst, tmp),
ntohs(PACKET->L4.dst), PACKET->DISSECTOR.user,

return NULL;
}

In the preceding code block, <tt>ptr</tt> is incremented by 5 to point to the password sent by the FTP client, which occurs after the string <tt>PASS</tt>. The <tt>dissect_create_ident( )</tt> function is used to create a session identifier, <tt>ident</tt>, which is used to invoke <tt>session_get_and_del( )</tt> . The <tt>session_get_and_del()</tt> function obtains the previous session into <tt>s</tt>, and deletes the session from memory because the dissector no longer needs the session after the current code block. If a previous session is not available, the dissector cannot proceed, and therefore returns after freeing <tt>ident</tt>.

<tt>PACKET->DISSECTOR.user</tt> is set to the data stored in <tt>s->data</tt>, which contains the FTP username as set in the <tt>if (!strncasecmp(ptr</tt>, "<tt>USER</tt> ", <tt>5))</tt> block. If <tt>s->data</tt> is not set (<tt>null</tt>), the dissector returns because we cannot proceed without the FTP username being available. <tt>PACKET->DISSECTOR.pass</tt> is set to the password sent by the FTP server as pointed to by <tt>ptr</tt>. The <tt>strchr( )</tt> function is used to parse until the end of the password by looking for <tt>\r</tt>. Next, <tt>s</tt> and <tt>ident</tt> are set free because the dissector no longer needs them. The <tt>DISSECT_MSG</tt> macro is used to display the FTP server IP address and the username and password sent by the FTP client to the FTP server. Once this is done, the dissector simply returns.

<div class="tip">
'''Tip'''

The source code for the FTP dissector is available in the ''src/dissectors/ec_ftp.c'' file in the Ettercap source tree. It is written by ALoR and NaGA, authors and maintainers of Ettercap.
</div>

== Writing an Ettercap Plug-in ==

You can enable or disable Ettercap plug-ins on the fly, and therefore you can use them to extend Ettercap functionality on demand. Ettercap comes bundled with a variety of plug-ins that you can find in the ''plug-ins'' directory of the Ettercap source tree. The following sections show you how to write <tt>find_tcp_conn</tt>, a plug-in that detects the initiation of a new TCP connection on the network.

=== The find_tcp_conn Plug-in ===

To establish a TCP connection with a remote host, the source host sends a TCP packet with the <tt>SYN</tt> flag set to the remote host. If the remote host is listening on a particular port, it responds with a TCP packet with the <tt>SYN</tt> and <tt>ACK</tt> flags set. The source host then sends a TCP packet with the <tt>ACK</tt> bit set to formally establish the TCP connection. This sequence is known as the ''three-way TCP handshake'' . Therefore, to detect new TCP connections with other hosts, our plug-in has to analyze the network traffic for TCP packets that have the <tt>SYN</tt> flag set. The <tt>find_tcp_conn</tt> plug-in described in the following paragraphs analyzes TCP packets for the <tt>SYN</tt> flag, and if one is found, it alerts the Ettercap user that a host on the network is attempting to establish a new TCP connection with another host.

The <tt>find_tcp_conn</tt> plug-in alerts the Ettercap user whenever a TCP packet with the <tt>SYN</tt> flag set is captured. Therefore, the plug-in alerts the Ettercap user even if the server host does not respond to the connection attempt. This plug-in can be useful for noticing when a SYN port-scan is being performed on a network.

<div class="warning">
'''Warning'''

The <tt>find_tcp_conn</tt> plug-in will not detect new TCP connections when the host running Ettercap is on a network switch because network switches attempt to segregate network traffic. Therefore, the <tt>find_tcp_conn</tt> plug-in will detect SYN packets from other hosts only when the host running Ettercap is on a network hub, or when Ettercap is instructed to perform ARP poisoning.
</div>

Every Ettercap plug-in needs to include ''ec.h'' and ''ec_plugins.h''. These files contain required global variables and plug-in APIs. The plug-in uses the <tt>packet_object</tt> structure defined in ''ec_packet.h'' along with various functions defined in ''ec_hook.h'' , so these header files need to be included as well:

#include <ec.h>
#include <ec_plugins.h>
#include <ec_packet.h>
#include <ec_hook.h>

All Ettercap plug-ins should declare <tt>plugin_load()</tt> , which serves as the entry point of a plug-in. Following is its prototype:

int plugin_load(void *);

Following is the prototype of <tt>find_tcp_conn_init( )</tt> , which is called when the plug-in is enabled, and <tt>find_tcp_conn_fini( )</tt>, which is called when the plug-in is disabled:

static int find_tcp_conn_init(void *);
static int find_tcp_conn_fini(void *);

The plug-in invokes <tt>parse_tcp()</tt> when a TCP packet is received. Here is its prototype:

static void parse_tcp(struct packet_object *po);

The <tt>plugin_register( )</tt> function in <tt>plugin_load()</tt> accepts a structure of type <tt>plugin_ops</tt> . Following is the definition of <tt>find_tcp_conn_ops</tt> , which is an instance of <tt>plugin_ops</tt>:

struct plugin_ops find_tcp_conn_ops = {
/* ettercap version MUST be the global EC_VERSION */
ettercap_version: EC_VERSION,
/* the name of the plugin */
name: "find_tcp_conn",
/* a short description of the plugin (max 50 chars) */
info: "Detect TCP connections",
/* the plugin version. */
version: "1.0",
/* activation function */
init: &find_tcp_conn_init,
/* deactivation function */
fini: &find_tcp_conn_fini,
};

Most of the items defined by <tt>find_tcp_conn_ops</tt> are self-explanatory. Note that <tt>ettercap_version</tt> must be set to <tt>EC_VERSION</tt>. Ettercap uses this value to prevent a plug-in compiled for a different version of Ettercap from attempting to load. The <tt>init</tt> item declares the function that is called when the user enables the plug-in, and the <tt>fini</tt> item declares the function that is called when the user disables the plug-in. For example, in the Ettercap GTK frontend, you can enable or disable plug-ins by selecting "Manage the plugins" from the Plugins menu and double-clicking the plug-in names.

Following is the definition of <tt>plugin_load( )</tt> , which is called when the plug-in is loaded. Users can load a plug-in by pressing Ctrl-O from the GTK frontend and selecting the appropriate plug-in file.

int plugin_load(void *handle)
{
return plugin_register(handle, &find_tcp_conn_ops);
}

Every plug-in must be assigned a unique handle, which the Ettercap engine generates when it invokes <tt>plugin_load( )</tt>. As a plug-in author, you simply need to pass <tt>handle</tt> to <tt>plugin_register( )</tt> as its first parameter. The second parameter, <tt>find_tcp_conn_ops</tt>, is the structure we declared in the previous paragraphs. As we already have seen, this structure defines plug-in details as well as the <tt>init</tt> and <tt>fini</tt> items.

Following is the definition of <tt>find_tcp_conn_init( )</tt> , which is defined as our <tt>init</tt> function and is called when the Ettercap user enables the plug-in:

static int find_tcp_conn_init(void *dummy)
{
USER_MSG("find_tcp_conn: plugin running...\n");

hook_add(HOOK_PACKET_TCP, &parse_tcp);

return PLUGIN_RUNNING;
}

The <tt>USER_MSG( )</tt> macro displays the given string to the Ettercap user. In the case of the GTK frontend, the string is displayed in the lower section of the GUI. In this case, the plug-in displays the string <tt>find_tcp_conn</tt>: <tt>plugin</tt> <tt>running..</tt>. to let the user know the plug-in has been enabled. The <tt>hook_add()</tt> function takes in two parameters. Following is its prototype:

void hook_add(int point, void (*func)(struct packet_object *po))

You use the <tt>point</tt> parameter to decide when the plug-in hook function is to be called. We pass <tt>HOOK_PACKET_TCP</tt> as the <tt>point</tt> parameter to <tt>hook_add( )</tt> to indicate that we want <tt>parse_tcp( )</tt> to be called every time Ettercap captures a TCP packet on the network. (For an explanation of other types of hooking points, see the ''doc/plugins'' text file in the Ettercap source tree.) The <tt>find_tcp_conn_init( )</tt> function returns <tt>PLUGIN_RUNNING</tt>, which indicates to the Ettercap engine that the plug-in has initialized successfully.

Here is a definition of <tt>find_tcp_conn_fini( )</tt> , which is invoked when the Ettercap user disables the plug-in:

static int find_tcp_conn_fini(void *dummy)
{
USER_MSG("find_tcp_conn: plugin terminated...\n");

hook_del(HOOK_PACKET_TCP, &parse_tcp);

return PLUGIN_FINISHED;
}

The <tt>hook_del( )</tt> function removes the <tt>parse_tcp( )</tt> function as the hook function. After <tt>hook_del( )</tt> returns, the Ettercap engine no longer invokes <tt>parse_tcp( )</tt> when a TCP packet is received. The <tt>find_tcp_conn_fini( )</tt> function returns <tt>PLUGIN_FINISHED</tt> to indicate to the Ettercap engine that the plug-in finished and can be deallocated.

Following is the definition of the <tt>parse_tcp( )</tt> function, which is called whenever Ettercap receives a TCP packet:

static void parse_tcp(struct packet_object *po)
{
char tmp1[MAX_ASCII_ADDR_LEN];
char tmp2[MAX_ASCII_ADDR_LEN];

if ( po->L4.flags != TH_SYN )
return;

USER_MSG("find_tcp_conn: Probable connection attempt %s -> %s [%d]\n",
ip_addr_ntoa(&po->L3.src, tmp1), ip_addr_ntoa(&po->L3.dst, tmp2), ntohs(po->L4.dst));
}

The <tt>if</tt> block inspects <tt>po</tt>, which contains the TCP packet captured by Ettercap. If the packet does not have the <tt>SYN</tt> flag set, <tt>L4.flags</tt> will not be equal to <tt>TH_SYN</tt>, and the function simply returns. The <tt>L4</tt> structure signifies " Layer 4," also known as the ''Transport Layer'' of the OSI model where TCP operates. <tt>L3</tt> signifies " Layer 3," also known as the ''Network Layer''" where the IP operates.

<tt>USER_MSG</tt> is invoked only if the previous <tt>if</tt> block did not return, in which case we can be certain that the captured TCP packet has the <tt>SYN</tt> flag set. Therefore, we call <tt>USER_MSG()</tt> to alert the user that an attempt to establish a new TCP connection was detected, as shown in [[Network Security Tools/Modifying and Hacking Security Tools/Developing Dissectors and Plug-ins for the Ettercap Network Sniffer#networkst-CHP-2-FIG-2|Figure 2-2]]. The <tt>ip_addr_ntoa()</tt> function accepts an IP address of type <tt>ip_addr</tt> as the first parameter and returns a string representation when given a <tt>char</tt> pointer as its second parameter. Because <tt>po->L3.src</tt> and <tt>po->L3.dst</tt> contain the source and destination IP addresses of the packet and are of type <tt>ip_addr</tt>, the plug-in invokes <tt>ip_addr_ntoa( )</tt> to convert them to strings to display them to the user via <tt>USER_MSG( )</tt>. The <tt>ntohs( )</tt> function is passed <tt>po->L4.dst</tt> as the parameter, which contains the destination port. The <tt>ntohs( )</tt> function converts a given value from network byte order to host byte order. This is useful in preserving portability because different CPUs use different byte orders.

<div id="networkst-CHP-2-FIG-2">
'''Figure 2-2. The find_tcp_conn plug-in in action'''

[[Image:Network Security Tools_I_2_tt125.png|The find_tcp_conn plug-in in action]]
</div>

=== find_tcp_conn.c ===

The easiest way to compile this plug-in is to make a new directory called ''find_tcp_conn'' in the ''plug-ins''directory in the Ettercap source tree. Then, copy over the ''Makefile'' from another plug-in called <tt>find_conn</tt>, and replace all occurrences of <tt>find_conn</tt> with <tt>find_tcp_conn</tt>. Run <tt>make</tt>, and you will end up with ''ec_find_tcp_conn.so'' in the ''.libs/'' directory. To load this plug-in from the GTK frontend, press Ctrl-O and select this file. Press Ctrl-P to go to the plug-in management section, and double-click the "find_tcp_conn" entry to enable the plug-in. Here is the complete source code for <tt>find_tcp_conn.c</tt> for easy reference:

#include <ec.h> /* required for global variables */
#include <ec_plugins.h> /* required for plugin ops */
#include <ec_packet.h>
#include <ec_hook.h>

/* prototypes */
int plugin_load(void *);
static int find_tcp_conn_init(void *);
static int find_tcp_conn_fini(void *);
static void parse_tcp(struct packet_object *po);

/* plugin operations */
struct plugin_ops find_tcp_conn_ops = {
/* ettercap version MUST be the global EC_VERSION */
ettercap_version: EC_VERSION,
/* the name of the plugin */
name: "find_tcp_conn",
/* a short description of the plugin (max 50 chars) */
info: "Detect TCP connections",
/* the plugin version. */
version: "1.0",
/* activation function */
init: &find_tcp_conn_init,
/* deactivation function */
fini: &find_tcp_conn_fini,
};
/* this function is called on plugin load */
int plugin_load(void *handle)
{
return plugin_register(handle, &find_tcp_conn_ops);
}

static int find_tcp_conn_init(void *dummy)
{
USER_MSG("find_tcp_conn: plugin running...\n");

hook_add(HOOK_PACKET_TCP, &parse_tcp);

return PLUGIN_RUNNING;
}

static int find_tcp_conn_fini(void *dummy)
{
USER_MSG("find_tcp_conn: plugin terminated...\n");

hook_del(HOOK_PACKET_TCP, &parse_tcp);

return PLUGIN_FINISHED;
}

/* Parse the TCP request */
static void parse_tcp(struct packet_object *po)
{
char tmp1[MAX_ASCII_ADDR_LEN];
char tmp2[MAX_ASCII_ADDR_LEN];

if ( po->L4.flags != TH_SYN )
return;

USER_MSG("find_tcp_conn: Probable connection attempt %s -> %s [%d]\n",
ip_addr_ntoa(&po->L3.src, tmp1), ip_addr_ntoa(&po->L3.dst, tmp2),
ntohs(po->L4.dst));
}

<div class="tip">
'''Tip'''

See the ''doc/plugins'' text file within the Ettercap source tree for a listing and description of other useful plug-in-related function calls.
</div>

Network Security Tools/Modifying and Hacking Security Tools/Developing Dissectors and Plug-ins for the Ettercap Network Sniffer - Revision history

Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki: Initial conversion from Docbook