📄 api.html
字号:
<html><head><title>Libnids-1.16 API</title><meta name="generator" content="with little help of c2html"></head><body><h1><center> ====================<br> libnids-1.16<br> ====================<br></h1></center><ol><li><a href="#Introduction">Introduction</a><li><a href="#IP defragmentation">IP defragmentation</a><li><a href="#TCP stream assembly">TCP stream assembly</a><li><a href="#A sample application"> A sample application</a><li><a href="#Libnids structures">Basic libnids structures and functions</a><li><a href="#misc hacks">Misc useful hacks</a></ol><center><h2> 1. <a name="Introduction">Introduction</a></h2></center><p> Declarations of data structures and functions defined by libnids aregathered in include file "nids.h". An application which uses libnids mustinclude this file and must be linked with libnids.a.<p> An application's function main usually looks this way:<br><pre>main(){ application private processing, not related to libnids optional modification of libnids parameters if (!nids_init() ) something's wrong, terminate; registration of callback functions nids_run(); // not reached in normal situation}</pre><p> Another method is <a href="#nids_next">mentioned</a> later.<center><h2> 2. <a name="IP defragmentation">IP defragmentation</a></h2></center><p> In order to receive all IP packets seen by libnids (including fragmented ones, packets with invalid checksum et cetera) a programmer should define a callback function of the following type<br><br><code><center> void ip_frag_func(struct ip * a_packet, int len)</center></code><br><p>After calling <code>nids_init</code>, this function should be registered withlibnids:<br><br><code><center> nids_register_ip_frag(ip_frag_func);</center></code><br><p>Function <code>ip_frag_func</code> will be called from libnids; parameter <code>a_packet</code> willpoint to a received datagram, <code>len</code> is the packet length.<p> Analogically, in order to receive only packets, which will be acceptedby a target host (that is, packets not fragmented or packets assembled fromfragments; a header correctness is verified) one should define a callbackfunction<br><br><code><center> void ip_func(struct ip * a_packet)</center></code><br><p>and register it with<br><br><code><center> nids_register_ip(ip_func);</center></code><br><p><center><h2> 3. <a name="TCP stream assembly">TCP stream assembly</a></h2></center><p> In order to receive data exchanged in a TCP stream, one must declare acallback function <br><br><code><center> void tcp_callback(struct tcp_stream * ns, void ** param)</center></code><br><p>Structure <code>tcp_stream</code> provides all info on a TCP connection. For instance, itcontains two fields of type <code>struct half_stream</code> (named <code> client</code> and <code>server</code>), eachof them describing one side of a connection. We'll explain all its fieldslater.<p> One of <code>tcp_stream</code> field is named<code>nids_state</code>. Behaviour of tcp_callbackdepends on value of this field.<br><ul><li><pre> ns->nids_state==NIDS_JUST_EST</pre> In this case, <code>ns</code> describes a connection which has just been established. Tcp_callback must decide if it wishes to be notified in future of arrival of data in this connection. All the connection parameters are available (IP addresses, ports numbers etc). If the connection is interesting, tcp_callback informs libnids which data it wishes to receive (data to client, to server, urgent data to client, urgent data to server). Then the function returns.<li><pre> ns->nids_state==NIDS_DATA</pre> In this case, new data has arrived. Structures <code>half_stream</code> (members of <code>tcp_stream</code>) contain buffers with data.<li> Other values of <code>nids_state</code> field (<code>NIDS_CLOSE, NIDS_RESET, NIDS_TIMEOUT</code>) mean that the connection has been closed. Tcp_callback should free allocated resources, if any.</ul><center><h2> 4. <a name="A sample application">A sample application</a></h2></center><p>Now let's have a look at a simple application, which displays on stderr dataexchanged in all TCP connections seen by libnids.<p><pre width="80"><font color="#A020F0">#include <sys/types.h></font><font color="#A020F0">#include <sys/socket.h></font><font color="#A020F0">#include <netinet/in.h></font><font color="#A020F0">#include <netinet/in_systm.h></font><font color="#A020F0">#include <arpa/inet.h></font><font color="#A020F0">#include <string.h></font><font color="#A020F0">#include <stdio.h></font><font color="#A020F0">#include </font><font color="#666666">"nids.h"</font><font color="#A020F0"></font><strong><font color="#228B22">#define int_ntoa(x) inet_ntoa(*((struct in_addr *)&x))</font></strong>// struct tuple4 contains addresses and port numbers of the TCP connections// the following auxiliary function produces a string looking like// 10.0.0.1,1024,10.0.0.2,23char *<strong><font color="#4169E1"><a name="dres"></a>adres (struct tuple4 addr)</font></strong>{ static char buf[256]; strcpy (buf, int_ntoa (addr.saddr)); sprintf (buf + strlen (buf), <font color="#666666">",%i,"</font>, addr.source); strcat (buf, int_ntoa (addr.daddr)); sprintf (buf + strlen (buf), <font color="#666666">",%i"</font>, addr.dest); <font color="#4169E1">return</font> buf;}<strong><font color="#4169E1"><a name="tcp_callback"></a>voidtcp_callback (struct tcp_stream *a_tcp, void ** this_time_not_needed)</font></strong>{ char buf[1024]; strcpy (buf, adres (a_tcp->addr)); // we put conn params into buf <font color="#4169E1">if</font> (a_tcp->nids_state == NIDS_JUST_EST) { // connection described by a_tcp is established // here we decide, if we wish to follow this stream // sample condition: if (a_tcp->addr.dest!=23) return; // in this simple app we follow each stream, so.. a_tcp->client.collect++; // we want data received by a client a_tcp->server.collect++; // and by a server, too a_tcp->server.collect_urg++; // we want urgent data received by a // server<font color="#A020F0">#ifdef WE_WANT_URGENT_DATA_RECEIVED_BY_A_CLIENT</font> a_tcp->client.collect_urg++; // if we don't increase this value, // we won't be notified of urgent data // arrival<font color="#A020F0">#endif</font> fprintf (stderr, <font color="#666666">"%s established\n"</font>, buf); <font color="#4169E1">return</font>; } <font color="#4169E1">if</font> (a_tcp->nids_state == NIDS_CLOSE) { // connection has been closed normally fprintf (stderr, <font color="#666666">"%s closing\n"</font>, buf); <font color="#4169E1">return</font>; } <font color="#4169E1">if</font> (a_tcp->nids_state == NIDS_RESET) { // connection has been closed by RST fprintf (stderr, <font color="#666666">"%s reset\n"</font>, buf); <font color="#4169E1">return</font>; } <font color="#4169E1">if</font> (a_tcp->nids_state == NIDS_DATA) { // new data has arrived; gotta determine in what direction // and if it's urgent or not <font color="#4169E1">struct half_stream</font> *hlf; <font color="#4169E1">if</font> (a_tcp->server.count_new_urg) { // new byte of urgent data has arrived strcat(buf,<font color="#666666">"(urgent->)"</font>); buf[strlen(buf)+1]=0; buf[strlen(buf)]=a_tcp->server.urgdata; write(1,buf,strlen(buf)); <font color="#4169E1">return</font>; } // We don't have to check if urgent data to client has arrived, // because we haven't increased a_tcp->client.collect_urg variable. // So, we have some normal data to take care of. <font color="#4169E1">if</font> (a_tcp->client.count_new) { // new data for the client hlf = &a_tcp->client; // from now on, we will deal with hlf var, // which will point to client side of conn strcat (buf, <font color="#666666">"(<-)"</font>); // symbolic direction of data } <font color="#4169E1">else</font> { hlf = &a_tcp->server; // analogical strcat (buf, <font color="#666666">"(->)"</font>); } fprintf(stderr,<font color="#666666">"%s"</font>,buf); // we print the connection parameters // (saddr, daddr, sport, dport) accompanied // by data flow direction (-> or <-) write(2,hlf->data,hlf->count_new); // we print the newly arrived data } <font color="#4169E1">return</font> ;}<strong><font color="#4169E1"><a name="main"></a>int main ()</font></strong>{ // here we can alter libnids params, for instance: // nids_params.n_hosts=256; <font color="#4169E1">if</font> (!nids_init ()) { fprintf(stderr,<font color="#666666">"%s\n"</font>,nids_errbuf); exit(1); } nids_register_tcp (tcp_callback); nids_run (); <font color="#4169E1">return</font> 0;}</pre><center><h2> 5. <a name="Libnids structures">Basic libnids structures and functions</a></h2></center><p> Now it's time for more systematic description of libnids structures. As mentioned, they're all declared in <code>nids.h</code><p><pre width="80"> <font color="#4169E1">struct tuple4</font> // TCP connection parameters { unsigned short source,dest; // client and server port numbers unsigned long saddr,daddr; // client and server IP addresses }; <font color="#4169E1">struct half_stream</font> // structure describing one side of a TCP connection { char state; // socket state (ie TCP_ESTABLISHED ) char collect; // if >0, then data should be stored in // <font color="#666666">"data"</font> buffer; else // data flowing in this direction will be ignored // have a look at samples/sniff.c for an example // how one can use this field char collect_urg; // analogically, determines if to collect urgent // data char * data; // buffer for normal data unsigned char urgdata; // one-byte buffer for urgent data⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -