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.
Harald Welte
714da0d58e