SIM card related Projects » SIMtrace

[[PageOutline]]

= Osmocom SIMtrace =

Osmocom SIMtrace is a software and hardware system for passively tracing SIM-ME communication between the SIM card and the mobile phone.

It looks a bit like this:

{{{

#!graphviz

digraph G{

  //rankdir = LR;

  Phone -> SIMtrace [label = "Flexi-PCB cable"];

  SIMtrace -> SIM;

  SIMtrace -> PC [label = "USB cable"];

  SIMtrace [ label = "SIMtrace hardware" ];

}

}}}

It works by utilizing the T=0 capable USART of the USB-attached AT91SAM7 microcontroller.

The USART passively receives the bytes as they are exchanged on the ISO 7816-3 / TS 11.11 interface between SIM and phone.

The received bytes are sent via USB to the PC, where a program called {{{simtrace}}} on the PC gathers data from the USB device,

parses the APDUs and forwards them via [wiki:GSMTAP] to the [wiki:wireshark] protocol analyzer.

== Features ==

 * Completely passive scanner

 * RST and ATR detection

 * Auto-bauding with PPS / PTS support

 * Segmentation of APDUs

== TODO ==

 * Check for parity errors

 * Verify TCK / PCK check-bytes

== Hardware ==

The first implementations used an Olimex SAM7-P64 development board with some of the I/O lines hooked up to the mechanical SIM card adapters from [wiki:RebelSIM_Scanner]. If the RebelSIM scanner is used, connect the USB even if just the lines are used. It needs to be powered, else the real reader will often fail to initialize the card.

Next we started prototyping a custom board.  More details are available at [wiki:SIMtrace/Hardware]

