WinPcap Autoit3 UDF

v1.2c (updated: May 23rd 2011)

http://opensource.grisambre.net/pcapau3

[Examples] [Function Reference] [Download] [History] [Links]


The below script (UDF) allows very simply from an Autoit script to access the main functionalities offered by the WinPcap driver: capture, filter, save/read and send data packets on a network interface. This was developped with Autoit3 v3.3.0.0 and is free and "open source", and licensed under the GNU GPL 3 - copyleft Nicolas Ricquemaque 2008 [contact: opensource (arobase) grisambre dot net].

Quick examples

A few quick examples is the best way to show how it works ! However, only minimal error detection is made here. For a more comprehensive example, just have a look into the winpcap_demo.au3 included with the library archive.

Example(1): Displaying your device list with full information:

Code:

#include <Array.au3> #include <Winpcap.au3> $winpcap=_PcapSetup() ; initialize winpcap $pcap_devices=_PcapGetDeviceList() ; get devices list _ArrayDisplay($pcap_devices,"Devices list",-1,1) ; display it _PcapFree() ; close winpcap

Example(2): Capturing ICMP packets for 10 seconds

Code:

; initialise the Library $winpcap=_PcapSetup() If ($winpcap=-1) Then MsgBox(16,"Pcap error !","WinPcap not found !") exit EndIf ; Get the interfaces list for which a capture is possible $pcap_devices=_PcapGetDeviceList() If ($pcap_devices=-1) Then MsgBox(16,"Pcap error !",_PcapGetLastError()) exit EndIf ; Start a capture on interface #0, for ICMP packets only $pcap=_PcapStartCapture($pcap_devices[0][0],"icmp") If ($pcap=-1) Then MsgBox(16,"Pcap error !",_PcapGetLastError()) EndIf ; Detect of what type is the opened interface (ethernet, ATM, X25...) $linktype=_PcapGetLinkType($pcap) If ($linktype[1]<>"EN10MB") Then MsgBox(16,"Pcap error !","This example only accepts Ethernet devices...") Endif ; Capture anything that matches our filter "ICMP" for 10 seconds... $time0=TimerInit() While (TimerDiff($time0)<10000) ; capture the packets for 10 seconds... $packet=_PcapGetPacket($pcap) If IsArray($packet) Then ; here do something with your data EndIf Wend ; Stop capture _PcapStopCapture($pcap) ; release ressources _PcapFree()

Example(3): Saving http traffic to a pcap file for 10s...

Code:

$winpcap=_PcapSetup() ; initialise the Library $pcap_devices=_PcapGetDeviceList() ; Get the interfaces list for which a capture is possible ; Start a capture on interface #0, in promiscuous mode, for http packets only $pcap=_PcapStartCapture($pcap_devices[0][0],"tcp port 80",1) ; Open pcap file for writting $pcapfile=_PcapSaveToFile($pcap,"mycapture.pcap") If ($pcapfile=0) Then MsgBox(16,"Pcap error !",_PcapGetLastError()) ; Write all http traffic to the file for 10s... $time0=TimerInit() While (TimerDiff($time0)<10000) $packet=_PcapGetPacket($pcap) If IsArray($packet) Then _PcapWriteLastPacket($pcapfile) Wend _PcapStopCaptureFile($pcapfile) ; Close pcap file _PcapStopCapture($pcap) ; Stop capture _PcapFree() ; release ressources

Example(4): Reading a whole existing pcap file...

Code:

$winpcap=_PcapSetup() ; initialise the Library ; Open pcap file for reading $pcap=_PcapStartCapture("file://mycapture.pcap") ; Read whatever is in the file until its end. Do $packet=_PcapGetPacket($pcap) If IsArray($packet) Then ; Do something with your data here... EndIf Until $packet=-2 ; EOF _PcapStopCapture($pcap) ; Stop capture _PcapFree() ; release ressources

Example(5): Sending a valid ethernet broadcast on your lan...

Code:

#include <Winpcap.au3> $winpcap=_PcapSetup() ; initialize winpcap $pcap_devices=_PcapGetDeviceList() ; get devices list $pcap=_PcapStartCapture($pcap_devices[1][0]) ; my interface $broadcastmac="FFFFFFFFFFFF" ; broacast $mymac=StringReplace($pcap_devices[1][6],":","") ; my mac address in hex $ethertype="3366" ; fake ethertype, means nothing, just for example... $mydata="0123456789" ; dumb padding... $mypacket="0x"&$broadcastmac&$mymac&$ethertype&$mydata ; stick together to a binary string ! _PcapSendPacket($pcap,$mypacket) ; sends a valid ethernet broadcast ! _PcapFree() ; close winpcap


