SPeaCAP

_SPeaCAP_

  Copyright (c) 2006, Evan Farrer 
  SPeaCAP is licensed under a BSD style license for more information see License.txt

  For more information see: http://www.cs.utah.edu/~farrer/SPeaCAP

  Send bug reports, questions, patches to [email protected]




			   *** Introduction ***

The SPeaCAP (pronounced "Speak Up") provides a thin wrapper around the libpcap packet sniffing library.

For up to date information about SPeaCAP see http://www.cs.utah.edu/~farrer/SPeaCAP.

Most functions have been modified very little from their C counterparts and to it should be relatively easy to port C libpcap utilities into Scheme.  Any differences are documented here.  For more information about libpcap you should refer to the libpcap documentation.

To use this library on UNIX you'll need to have libpcap installed.  Many (most?) UNIX machines will already have this library installed.  For Windows the WinPcap .dlls are packaged with SPeaCAP and they should be found automatically.  Run one of the included examples to verify that the libraries are installed correctly.

Warning!
Sniffing packets on most Unix machines requires root privileges.  Although I have tried to diligently test out these functions, I make no guarantees.  You should use caution whenever writing code that will be run with root privileges.  It is recommended that root privileges be dropped (see privdrop in the Utility Functions section) obtaining a pcap descriptor to minimize the risk.  Windows users will likewise need Administrator privileges to sniff packets.  At this time privdrop doesn't do anything on Windows, but Windows users are more accustomed to having their machines broken ;).

To use the SPeaCAP library in your code use the following require:
> (require (planet "SPeaCAP.ss" ("evanfarrer" "SPeaCAP.plt" 1 0)))



			     *** Known Issues ***

Some early versions of Windows don't support getnameinfo which is used internally.



			   *** Naming Conventions ***

The functions/data provided have similar names to their C counterparts but have been modified to follow Scheme conventions.  The following rules have been followed throughout the library.  Any deviations, or other modifications to these rules will be noted when documenting the function/data.

	* The leading "pcap_" has been removed.
	* All "_"'s have been replaced with "-"'s
	* Any "unsafe" functions (see Help Desk 'ffi') have a "*" on the end.
        * All predicates have a trialing "?"
	* All setters follow the "set-foo!" convention
	* All words are separated by "-"'s



			     *** Errors ***

The SPeaCAP library handles errors by raising exceptions.  A custom exception type of exn:fail:pcap is raised for most errors.



			     *** The Data ***

The following data are provided by SPeaCAP:

> SNAPLEN = 65535
A recommended snaplen value that should be large enough for most packets

