Commit 7c0b0711 authored by Mohammad Imran Syed's avatar Mohammad Imran Syed
Browse files

Update README.md

parent f37a7588
# PyPal
PyPal is the Python version of the tool Wipal which is used for time synchronization of traces captured by sniffers. It provides the functionality of merging or concatenating traces after synchronization. Additionally, the tool creates "per MAC address" traces.
PyPal is the Python version of the tool Wipal [1] which is used for time synchronization of traces captured by sniffers. It provides the functionality of merging or concatenating traces after synchronization. Additionally, the tool creates "per MAC address" traces.
The tool takes two traces (in csv or txt format) as input and then performs the option you select. You would need to have the following fields in the traces:
frame.number: Frame_number
frame.time_epoch: Frame_time_epoch
wlan.fixed.timestamp: Fixed_timestamp
wlan_radio.signal_dbm: RSSI_dBm
wlan_radio.channel: Channel
wlan.fc.type: Frame_type
wlan.fc.type_subtype: Frame_subtype
wlan.fc.retry: Retransmission
wlan.fcs: Checksum
wlan.sa: Source_MAC_address
wlan.seq: Sequence_number
wlan.frag: Fragment_number
You can use the following tshark command to extract the above mentioned fields from a pcap file.
tshark -r pcap_input_file -Y '!_ws.malformed and wlan_radio.channel==1' -T fields -E header=y -E separator=/t -e frame.number -e frame.time_epoch -e wlan.fixed.timestamp -e wlan_radio.signal_dbm -e wlan_radio.channel -e wlan.fc.type -e wlan.fc.type_subtype -e wlan.fc.retry -e wlan.fcs -e wlan.sa -e wlan.seq -e wlan.frag > csv_or_txt_output_file
**It is, however, essential to clearly define which data one can sniff depending on the location of the measurement campaign to preserve the privacy of the users. It is also necessary to carry out hashing of MAC addresses to preserve the privacy.**
**Steps involved in synchronization:**
The beacons are the closest representatives of real-time clocks. We use these frames as a base for the synchronization of traces. Two traces are used as input, one as a reference trace and the second trace is the one which has to be synchronized. The first step is to independently extract the beacons that are common in both traces. Hence, the coverage areas of the sniffers capturing these traces should overlap to perform this step. The common frames are referred to as reference frames. In the next step, the timestamps of reference frames are synchronized using linear regression over a sliding window of 3 frames. The synchronized reference frames are then used to synchronize the complete trace. The tool provides an additional option of concatenating or merging the synchronized traces [1].
**How to run to tool:**
It is preferable to use Python3.
Python3 pypal.py -h will also show you the information on how to operate the tool.
The tool has to positional arguments and those are the two traces:
trace1: trace to be synchronized
trace2: reference trace
There are several optional arguments but you have to tell the tool which one you want to use. You can use only one optional argument at a time. The arguments are given below:
-U : extract unique frames
-R : extract unique reference frames
-SR : synchronize unique reference frames
-S : synchronize traces
-C : concatenate traces (and keep the duplicate frames)
-M : merge the traces and remove the duplicate frames within a time difference of 106µs.
The time synchronization error (the difference between two timestamps of different sniffers for the same frame) has to be less than half the minimum gap between two valid IEEE 802.11 frames. In the IEEE 802.11b protocol, the minimum gap can be calculated as the 192 microsecond preamble delay plus 10 microsecond SIFS (Short Inter-Frame Space) plus 10 microsecond minimum transmission time for a MAC frame, to be a total of 212 microseconds [2].
So the precision is 212/2 = 106µs
[1] T. Claveirole and M. Dias de Amorim, “Wipal: Efficient offline merging of ieee 802.11 traces,” SIGMOBILE Mob. Comput. Commun. Rev., vol. 13, no. 4, p. 39–46, Mar. 2010. [Online]. Available: https://doi.org/10.1145/1740437.1740443
[2] J. Yeo, M. Youssef, and A. Agrawala, “A framework for wireless lan monitoring and its applications,” in Proceedings of the 3rd ACM Workshop on Wireless Security, ser. WiSe ’04. New York, NY, USA: Association for Computing Machinery, 2004, p. 70–79. [Online]. Available: https://doi.org/10.1145/1023646.1023660
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment