SIM card related Projects » SIMtrace 2

h1. Osmocom SIMtrace 2

{{>toc}}

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

While it was designed for SIM-ME communication, it supports all ISO 7816 smart-cards using the T=0 protocol (the most common case).

It is a followup of the "SIMtrace project":/projects/simtrace/wiki, providing more functionalities (e.g. remote SIM operation) and supporting multiple boards (e.g. SIMtrace with SAM3S, "sysmoQMOD":https://www.sysmocom.de/products/lab/sysmoqmod/index.html).

h2. Hardware

The SIMtrace 2 firmware supports several boards.

The firmware is written for an "ATSAM3S4B":https://www.microchip.com/wwwproducts/en/ATSAM3S4B micro-controller.

Note: The SAM3S is meanwhile labelled as _not recommended for new designs_ by Atmel. However, there are plenty of hardware and software compatible upgrade options, including SAM4S. The upgrade is possible in the future.

h3. SIMtrace board for SIMtrace 2 project

!{width:20%}simtrace-board-mini.jpg!

The main purpose of this board is to sniff the communication between a phone and a SIM card (or any card reader and smart-card).

This is the same circuit board as the previous "SIMtrace v1":/projects/simtrace/wiki/SIMtrace_Hardware, with the exception that the "ATSAM3S4B":https://www.microchip.com/wwwproducts/en/ATSAM3S4B micro-controller replaces the old "AT91SAM7S64":https://www.microchip.com/wwwproducts/en/AT91SAM7S64. Since the SAM3S is pin compatible with the SAM7S, any SIMtrace v1 board can be converted into a SIMtrace v2 board simply by replacing the micro-controller.

Note: This hardware is "open source hardware (OSHW)":https://gitea.osmocom.org/sim-card/simtrace2/src/branch/master/hardware

h4. SIMtrace2 hardware availability

Fully assembled SIMtrace2 boards and related accessories like FPC cables can be obtained from the "sysmocom webshop":https://shop.sysmocom.de/SIMtrace2-Hardware-Kit/simtrace2-kit

h3. ngff-cardem

!{width:25%}ngff-cardem.jpg!

This is a carrier board for cellular modems in ngff / M.2 form-factor with on-board simtrace2.  It is wired in a way that it can operate both as passive tracer/sniffer, or in @cardem@ mode.

See [[ngff-cardem:]] for all information on the ngff-cardem board, including design files.

Note: This hardware is "open source hardeware (OSHW)":https://gitea.osmocom.org/electronics/osmo-small-hardware/src/branch/master/ngff-cardem

h4. ngff-cardem availability

Fully assembled ngff-cardem boards can be obtained from the "sysmocom webshop":https://shop.sysmocom.de/M.2-modem-carrier-with-remote-SIM-tracing/ngff-cardem-kit-external

h3. sysmoQMOD

!{width:25%}sysmoqmod.png!

The SAM3S micro-controller with SIMtrace 2 firmware is also used on the "sysmoQMOD":https://www.sysmocom.de/products/lab/sysmoqmod/index.html board to provide remote SIM operation capabilities.

Note: This hardware is not open source.

h4. sysmoQMOD hardware availability

Fully assembled sysmoQMOD boards and related products can be obtained from "sysmocom":https://www.sysmocom.de/products/lab/sysmoqmod/index.html 

An Evaluation kit is available from the "sysmocom webshop":https://shop.sysmocom.de/sysmoQMOD-evaluation-kit/sysmoQMOD-evk - please contact sales@sysmocom.de for inquiries on quantity pricing.

h2. Firmware

The SIMtrace 2 firmware source code is available in "git":https://gitea.osmocom.org/sim-card/simtrace2/src/branch/master/firmware

Pre-built firmware binaries are available "here":https://ftp.osmocom.org/binaries/simtrace2/firmware/.

The firmware are currently under active development and we recommend to [[Flashing|flash]] the new firmware images to profit from the latest bug fixes and added functionalities.

The SIMtrace 2 firmware is a complete rewrite and *can only be flashed on hardware with SAM3S* ARM Cortex-M3-based micro-controllers.

*The SIMtrace 2 firmware is not compatible with the older "SIMtrace v1":/projects/simtrace/wiki/SIMtrace_Hardware using SAM7S ARM7TDMI-based micro-controllers.*

To get the version of the firmware flashed on the device, you can use the @simtrace2-list@ tool

h3. trace

The trace application firmware allow to sniff the communication between a phone and a SIM card (or any card reader and smart-card).

It is intended for the [[Wiki#SIMtrace v2|SIMtrace v2 hardware]] and its function is analog to the "SIMtrace v1":/projects/simtrace/wiki/SIMtrace_Firmware.

The sniffing is completely passive. It uses the RST, ATR, PPS (baud rate tested with F/D up to 512/32), and WT (waiting timeout) to properly parse the ISO 7816-3 TPDUs.

Currently only the T=0 protocol is supported since this is the most common protocol used (we haven't seen T=1 in use).

!{width:25%}simtrace_and_phone.jpg!

The application firmware to be flashed using [[Flashing#DFU|DFU]] is "simtrace-trace-dfu.bin":https://ftp.osmocom.org/binaries/simtrace2/firmware/latest/simtrace-trace-dfu-latest.bin.

h3. card emulation

The card emulation application firmware allows to emulate a card (e.g SIM). This is useful if you don't want to change the card in the device (e.g. phone), or have the card in a remote location.

This firmware comes preflashed on the sysmoQMOD board.

It also exists for the SIMtrace v2 board, but is currently in beta. If you still would like to try it, read this [[Cardem|article]].

h3. Development

To compile the firmware using the source code, or participate in the development, please refer to the instructions provided in the "README":https://gitea.osmocom.org/sim-card/simtrace2/src/branch/master/firmware/README.txt

h2. Flashing

The [[Wiki#Firmware|firmware images]] can be flashed as described [[Flashing|here]].

h2. Host PC Software

The source code of the SIMtrace 2 host PC software are available in the "simtrace2 git":https://gitea.osmocom.org/sim-card/simtrace2/src/branch/master/host

Binary packages are made available for a variety of Linux distributions, see [[cellular-infrastructure:Binary_Packages]] for more details.   In case of doubt, use the nightly builds.

h3. Installing binary packages

We assume that you've added the binary package feed, for example as described at [[cellular-infrastructure:Nightly_Builds]].

All you need to do is to do

<pre>

$ sudo apt-get install simtrace2-utils

</pre>

h3. Building from source

this assumes you are a software developer familiar with building software from source using GNU autotools.  If you're not, please use the binary packages (see above).

h4. Preconditions

[[libosmocore:]], libpcsclite and libusb.

to install those packages:

<pre>

sudo apt-get install libusb-1.0-0-dev libosmocore-dev libpcsclite-dev

</code></pre>

h4. Compiling it

<pre>

git clone https://gitea.osmocom.org/sim-card/simtrace2.git

cd simtrace2/host/

autoreconf -fi

./configure

make

</pre>

h3. Accessing it

Add udev rules so to be able to use SIMtrace 2 devices and access the device as non-root user:

<pre>

# add current user to plugdev group (user needs to re-login for this change to take effect)

sudo adduser $USERNAME plugdev

# grant access permission to SIMtrace 2 for plugdev group

sudo wget -O /etc/udev/rules.d/99-simtrace2.rules https://gitea.osmocom.org/sim-card/simtrace2/raw/branch/master/host/contrib/99-simtrace2.rules

# reload udev rules

sudo udevadm control --reload-rules

sudo udevadm trigger

</pre>

h3. Applications

h4. simtrace2-list

@simtrace2-list@ allows to list all SIMtrace 2 compatible devices:

<pre>

./simtrace2-list

USB matches: 1

	1d50:60e3 Addr=4, Path=2-2.3, Cfg=1, Intf=0, Alt=0: 255/1/0 (SIMtrace Sniffer)

</pre>

This is useful when you have multiple devices (such as with the [[Wiki#sysmoQMOD]]) and have to specify which device to use by other applications.

h4. simtrace2-sniff

This will use the [[Wiki#trace|trace]] firmware and retrieve the sniffed phone-SIM communication.

The activity will be shown on the console output:

<pre>

./simtrace2-sniff 

simtrace2-sniff - Phone-SIM card communication sniffer 

(C) 2010-2017 by Harald Welte <laforge@gnumonks.org>

(C) 2018 by Kevin Redon <kredon@sysmocom.de>

Using USB device 1d50:60e3 Addr=4, Path=2-2.3, Cfg=1, Intf=0, Alt=0: 255/1/0 (SIMtrace Sniffer)

Entering main loop

Card state change: reset hold

Card state change: reset release

ATR: 3b 9f 96 80 1f c7 80 31 a0 73 be 21 13 67 43 20 07 18 00 00 01 a5 

PPS: ff 10 96 79 

PPS: ff 10 96 79 

Fi/Di switched to 512/32

TPDU: a0 a4 00 00 02 3f 00 9f 22 

TPDU: a0 a4 00 00 02 7f 20 9f 22 

TPDU: a0 a4 00 00 02 6f 46 9f 0f 

TPDU: a0 b0 00 00 11 81 43 43 43 20 45 76 65 6e 74 ff ff ff ff ff ff ff 90 00 

Card state change: reset hold

</pre>

The TPDU will also be sent via [[baseband:GSMTAP]] frames to UDP/IPv4 localhost:4729.  This means you can have other programs that process and further decode the data.  This also means you can create pcap files of the SIM TPDUs by e.g. tcpdump using a command line like @tcpdump -npi lo -w /tmp/my_pcap_file.pcap udp port 4729@.

The real-time TPDU stream (via GSMTAP) or the recorded pcap file containing GSMTAP can be analyzed in other programs such as 

* wireshark (general-purpose network protocol analyzer, https://wireshark.org/)

** very basic decoder only at the the CLA/INS level, knows some FIDs without understanding filesystem hierarchy

** primarily focussed on classic GSM SIM cards

** doesn't receive much love

** nice GUI

* @pySim-trace.py@ (part of [[pySim:]] suite of SIM card related tools)

** *very* complete/comprehensive decode all the way up into the contents of the files read/written

** primarily focussed on modern UICC/USIM/ISIM cards

** no GUI at all

wireshark using the GSM SIM dissector.

!{width:50%}wireshark-sim.png!

{{include(cellular-infrastructure:MacroBinaryPackages)}}

{{include(cellular-infrastructure:MacroCommercialSupport)}}