Libnids-1.19-win32-rebuid.zip

==================== libnids-1.19 ==================== 1. Introduction 2. IP defragmentation 3. TCP stream assembly 4. A sample application 5. Basic libnids structures and functions 6. Misc useful hacks 1. Introduction Declarations of data structures and functions defined by libnids are gathered in include file "nids.h". An application which uses libnids must include this file and must be linked with libnids.a. An application's function main usually looks this way: 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 } Another method is mentioned later. 2. IP defragmentation 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 void ip_frag_func(struct ip * a_packet, int len) After calling nids_init, this function should be registered with libnids: nids_register_ip_frag(ip_frag_func); Function ip_frag_func will be called from libnids; parameter a_packet will point to a received datagram, len is the packet length. Analogically, in order to receive only packets, which will be accepted by a target host (that is, packets not fragmented or packets assembled from fragments; a header correctness is verified) one should define a callback function void ip_func(struct ip * a_packet) and register it with nids_register_ip(ip_func); 3. TCP stream assembly In order to receive data exchanged in a TCP stream, one must declare a callback function void tcp_callback(struct tcp_stream * ns, void ** param) Structure tcp_stream provides all info on a TCP connection. For instance, it contains two fields of type struct half_stream (named client and server), each of them describing one side of a connection. We'll explain all its fields later. One of tcp_stream field is named nids_state. Behaviour of tcp_callback depends on value of this field. * ns->nids_state==NIDS_JUST_EST In this case, ns 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. * ns->nids_state==NIDS_DATA In this case, new data has arrived. Structures half_stream (members of tcp_stream) contain buffers with data. * The following values of nids_state field : + NIDS_CLOSE + NIDS_RESET + NIDS_TIMEOUT mean that the connection has been closed. Tcp_callback should free allocated resources, if any. * ns->nids_state==NIDS_EXITING In this case, libnids is exiting. This is the applications last opportunity to make use of any data left stored in the half_stream buffers. When reading traffic from a capture file rather than the network, libnids may never see a close, reset, or timeout. If the application has unprocessed data (e.g., from using nids_discard(), this allows the application to process it. 4. A sample application Now let's have a look at a simple application, which displays on stderr data exchanged in all TCP connections seen by libnids. #include <sys/types.h> #include <sys/socket.h> #include <netinet/in.h> #include <netinet/in_systm.h> #include <arpa/inet.h> #include <string.h> #include <stdio.h> #include "nids.h" #define int_ntoa(x) inet_ntoa(*((struct in_addr *)&x)) // 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,23 char * adres (struct tuple4 addr) { static char buf[256]; strcpy (buf, int_ntoa (addr.saddr)); sprintf (buf + strlen (buf), ",%i,", addr.source); strcat (buf, int_ntoa (addr.daddr)); sprintf (buf + strlen (buf), ",%i", addr.dest); return buf; } void tcp_callback (struct tcp_stream *a_tcp, void ** this_time_not_needed) { char buf[1024]; strcpy (buf, adres (a_tcp->addr)); // we put conn params into buf if (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 #ifdef WE_WANT_URGENT_DATA_RECEIVED_BY_A_CLIENT a_tcp->client.collect_urg++; // if we don't increase this value, // we won't be notified of urgent data // arrival #endif fprintf (stderr, "%s established\n", buf); return; } if (a_tcp->nids_state == NIDS_CLOSE) { // connection has been closed normally fprintf (stderr, "%s closing\n", buf); return; } if (a_tcp->nids_state == NIDS_RESET) { // connection has been closed by RST fprintf (stderr, "%s reset\n", buf); return; } if (a_tcp->nids_state == NIDS_DATA) { // new data has arrived; gotta determine in what direction // and if it's urgent or not struct half_stream *hlf; if (a_tcp->server.count_new_urg) { // new byte of urgent data has arrived strcat(buf,"(urgent->)"); buf[strlen(buf)+1]=0; buf[strlen(buf)]=a_tcp->server.urgdata; write(1,buf,strlen(buf)); return; } // 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. if (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, "(<-)"); // symbolic direction of data } else { hlf = &a_tcp->server; // analogical strcat (buf, "(->)"); } fprintf(stderr,"%s",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 } return ; } int main () { // here we can alter libnids params, for instance: // nids_params.n_hosts=256; if (!nids_init ()) { fprintf(stderr,"%s\n",nids_errbuf); exit(1); } nids_register_tcp (tcp_callback); nids_run (); return 0; } 5. Basic libnids structure