The following are valid datalink symbols:
  'DLT-INVALID
  'DLT-NULL
  'DLT-EN10MB
  'DLT-EN3MB
  'DLT-AX25
  'DLT-PRONET
  'DLT-CHAOS
  'DLT-IEEE802
  'DLT-ARCNET
  'DLT-SLIP
  'DLT-PPP
  'DLT-FDDI
  'DLT-ATM-RFC1483
  'DLT-RAW
  'DLT-SLIP-BSDOS
  'DLT-PPP-BSDOS
  'DLT-ATM-CLIP
  'DLT-PPP-SERIAL
  'DLT-PPP-ETHER
  'DLT-SYMANTEC-FIREWALL
  'DLT-C-HDLC
  'DLT-IEEE802-11
  'DLT-FRELAY
  'DLT-LOOP
  'DLT-ENC
  'DLT-LINUX-SLL
  'DLT-LTALK
  'DLT-ECONET
  'DLT-IPFILTER
  'DLT-PFLOG
  'DLT-CISCO-IOS
  'DLT-PRISM-HEADER
  'DLT-AIRONET-HEADER
  'DLT-PFSYNC
  'DLT-IP-OVER-FC
  'DLT-SUNATM
  'DLT-RIO
  'DLT-PCI-EXP
  'DLT-AURORA
  'DLT-IEEE802-11-RADIO
  'DLT-TZSP
  'DLT-ARCNET-LINUX
  'DLT-JUNIPER-MLPPP
  'DLT-APPLE-IP-OVER-IEEE1394
  'DLT-JUNIPER-MLFR
  'DLT-JUNIPER-ES
  'DLT-JUNIPER-GGSN
  'DLT-JUNIPER-MFR
  'DLT-JUNIPER-ATM2
  'DLT-JUNIPER-SERVICES
  'DLT-JUNIPER-ATM1
  'DLT-MTP2-WITH-PHDR
  'DLT-MTP2
  'DLT-MTP3
  'DLT-SCCP
  'DLT-DOCSIS
  'DLT-LINUX-IRDA
  'DLT-IBM-SP
  'DLT-IBM-SN
  'DLT-USER0
  'DLT-USER1
  'DLT-USER2
  'DLT-USER3
  'DLT-USER4
  'DLT-USER5
  'DLT-USER6
  'DLT-USER7
  'DLT-USER8
  'DLT-USER9
  'DLT-USER10
  'DLT-USER11
  'DLT-USER12
  'DLT-USER13
  'DLT-USER14
  'DLT-USER15
  'DLT-IEEE802-11-RADIO-AVS
  'DLT-JUNIPER-MONITOR
  'DLT-BACNET-MS-TP
  'DLT-PPP-PPPD
  'DLT-JUNIPER-PPPOE
  'DLT-JUNIPER-PPPOE-ATM
  'DLT-GPRS-LLC
  'DLT-GPF-T
  'DLT-GPF-F
  'DLT-GCOM-T1E1
  'DLT-GCOM-SERIAL
  'DLT-JUNIPER-PIC-PEER
  'DLT-ERF-ETH
  'DLT-ERF-POS
  'DLT-LINUX-LAPD


The following are valid iface-flags symbols:
  'PCAP-IF-FLAG-NONE
  'PCAP-IF-FLAG-LOOPBACK



			     *** The Structures ***

_net struct_
 (define-struct net (ip mask))
> net-ip : net -> (union false/c string?) 
> net-mask : net -> (union false/c string?)


_addr struct_
 (define-struct addr (addr netmask broadaddr dstaddr))
> addr-addr : addr -> sockaddr?
> addr-netmask : addr -> sockaddr?
> addr-broadaddr : addr -> sockaddr?
> addr-dstaddr : addr -> sockaddr?


_sockaddr struct_
 (define-struct sockaddr (host port))
> sockaddr-host : sockaddr -> string?
> sockaddr-port : sockaddr -> string?


_iface struct_
 (define-struct iface (name description addresses flags))
> iface-name : iface -> string?
> iface-description : iface -> string?
> iface-addresses : iface -> (listof addr?)
> iface-flags : iface -> iface-flags


_stat struct_
 (define-struct stat (ps-recv ps-drip ps-ifdrop ps-bs-capt))
> stat-recv : stat -> integer? 
> stat-drop : stat -> integer?
> stat-ifdrop : stat -> integer?
> stat-bs-capt : stat -> integer?


_timeval struct_
 (define-struct timeval (tv-sec tv-usec))
> timeval-sec : timeval -> integer? 
> timeval-usec : timeval -> integer?


_pkthdr struct_
 (define-struct pkthdr (ts caplen len))
> pkthdr-ts : pkthdr -> timeval?
> pkthdr-caplen : pkthdr -> integer?
> pkthdr-len : pkthdr -> integer?


_packet struct_
 (define-struct packet (head data))
> packet-head : packet -> pkthdr?
> packet-data : packet -> (union cpointer? bytes?)



			     *** The Pcap Functions ***

The following functions are provided by SPeaCAP:

> (unsafe-pcap!)

Provides the unsafe functions (those ending with a "*").  See Help Desk 'ffi' for more information on unsafe interfaces.