UDF Functions reference

_PcapSetup()

Initialise the Winpcap DLL and setup some Global variables.

Parameters: None

Return Value:

_PcapFree()

Free resources opened by a previous call to _PcapSetup().

Parameters: None

Return Value: None



_PcapGetLastError([$pcap=0])

Function to be called to get clues why an error was returned by any other function in this library.

Parameters:
Return Value:

_PcapGetDeviceList()

Returns a list of interface/devices which can be opened for capture.

Parameters: None

Return Value:


_PcapGetLinkType($pcap)

Provides LinkType for opened capture $pcap.

Parameters:
Return Value:

_PcapGetStats($pcap)

Provide some statistics about the current capture.

Parameters:
Return Value:

_PcapStartCapture($DeviceName[,$filter=""[,$promiscuous=0[,$PacketLen=65536[,$buffersize=0[,$realtime=1]]]])

Starts a non-blocking capture on interface $DeviceName.

Parameters:
Return Value:

_PcapStopCapture($pcap)

Stops an previously opened capture.

Parameters:
Return Value: None



_PcapIsPacketReady($pcap)

Returns true if some packets has been received and is ready for reading.

Parameters:
Return Value:

_PcapGetPacket($pcap)

Get last packet captured from Winpcap buffer.

Parameters:
Return Value:

_PcapSendPacket($pcap,$data)

Sends a raw packet to the interface.

Parameters:
Return Value:

_PcapSaveToFile($pcap,$filename)

Opens a pcap file so save packets.

Parameters:
Return Value:

_PcapWriteLastPacket($handle)

Writes the last received packet to the pcap file previously opened by a call to _PcapSaveToFile().

Parameters:
Return Value:

_PcapStopCaptureFile($handle)

Closes the pcap file previously opened by a call to _PcapSaveToFile().

Parameters:
Return Value:

_PcapListLinkTypes($pcap)

Get a list of available LinkTypes for opened capture $pcap.

Parameters:
Return Value:

_PcapSetLinkType($pcap,$dlt)

Set one of the available linktype given by a call to _PcapListLinkTypes() as the active linktype for opened capture $pcap.

Parameters:
Return Value:

_PcapBinaryGetVal($data,$offset,$bytes)

Extract a value from a binary string (from 1 to 4 bytes, so 8 to 32 bits unsigned).

Parameters:
Return Value:

_PcapBinarySetVal(Byref $data,$offset,$value,$bytes)

Sets a value inside a binary string (from 1 to 4 bytes, so 8 to 32 bits unsigned). Before calling this function, one should make sure that $data contains at least $offset+$bytes binary bytes !

Parameters:
Return Value:

_PcapIpCheckSum($data,$ipoffset=14)

Computes the IP checksum of the packet; useful for forging a new packet. Before calling this function, one should make sure that $data contains an IP packet !

Parameters: Return Value:

_PcapIcmpCheckSum($data,$ipoffset=14)

Computes the ICMP checksum of the packet; useful for forging a new packet. Before calling this function, one should make sure that $data contains an ICMP packet !

Parameters: Return Value:

_PcapTcpCheckSum($data,$ipoffset=14)

Computes the TCP checksum of the packet; useful for forging a new packet. Before calling this function, one should make sure that $data contains a TCP packet !

Parameters: Return Value:

_PcapUdpCheckSum($data,$ipoffset=14)

Computes the UDP checksum of the packet; useful for forging a new packet. Before calling this function, one should make sure that $data contains an UDP packet !

Parameters: Return Value:

_PcapCleanDeviceName($fullname)

Remove boring text from the WinPcap device name (example: returns "VIA Rhine II Fast Ethernet Adapter (Microsoft's Packet Scheduler)" instead of "Network adapter 'VIA Rhine II Fast Ethernet Adapter (Microsoft's Packet Scheduler) ' on local host").

Parameters: Return Value:

Download

Contents : Actual version (1.2b): winpcapau3.zip


History

v1.0a (April 2009)
First public release.
v1.0b (April 2009)

v1.1a (April 11th 2009)

v1.2a (April 22th 2009) : A few IP utility functions...

v1.2b (April 24th 2009)

v1.2c (April 23rd 2011)

Links