include a copy instead of the symlink

http://software.opensuse.org/download.html?project=home:zecke23&package=simtrace
comes to rescue to show the binaries and the commands

docs/chapters/building.xml

@@ -1,8 +1,47 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <chapter id="chapter_building">
     <title>Getting and Building the Software</title>
-    <section id="building_dependencies">
+    <section id="building_intros">
-        <title>Installing Dependencies</title>
+        <title>Building software</title>
-        <para></para>
+        <para>There are three parts that can be built. It is the firmware
+        for the SIMtrace hardware, the SIMtrace software and the modified
+        version of wireshark. All of these have different source trees and
+        dependencies.</para>
+    </section>
+
+    <section id="building_simtrace">
+        <title>Building SIMtrace</title>
+
+        <section id="libosmocore">
+            <title>Building the Osmocom libosmocore library</title>
+            <screen>
+$ <command>git</command> clone git://git.osmocom.org/libosmocore
+$ <command>cd</command> libosmocore
+$ <command>autoreconf</command> --install --force
+$ <command>./configure</command>
+$ <command>sudo</command> <command>make</command> install
+</screen>
+        </section>
+
+        <section id="libusb">
+            <title>Installing libusb</title>
+            <para>You will need to install the libusb header files
+            to be able to compile <command>simtrace</command></para>.
+        </section>
+
+        <section id="simtrace">
+            <title>Building <command>simtrace</command></title>
+            <screen>
+$ wget https://api.opensuse.org/public/source/home:zecke23/simtrace/simtrace_0.0.1.tar.gz
+$ tar xzf simtrace_0.0.1.tar.gz
+$ cd simtrace-0.0.1 
+$ PKG_CONFIG_PATH=/usr/local/lib/pkgconfig make
+cc  `pkg-config --cflags libosmocore` -o main.o -c main.c
+cc  `pkg-config --cflags libosmocore` -o usb_helper.o -c usb_helper.c
+cc  `pkg-config --cflags libosmocore` -o usb.o -c usb.c
+cc  `pkg-config --cflags libosmocore` -o apdu_split.o -c apdu_split.c
+cc -o simtrace main.o usb_helper.o usb.o apdu_split.o -lusb `pkg-config --libs libosmocore` -losmocore
+            </screen>
+        </section>
     </section>
 </chapter>

docs/chapters/installation.xml

