api.txt

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

   unsigned char urgdata; // one-byte buffer for urgent data
   int count;             // how many bytes has been appended to buffer "data"
                          // since the creation of a connection
   int offset;            // offset (in data stream) of first byte stored in
                          // the "data" buffer; additional explanations
                          // follow
   int count_new;         // how many bytes were appended to "data" buffer
                          // last (this) time; if == 0, no new data arrived
   char count_new_urg;    // if != 0, new urgent data arrived

   ... // other fields are auxiliary for libnids

   };


   struct tcp_stream
   {
   struct tuple4 addr;   // connections params (saddr, daddr, sport, dport)
   char nids_state;                  // logical state of the connection
   struct half_stream client,server; // structures describing client and
                                     // server side of the connection
   ...                               // other fields are auxiliary for libnids
   };

   In the above sample program function tcp_callback printed data from
   hlf->data buffer on stderr, and this data was no longer needed. After
   tcp_callback return, libnids by default frees space occupied by this
   data. Field hlf->offset will be increased by number of discarded
   bytes, and new data will be stored at the beginning of "data" buffer.
   If the above is not the desired behaviour (for instance, data
   processor needs at least N bytes of input to operate, and so far
   libnids received count_new<N bytes) one should call function
   
        void nids_discard(struct tcp_stream * a_tcp, int num_bytes)
                                      
   before tcp_callback returns. As a result, after tcp_callback return
   libnids will discard at most num_bytes first bytes from buffer "data"
   (updating "offset" field accordingly, and moving rest of the data to
   the beginning of the buffer). If nids_discard function is never called
   (like in above sample program), buffer hlf->data contains exactly
   hlf->count_new bytes. Generally, number of bytes in buffer hlf->data
   equals hlf->count-hlf->offset.
   
   Thanks to nids_discard function, a programmer doesn't have to copy
   received bytes into a separate buffer - hlf->data will always contain
   as many bytes, as possible. However, often arises a need to maintain
   auxiliary data structures per each pair (libnids_callback, tcp
   stream). For instance, if we wish to detect an attack against wu-ftpd
   (this attack involves creating deep directory on the server), we need
   to store somewhere current directory of a ftpd daemon. It will be
   changed by "CWD" instructions sent by ftp client. That's what the
   second parameter of tcp_callback is for. It is a pointer to a pointer
   to data private for each (libnids_callback, tcp stream) pair.
   Typically, one should use it as follows:
   
   void
   tcp_callback_2 (struct tcp_stream * a_tcp, struct conn_param **ptr)
   {
   if (a_tcp->nids_state==NIDS_JUST_EST)
   {
        struct conn_param * a_conn;
        if the connection is uninteresting, return;
        a_conn=malloc of some data structure
        init of a_conn
        *ptr=a_conn // this value will be passed to tcp_callback_2 in future
                    // calls
        increase some of "collect" fields
        return;
   }
   if (a_tcp->nids_state==NIDS_DATA)
   {
        struct conn_param *current_conn_param=*ptr;
        using current_conn_param and the newly received data from the net
        we search for attack signatures, possibly modyfying
        current_conn_param
        return ;

   }

   Functions nids_register_tcp and nids_register_ip* can be called
   arbitrary number of times. Two different functions (similar to
   tcp_callback) are allowed to follow the same TCP stream (with a
   certain non-default exception).
   
   Libnids parameters can be changed by modyfication of fields of the
   global variable nids_params, declared as follows:
   struct nids_prm
   {
   int n_tcp_streams; // size of the hash table used for storing structures
                      // tcp_stream; libnis will follow no more than
                      // 3/4 * n_tcp_streams connections simultaneously
                      // default value: 1040. If set to 0, libnids will
                      // not assemble TCP streams.
   int n_hosts;       // size of the hash table used for storing info on
                      // IP defragmentation; default value: 256
   char * device;     // interface on which libnids will listen for packets;
                      // default value == NULL, in which case device will
                      // be determined by call to pcap_lookupdev; special
                      // value of "all" results in libnids trying to
                      // capture packets on all interfaces (this works only
                      // with Linux kernel > 2.2.0); see also doc/NEW_LIBPCAP
   int sk_buff_size;  // size of struct sk_buff, a structure defined by
                      // Linux kernel, used by kernel for packets queuing. If
                      // this parameter has different value from
                      // sizeof(struct sk_buff), libnids can be bypassed
                      // by attacking resource managing of libnis (see TEST
                      // file). If you are paranoid, check sizeof(sk_buff)
                      // on the hosts on your network, and correct this
                      // parameter. Default value: 168
   int dev_addon;     // how many bytes in structure sk_buff is reserved for
                      // information on net interface; if dev_addon==-1, it
                      // will be corrected during nids_init() according to
                      // type of the interface libnids will listen on.
                      // Default value: -1.
   void (*syslog)();  // see description below the nids_params definition
   int syslog_level;  // if nids_params.syslog==nids_syslog, then this field
                      // determines loglevel used by reporting events by
                      // system daemon syslogd; default value: LOG_ALERT
   int scan_num_hosts;// size of hash table used for storing info on port
                      // scanning; the number of simultaneuos port
                      // scan attempts libnids will detect. if set to
                      // 0, port scanning detection will be turned
                      // off. Default value: 256.
   int scan_num_ports;// how many TCP ports has to be scanned from the same
                      // source. Default value: 10.
   int scan_delay;    // with no more than scan_delay milisecond pause
                      // between two ports, in order to make libnids report
                      // portscan attempt. Default value: 3000
   void (*no_mem)();  // called when libnids runs out of memory; it should
                      // terminate the current process
   int (*ip_filter)(struct ip*);  // this function is consulted when an IP
                      // packet arrives; if ip_filter returns non-zero, the
                      // packet is processed, else it is discarded. This way
                      // one can monitor traffic directed at selected hosts
                      // only, not entire subnet. Default function
                      // (nids_ip_filter) always returns 1
   char *pcap_filter; // filter string to hand to pcap(3). Default is
                      // NULL. be aware that this applies to the
                      // link-layer, so filters like "tcp dst port 23"
                      // will NOT correctly handle fragmented traffic.
   int promisc;       // if non-zero, the device(s) libnids reads packets
                      // from will be put in promiscuous mode. Default: 1
   int one_loop_less; // disabled by default; see the explanation
   } nids_params;

   The field syslog of nids_params variable by default contains the
   address of function nids_syslog, declared as:
   
    void nids_syslog (int type, int errnum, struct ip *iph, void *data);
                                      
   Function nids_params.syslog is used to report unusual condition, such
   as port scan attempts, invalid TCP header flags and other. This field
   should be assigned the address of a custom event logging function.
   Function nids_syslog (defined in libnids.c) can be an example on how
   to decode parameters passed to nids_params.syslog. Nids_syslog logs
   messages to system daemon syslogd, disregarding such things like
   message rate per second or free disk space (that is why it should be
   replaced).
   
   If one is interested in UDP datagrams, one should declare
   
   void udp_callback(struct tuple4 * addr, char * buf, int len, struct ip
                                  * iph);
                                      
   and register it with
   
                      nids_register_udp(udp_callback)
                                      
   Parameter addr contains address info, buf points to data carried by
   UDP packet, len is the data length, and iph points to the IP packet
   which contained the UDP packet. The checksum is verified.
   
                            6. Misc useful hacks
                                      
   As a nice toy :) function
   
                void nids_killtcp(struct tcp_stream * a_tcp)
                                      
   is implemented. It terminates TCP connection described by a_tcp by
   sending RST segments.
     _________________________________________________________________
   
   Using nids_run() has one disadvantage - the application becomes
   totally packets driven. Sometimes it is necessary to perform some task
   even when no packets arrive. Instead of nids_run(), one can use
   function
   
                              int nids_next()
                                      
   It calls pcap_next() instead of pcap_loop, that is it processes only
   one packet. If no packet is available, the process will sleep.
   Nids_next() returns 1 on success, 0 on error (nids_errbuf contains
   appropriate message then).
   
   Typically, when using nids_next(), an aplication will sleep in a
   select() function, with a snooping socket fd present in read fd_set.
   This fd can be obtained via a call to
   
                              int nids_getfd()
                                      
   It returns a file descriptor when succeeded and -1 on error (
   nids_errbuf is filled then).
     _________________________________________________________________
   
   The include file nids.h defines the constants NIDS_MAJOR (1) and
   NIDS_MINOR (16), which can be used to determine in runtime the version
   of libnids. If HAVE_NEW_PCAP (the constant also defined in nids.h ) is
   set to 1, then libnids has been compiled with support to capture
   packets on all devices (see NEW_LIBPCAP file).
     _________________________________________________________________
   
   Typically, data carried by a tcp stream can be divided into
   protocol-dependent records (say, lines of input). A tcp callback can
   receive an amount of data, which contains more then one record.
   Therefore, a tcp callback should iterate its protocol parsing routine
   over the whole amount of data received. This adds complexity to the
   code.
   If nids_params.one_loop_less is non-zero, libnids behaviour changes
   slightly. If a callback consumes some (but not all) of newly arrived
   data, libnids calls it immediately again. Only non-processed data
   remain in the buffer, and rcv->count_new is decreased appropriately.
   Thus, a callback can process only one record at the time - libnids
   will call it again, until no new data remain or no data can be
   processed. Unfortunately, this behaviour introduces horrible semantics
   problems in case of 2+ callbacks reading the same half of a tcp
   stream. Therefore, if nids_params.one_loop_less is non-zero, you are
   not allowed to attach two or more callbacks to the same half of tcp
   stream. Unfortunately, the existing interface is unable to propagate
   the error to the callback - therefore, you must watch it yourself. You
   have been warned.
     _________________________________________________________________
   
   Other applications using libnids can be found in "samples" directory.