1. Agostinho L S Castro alcastro@inescporto.pt Telecommunications and Multimedia Unit BPF - BSD Packet Filter

2. Agostinho L S Castro alcastro@inescporto.pt Telecommunications and Multimedia Unit BPF - BSD Packet Filter BPF is essentially a device driver that can be used by applications to read the packets from the network through the network adapter. BPF is an anomalous driver because it does not have a direct control on the network adapter: the adapter's device driver itself calls the BPF passing it the packets. BPF is normally used as a diagnostic tool to examine the traffic on a locally attached network. A BPF device can be configured with a filter that discards or accepts incoming packets according to a filter specification.

3. Agostinho L S Castro alcastro@inescporto.pt Telecommunications and Multimedia Unit BPF - BSD Packet Filter BPF has two main components: The network tap The packet filter The network tap collects copies of packets from the network device drivers and delivers them to listening applications. The filter decides if a packet has to be accepted and copied to the listening application.

4. Agostinho L S Castro alcastro@inescporto.pt Telecommunications and Multimedia Unit BPF - BSD Packet Filter BPF’s interface

5. Agostinho L S Castro alcastro@inescporto.pt Telecommunications and Multimedia Unit BPF - BSD Packet Filter BPF associates a filter and two buffers to every capture process that requests its services. The buffers are allocated by BPF and their dimension is usually 4 KB The store buffer is used to receive the data from the adapter The hold buffer is used to copy the packets to the application

6. Agostinho L S Castro alcastro@inescporto.pt Telecommunications and Multimedia Unit BPF - BSD Packet Filter When a packet arrives at a network interface, the link level device driver usually sends it up to the system protocol stack. But when BPF is listening on this interface, the driver first calls BPF’s network tap function. The tap feeds the packet to each participating application’s filter. This user-defined filter decides whether - a packet is to be accepted - how many bytes of each packet should be saved

7. Agostinho L S Castro alcastro@inescporto.pt Telecommunications and Multimedia Unit BPF - BSD Packet Filter If the filter accepts the packet, the tap copies the number of bytes specified by the filter from the link-level diver’s memory to the store buffer associated with that filter. At this point the interface’s device driver re-obtains control and the normal protocol processing proceeds.

8. Agostinho L S Castro alcastro@inescporto.pt Telecommunications and Multimedia Unit BPF - BSD Packet Filter The process performs a read system call to receive packets from BPF. When the hold buffer is full (or when a special timeout elapses), BPF copies it to the process’ memory and awakes the process. An application can receive more then one packet at a time. To maintain packet boundaries, BPF encapsulates the captured data from each packet with a header that includes a time stamp, length, and offsets for data alignment.

9. Agostinho L S Castro alcastro@inescporto.pt Telecommunications and Multimedia Unit BPF - BSD Packet Filter and....how can I use it PCAP – Packet Capture Library The Packet Capture library provides a high level interface to packet capture systems. All packets on the network, even those destined for other hosts, are accessible through this mechanism. ftp://ftp.ee.lbl.gov/libcap.tar.z The current version is available via anonymous ftp

10. Agostinho L S Castro alcastro@inescporto.pt Telecommunications and Multimedia Unit BPF - BSD Packet Filter #include pcap_t *pcap_open_live(char *device, int snaplen,int promisc, int to_ms, char *ebuf) pcap_t *pcap_open_offline(char *fname, char *ebuf) pcap_open_live() is used to obtain a packet capture descriptor to look at packets on the network. device is a string that specifies the network device to open. snaplen specifies the maximum number of bytes to capture. promisc specifies if the interface is to be put into promiscuous mode. to_ms specifies the read timeout in milliseconds. ebuf is used to return error text and is only set when pcap_open_live() fails and returns NULL pcap_open_offline() is called to open a ``savefile'' for reading. fname specifies the name of the file to open.

11. Agostinho L S Castro alcastro@inescporto.pt Telecommunications and Multimedia Unit BPF - BSD Packet Filter pcap_dumper_t *pcap_dump_open(pcap_t *p, char *fname) pcap_dump_open() is called to open a ``savefile'' for writing pcap_lookupdev() returns a pointer to a network device suitable for use with pcap_open_live() and pcap_lookupnet(). char *pcap_lookupdev(char *errbuf) int pcap_lookupnet(char *device, bpf_u_int32 *netp, bpf_u_int32 *maskp, char *errbuf) pcap_lookupnet() is used to determine the network number and mask associated with the network device device. netp and maskp are bpf_u_int32 pointers

12. Agostinho L S Castro alcastro@inescporto.pt Telecommunications and Multimedia Unit BPF - BSD Packet Filter pcap_dispatch() is used to collect and process packets. cnt specifies the maximum number of packets to process before returning int pcap_dispatch(pcap_t *p, int cnt, pcap_handler callback, u_char *user) void pcap_dump(u_char *user, struct pcap_pkthdr *h, u_char *sp) pcap_dump() outputs a packet to the ``savefile'' opened with pcap_dump_open(). pcap_compile() is used to compile the string str into a filter program. program is a pointer to a bpf_program struct and is filled in by pcap_compile(). optimize controls whether optimization on the resulting code is performed. netmask specifies the netmask of the local net. int pcap_compile(pcap_t *p, struct bpf_program *fp, char *str, int optimize, bpf_u_int32 netmask)

13. Agostinho L S Castro alcastro@inescporto.pt Telecommunications and Multimedia Unit BPF - BSD Packet Filter int pcap_setfilter(pcap_t *p, struct bpf_program *fp) pcap_setfilter() is used to specify a filter program. fp is a pointer to an array of bpf_program struct, usually the result of a call to pcap_compile(). pcap_loop() is similar to pcap_dispatch() except it keeps reading packets until cnt packets are processed or an error occurs. It does not return when live read timeouts occur. int pcap_loop(pcap_t *p, int cnt, pcap_handler callback, u_char *user) u_char *pcap_next(pcap_t *p, struct pcap_pkthdr *h) pcap_next() returns a u_char pointer to the next packet int pcap_datalink(pcap_t *p) pcap_datalink() returns the link layer type, e.g. DLT_EN10MB

14. Agostinho L S Castro alcastro@inescporto.pt Telecommunications and Multimedia Unit BPF - BSD Packet Filter int pcap_is_swapped(pcap_t *p) int pcap_snapshot(pcap_t *p) int pcap_major_version(pcap_t *p) pcap_snapshot() returns the snapshot length specified when pcap_open_live was called pcap_is_swapped() returns true if the current ``savefile'' uses a different byte order than the current system. pcap_major_version() returns the major number of the version of the pcap used to write the savefile pcap_minor_version() returns the major number of the version of the pcap used to write the savefile. int pcap_minor_version(pcap_t *p)

15. Agostinho L S Castro alcastro@inescporto.pt Telecommunications and Multimedia Unit BPF - BSD Packet Filter pcap_file() returns the name of the ``savefile.'' FILE *pcap_file(pcap_t *p) int pcap_stats(pcap_t *p, struct pcap_stat *ps) int pcap_fileno(pcap_t *p) void pcap_perror(pcap_t *p, char *prefix) char *pcap_geterr(pcap_t *p) int pcap_stats() returns 0 and fills in a pcap_stat struct. The values represent packet statistics from the start of the run to the time of the call. pcap_fileno() returns the file descriptor number of the ``savefile.'' pcap_geterr() returns the error text pertaining to the last pcap library error. pcap_perror() prints the text of the last pcap library error on stderr, prefixed by prefix

16. Agostinho L S Castro alcastro@inescporto.pt Telecommunications and Multimedia Unit BPF - BSD Packet Filter char *pcap_strerror(int error) void pcap_close(pcap_t *p) void pcap_dump_close(pcap_dumper_t *p) pcap_strerror() is provided in case strerror(1) isn't available pcap_dump_close() closes the ``savefile pcap_close() closes the files associated with p and deallocates resources. Examples tcpdump and arpwatch programs

17. Agostinho L S Castro alcastro@inescporto.pt Telecommunications and Multimedia Unit BPF - BSD Packet Filter Bibliography 1. PCAP(3) – manual pages 2. Wright, G. R., Stevens, W. R.,"TCP/IP Illustrated", Volume 2., Addison-Wesley, 1995 (Cap 31). 3. Wright, G. R., Stevens, W. R.,"TCP/IP Illustrated", Volume 1., Addison-Wesley, 1994 (Appendix A – The tcpdump program).

18. Agostinho L S Castro alcastro@inescporto.pt Telecommunications and Multimedia Unit BPF - BSD Packet Filter