summaryrefslogtreecommitdiffstats
path: root/Tex/Content/Appendix.tex
blob: 65c6fdf51bac6c8347189ebeecb6fe6afe438654 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
\chapter{OsmocomBB}
This section contains general information about how to operate and setup the OsmocomBB framework and the Motorola C123.
\section{Installation}
\label{sec:osmo_install}
The environment used for this project was a Thinkpad X220 Tablet running Xubuntu Linux 11.10.
The instructions should work for any other distribution of the Ubuntu product palette.

\begin{enumerate}
	\item Build libraries must be installed on the operating system to enable compiling libraries.
	\begin{lstlisting}
sudo apt-get install libtool shtool autoconf git-core 
pkg-config make gcc wget
	\end{lstlisting}
	\item The GNU Arm cross compiler toolchain needs to be installed so the firmware for the Motorola C123 can be built.
	It will be added as a repository to \texttt{sources} so it can be easily removed if it is not required any more.
	\begin{lstlisting}
sudo add-apt-repository ppa:bdrung/bsprak
sudo apt-get update
sudo apt-get install arm-elf-toolchain
	\end{lstlisting}
	\item The source code needs to be obtained.
	This can be either done by checking out the latest version of the framework from the developers, or by using the code on the CD.
	\begin{lstlisting}
git clone git://git.osmocom.org/osmocom-bb.git
	\end{lstlisting}
	\item At this point some firmwares had build errors, therefore we will compile only the firmware for the Calypso board used by the Motorola C123.
	This constraint might not be necessary if a newer version of the framework is used.
	In the \texttt{src} directory of the OsmocomBB framework the build process can be started.
	\begin{lstlisting}
make BOARDS=compal_e88
	\end{lstlisting}
	\item If a new version of OsmocomBB is used, the extra code from this project must be included in the build.
	The two files \texttt{catcher.c} and \texttt{app\_catcher.c} must be moved to \texttt{osmocom-bb/src/host/layer23/src/misc} and the \texttt{Makefile.am} must be edited to include the new code.
	\begin{lstlisting}
bin_PROGRAMS = bcch_scan ... cbch_sniff catcher
catcher_SOURCES = ../common/main.c app_catcher.c
	\end{lstlisting}
\end{enumerate}

\section{Usage}
\label{sec:osmo_usage}
To use a program written in the framework, the Motorola C123 needs to be flashed with the custom firmware.
This can be done with the \texttt{osmocon} application. 
\begin{lstlisting}
cd src/host/osmocon
sudo ./osmocon -p /dev/ttyUSB0 -m c123xor
 ../../target/firmware/board/compal_e88/layer1.compalram.bin
\end{lstlisting}
After \texttt{osmocon} is started and running any application can be started with root privileges.
\begin{lstlisting}
cd ../layer23/src/misc/
sudo catcher
\end{lstlisting}
\newpage
\section{Serial Cable Schematics}
\label{sec:osmo_serial_schematics}
A T191 unlock cable used to connect the Motorola C123 can either be obtained by ordering it from one of the mentioned stores or by building it from scratch.
These are the schematics required for building the unlock cable.
\vfill
\begin{center}
\includegraphics[width=.9\textwidth]{../Images/t191cable}
\end{center}
\vfill
\chapter{IMSI Catcher Detection System}
This section will cover some code related topics of the ICDS.
\section{Extextions}
\label{sec:extensions}
Rules, evaluators and filters are implemented in a way that new modules can be added quickly by way of inheritance and instantiating them in the constructor of the controller so they are known to the system.
The following example shows how to implement a new rule and add it to the system.
This exemplary process is nearly the same for filters and evaluators.

At first this base class has to be derived.
\begin{lstlisting}
class Rule:
    #set whether the rule should be used by the 
    #controller
    is_active = False
    #string that will identify the rule in the report
    identifier = 'Rule'

    #the logic of the rule, will be called by controller
    def check(self, arfcn, base_station_list):
        return RuleResult.CRITICAL
\end{lstlisting}

The new rule class needs to override the check method to do something meaningful.
The identifier should also be set to a proper value.
\begin{lstlisting}
class MyRule (Rule):
    identifier = 'My own Rule'
    def check(self,arfcn, base_station_list):
        result = RuleResult.CRITICAL
        #do some logic here and set result 
        return result
\end{lstlisting}
\texttt{arfcn} and \texttt{base\_station\_list} are given to the check method by the controller.
The first parameter is the ARFCN of the base station to which the evaluation will be applied.
The second one is a list of all the base stations with complete information as far as it has been
obtained by the ICDS.

After it has been implemented it can be instatiated and added to the list of active rules in the 
constructor of the controller.
\begin{lstlisting}
class PyCatcherController:
    ...
    def __init__ (self):
        ...
        self.my_rule = MyRule()
        self.my_rule.is_active = True
        self._rules.add(self._my_rule)
        ...
\end{lstlisting}
\section{Example Configuration}
\label{sec:example_config}
This example configuration has been used for the evaluation in the Freiburg area.
\begin{lstlisting}
#Core Configuration ---------------------------------------

#Settings for the Motorola C123 .
Device_settings = { 'mobile_device' : '/dev/ttyUSB0',
                    'xor_type' : 'c123xor',
                    'firmware' : 'compal_e88',
                   }

