Project

General

Profile

SIMtrace » History » Version 39

zecke2, 02/19/2016 10:48 PM
Mention the manual

1 1 laforge
[[PageOutline]]
2 1 laforge
= Osmocom SIMtrace =
3 1 laforge
4 1 laforge
Osmocom SIMtrace is a software and hardware system for passively tracing SIM-ME communication between the SIM card and the mobile phone.
5 1 laforge
6 18 laforge
It looks a bit like this:
7 18 laforge
{{{
8 18 laforge
#!graphviz
9 18 laforge
digraph G{
10 18 laforge
  //rankdir = LR;
11 18 laforge
  Phone -> SIMtrace [label = "Flexi-PCB cable"];
12 18 laforge
  SIMtrace -> SIM;
13 18 laforge
  SIMtrace -> PC [label = "USB cable"];
14 1 laforge
15 18 laforge
  SIMtrace [ label = "SIMtrace hardware" ];
16 18 laforge
}
17 18 laforge
}}}
18 18 laforge
19 29 laforge
When connected to a phone, it looks like this:
20 29 laforge
21 29 laforge
22 30 tsaitgaist
[[Image(simtrace_and_phone.jpg, align=center,50%)]]
23 33 zecke2
[[Image(simtrace_functions.png, align=right,33%)]]
24 29 laforge
25 18 laforge
It works by utilizing the T=0 capable USART of the USB-attached AT91SAM7 microcontroller.
26 18 laforge
27 1 laforge
The USART passively receives the bytes as they are exchanged on the ISO 7816-3 / TS 11.11 interface between SIM and phone.
28 1 laforge
The received bytes are sent via USB to the PC, where a program called {{{simtrace}}} on the PC gathers data from the USB device,
29 1 laforge
parses the APDUs and forwards them via [wiki:GSMTAP] to the [wiki:wireshark] protocol analyzer.
30 1 laforge
31 1 laforge
== Features ==
32 38 tsaitgaist
33 1 laforge
 * Completely passive scanner
34 17 dw
 * RST and ATR detection
35 1 laforge
 * Auto-bauding with PPS / PTS support
36 1 laforge
 * Segmentation of APDUs
37 32 tsaitgaist
38 1 laforge
39 38 tsaitgaist
SIMtrace can be used to monitor the ME-SIM communication, but also emulate a phone or SIM, or be MitM.
40 38 tsaitgaist
While the hardware supports all these modes, only the monitoring aspect has been implemented in software.
41 38 tsaitgaist
42 1 laforge
== TODO ==
43 38 tsaitgaist
44 1 laforge
 * Check for parity errors
45 1 laforge
 * Verify TCK / PCK check-bytes
46 31 laforge
 * Implement MITM