@@ -0,0 +1,118 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="chapter_installation">
+    <title>Installation</title>
+    <para><application>SIMtrace</application> will need a patched version of
+    <application>wireshark</application> and the <command>simtrace</command>
+    host utility to fully operate. The installation might be possible from
+    binary packages or will require building from source. The following
+    sections provide some hints how to achieve this on the various Linux
+    distributions. All these operations must be executed as root.</para>
+
+    <section id="install_ubuntu_natty">
+        <title>Installation Ubuntu Natty</title>
+        <para>Ubuntu Natty users can use the holger+lp/osmocom PPA to install
+<application>SIMtrace</application> and upgrade wireshark. The PPA needs to
+        be added to the system, the package database needs to be refreshed
+        and the applications can be installed afterwards.</para>
+
+        <screen>
+$ <command>sudo</command> <command>add-apt-repository</command> ppa:holger+lp/osmocom
+[sudo] password for username:
+Executing: gpg --ignore-time-conflict --no-options --no-default-keyring --secret-keyring /etc/apt/secring.gpg --trustdb-name /etc/apt/trustdb.gpg --keyring /etc/apt/trusted.gpg --primary-keyring /etc/apt/trusted.gpg --keyserver hkp://keyserver.ubuntu.com:80/ --recv 84C86214C00BAF820F43585CCABF944FA2AD19FA
+gpg: requesting key A2AD19FA from hkp server keyserver.ubuntu.com
+gpg: Total number processed: 1
+gpg:              unchanged: 1
+        </screen>
+
+        <para>The next step is to update the package database and install or upgrade
+        the <application>wireshark</application> application.</para>
+
+        <screen>
+$ <command>sudo</command> <command>apt-get</command> update
+...
+$ <command>sudo</command> <command>apt-get</command> install wireshark simtrace
+...
+        </screen>
+    </section>
+
+    <section id="install_opensuse">
+        <title>Installation OpenSUSE</title>
+        <para>The installation on OpenSUSE uses zypper. The repository must be added
+        via the <command>zypper</command> application and then the binary packages
+        can be installed.</para>
+
+        <section>
+            <title>openSUSE 11.3</title>
+            <screen>
+$ <command>zypper</command> addrepo http://download.opensuse.org/repositories/home:/zecke23/openSUSE_11.3/home:zecke23.repo
+$ <command>zypper</command> refresh
+$ <command>zypper</command> install wireshark simtrace
+            </screen>
+        </section>
+
+        <section>
+            <title>openSUSE 11.4</title>
+            <screen>
+$ <command>zypper</command> addrepo http://download.opensuse.org/repositories/home:/zecke23/openSUSE_11.4/home:zecke23.repo
+$ <command>zypper</command> refresh
+$ <command>zypper</command> install wireshark simtrace
+            </screen>
+        </section>
+    </section>
+
+    <section id="install_fedora">
+        <title>Installation Fedora</title>
+        <section>
+            <title>Fedora 14</title>
+            <screen>
+$ cd /etc/yum/repos.d/
+$ wget http://download.opensuse.org/repositories/home:zecke23/Fedora_14/home:zecke23.repo
+$ yum install wireshark simtrace
+            </screen>
+        </section>
+
+        <section>
+            <title>Fedora 15</title>
+            <screen>
+$ cd /etc/yum/repos.d/
+$ wget http://download.opensuse.org/repositories/home:zecke23/Fedora_15/home:zecke23.repo
+$ yum install wireshark simtrace
+            </screen>
+        </section>
+    </section>
+
+    <section id="install_centos">
+        <title>Installation CentOS</title>
+        <section>
+            <title>CentOS 5</title>
+            <screen>
+$ cd /etc/yum/repos.d/
+$ wget http://download.opensuse.org/repositories/home:zecke23/CentOS_CentOS-5/home:zecke23.repo
+$ yum install wireshark simtrace
+            </screen>
+        </section>
+
+        <section>
+            <title>Fedora 15</title>
+            <screen>
+$ cd /etc/yum/repos.d/
+$ wget http://download.opensuse.org/repositories/home:zecke23/CentOS_CentOS-6/home:zecke23.repo
+$ yum install wireshark simtrace
+            </screen>
+        </section>
+    </section>
+
+    <section id="install_mandriva">
+        <title>Mandriva 2010.1</title>
+        <screen>
+$ urpmi.addmedia home:zecke23 http://download.opensuse.org/repositories/home:zecke23/Mandriva_2010.1/
+$ urpmi.update -a
+$ urpmi wireshark simtrace
+        </screen>
+    </section>
+
+    <section id="installation_from_source">
+        <title>Installation from Source</title>
+        <para>Please see the <xref linkend="chapter_building"/></para>
+    </section>
+</chapter>

docs/chapters/introduction.xml

@@ -2,7 +2,43 @@
 <chapter id="chapter_introduction">
     <title>Introduction</title>
     <section id="intro_overview">
+        <title>History</title>
+        <para>SIMtrace was created out of necessity. Harald Welte wanted
+        to see the communication between a GSM Mobile Station (or
+        what we call a cellphone) and the SIM. He was not able to
+        find an existing solution, or the existing ones had mayor
+        drawbacks that made using them very time consuming and slow.
+        The Atmel AT91SAM7 came to the rescue. This microcontroller
+        has hardware support for the  ISO7816 T0/T1 Smart Card
+        specification. Using this hardware with the clock coming from
+        the normal connection we are able to read bytes coming from
+        and going to the SIM.
+        The next step in the project was taken by Kevin Redon
+        that started to modify an existing AT91SAM7 design, started
+        to use the Free Software KiCAD CAD Software. In 2011 the project
+        went from having Schematics to having routed circuits, prototypes
+        and the final product. The first production run was in August.</para>
+    </section>
+    <section id="intro_picture">
         <title>Overview</title>