#Location of the osmocom library.
Osmocon_lib = '''/home/tom/imsi-catcher-detection/Src/
osmolib/src'''

#Generates commands from location and device settings.
#Does normally not have to be edited.
Commands = {'osmocon_command' : [Osmocon_lib + 
    '/host/osmocon/osmocon', 
    '-p', Device_settings['mobile_device'], 
    '-m', Device_settings['xor_type'], 
    Osmocon_lib + '/target/firmware/board/' 
    + Device_settings['firmware']
    + '/layer1.compalram.bin'],
    'scan_command' : [Osmocon_lib 
    + '/host/layer23/src/misc/catcher'],
}

#Rules Configuration --------------------------------------

#A list of providers that should be taken as legitimate.
Provider_list = ['T-Mobile', 'O2', 'Vodafone', 'E-Plus']

#Countries where the given providers have presence.
Provider_Country_list = {
    'T-Mobile':'Germany',
    'O2':'Germany',
    'Vodafone':'Germany',
    'E-Plus':'Germany'
}

#Comma separated list of LACs that can be observed in the
#given area.
LAC_mapping = {
    'T-Mobile' : [21014,21015],
    'O2' : [50945],
    'Vodafone' : [793],
    'E-Plus' : [138,588]
}

#Frequency intervals that are registered to the 
#given providers.
ARFCN_mapping = {
    'T-Mobile' : [(13,39),(81, 102),(122,124),(587,611)],
    'O2' : [(0,0),(1000,1023),(637,723)],
    'Vodafone' : [(1,12),(50,80),(103,121),(725,751)],
    'E-Plus' : [(975,999),(777,863)]
}

#How much % the LAC of a base station can deviate from the
#median before throwing an error (range 0 to 1 where 0 
#means no tolerance).
LAC_threshold = 0

#How much % the rx level is allowed to be away from the
#interval located in the Location Area Database
DB_RX_threshold = 0.05

#How much % the rx is allowed to change during the course
#of a scan.
CH_RX_threshold = 0.02

#Database Configuration -----------------------------------

#The API key for OpenCellID.
#Can be freely obtained by registering on the web site. 
Open_Cell_ID_Key = 'd7a5bc3f21b44d4bf93d1ec2b3f83dc4'

#Path to the folder where databases should be saved to or
#loaded from. The ICDS will look in this folder if databa-
#ses are available.
Database_path = '''/home/tom/imsi-catcher-detection/Src
/PyCatcher/Databases/'''
\end{lstlisting}

\chapter{System Information}
\label{sec:system_infos}
The following pages contain parsed System Information Messages of type 1-4  for reference.
\begin{figure}
\centering
\includegraphics[width=.9\textwidth]{../Images/sysinfo1}
\caption{System Information 1 Message}
\end{figure}
\begin{figure}
\centering
\includegraphics[width=.9\textwidth]{../Images/sysinfo2}
\caption{System Information 2 Message}
\end{figure}
\begin{figure}
\centering
\includegraphics[width=.9\textwidth]{../Images/sysinfo3}
\caption{System Information 3 Message}
\end{figure}
\begin{figure}
\centering
\includegraphics[width=.9\textwidth]{../Images/sysinfo4}
\caption{System Information 4 Message}
\end{figure}
\chapter{Evaluation Data}
\section{IMSI Catcher Configurations}
\label{sec:config_data}
The folliwing tables contain the configurations that have been used throughout the long term test period.
The configurations have been used in the order they appear in the tables.
\begin{center}
\begin{tabular}{lllll}
\toprule
			&Conf. 1		&Conf. 2		&Conf. 3		&Conf. 4\\
\midrule
ARFCN		&50				&2				&978			&695	\\
ShortName	&T-Mobile		&Vodafone		&E-Plus			&O2		\\
MCC			&262			&262			&262			&505	\\
MNC			&01				&02				&03				&07		\\
LAC			&21010			&793			&588			&50945	\\
Cell ID		&1				&2				&3				&4		\\
Neighbours	&-				&1,2,3			&695, 20		&10, 20, 30\\
\bottomrule
\end{tabular}\\
\vspace{1cm}
\begin{tabular}{lllll}
\toprule
			&Conf. 5		&Conf. 6		&Conf. 7		&Conf. 8\\
\midrule
ARFCN		&50				&2				&978			&695	\\
ShortName	&T-Mobile		&Vodafone		&E-Plus			&O2		\\
MCC			&262			&262			&262			&505	\\
MNC			&01				&02				&03				&07		\\
LAC			&21010			&793			&588			&50945	\\
Cell ID		&1				&2				&3				&4		\\
Neighbours	&-				&1,2,3			&695, 20		&10, 20, 30\\
\bottomrule
\end{tabular}\\
\vspace{1cm}
\begin{tabular}{lllll}
\toprule
			&Conf. 9		&Conf. 10		&Conf. 11		&Conf. 12\\
\midrule
ARFCN		&50				&2				&978			&695	\\
ShortName	&T-Mobile		&Vodafone		&E-Plus			&O2		\\
MCC			&262			&262			&262			&505	\\
MNC			&01				&02				&03				&07		\\
LAC			&21010			&793			&588			&50945	\\
Cell ID		&1				&2				&3				&4		\\
Neighbours	&-				&1,2,3			&695, 20		&10, 20, 30\\
\bottomrule
\end{tabular}
\end{center}