Update (2011-07-29): We just have received the first 100 units from the SMT factory. They will be available at [http://events.ccc.de/camp/2011 CCC Camp 2011].

This is how the v0.9 hardware looks like:

[[Image(SIMtrace/Hardware:simtrace_v09_top_mid.jpg, 33%)]]

=== Interconnections ===

The hardware schematics are very, very simple:

 * Connect SIM-RST with PA7

 * Connect SIM-I/O with PA6(TXD0) and PA1(TIOB0)

 * Connect SIM-CLK with PA2(SCK0) and PA4(TCLK0)

 * Connect SIM-GND with GND

=== Mode of operation ===

The USART of the AT91SAM7S is capable of T=0. The documentation only mentions it in clock-master mode, like you

would run it in a smart card reader to actively talk to a smart card. However, by using the USART input clock multiplexer,

you can use an externally-generated CLK like the one from the SIM card socket of the phone.

Unfortunately, the Rx Timeout feature of the USART is not working in T=0 mode, so I had to re-implement Rx timeout (waiting time)

handling by means of the TC (timer/counter) block 0.  Due to technical limitations, we will wait up to one byte (12 etu) more

than we should.

== Firmware ==

The Firmware for the AT91SAM7S device was written by reusing a lot of the code for the [http://www.openpcd.org/ OpenPCD]

RFID reader.  

There is a {{{simtrace}}} Makefile target in the git://git.gnumonks.org/openpcd.git repository containing the latest firmware code.

Eventually, the OS part of OpenPCD/OpenPICC/SIMtrace will be separated.  At that point, the firmware source can become

part of simtrace.git

=== Building the firmware ===

Precondition: You need to set your PATH in a way that contains an arm-elf [wiki:toolchain], i.e. the same way that you build [wiki:GettingStarted OsmocomBB].

{{{

git clone git://git.gnumonks.org/openpcd.git

cd openpcd/firmware

make -f Makefile.dfu BOARD=SIMTRACE

make BOARD=SIMTRACE DEBUG=1 TARGET=main_simtrace

cat dfu.bin main_simtrace.bin > main_simtrace.samba

cd ../..

}}}

=== Firmware parts ===

The firmware build process creates two images:

 * dfu.bin -- the sam7dfu 2nd level bootloader. It implements the USB DFU (Device Firmware Upgrade) profile.

 * main_simtrace.bin -- the actual simtrace program. To be loaded via DFU, using [http://dfu-util.gnumonks.org/ dfu-util].

 * main_simtrace.samba -- [http://www.openpcd.org/Sam7dfu sam7dfu] + simtrace image. to be loaded via SAM-BA, using sam7utils (see below).

=== Flashing the firmware ===

after the firmware has been flashed, '''lsusb''' should show:

{{{

Bus 004 Device 005: ID 16c0:0762 VOTI

}}}

==== SAM-BA ====

The first time you flash the device, you will have to use the SAM-BA method using the '''main_simtrace.samba''' image.

To put the board into SAM-BA mode, use the following steps:

 * unplug the board

 * short TEST to VCC (3.3V) pin using a jumper. leave PA0,PA1,PA2 unconnected.

 * power up the board

 * wait 20s

 * unplug board

 * remove jumper

Now when the board is attached to USB, '''lsusb''' should show :

{{{

Bus 002 Device 015: ID 03eb:6124 Atmel Corp. at91sam SAMBA bootloader

}}}

note for v1.0p boards: sometimes the SAM-BA mode it not working.

This is the case if the 2 LEDs are on when powering up the board while VCC and TEST are shorted.

The reason in unknown yet, but there are several methods to correct this:

 * press the RESET button while powering up

 * touch PA0 (pin 48, on the right upper corner) with a piece of metal

 * short PA0 and PA1 (pin 48 and 47, next to ech other on the right upper corner)

As soon as the LEDs go off, the SAM-BA mode is working.

For more information about SAM-BA, please refer to the Atmel documentation on the AT91SAM7S component.

==== sam7utils ====

sam7utils will be used to flash the '''main_simtrace.samba''' image over SAM-BA.

{{{

sudo aptitude install libreadline-dev

wget http://www.openpcd.org/dl/sam7utils-0.2.1-bm.tar.bz2

tar xf sam7utils-*.tar.bz2

cd sam7utils

./configure --prefix=/usr/local

make

}}}

to flash the samba image using serial :

{{{

sudo ./sam7 -l /dev/ttyUSB0 --exec set_clock --exec unlock_regions --exec "flash ../openpcd/firmware/main_simtrace.samba"

}}}

to flash the samba image using libusb :

{{{

sudo ./sam7 --exec set_clock --exec unlock_regions --exec "flash ../openpcd/firmware/main_simtrace.samba"

}}}

===== sam7utils for x86 =====

On x86, sam7utils will be compiled to communicate with the board using POSIX.

The board should be attached to a node. On ubuntu 10.10, the usb device 03eb:6124 is mapped on /dev/ttyACM0 using the cdc_cam module. If not mapped, use usbserial :

{{{

sudo rmmod usbserial

sudo modprobe usbserial vendor=0x03EB product=0x6124

}}}

Now replug board. It should map to /dev/ttyUSBx (use dmesg to know which).

===== sam7utils for amd64 =====

On amd64, sam7utils will be compiled to communicate with the board using libusb.

On ubuntu 10.10 & 11.04, the usb device 03eb:6124 is mapped on /dev/ttyACMx using the cdc_cam module.

Remove it while the board is plugged, so sam7utils is able to communicate with it (using libusb for 10.10 and serial for 11.04).

{{{

sudo rmmod cdc_acm

}}}

==== DFU ====

The SAM-BA mode is useful to recover from broken firmwares, but the DFU bootloader included into it is easier to use for updates.

You can upload the firmware over USB using dfu-util.

To get dfu-util:

{{{

sudo apt-get install dfu-util

}}}

To flash the firmware:

{{{

dfu-util -d 16c0:0762 -a0 -D ./main_simtrace.bin -R

}}}

dfu-util should reset the board and use the DFU bootloader. Try the command a second time if it did not work at first.

If this still does not work, power up the board while pressing the '''BOOTLOADER''' button.

== Host PC Software ==

The {{{simtrace}}} program is part of the git://git.osmocom.org/simtrace.git repository. It will bind to the USB device

and send GSMTAP frames using UDP/IPv4 to localhost:4729.

=== Preconditions ===

[wiki:libosmocore] and headers (simtrace_usb.h) from the firmware.

additional packages :

{{{

sudo apt-get install libusb-dev

}}}

=== Compiling it ===

Precondition:  [wiki:libosmocore] and headers (simtrace_usb.h) from the firmware.

{{{

git clone git://git.osmocom.org/simtrace.git

cd simtrace/host/

make

}}}

=== Using it ===

Simply start '''simtrace'''.

It will send the GSMTAP frames to UDP/IPv4 localhost:4729.

It will also print hexdumps of the frames to the console, looking like this:

{{{

sudo ./simtrace

APDU: (9):  a0 a4 00 00 02 6f 07 9f 0f

APDU: (22):  a0 c0 00 00 0f 00 00 00 09 6f 07 04 00 15 00 15 01 02 00 00 91 78

APDU: (9):  a0 a4 00 00 02 6f 38 9f 0f

APDU: (22):  a0 c0 00 00 0f 00 00 00 09 6f 38 04 00 15 00 55 01 02 00 00 91 78

APDU: (16):  a0 b0 00 00 09 ff 3f ff ff 00 00 3f 03 00 91 78

APDU: (9):  a0 a4 00 00 02 6f ad 9f 0f

APDU: (8):  a0 b0 00 00 01 00 91 78

APDU: (9):  a0 a4 00 00 02 6f 07 9f 0f

APDU: (16):  a0 b0 00 00 09 08 49 06 20 11 49 00 11 06 91 78

APDU: (9):  a0 a4 00 00 02 6f 7e 9f 0f

APDU: (18):  a0 b0 00 00 0b ff ff ff ff 64 f0 00 ff fe 00 03 91 78

APDU: (9):  a0 a4 00 00 02 6f 78 9f 0f

APDU: (9):  a0 b0 00 00 02 00 01 91 78

APDU: (9):  a0 a4 00 00 02 6f 74 9f 0f

APDU: (23):  a0 b0 00 00 10 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 91 78

APDU: (9):  a0 a4 00 00 02 6f 20 9f 0f

APDU: (16):  a0 b0 00 00 09 ff ff ff ff ff ff ff ff 07 91 78

APDU: (9):  a0 a4 00 00 02 6f 30 9f 0f

APDU: (22):  a0 c0 00 00 0f 00 00 00 f0 6f 30 04 00 11 00 55 01 02 00 00 91 78

}}}

== Wireshark integration ==

There is an experimental patch, also part of the simtrace.git package.  You will have to apply this against the latest

[wiki:wireshark] developer version.

[[Image(wireshark-sim.png)]]

Protocol parsing is far from being complete, patches are always welcome!