47 1 laforge
48 1 laforge
== Hardware ==
49 17 dw
50 1 laforge
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.
51 1 laforge
52 31 laforge
Now we have a dedicated PCB design.  The schematics and Gerber files are released as open source hardware and can be produced by everyone.
53 31 laforge
54 31 laforge
However, those of you who are not interested in building it from scratch can buy a complete factory-produced, tested and flashed PCB assembly from http://shop.sysmocom.de/products/simtrace
55 31 laforge
56 27 zecke2
More details are available at [wiki:SIMtrace/Hardware]
57 4 laforge
58 1 laforge
== Firmware ==
59 1 laforge
60 28 zecke2
The firmware for the AT91SAM7S device was written by reusing a lot of the code for the [http://www.openpcd.org/ OpenPCD]
61 28 zecke2
RFID reader.  Details are available at [wiki:SIMtrace/Firmware].
62 24 tsaitgaist
63 39 zecke2
== Documentation ==
64 39 zecke2
65 39 zecke2
Please check the attachments for a usermanual. In there you will find some hints to install ready made packages for
66 39 zecke2
your favorite Linux Distribution.
67 1 laforge
68 5 laforge
== Host PC Software ==
69 5 laforge
70 6 tsaitgaist
The {{{simtrace}}} program is part of the git://git.osmocom.org/simtrace.git repository. It will bind to the USB device
71 5 laforge
and send GSMTAP frames using UDP/IPv4 to localhost:4729.
72 6 tsaitgaist
73 14 tsaitgaist
=== Preconditions ===
74 1 laforge
75 14 tsaitgaist
[wiki:libosmocore] and headers (simtrace_usb.h) from the firmware.
76 14 tsaitgaist
77 14 tsaitgaist
additional packages :
78 6 tsaitgaist
{{{
79 26 tsaitgaist
sudo apt-get install libusb-1.0-0-dev
80 7 tsaitgaist
}}}
81 1 laforge
82 6 tsaitgaist
=== Compiling it ===
83 6 tsaitgaist
84 1 laforge
{{{
85 14 tsaitgaist
git clone git://git.osmocom.org/simtrace.git
86 21 tsaitgaist
cd simtrace/host/
87 6 tsaitgaist
make
88 6 tsaitgaist
}}}
89 6 tsaitgaist
90 35 tsaitgaist
=== Accessing it ===
91 35 tsaitgaist
92 35 tsaitgaist
Add udev rules so to be able to use simtrace and access the device as non-root user (only need to be in the osmocom group)
93 35 tsaitgaist
94 35 tsaitgaist
{{{
95 35 tsaitgaist
sudo groupadd osmocom
96 35 tsaitgaist
sudo adduser $USERNAME osmocom
97 35 tsaitgaist
sudo tee /etc/udev/rules.d/10-osmocom.rules << EOF
98 35 tsaitgaist
# to use, install this file in /etc/udev/rules.d as 10-osmocom.rules
99 35 tsaitgaist
# rule to grant read/write access on SIMtrace to group named osmocom.
100 35 tsaitgaist
ACTION=="add", BUS=="usb", SYSFS{idVendor}=="16c0", SYSFS{idProduct}=="0762", GROUP:="osmocom", MODE:="0660"
101 35 tsaitgaist
EOF
102 35 tsaitgaist
sudo service udev reload
103 35 tsaitgaist
}}}
104 35 tsaitgaist
105 35 tsaitgaist
you must log out and back in so to take effect.
106 35 tsaitgaist
107 6 tsaitgaist
=== Using it ===
108 6 tsaitgaist
109 6 tsaitgaist
Simply start '''simtrace'''.
110 13 tsaitgaist
It will send the GSMTAP frames to UDP/IPv4 localhost:4729.
111 1 laforge
112 1 laforge
It will also print hexdumps of the frames to the console, looking like this:
113 6 tsaitgaist
{{{
114 1 laforge
sudo ./simtrace
115 1 laforge
APDU: (9):  a0 a4 00 00 02 6f 07 9f 0f
116 1 laforge
APDU: (22):  a0 c0 00 00 0f 00 00 00 09 6f 07 04 00 15 00 15 01 02 00 00 91 78
117 1 laforge
APDU: (9):  a0 a4 00 00 02 6f 38 9f 0f
118 1 laforge
APDU: (22):  a0 c0 00 00 0f 00 00 00 09 6f 38 04 00 15 00 55 01 02 00 00 91 78
119 1 laforge
APDU: (16):  a0 b0 00 00 09 ff 3f ff ff 00 00 3f 03 00 91 78
120 1 laforge
APDU: (9):  a0 a4 00 00 02 6f ad 9f 0f
121 1 laforge
APDU: (8):  a0 b0 00 00 01 00 91 78
122 1 laforge
APDU: (9):  a0 a4 00 00 02 6f 07 9f 0f
123 1 laforge
APDU: (16):  a0 b0 00 00 09 08 49 06 20 11 49 00 11 06 91 78
124 1 laforge
APDU: (9):  a0 a4 00 00 02 6f 7e 9f 0f
125 1 laforge
APDU: (18):  a0 b0 00 00 0b ff ff ff ff 64 f0 00 ff fe 00 03 91 78
126 1 laforge
APDU: (9):  a0 a4 00 00 02 6f 78 9f 0f
127 1 laforge
APDU: (9):  a0 b0 00 00 02 00 01 91 78
128 1 laforge
APDU: (9):  a0 a4 00 00 02 6f 74 9f 0f
129 2 laforge
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
130 2 laforge
APDU: (9):  a0 a4 00 00 02 6f 20 9f 0f
131 2 laforge
APDU: (16):  a0 b0 00 00 09 ff ff ff ff ff ff ff ff 07 91 78
132 2 laforge
APDU: (9):  a0 a4 00 00 02 6f 30 9f 0f
133 1 laforge
APDU: (22):  a0 c0 00 00 0f 00 00 00 f0 6f 30 04 00 11 00 55 01 02 00 00 91 78
134 1 laforge
}}}
135 1 laforge
136 1 laforge
== Wireshark integration ==
137 1 laforge
138 34 tsaitgaist
There is an experimental patch, also part of the simtrace.git package.  It is also included in the [wiki:wireshark] developer version (since wireshark 1.7.1).
139 34 tsaitgaist
140 34 tsaitgaist
To see the APDUs in wireshark:
141 37 tsaitgaist
 * on localhost SIMtrace automatically opens a UDP sink locally, no need to do any anything
142 37 tsaitgaist
 * to get the data on another machine
143 37 tsaitgaist
  * start an UDP sink for GSMTAP on the other machine (do not use netcat as it "connects" back)
144 34 tsaitgaist
{{{
145 37 tsaitgaist
socat -u udp-recv:4729 /dev/null
146 34 tsaitgaist
}}}
147 37 tsaitgaist
  * tell SIMtrace on which machine to forward
148 34 tsaitgaist
{{{
149 37 tsaitgaist
./simtrace -i 192.168.0.1
150 34 tsaitgaist
}}}
151 1 laforge
152 1 laforge
[[Image(wireshark-sim.png)]]
153 1 laforge
154 1 laforge
Protocol parsing is far from being complete, patches are always welcome!
155 31 laforge
156 31 laforge
== Contact / Mailing List ==
157 31 laforge
158 31 laforge
For any development or usage related questions, there is a mailinglist [mailto:simtrace@lists.osmocom.org], you can subscribe/unsubscribe to it at http://lists.osmocom.org/mailman/listinfo/simtrace and read the archives at http://lists.osmocom.org/pipermail/simtrace/
159 31 laforge
160 31 laforge
Please kindly observe our [http://openbsc.osmocom.org/trac/wiki/MailingListRules Mailing List Rules]
Add picture from clipboard (Maximum size: 48.8 MB)