Network.Pcap.Base

pcap-0.3: A system-independent interface for user-level packet capture

Network.Pcap.Base

Portability	non-portable
Stability	experimental
Maintainer	bos@serpentine.com

Contents

Types
Device opening
Filter handling
Device utilities
Interface control
Link layer utilities
Packet processing
Sending packets
Conversion
Miscellaneous

Description

The Base module is a low-level binding to all of the functions in libpcap. See http://www.tcpdump.org for more information.

Only a minimum of marshaling is done. For a higher-level interface that's more friendly, use the Pcap module.

To convert captured packet data to a list, extract the length of the captured buffer from the packet header record and use peekArray to convert the captured data to a list. For illustration:

	import Network.Pcap.Base
	import Foreign.Marshal.Array (peekArray)

	main = do
        let printIt :: PktHdr -> Ptr Word8 -> IO ()
		printIt ph bytep = do
	          a <- peekArray (fromIntegral (hdrCaptureLength ph)) bytep 
	       	  print a

	    p <- openLive "em0" 100 True 10000
	    s <- withForeignPtr p $ \ptr -> do
	           dispatch ptr (-1) printIt
	    return ()

Note that the SockAddr exported here is not the SockAddr from Socket. The SockAddr from Socket corresponds to struct sockaddr_in in BSD terminology. The SockAddr record here is BSD's struct sockaddr. See W.R.Stevens, TCP Illustrated, volume 2, for further elucidation.

This binding should be portable across systems that can use the libpcap library from tcpdump.org. It will not work with Winpcap, a similar library for Windows, although adapting it should not prove difficult.

Synopsis

data PcapTag

data PcapDumpTag

type Pdump = ForeignPtr PcapDumpTag

type BpfProgram = ForeignPtr BpfProgramTag

data BpfProgramTag

type Callback = PktHdr -> Ptr Word8 -> IO ()

data Direction

= InOut

| In

| Out

data Link

| DLT_PPP

| DLT_RAW

| DLT_REDBACK_SMARTEDGE

| DLT_PPP_SERIAL

| DLT_PPP_ETHER

| DLT_SYMANTEC_FIREWALL

| DLT_ENC

| DLT_IEEE802_11_RADIO

| DLT_ARCNET_LINUX

| DLT_APPLE_IP_OVER_IEEE1394

| DLT_USB

| DLT_BLUETOOTH_HCI_H4

| DLT_MFR

| DLT_IEEE802_16_MAC_CPS

| DLT_USB_LINUX

| DLT_CAN20B

| DLT_IEEE802_15_4_LINUX

| DLT_PPI

| DLT_IEEE802_16_MAC_CPS_RADIO

| DLT_IEEE802_15_4

data Interface = Interface {

ifName :: String

ifDescription :: String

ifAddresses :: [PcapAddr]

ifFlags :: Word32

}

data PcapAddr = PcapAddr {

addrSA :: SockAddr

addrMask :: (Maybe SockAddr)

addrBcast :: (Maybe SockAddr)

addrPeer :: (Maybe SockAddr)

}

data SockAddr = SockAddr {

saFamily :: !Family

saAddr :: !ByteString

}

data Network = Network {

netAddr :: !Word32

netMask :: !Word32

}

data PktHdr = PktHdr {

hdrSeconds :: !Word32

hdrUseconds :: !Word32

hdrCaptureLength :: !Word32

hdrWireLength :: !Word32

}

data Statistics = Statistics {

statReceived :: !Word32

statDropped :: !Word32

statIfaceDropped :: !Word32

}

openOffline :: FilePath -> IO (ForeignPtr PcapTag)

openLive :: String -> Int -> Bool -> Int -> IO (ForeignPtr PcapTag)

openDead :: Link -> Int -> IO (ForeignPtr PcapTag)

openDump :: Ptr PcapTag -> FilePath -> IO Pdump

setFilter :: Ptr PcapTag -> String -> Bool -> Word32 -> IO ()

compileFilter :: Int -> Link -> String -> Bool -> Word32 -> IO BpfProgram

lookupDev :: IO String

findAllDevs :: IO [Interface]

lookupNet :: String -> IO Network

setNonBlock :: Ptr PcapTag -> Bool -> IO ()

getNonBlock :: Ptr PcapTag -> IO Bool

setDirection :: Ptr PcapTag -> Direction -> IO ()

datalink :: Ptr PcapTag -> IO Link

setDatalink :: Ptr PcapTag -> Link -> IO ()

listDatalinks :: Ptr PcapTag -> IO [Link]

dispatch :: Ptr PcapTag -> Int -> Callback -> IO Int

loop :: Ptr PcapTag -> Int -> Callback -> IO Int

