<note warning>This is outdated. We are working hard on getting this project finished (ETA Christmas 2013).</note>

<note tip>It seems that nobody cares about "ETA Christmas 2013". (--Christmas 2015)</note>

brmlab GSM stack is similar to ccch_scan, but should implement the following two important features:
  * use "sendfifo" to inject a hopping sequence into a running sniffer - to sniff calls after you cracked the key
  * use master-slave architecture to sniff multiple parallel conversations on one BTS - one phone camps on BCCH and instructs other phones to go to CCCH

It used to work, but now it is broken.
  * Hopping channels don't work at all. Like if you have an immediate assignment to a hopping CCCH, you won't sniff anything.
  * The slave takes several frames to sync, so you lose valuable known plaintext. This could be fixed by pre-syncing slaves.

Despite having my e-mail address in AUTHORS file, I will not support this thing anymore. Use [[user:jenda:gsm|gsmtk]] or try to work this out.

<code>

Quick start guide to this distribution

***

 What you will need

  + A Linux distribution (tested Debian Wheezy and Fedora on x86 and amd64)
    + there used to be "recent" here, but it was here for several years, so "recent" is not required anymore
  + An osmocom-compatible phone (Motorola Cxxx) or modem (openmoko/freerunner) and serial interface to it
  + Wireshark 1.8.0 or newer
  + ~600 MB of disk space
  + 1337 h4x1n9 skillz

It would be nice to have
  + More phones
  + Uplink filters removed
    Phones have bandpass filter that they don't receive uplink well (only 10-30 metres).
    http://bb.osmocom.org/trac/wiki/Hardware/FilterReplacement
  + Access to a fast A5/1 cracker (demand 1s/burst throughput and 10s latency :)
    It is possible to do some work on desktop with 2TB harddrive, but it's extremely slow.
  + Genuine brmbora™ hardware with Next-Businness-Day support

The compilation of all sources will take several minutes on a modern Core i* computer or 2 hours on Intel Atom netbook.

***

 OsmocomBB firmware

http://bb.osmocom.org/trac/wiki/GettingStarted

  + Install ARM toolchain. The phone is an arm, so we will crosscompile on our x86.
  + git clone git://git.osmocom.org/osmocom-bb.git
  + git checkout sylvain/burst_ind
    this branch has patched DSP so it allows us to sniff traffic off-the-air
  + make

***

 Installing other tools

  + Copy mysrc/.omgsm to ~
  + edit ~/.omgsm/config and ~/.omgsm/phones
    GSMPATH=path to this
    GSMDEFSESSION=where sniffed data are stored (usually several MB per hour)
    GSMMAXCELLS=when scanning for BTS, pick N strongest
    GSMKRAKENHOST,GSMKRAKENPORT=where your A5/1 cracker lives
      they tend to listen only on localhost, so try ssh -L 6666:localhost:6666
    GSMBRMBORACTL=where brmbora™ conTROLLer is
      leave blank if you don't have a brmbora™ genuine device and order on at shop.brmlab.cz
    GSMSESSION=current session, will be set automatically on first run
  + cd mysrc; make
  + Kraken will tell you the secret state at some round of A5/1 keystream generator. You need something to backclock (revert and extract original key) the cipher. Use find_kc from Kraken-Utilities patched with our version to support uplink.
    git clone git://git.srlabs.de/kraken.git
    cd kraken/Utilities
    cp mysrc/find_kc.cpp .
    make find_kc
    deposit the binary to GSMPATH/kraken/Utilities/

***

 Initializing hardware

Check scripts in bin/
  + gsm_init_hw.sh
  + Without a brmbora™ genuine device you need to press button on your phone.
  + You should see the firmware loading. The correct output should have the following features:
     Received PROMPT1 from phone, responding with CMD
     read_file(../../target/firmware/board/compal_e88/hello_world.compalram.bin): file_size=27192, hdr_len=4, dnload_len=27199
     Received PROMPT2 from phone, starting download
     handle_write(): finished
     Received DOWNLOAD ACK from phone, your code is running now!
     LOST nnnn!
    If it got stuck before the "LOST" message, try again. Contact your brmbora™ authorized reseller in case of problems.

***

 Initianing a new session, scanning BTS

  + gsm_bts_scan.sh

***

 Investigating the SESSION direstory

arfcn    - what channels we will sniff on
new/     - captured data
tmsi2bursts.txt - phones seen on air and their data

***

 Start sniffing

gsm_start_sniff.sh

Some .dat files should appear in SESSION/new/. They are usually 5-15 kB each.

FIXME We now have better sniffer using master-slave architecture useful if you have 4+ phones. See bin/gsm_spawn_master_slave.sh for more info.

***

 Viewing sniffed data with Wireshark

iptables -A INPUT -p UDP --dport 4729 -j DROP
# we will send dummy packets and kernel will reply with ICMP port unreachable

start Wireshark on localhost

gsm_convert -f SESSION/new/file-to-view.dat -d
will convert data to GSMTAP frames and send them to Wireshark

Some packets should appear in Wireshark: http://bb.osmocom.org/trac/wiki/WiresharkIntegration

***

 Cracking your own data from your very own phone of course!

Use napalmex.py for a statistical keystream guesser with up to 100% efficiency on less-secure networks and ability to crack about 50% of traffic even on secure networks!

***

 Viewing cracked data

start Wireshark on localhost

gsm_convert -f SESSION/new/file-to-view.dat -k KEY

Interesting .dat files are the bigger ones (10kB). Interesting frames are "GSM-SMS CP-DATA".
See gsm_evenlog.sh for tips how to extract phone numbers, SMS messages etc.
See this link for guessing which types of communication are in the file even berofe it is cracked:
http://jenda.hrach.eu/brm/sms_analysis.png
</code>