api.txt

基于TCP/IP协议的网络入侵检测系统是在Linux平台下

                            ====================
                                libnids-1.16
                            ====================
                                      
    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.
     * Other 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.
       
                          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 structures and functions
                                      
   Now it's time for more systematic description of libnids structures.
   As mentioned, they're all declared in nids.h
   
   struct tuple4 // TCP connection parameters
   {
   unsigned short source,dest; // client and server port numbers
   unsigned long saddr,daddr;  // client and server IP addresses
   };


   struct half_stream // 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
                          // "data" 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