| NCAP(3) | Library Functions Manual | NCAP(3) |
ncap — network
data capture
#include
<ncap.h>
ncap_t
ncap_create(int
maxmsgsize);
The ncap library is a high level interface
for network data capture. The source of network data can be either live
traffic or files containing previously captured or generated data. Files can
be in ncap format, as defined below, or in
pcap(3) format, and can be either normal binary files or
network sockets.
The
ncap_create()
function returns a new ncap object (structure)
having various methods (function pointers) which can be referenced to add
data sources, poll for data, loop while collecting data, and so on.
maxmsgsize is the size of the largest message (in
portable binary export format) you are expecting to handle, usually this is
70000, to allow for a 64Kbyte payload plus ncap
message header overhead. ncap_create() returns
NULL if an error occurs, in which case
errno will be set to indicate the error cause.
The ncap_t data structure is defined in the
<ncap.h> include file, which
defines at least the following symbols:
typedef enum { ncap_success = 0, ncap_failure } ncap_result_e;
typedef void (*ncap_callback_t)(ncap_t, void *, ncap_msg_ct);
typedef struct ncap *ncap_t;
struct ncap {
char * errstr;
ncap_result_e (*add_if)(ncap_t, const char *name,
const char *bpf, int promisc,
const int vlans[], int nvlan,
int *fdes);
ncap_result_e (*drop_if)(ncap_t, int fdes);
ncap_result_e (*add_nf)(ncap_t, int fdes, const char *);
ncap_result_e (*drop_nf)(ncap_t, int fdes);
ncap_result_e (*add_pf)(ncap_t, FILE *, const char *);
ncap_result_e (*drop_pf)(ncap_t, FILE *);
ncap_result_e (*add_dg)(ncap_t, int fdes);
ncap_result_e (*drop_dg)(ncap_t, int fdes);
ncap_result_e (*filter)(ncap_t, const char *);
ncap_result_e (*collect)(ncap_t, int polling,
ncap_callback_t,
void *closure);
void (*stop)(ncap_t);
struct ncap_msg (*cons)(ncap_t, struct timespec,
unsigned, unsigned,
ncap_np_e, ncap_np_ct,
ncap_tp_e, ncap_tp_ct,
size_t, const u_char *);
int (*match)(ncap_t, ncap_msg_ct);
ncap_result_e (*write)(ncap_t, ncap_msg_ct, int fdes);
ncap_result_e (*fwrite)(ncap_t, ncap_msg_ct, FILE *);
ncap_result_e (*send)(ncap_t, ncap_msg_ct, int fdes,
int flags);
void (*destroy)(ncap_t);
};
The elements of ncap_t are defined as follows:
NULL.stop()
is called). Each collected message will be formatted into an
ncap_msg structure and, if no filter has been
installed or if the message matches the installed filter, passed to the
supplied callback along with the supplied
closure.collect()
callback or from within an operating system signal
handler, this will end the loop inside
collect().NULL) , a "file
header" is output, containing a magic number and the
ncap library version number. A file header must be
the first thing in an ncap file, and should be
sent periodically on a datagram socket. If the result isncap object,
including heap memory and underlying pcap(3) objects.
Standard I/O files as provided to add_pf() are not
closed here and are the responsibility of the caller.An in-memory ncap message has the
following structure:
typedef enum { ncap_ip4 = 0, ncap_ip6 } ncap_np_e;
typedef union ncap_np *ncap_np_t;
typedef const union ncap_np *ncap_np_ct;
union ncap_np {
struct {
struct in_addr src, dst;
} ip4;
struct {
struct in6_addr src, dst;
} ip6;
};
typedef enum { ncap_udp = 0, ncap_tcp } ncap_tp_e;
typedef union ncap_tp *ncap_tp_t;
typedef const union ncap_tp *ncap_tp_ct;
union ncap_tp {
struct {
unsigned sport, dport;
} udp;
struct {
unsigned sport, dport;
unsigned offset;
unsigned flags;
} tcp;
};
#define ncap_tcp_syn 0x0001 /* first segment */
#define ncap_tcp_fin 0x0002 /* last segment */
#define ncap_tcp_rst 0x0004 /* session reset */
#define ncap_tcp_sum 0x0008 /* checksum failed */
typedef struct ncap_msg *ncap_msg_t;
typedef const struct ncap_msg *ncap_msg_ct;
struct ncap_msg {
/* Fixed part. */
struct timespec ts;
unsigned user1, user2;
ncap_np_e np;
ncap_tp_e tp;
size_t paylen;
/* Variable part. */
union ncap_np npu;
union ncap_tp tpu;
const u_char * payload;
};
The portable binary export format of an
ncap message is as follows:
Fixed part (size is 28): uint32_t message length (includes self, padding) uint32_t sec, nsec uint32_t user1, user2 uint16_t network union type (includes padding) uint16_t transport union type (includes padding) uint32_t payload length (no padding) Variable part (size is always evenly divisible by 4): u_char [] network union u_char [] transport union u_char [] payload
Reliable streams of portable binary format
ncap messages should begin with a "file
header", and datagram streams should include a "file header"
every so often for receiver synchronization. A "file header" has
the following structure:
ncap
version (currently 0x00 0x00 0x00 0x2a).select(2), sendmsg(2), writev(2), pcap(3), fdopen(3), bpf(4)
ncap filters are not implemented yet, so
for now, use bpf(3) filters in
add_if().
Copyright (c) 2007 by Internet Systems Consortium, Inc. ("ISC")
Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
| August, 2007 | Debian |