-        <para></para>
+        <para>The setup of SIMtrace consists out of a Hardware and a
+        Software part. The SIM card needs to be put into the SIMtrace
+        Hardware, the flex cable needs to be connected to the SIMtrace
+        Hardware and the SIM end needs to be placed in the SIM socket
+        of the phone. The SIMtrace hardware can be seen as a USB device
+        from the host, the SIMtrace software will try to find this device
+        and claim it. The SIMtrace software will receive packets from the
+        SIMtrace hardware and can forward them using the GSMTAP protocol
+        to the IANA assigned GSMTAP port (4729). A modified version of Wireshark
+        can be used to analyze the data.</para>
+
+         <figure><title>Schematic Overview</title>
+         <mediaobject>
+           <imageobject>
+             <imagedata fileref="images/setup_overview.png" width="6cm"/>
+           </imageobject>
+           <textobject><phrase>SIMtrace being connected</phrase></textobject>
+         </mediaobject>
+         </figure>
     </section>
 </chapter>

docs/chapters/using.xml

@@ -2,19 +2,50 @@
 <chapter id="chapter_using">
     <title>Sniffing your SIM</title>
 
+    <section id="hw_setup">
+        <title>Connecting your device</title>
+        <para>You will need to put your SIM into the SIMtrace hardware, connect
+        one of the four flex cables to the SIMtrace hardware, put the other side
+        into the SIM socket of your phone. Use USB to connect the SIMtrace hardware
+        to the PC. On your PC you should be able to see the USB device now.</para>
+
+        <figure><title>Connecting the SIMtrace Hardware</title>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="images/simtrace_hw_setup.png" width="15cm"/>
+          </imageobject>
+          <textobject><phrase>SIMtrace being connected</phrase></textobject>
+        </mediaobject>
+        </figure>
+    </section>
+
     <section id="launching_simtrace">
         <title>Launching SIMtrace</title>
-        <para></para>
         <screen>
-$ <command>simtrace</command>
+$ <command>./simtrace</command>
+simtrace - GSM SIM and smartcard tracing
+(C) 2010 by Harald Welte &lt;laforge@gnumonks.org&gt;
         </screen>
+        <para>Launching the <command>simtrace</command> will try to find
+        the SIMtrace hardware and then try to claim the USB device. The
+        application will send the received data encapsulated in the GSMTAP
+        format on localhost and the IANA assigned GSMTAP port.</para>
     </section>
 
     <section id="launching_wireshark">
         <title>Launching Wireshark</title>
-        <para></para>
+        <para>The <command>wireshark</command> application will start a GUI
-        <screen>
+        and given the right permissions you should be able listen to the
-$ <command>wireshark</command>
+        localhost interface and filter for the GSMTAP port on 4729. You should
-        </screen>
+        be able to see the decoded messages like in the figure below.</para>
+
+         <figure><title>GSMTAP in Wireshark</title>
+         <mediaobject>
+           <imageobject>
+             <imagedata fileref="images/wireshark-sim.png" width="16cm"/>
+           </imageobject>
+           <textobject><phrase>SIMtrace sending data</phrase></textobject>
+         </mediaobject>
+         </figure>
     </section>
 </chapter>

docs/usermanual.xml

@@ -6,6 +6,7 @@
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
 <!ENTITY chapter-introduction SYSTEM "chapters/introduction.xml">
+<!ENTITY chapter-installation SYSTEM "chapters/installation.xml">
 <!ENTITY chapter-using SYSTEM "chapters/using.xml">
 <!ENTITY chapter-building SYSTEM "chapters/building.xml">
 <!ENTITY chapter-appendix SYSTEM "chapters/appendix.xml">
@@ -39,6 +40,7 @@
 
   <!-- Main chapters-->
   &chapter-introduction;
+  &chapter-installation;
   &chapter-using;
   &chapter-building;
 

host/Makefile

@@ -3,7 +3,7 @@ LDFLAGS=-lusb `pkg-config --libs libosmocore` -losmocore
 all: simtrace
 
 simtrace: main.o usb_helper.o usb.o apdu_split.o
-	$(CC) $(LDFLAGS) -o $@ $^
+	$(CC) -o $@ $^ $(LDFLAGS)
 
 %.o: %.c
 	$(CC) $(CFLAGS) `pkg-config --cflags libosmocore` -o $@ -c $^
@@ -13,6 +13,5 @@ install: simtrace
 	install -m 0755 simtrace $(DESTDIR)/usr/bin/
 .PHONY: install
 
-
 clean:
 	@rm -f simtrace *.o

host/apdu_split.c

@@ -136,7 +136,7 @@ static void apdu_split_inbyte(struct apdu_split *as, uint8_t ch)
 		break;
 	case APDU_S_SW2:
 		apdu_buf_append(as, ch);