next :: Ptr PcapTag -> IO (PktHdr, Ptr Word8)

dump :: Ptr PcapDumpTag -> Ptr PktHdr -> Ptr Word8 -> IO ()

sendPacket :: Ptr PcapTag -> Ptr Word8 -> Int -> IO ()

toPktHdr :: Ptr PktHdr -> IO PktHdr

statistics :: Ptr PcapTag -> IO Statistics

version :: Ptr PcapTag -> IO (Int, Int)

isSwapped :: Ptr PcapTag -> IO Bool

snapshotLen :: Ptr PcapTag -> IO Int

Types

data PcapTag

data PcapDumpTag

packet capture descriptor

type Pdump = ForeignPtr PcapDumpTag

dump file descriptor

type BpfProgram = ForeignPtr BpfProgramTag

Compiled Berkeley Packet Filter program

data BpfProgramTag

type Callback = PktHdr -> Ptr Word8 -> IO ()

the type of the callback function passed to dispatch or loop.

data Direction

The direction in which packets are to be captured. See setDirection.

Constructors

InOut	incoming and outgoing packets (the default
In	incoming packets
Out	outgoing packets

Instances

Eq Direction

Read Direction

Show Direction

data Link

Datalink types.

This covers all of the datalink types defined in bpf.h. Types defined on your system may vary.

Constructors

DLT_NULL	no link layer encapsulation
DLT_UNKNOWN Int	unknown encapsulation
DLT_EN10MB	10 Mbit per second (or faster) ethernet
DLT_EN3MB	original 3 Mbit per second ethernet
DLT_AX25	amateur radio AX.25
DLT_PRONET	Proteon ProNET Token Ring
DLT_CHAOS	Chaos
DLT_IEEE802	IEEE 802 networks
DLT_ARCNET	ARCNET
DLT_SLIP	Serial line IP
DLT_PPP	Point-to-point protocol
DLT_FDDI	FDDI
DLT_ATM_RFC1483	LLC SNAP encapsulated ATM
DLT_RAW	raw IP
DLT_SLIP_BSDOS	BSD OS serial line IP
DLT_PPP_BSDOS	BSD OS point-to-point protocol
DLT_ATM_CLIP	Linux classical IP over ATM
DLT_REDBACK_SMARTEDGE	Redback SmartEdge 400/800
DLT_PPP_SERIAL	PPP over serial with HDLC encapsulation
DLT_PPP_ETHER	PPP over ethernet
DLT_SYMANTEC_FIREWALL	Symantec Enterprise Firewall
DLT_C_HDLC	Cisco HDLC
DLT_IEEE802_11	IEEE 802.11 wireless
DLT_FRELAY	Frame Relay
DLT_LOOP	OpenBSD loopback device
DLT_ENC	Encapsulated packets for IPsec
DLT_LINUX_SLL	Linux cooked sockets
DLT_LTALK	Apple LocalTalk
DLT_ECONET	Acorn Econet
DLT_IPFILTER	OpenBSD's old ipfilter
DLT_PFLOG	OpenBSD's pflog
DLT_CISCO_IOS	Cisco IOS
DLT_PRISM_HEADER	Intersil Prism II wireless chips
DLT_AIRONET_HEADER	Aironet (Cisco) 802.11 wireless
DLT_HHDLC	Siemens HiPath HDLC
DLT_IP_OVER_FC	RFC 2625 IP-over-Fibre Channel
DLT_SUNATM	Full Frontal ATM on Solaris with SunATM
DLT_IEEE802_11_RADIO	802.11 plus a number of bits of link-layer information
DLT_ARCNET_LINUX	Linux ARCNET header
DLT_APPLE_IP_OVER_IEEE1394	Apple IP-over-IEEE 1394
DLT_MTP2_WITH_PHDR	SS7, C7 MTP2 with pseudo-header
DLT_MTP2	SS7, C7 Message Transfer Part 2 (MPT2)
DLT_MTP3	SS7, C7 Message Transfer Part 3 (MPT3)
DLT_SCCP	SS7, C7 SCCP
DLT_DOCSIS	DOCSIS MAC frame
DLT_LINUX_IRDA	Linux IrDA packet
DLT_USER0	Reserved for private use
DLT_USER1	Reserved for private use
DLT_USER2	Reserved for private use
DLT_USER3	Reserved for private use
DLT_USER4	Reserved for private use
DLT_USER5	Reserved for private use
DLT_USER6	Reserved for private use
DLT_USER7	Reserved for private use
DLT_USER8	Reserved for private use
DLT_USER9	Reserved for private use
DLT_USER10	Reserved for private use
DLT_USER11	Reserved for private use
DLT_USER12	Reserved for private use
DLT_USER13	Reserved for private use
DLT_USER14	Reserved for private use
DLT_USER15	Reserved for private use
DLT_PPP_PPPD	Outgoing packets for ppp daemon
DLT_GPRS_LLC	GPRS LLC
DLT_GPF_T	GPF-T (ITU-T G.7041/Y.1303)
DLT_GPF_F	GPF-F (ITU-T G.7041/Y.1303)
DLT_LINUX_LAPD	Raw LAPD for vISDN (not generic LAPD)
DLT_A429	ARINC 429
DLT_A653_ICM	ARINC 653 Interpartition Communication messages
DLT_USB	USB packet
DLT_BLUETOOTH_HCI_H4	Bluetooth HCI UART transport layer (part H:4)
DLT_MFR	Multi Link Frame Relay (FRF.16)
DLT_IEEE802_16_MAC_CPS	IEEE 802.16 MAC Common Part Sublayer
DLT_USB_LINUX	USB packets, beginning with a Linux USB header
DLT_CAN20B	Controller Area Network (CAN) v2.0B
DLT_IEEE802_15_4_LINUX	IEEE 802.15.4, with address fields padded
DLT_PPI	Per Packet Information encapsulated packets
DLT_IEEE802_16_MAC_CPS_RADIO	802.16 MAC Common Part Sublayer with radiotap radio header
DLT_IEEE802_15_4	IEEE 802.15.4, exactly as in the spec

Instances

data Interface

The interface structure.

Constructors

Interface

ifName :: String	the interface name
ifDescription :: String	interface description string (if any)
ifAddresses :: [PcapAddr]	address families supported by this interface
ifFlags :: Word32

Instances

Eq Interface

Read Interface

Show Interface

data PcapAddr

The address structure.

Constructors

PcapAddr

addrSA :: SockAddr	interface address
addrMask :: (Maybe SockAddr)	network mask
addrBcast :: (Maybe SockAddr)	broadcast address
addrPeer :: (Maybe SockAddr)	address of peer, of a point-to-point link

Instances

Eq PcapAddr

Read PcapAddr

Show PcapAddr

data SockAddr

The socket address record. Note that this is not the same as SockAddr from Socket. (That is a Haskell version of C's struct sockaddr_in. This is the real struct sockaddr from the BSD network stack.)

Constructors

SockAddr

saFamily :: !Family	an address family exported by Network.Socket
saAddr :: !ByteString

Instances

Eq SockAddr

Read SockAddr

Show SockAddr

data Network

The network address record. Both the address and mask are in network byte order.

Constructors

Network

netAddr :: !Word32	IPv4 network address
netMask :: !Word32	IPv4 netmask

Instances

Eq Network

Read Network

Show Network

data PktHdr

Constructors

PktHdr

hdrSeconds :: !Word32	timestamp (seconds)
hdrUseconds :: !Word32	timestamp (microseconds)
hdrCaptureLength :: !Word32	number of bytes present in capture
hdrWireLength :: !Word32	number of bytes on the wire

Instances

Eq PktHdr

Show PktHdr

data Statistics

Constructors

Statistics

statReceived :: !Word32	packets received
statDropped :: !Word32	packets dropped by `libpcap`
statIfaceDropped :: !Word32	packets dropped by the network interface

Instances

Eq Statistics

Show Statistics

Device opening

openOffline

:: FilePath	filename
-> IO (ForeignPtr PcapTag)
`openOffline` opens a dump file for reading. The file format is the same as used by `tcpdump` and Wireshark. The string `"-"` is a synonym for `stdin`.

openLive

:: String	device name
-> Int	snapshot length
-> Bool	set to promiscuous mode?
-> Int	timeout in milliseconds
-> IO (ForeignPtr PcapTag)
`openLive` is used to get a packet descriptor that can be used to look at packets on the network. The arguments are the device name, the snapshot legnth (in bytes), the promiscuity of the interface (`True` == promiscuous) and a timeout in milliseconds. Using `"any"` as the device name will capture packets from all interfaces. On some systems, reading from the `"any"` device is incompatible with setting the interfaces into promiscuous mode. In that case, only packets whose link layer addresses match those of the interfaces are captured.

openDead

:: Link	datalink type
-> Int	snapshot length
-> IO (ForeignPtr PcapTag)	packet capture descriptor
`openDead` is used to get a packet capture descriptor without opening a file or device. It is typically used to test packet filter compilation by `setFilter`. The arguments are the link type and the snapshot length.

openDump

:: Ptr PcapTag	packet capture descriptor
-> FilePath	dump file name
-> IO Pdump	davefile descriptor
`openDump` opens a dump file for writing. This dump file is written to by the `dump` function. The arguments are a raw packet capture descriptor and the file name, with "-" as a synonym for `stdout`.

Filter handling

setFilter

:: Ptr PcapTag	packet capture descriptor
-> String	filter string
-> Bool	optimize?
-> Word32	IPv4 network mask
-> IO ()
Set a filter on the specified packet capture descriptor. Valid filter strings are those accepted by `tcpdump`.

compileFilter

:: Int	snapshot length
-> Link	datalink type
-> String	filter string
-> Bool	optimize?
-> Word32	IPv4 network mask
-> IO BpfProgram
Compile a filter for use by another program using the Berkeley Packet Filter library.

Device utilities

lookupDev :: IO String

lookupDev returns the name of a device suitable for use with openLive and lookupNet. If you only have one interface, it is the function of choice. If not, see findAllDevs.

findAllDevs :: IO [Interface]

findAllDevs returns a list of all the network devices that can be opened by openLive. It returns only those devices that the calling process has sufficient privileges to open, so it may not find every device on the system.

lookupNet

:: String	device name
-> IO Network
Return the network address and mask for the specified interface name. Only valid for IPv4. For other protocols, use `findAllDevs` and search the `Interface` list for the associated network mask.

Interface control

setNonBlock :: Ptr PcapTag -> Bool -> IO ()

Set a packet capture descriptor into non-blocking mode if the second argument is True, otherwise put it in blocking mode. Note that the packet capture descriptor must have been obtaine from openLive.

getNonBlock :: Ptr PcapTag -> IO Bool

Return the blocking status of the packet capture descriptor. True indicates that the descriptor is non-blocking. Descriptors referring to dump files opened by openDump always return False.

setDirection :: Ptr PcapTag -> Direction -> IO ()

Specify the direction in which packets are to be captured. Complete functionality is not necessarily available on all platforms.

Link layer utilities

datalink :: Ptr PcapTag -> IO Link

Returns the datalink type associated with the given pcap descriptor.

setDatalink :: Ptr PcapTag -> Link -> IO ()

Sets the datalink type for a given pcap descriptor.

listDatalinks :: Ptr PcapTag -> IO [Link]

List all the datalink types supported by a pcap descriptor. Entries from the resulting list are valid arguments to setDatalink.

Packet processing

dispatch

:: Ptr PcapTag	packet capture descriptor
-> Int	number of packets to process
-> Callback	packet processing function
-> IO Int	number of packets read
Collect and process packets. The arguments are the packet capture descriptor, the count and a callback function. The count is the maximum number of packets to process before returning. A count of -1 means process all of the packets received in one buffer (if a live capture) or all of the packets in a dump file (if offline). The callback function is passed two arguments, a packet header record and a pointer to the packet data (`Ptr Word8`). THe header record contains the number of bytes captured, whcih can be used to marshal the data into a list or array.

loop

:: Ptr PcapTag	packet capture descriptor
-> Int	number of packet to read
-> Callback	packet processing function
-> IO Int	number of packets read
Similar to `dispatch`, but loop until the number of packets specified by the second argument are read. A negative value loops forever. This function does not return when a live read tiemout occurs. Use `dispatch` instead if you wnat to specify a timeout.

next

:: Ptr PcapTag	packet capture descriptor
-> IO (PktHdr, Ptr Word8)	packet header and data of the next packet
Read the next packet (equivalent to calling `dispatch` with a count of 1).

dump

:: Ptr PcapDumpTag	dump file descriptor
-> Ptr PktHdr	packet header record
-> Ptr Word8	packet data
-> IO ()
Write the packet data given by the second and third arguments to a dump file opened by `openDead`. `dump` is designed so it can be easily used as a default callback function by `dispatch` or `loop`.

Sending packets

sendPacket

:: Ptr PcapTag
-> Ptr Word8	packet data (including link-level header)
-> Int	packet size
-> IO ()
Send a raw packet through the network interface.

Conversion

toPktHdr :: Ptr PktHdr -> IO PktHdr

Miscellaneous

statistics :: Ptr PcapTag -> IO Statistics

Returns the number of packets received, the number of packets dropped by the packet filter and the number of packets dropped by the interface (before processing by the packet filter).

version :: Ptr PcapTag -> IO (Int, Int)

Version of the library. The returned pair consists of the major and minor version numbers.

isSwapped :: Ptr PcapTag -> IO Bool

isSwapped returns True if the current dump file uses a different byte order than the one native to the system.

snapshotLen :: Ptr PcapTag -> IO Int

The snapshot length that was used in the call to openLive.

Produced by Haddock version 0.8