diff options
Diffstat (limited to 'gssm/README')
| -rw-r--r-- | gssm/README | 247 |
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. + + |