-		//printf("APDU: %s\n", hexdump(as->apdu_buf, as->apdu_len));
+		//printf("APDU: %s\n", osmo_hexdump(as->apdu_buf, as->apdu_len));
 		as->apdu_out_cb(as->apdu_buf, as->apdu_len, as->user_data);
 		set_state(as, APDU_S_CLA);
 		break;

host/debian/changelog

@@ -1,23 +0,0 @@
-simtrace (0.0.1+deb1-4) natty; urgency=low
-
-  * Fix the osmocore dependency. 
-
- -- Holger Freyther <zecke@selfish.org>  Thu, 14 Jul 2011 21:11:39 +0200
-
-simtrace (0.0.1+deb1-3) natty; urgency=low
-
-  * Try to fix the dependencies.
-
- -- Holger Freyther <zecke@selfish.org>  Thu, 14 Jul 2011 18:44:06 +0200
-
-simtrace (0.0.1+deb1-2) natty; urgency=low
-
-  * Try to fix the build.
-
- -- Holger Freyther <zecke@selfish.org>  Thu, 14 Jul 2011 18:22:44 +0200
-
-simtrace (0.0.1+deb1-1) natty; urgency=low
-
-  * Initial release of the SIMtrace.
-
- -- Holger Freyther <zecke@selfish.org>  Mon, 14 Jul 2011 18:00:00 +0200

host/debian/compat

@@ -1 +0,0 @@
-7

host/debian/control

@@ -1,16 +0,0 @@
-Source: simtrace
-Section: net
-Priority: optional
-Maintainer: Holger Freyther <zecke@selfish.org>
-Build-Depends: libusb-dev, make, libosmocore-dev, debhelper
-Standards-Version: 3.8.4
-Homepage: http://simtrace.osmocom.org/
-Vcs-Git: git://git.osmocom.org/simtrace.git
-Vcs-Browser: http://git.osmocom.org/gitweb?p=simtrace.git;a=summary
-
-Package: simtrace
-Section: net
-Architecture: any
-Depends: ${shlibs:Depends}, ${misc:Depends}
-Description: SIMtrace host utility
-

host/debian/copyright

@@ -1,28 +0,0 @@
-This work was packaged for Debian by:
-
-    Holger Freyther <zecke@selfish.org> on Thu, 14 Jul 2011 17:55:07 +0200
-
-It was downloaded from:
-
-    git://git.osmocom.org/simtrace.git
-
-Upstream Author(s):
-
-    Harald Welte <laforge@gnumonks.org>
-
-Copyright:
-
-    Copyright (C) 2006-2011 Harald Welte <laforge@gnumonks.org>
-
-License:
-
-    GNU General Public License, Version 2
-
-The Debian packaging is:
-
-    Copyright (C) 2011 Holger Freyther <zecke@selfish.org>
-
-
-and is licensed under the GPL version 2,
-see "/usr/share/common-licenses/GPL-2".
-

host/debian/rules

@@ -1,21 +0,0 @@
-#!/usr/bin/make -f
-# -*- makefile -*-
-# Sample debian/rules that uses debhelper.
-# This file was originally written by Joey Hess and Craig Small.
-# As a special exception, when this file is copied by dh-make into a
-# dh-make output file, you may use that output file without restriction.
-# This special exception was added by Craig Small in version 0.37 of dh-make.
-
-# Uncomment this to turn on verbose mode.
-#export DH_VERBOSE=1
-
-CFLAGS = -Wall -g
-
-DEB_UPSTREAM_VERSION=$(shell dpkg-parsechangelog | sed -rne 's,^Version: ([^-]+).*,\1,p')
-
-%:
-	dh $@ 
-
-tarball-version:
-	git describe --abbrev=4 --match '*.*.*' $(DEB_UPSTREAM_VERSION) | sed 's/-/./;s/\(.*\)-g/\1-/' > .tarball-version
-

host/debian/simtrace.install

@@ -1 +0,0 @@
-debian/simtrace/usr/bin/simtrace

host/debian/source/format

@@ -1 +0,0 @@
-3.0 (quilt)

host/main.c

@@ -40,6 +40,7 @@
 
 #include <osmocom/core/gsmtap.h>
 #include <osmocom/core/gsmtap_util.h>
