summaryrefslogtreecommitdiff
path: root/gssm/README
diff options
context:
space:
mode:
Diffstat (limited to 'gssm/README')
-rw-r--r--gssm/README247
1 files changed, 247 insertions, 0 deletions
diff --git a/gssm/README b/gssm/README
new file mode 100644
index 0000000..370a0a1
--- /dev/null
+++ b/gssm/README
@@ -0,0 +1,247 @@
+gssm -- Groupe Special (Software) Mobile
+
+ or
+
+gssm -- The Global Software System for Mobile communications
+
+---
+
+SUMMARY
+
+This package monitors GSM base station control channels. It uses the USRP
+and various daughterboards to capture live data, GNU Radio and custom
+modules to demodulate and decode the GSM packets, and Wireshark to display
+the data.
+
+Get it here: http://thre.at/gsm.
+
+Talk about it here: gsm-subscribe@lists.segfault.net.
+
+More here: http://wiki.thc.org/gsm.
+
+---
+
+WHAT
+
+This package monitors GSM base station control channels. It uses the USRP
+and various daughterboards to capture live data, GNU Radio and custom
+modules to demodulate and decode the GSM packets, and Wireshark to display
+the data.
+
+This version of gssm decodes most of the control channels. The control
+channels contain the information necessary for a mobile to communicate with
+a base station. The control channels which gssm currently decodes are:
+
+ FCCH The frequency correction channel.
+ SCH The synchronization channel.
+ BCCH The broadcast control channel.
+ PCH The paging channel. Downlink only, used to page mobiles.
+ AGCH The access grant channel. Downlink only, used to allocate
+ an SDCCH or directly a TCH.
+ SACCH Slow associated control channel.
+ SDCCH Stand-alone dedicated control channel.
+
+gssm displays the decoded data using Wireshark. Not only does this give us a
+very nice graphical front end to examine the dissected packets, but Wireshark
+already has quite a bit of code to dissect GSM data. Unfortunately, the
+current implementation of Wireshark does not dissect packets unique to the
+wireless interface. Up to now, there was no reason to include code to dissect
+these packets. I include a patch for wireshark-0.99.5 which adds (partial) Um
+packet dissection capability and a new custom ethertype to interface with the
+USRP.
+
+While gssm has basic functionality now, it really is alpha-quality software
+and there are a number of enhancements which must be made before it becomes
+truly useful.
+
+ 1. The Mueller and Muller clock recovery method doesn't always
+ handle the quarter-bits present in a GSM burst. A more reliable
+ method must be implemented. Until then, this software will suffer
+ from a large number of receive errors even with a high
+ signal-to-noise ratio.
+
+ 2. Wireshark dissects most GSM packets except those specific to
+ the Um interface, the wireless interface between the mobile and
+ the BTS, the Base Transciever Station.
+
+ a. I've only implemented a small portion of the Um
+ interface. Much more work must be done to complete this.
+
+ b. Only the Bbis frame type is implemented. When packets
+ arrive in Wireshark which are "malformed" or with strange
+ protocol descriptors, it is because they were sent using
+ some other frame type.
+
+ c. The interface between gssm and Wireshark is extremely
+ hacky, to say the least. It would be nice to eventually
+ standardize a GNU Radio interface for Wireshark. I also want
+ to clean up my Um interface and submit that there as well.
+
+ 3. You need to find your local GSM tower by hand. Once you've
+ found it, you need to edit the python script and enter the
+ information by hand. It would be very nice if this information was
+ automatically generated.
+
+ 4. The code is designed to support all frequency bands but I
+ haven't implemented anything but U.S. support.
+
+ 5. This code is receive-only and currently can only monitor tower
+ to mobile transmissions.
+
+ 6. Lots more.
+
+---
+
+WHERE
+
+This code is being adopted by the GSM Scanner Project and will be used as
+the base for further improvements. Questions and suggestions can certainly
+be sent to me, but they also should be directed to the mailing list --
+gsm-subscribe@lists.segfault.net. Also, check out the wiki at
+http://wiki.thc.org/gsm.
+
+The current version of the code can be found here: http://thre.at/gsm.
+Updates and bug-fixes will be found at the GSM Scanner Project,
+http://wiki.thc.org/gsm.
+
+---
+
+HOW
+
+First, you must install the gssm package.
+
+1. First install GNU Radio. Any relatively recent GNU Radio build
+ should work. I've been testing on revision 5220.
+
+2. Now build gssm. It should be as simple to install as:
+
+ jl@hackphoo ~ $ cd ~/src/gssm
+ jl@hackphoo ~/src/gssm $ ./bootstrap && ./configure && make && sudo make install
+ [...]
+ jl@hackphoo ~/src/gssm $
+
+3. Get the latest version of Wireshark and apply the patch in the
+ patch directory and then build Wireshark as usual. Note that the
+ current version of this patch is for wireshark-0.99.5 and may not
+ apply cleanly to newer versions.
+
+ jl@hackphoo ~ $ cd ~/src/wireshark-0.99.5
+ jl@hackphoo ~/src/wireshark-0.99.5 $ patch -p1 < ~/src/gssm/patch/wireshark-0.99.5-gssm.patch
+ patching file epan/dissectors/packet-gsm_a.c
+ jl@hackphoo ~/src/wireshark-0.99.5 $ ./configure && make && sudo make install
+ [...]
+ jl@hackphoo ~/src/wireshark-0.99.5 $
+
+4. gssm uses a TUN interface to send packets to Wireshark. You must
+ have the tun.ko kernel module loaded.
+
+ jl@hackphoo:~$ lsmod | grep tun
+ tun 12032 0
+ jl@hackphoo:~$
+
+ If the tun.ko kernel module is not loaded, you can try and load it
+ by hand.
+
+ jl@hackphoo:~$ lsmod | grep tun
+ jl@hackphoo:~$ sudo modprobe tun
+ jl@hackphoo:~$ lsmod | grep tun
+ tun 12032 0
+ jl@hackphoo:~$
+
+ If that doesn't work and you get a "FATAL: Module tun not found",
+ you are most likely going to have to rebuild your kernel and make
+ sure that you enable support for the TUN device.
+
+ It appears that Ubuntu 7.04 supports the TUN device by default.
+
+5. It is possible to configure the TUN device so that any user, or
+ users in a certain group, can create and delete interfaces.
+ Unfortunately, it appears that no matter who creates the
+ interfaces only root can mark these interfaces up.
+
+ Rather than require gssm to run as root, we instead use another
+ simpler program to create the interface and mark it up. This
+ program, mktun, was installed with gssm.
+
+ jl@hackphoo:~$ /usr/local/bin/mktun --help
+ note: you must be root (except perhaps to delete the interface)
+ usage: mktun [--help | -h] | [--delete | -d] <interface_name>
+ jl@hackphoo:~$ sudo /usr/local/bin/mktun gsm
+ jl@hackphoo:~$ ifconfig
+ [...]
+
+ gsm Link encap:Ethernet HWaddr 22:07:3F:7F:6A:EC
+ inet6 addr: fe80::2007:3fff:fe7f:6aec/64 Scope:Link
+ UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
+ RX packets:33324 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:0 errors:0 dropped:6 overruns:0 carrier:0
+ collisions:0 txqueuelen:500
+ RX bytes:1199664 (1.1 MiB) TX bytes:0 (0.0 b)
+
+ [...]
+ jl@hackphoo:~$
+
+ You can always delete the interface when you want to get rid of it.
+
+ jl@hackphoo:~$ sudo /usr/local/bin/mktun -d gsm
+ jl@hackphoo:~$ ifconfig | grep gsm
+ jl@hackphoo:~$
+
+Now, demod some traffic.
+
+1. Since this program doesn't scan the GSM frequency ranges for you, you
+ must locate your closest tower by hand. There are instructions on how
+ to do this at http://wiki.thc.org/gsm.
+
+ Essentially, use usrp_fft.py in the GSM frequency ranges
+ (http://en.wikipedia.org/wiki/GSM_frequency_ranges) and look for a peak
+ roughly 300kHz wide. The main channel on a base station, channel 0,
+ does not use frequency hopping so the peak of the signal you are
+ looking for should be constant.
+
+ The M&M clock recovery occasionally fails to synchronize with bursts
+ and so you need a fairly strong signal to get good results with the
+ current code. Look for signals that are at least 20dB above the noise
+ floor. (!)
+
+2. The USRP daughterboards have a frequency offset error which differs
+ from board to board. Normally this error ranges from 4kHz to 32kHz.
+ The current code will demodulate data with offsets up to 32kHz but will
+ perform much better if you compensate for the offset.
+
+ The GSM Scanner Project has a matlab script which will locate your
+ offset. This doesn't help if you don't own matlab. Currently, the
+ easiest alternative method is as follows.
+
+ a. Use usrp_fft.py and set the decimation rate to 112. When
+ the frequency correction burst is transmitted it forms a peak
+ in the signal 62.5kHz above the center of the channel.
+
+ b. Locate the 62.5kHz peak and eyeball the offset. You should
+ be able to estimate the offset within 10kHz or so.
+
+3. Enter in the frequency and the offset above into the script
+ gssm-v0.1/src/python/gssm_usrp.py.
+
+4. Start Wireshark and monitor the gsm interface.
+
+5. Start the gssm_usrp.py script.
+
+ You should see a bunch of errors start flying by. This is expected
+ even when we aren't receiving bad data because of the fairly brain-dead
+ way the code determines if channels have data. Any data displayed in
+ Wireshark has been successfully Viterbi decoded and has survived a FIRE
+ parity check and is therefore, with extremely high-probability, valid.
+ So, don't worry about all the errors. There aren't really that many
+ and it doesn't affect the valid data anyway.
+
+ If it is displayed incorrectly in Wireshark it is because I haven't
+ implemented frame types besides Bbis.
+
+ You can expand most of the packets you see and you can use the
+ Wireshark filter functionality on quite a few of the GSM information
+ elements.
+
+6. Notice obvious errors. Write code to fix the errors. Send us patches.
+
+
personal git repositories of Harald Welte. Your mileage may vary