> (open-live [device (lookupdev)] [snaplen SNAPLEN] [promisc #t] [to-ms 1]) raises exn:fail:pcap

Obtain a packet descriptor for sniffing packets over a network.  The device is a string name for the interface to sniff.  The snaplen specifies the maximum number of bytes to capture.  The promisc is a boolean value specifying whether to place the interface in promiscuous mode.  An to-ms is the read timeout in milliseconds (+inf.0 for never).  Returns a pcap descriptor.  Note this function respects the current-security-guard parameter for listening sockets.


> (call-with-open-live [device (lookupdev)] [snaplen SNAPLEN] [promisc #t] [to-ms 1] proc) raises exn:fail:pcap

Calls proc passing the pcap descriptor created with open-live.  This procedure guarantees that the pcap will be closed.  Note that all of the parameters but the last one are optional.

 
> (open-dead datalink snaplen) raises exn:fail:pcap

Used to create a pcap descriptor for use in calling other SPeaCAP functions.  Can not be used for sniffing packets.  It is usually used for creating filters.  linktype is a datalink symbol, and snaplen is the maximum number of bytes to capture.  Returns a pcap descriptor.

 
> (open-offline filename) raises exn:fail:pcap

Obtain a packet descriptor for reading packets from a 'savefile'.  The filename is a string/path for the savefile.  Returns a pcap descriptor.  Note this function respects the current-security-guard parameter for file access.

 
> (call-with-open-offline filename proc) raises exn:fail:pcap

Calls proc passing the pcap descriptor created with open-offline.  This procedure guarantees that the pcap will be closed.


> (dump-open pcap filename) raises exn:fail:pcap

Opens a 'savefile' for writing. The pcap is a structure returned for open-live or open-offline.  The filename is a string name for the savefile path.  Returns a dumper descriptor.  Note this function respects the current-security-guard parameter for file access.

 
> (call-with-dump-open pcap filename proc) raises exn:fail:pcap

Calls proc passing the dumper descriptor created with dump-open.  This procedure guarantees that the dumper will be closed.


> (dump-fopen pcap FILE) raises exn:fail:unsupported

Raises a exn:fail:unsupported.  There is currently not any way to use a C-lib FILE* from Scheme.  

 
> (dump dumper pkthdr bytes)

Outputs a packet to the savefile.  dumper is the dumper descriptor returned by dump-open and pkthdr is is the packet header with bytes as the packet body.  Either could be 'hand' crafted or returned from next, next-ex and friends.

 
> (dump* dumper pkthdr cptr)

Same as dump but 3rd argument is a cpointer instead of bytes.

> (dump-flush dumper) raises exn:fail:pcap

Flushes any buffered output to the 'savefile'.


> (dump-file dumper) raises exn:fail:unsupported

Raises a exn:fail:unsupported.  There is currently not any way to use a C-lib FILE* from Scheme.  


> (dump-close dumper)

Closes the 'savefile'.


> (set-nonblock! pcap nonblock) raises exn:fail:pcap

Places the pcap descriptor into non-blocking mode or takes it out of non-blocking mode.


> (get-nonblock pcap nonblock) raises exn:fail:pcap

Returns the current non-blocking mode.


> (set-filter! pcap bpf-program) raises exn:fail:pcap

Applies a filter to a pcap descriptor.  pcap is a descriptor returned by open-live or open-offline bpf-program is the bpf-program structure returned by compile-filter.


> (find-all-devs) raises exn:fail:pcap, exn:fail:network

Returns a list off all devices that can be opened with open-live and lookup-net.  Note that there may be more interfaces on a system that are not listed due to insufficient user rights.


> (lookup-dev) raises exn:fail:pcap

Returns a single device that can be opened with open-live and lookup-net.


> (dispatch pcap count (pkthdr data breakloop) raises exn:fail:pcap

Utility function for collecting and processing packets.  Pcap is a descriptor returned from open-live or open-offline.  count is the maximum number of packet to read before returning.  The third argument is a function that takes 3 arguments.  pkthdr is the packet header structure.  data is the packet bytes.  breakloop is the continuation that can be called to break out of the dispatch loop.  dispatch will return when count packets have been read or a read timeout occurs.  Returns the number of packets read or #f if breakloop was called.


> (dispatch* pcap count (pkthdr ptr breakloop) raises exn:fail:pcap

The same as dispatch but instead of passing the packet bytes a cpointer is passed.  Note caller must call (unsafe-pcap!) first to make this and other unsafe functions available.


> (loop pcap count (pkthdr data breakloop) raises exn:fail:pcap

Same as dispatch but does return when a read timeout occurs.


> (loop* pcap count (pkthdr ptr breakloop)) raises exn:fail:pcap

The same as loop but instead of passing the packet bytes a cpointer is passed.  Note caller must call (unsafe-pcap!) first to make this and other unsafe functions available.


> (compile-filter pcap filter [optimize #t] [netmask "0.0.0.0"]) raises exn:fail:pcap

Compile filter into a bpf-program.  Pcap is a descriptor returned from open-live, open-dead, or open-offline. filter is a string that contains the bpf syntax.  optimize is whether to optimize the filter, and netmask is a string containing the netmask to filter on or "0.0.0.0" for any.  Note that the compile-filter name deviates from the standard convention to avoid a conflict with the built in compile function.


> (compile-nopcap datalink snaplen filter [optimize #t] [netmask "0.0.0.0"]) raises exn:fail:pcap

Like compile-filter.  This is provided to compile bpf filters without having to call open-*.  The datalink is a datalink symbol.  The snaplen specifies the maximum number of bytes to capture.  It returns a bpf-program.


> (next pcap)

Reads the next packet from pcap.  It returns a packet structure, or #f on error, or timeout.


> (next* pcap)

Same as next but the data field of the packet structure is a cpointer instead of bytes.  You must call (unsafe-pcap!) to make this function available.


> (next-ex pcap) raises exn:fail:pcap

Reads the next packet from pcap.  It returns a packet structure, #f on timeout, EOF if no more packets are available from a savefile.  It raises an exception if an error occurs.


> (next-ex* pcap)

Same as next-ex but the data field of the packet structure is a cpointer instead of bytes.  You must call (unsafe-pcap!) to make this function available.


> (datalink pcap)

Returns the datalink symbol for a given pcap descriptor.


> (list-datalinks pcap) raises exn:fail:pcap

Returns a list of all supported datalinks supported by the interface associated with pcap.


> (set-datalink! pcap datalink) raises exn:fail:pcap

Sets the current datalink type of of the pcap descriptor.  An exception is raised on error.


> (datalink-name-to-val name) raises exn:fail:pcap

Converts a datalink name to a datalink symbol.  This is not very useful for scheme but is included for completeness.


> (datalink-val-to-name val) raises exn:fail:pcap

Converts a datalink symbol to it's name.  This is not very usefully for scheme but is included for completeness.


> (datalink-val-to-description val) raises exn:fail:pcap

Retrieves a datalink symbols description.


> (snapshot pcap) 

Returns the snaplen that was passed to open-live.


> (swapped? pcap) 

Returns #t if the current savefile uses a different byte order than the current system, #f otherwise.


> (major-version pcap) 

Returns the format major version of the savefile associated with the pcap descriptor.


> (minor-version pcap) 

Returns the format minor version of the savefile associated with the pcap descriptor.


> (stats pcap) raises exn:fail:pcap

Returns the stats for a live capture.  Returns a stat structure.


> (file pcap) raises exn:fail:unsupported

Raises a exn:fail:unsupported exception.


> (fileno pcap) raises exn:fail:unsupported

Raises a exn:fail:unsupported exception.


> (get-selectable-fd pcap) raises exn:fail:unsupported

Raises a exn:fail:unsupported exception.


> (perror pcap string) raises exn:fail:unsupported

Raises a exn:fail:unsupported exception.


> (get-err pcap)

Returns the error text of the last error.


> (strerror integer)

Returns the error text for the given error number.
of the last error.


> (lib-version)

Returns the libpcap library version.


> (pcap-close pcap)

Closes the packet descriptor.



			     *** The Utility Functions ***

The following functions are not in libpcap but are provided for convenience:


> (privdrop username)

On Unix drops root privileges and runs as user, returns #t on success #f otherwise.  Not implemented on Windows yet.


> (inet-ntoa integer)

Converts an Internet address into an string representation.


> (inet-aton string)

Converts an Internet string into an Internet address.


> (ntohl integer)

Converts a 4 byte integer from network to host order.


> (ntohs integer)

Converts a 2 byte integer from network to host order.


> (htonl integer)

Converts a 4 byte integer from host to network order.


> (htons integer)

Converts a 2 byte integer from host to network order.