+#include <osmocom/core/utils.h>
 
 static struct usb_dev_handle *udev;
 static struct apdu_split *as;
@@ -76,7 +77,7 @@ static int gsmtap_send_sim(const uint8_t *apdu, unsigned int len)
 
 static void apdu_out_cb(uint8_t *buf, unsigned int len, void *user_data)
 {
-	printf("APDU: %s\n", hexdump(buf, len));
+	printf("APDU: %s\n", osmo_hexdump(buf, len));
 	gsmtap_send_sim(buf, len);
 }
 
@@ -140,7 +141,7 @@ int main(int argc, char **argv)
 	char *gsmtap_host = "127.0.0.1";
 	int rc, c;
 	int skip_atr = 0;
-	unsigned int msg_count, byte_count;
+	unsigned int msg_count, byte_count = 0;
 
 	print_welcome();
 
@@ -189,7 +190,7 @@ int main(int argc, char **argv)
 			exit(1);
 		}
 		if (rc > 0) {
-			//printf("URB: %s\n", hexdump(buf, rc));
+			//printf("URB: %s\n", osmo_hexdump(buf, rc));
 			process_usb_msg(buf, rc);
 			msg_count++;
 			byte_count += rc;

host/simtrace.1

@@ -0,0 +1,55 @@
+.\"                                      Hey, EMACS: -*- nroff -*-
+.\" First parameter, NAME, should be all caps
+.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
+.\" other parameters are allowed: see man(7), man(1)
+.TH SIMTRACE 1 "July 17, 2011"
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.\" Some roff macros, for reference:
+.\" .nh        disable hyphenation
+.\" .hy        enable hyphenation
+.\" .ad l      left justify
+.\" .ad b      justify to both left and right margins
+.\" .nf        disable filling
+.\" .fi        enable filling
+.\" .br        insert line break
+.\" .sp <n>    insert n+1 empty lines
+.\" for manpage-specific macros, see man(7)
+.SH NAME
+SIMtrace \- GSM SIM and smartcard tracing
+.SH SYNOPSIS
+.B simtrace
+.RI [ options ]
+.br
+.SH DESCRIPTION
+This manual page documents briefly the
+.B simtrace 
+command.
+.PP
+.\" TeX users may be more comfortable with the \fB<whatever>\fP and
+.\" \fI<whatever>\fP escape sequences to invode bold face and italics, 
+.\" respectively.
+\fBsimtrace\fP is a utility that communicates with the sysmocom SIMtrace
+hardware and forwards messages coming from the USB device to IP using
+the GSMtap protcol. The wireshark utility contains a protocol analyzer.
+.SH OPTIONS
+This program follows the usual GNU command line syntax, with long
+options starting with two dashes (`-').
+.TP
+.B \-h, \-\-help
+Show summary of options.
+.TP
+.B \-iIP, \-\-gsmtap-ip=IP
+The destination IP address for the SIM PDUs encapsulated in the GSMtap
+protocol.
+.TP
+.B \-a, \-\-skip\-atr
+Skip the ATR of the SIMcard.
+.TP
+
+.SH AUTHORS
+SIMtrace was written by 
+Harald Welte
+.PP
+This manual page was written by Holger Freyther
+for the Debian project (but may be used by others).

host/usb_helper.c

@@ -28,26 +28,6 @@
 
 #include <usb.h>
 
-const char *
-hexdump(const void *data, unsigned int len)
-{
-	static char string[65535];
-	unsigned char *d = (unsigned char *) data;
-	unsigned int i, left, ofs;
-
-	string[0] = '\0';
-	ofs = snprintf(string, sizeof(string)-1, "(%u): ", len);
-	
-	left = sizeof(string) - ofs;
-	for (i = 0; len--; i += 3) {
-		if (i >= sizeof(string) -4)
-			break;
-		snprintf(string+ofs+i, 4, " %02x", *d++);
-	}
-	string[sizeof(string)-1] = '\0';
-	return string;
-}
-
 static struct usb_device *find_usb_device (uint16_t vendor_id, uint16_t product_id)
 {
 	struct usb_bus *bus;

host/usb_helper.h

@@ -21,8 +21,6 @@
 
 #include <stdint.h>
 
-const char *hexdump(const void *data, unsigned int len);
-
 struct usb_dev_handle *usb_find_open(uint16_t vendor_id, uint16_t product_id);
 
 #endif