Introduction️
Osmocom (Open Source Mobile Communications) is an open source project dedicated to developing software and tools for mobile communication networks. Its main objective is to implement a range of mobile network technologies, such as GSM (2G), in an open and accessible way, with its different modules in the form of libraries.️
The project related to the creation of mobile networks is the CNI (Cellular Network Infrastructure), which are implementations of the protocol stack and network elements of GSM. The projects used for creating the network are OsmoMSC, OsmoBSC, OsmoSTP, OsmoHLR, OsmoMGW. On the other hand, we need the element that creates the base station, OsmoBTS, which supports different hardware and software devices. And finally, the transceiver that will support OsmoBTS, the component OsmocomBB.️
OsmoMSC (Mobile Switching Center) implements the routing management of calls and text messages within the network. It allows managing user authentication and mobility, phone number management, and call switching.️
OsmoBSC (Base Station Controller) acts as the controller of the base stations within a GSM network, managing communications between mobile devices and the main network with OsmoMSC traffic.️
OsmoSTP (Signaling Transfer Point) routes signaling messages between the different elements of the network such as OsmoMSC and OsmoBSC through the SS7 (Signaling System No. 7) protocol. SS7 is the traditional protocol used for signaling in telecommunications networks.️
OsmoHLR (Home Location Register) acts as the central database for subscribers, storing user information such as phone number (MSISDN), identifier (IMSI), authentication and subscription status. It integrates with OsmoMSC.️
OsmoMGW (Media Gateway) acts as a media gateway whose main function is to handle voice and other types of data traffic between different parts of the network, converting and transmitting audio data. It integrates with OsmoMSC and OsmoBSC.️
OsmoBTS (Base Transceiver Station) controls the base station that transmits and receives signals from devices in a GSM network. It can be connected to the OsmoBSC controller.️
OsmocomBB (Base Band) develops an open-source firmware for the baseband of GSM mobile phones. This firmware allows replacing proprietary software, accessing the modem hardware and low-level GSM protocols. This allows sending and receiving network control messages, calls and text messages.️
OsmocomBB is very used in security research, as it provides an accessible platform to analyze vulnerabilities in the GSM network, study encryption, intercept communications or understand how authentication and control protocols work.️
It can operate in conjunction with OsmoBTS and OpenBSC, to create complete physical experimental networks where a device acts as the base station of the network. It also can act as a client device on the network. OsmocomBB is only compatible with a very small number of phone models (such as some Motorola C123, C139, etc.).️
FakeTRX is a module that allows emulating this functionality without the need to use real radio hardware, making it easier to test and experiment with GSM networks by creating a virtual base station using the transceiver application and a virtual mobile device using the mobile application. In the case of using a software-defined radio (SDR) device such as the LimeSDR family, OsmoTRX will be used instead of OsmocomBB.️
Installation of the software️
OsmoMSC, OsmoBSC, OsmoSTP, OsmoHLR, OsmoMGW y OsmoBTS can be installed directly from the Debian repository or compiled and installed from source code. In contrast, OsmocomBB, being an experimental software, needs to be compiled from source code. The project directories to compile will be located in the ~/osmocom directory.️
mkdir ~/osmocom
cd ~/osmocom
Option 1: Installation of components from the repository.️
sudo apt install osmo-msc osmo-bsc osmo-stp osmo-hlr osmo-mgw osmo-bts
Option 2: Installation of components from source code.️
Dependencies for compilation of️
osmo-hlr
sudo apt install libsqlite3-dev
libosmo-abis (dependency of osmo-bts)
sudo apt install build-essential libtool libortp-dev osmocom-dahdi-source libsctp-dev shtool autoconf automake git-core pkg-config make gcc
Compilation and installation️
osmo-msc
libosmo-sigtran (dependency) (includes osmo-stp)
git clone https://gitea.osmocom.org/osmocom/libosmo-sigtran.git
cd libosmo-sigtran/
autoreconf -i
./configure
make -j16
sudo make install
sudo ldconfig -i
cd ..
osmo-msc
git clone https://gitea.osmocom.org/cellular-infrastructure/osmo-msc.git
cd osmo-msc/
autoreconf -i
./configure
make -j16
sudo make install
sudo ldconfig -i
cd ..
osmo-bsc
osmo-bsc
git clone https://gitea.osmocom.org/cellular-infrastructure/osmo-bsc.git
cd osmo-bsc/
autoreconf -i
./configure
make -j16
sudo make install
sudo ldconfig -i
cd ..
osmo-hlr
osmo-hlr
git clone https://gitea.osmocom.org/cellular-infrastructure/osmo-hlr.git
cd osmo-hlr/
autoreconf -i
./configure
make -j16
sudo make install
sudo ldconfig -i
cd ..
osmo-mgw
osmo-mgw
git clone https://gitea.osmocom.org/cellular-infrastructure/osmo-mgw.git
cd osmo-mgw/
autoreconf -i
./configure
make -j16
sudo make install
sudo ldconfig -i
cd ..
osmo-bts
libosmo-abis (dependency)
git clone https://gitea.osmocom.org/osmocom/libosmo-abis.git
cd libosmo-abis/
autoreconf -i
./configure
make -j16
sudo make install
sudo ldconfig -i
cd ..
libosmo-netif (dependency)
git clone https://gitea.osmocom.org/osmocom/libosmo-netif
cd libosmo-netif/
autoreconf -i
./configure
make -j16
sudo make install
sudo ldconfig -i
cd ..
osmo-bts
git clone https://gitea.osmocom.org/cellular-infrastructure/osmo-bts.git
cd osmo-bts/
autoreconf -i
./configure --enable-trx
make -j16
sudo make install
sudo ldconfig -i
cd ..
Installing OsmocomBB from source code
Dependencies for compilation of️
libosmocore (dependency de osmocom-bb)
sudo apt install build-essential libtool libtalloc-dev libsctp-dev shtool autoconf automake git-core pkg-config make gcc gnutls-dev python3-minimal libusb-1.0-0-dev libmnl-dev liburing-dev libpcsclite-dev
osmocom-bb
sudo apt install libtool shtool automake autoconf git-core pkg-config make gcc
Compilation and installation️
osmocom-bb
libosmocore (dependency)
git clone https://gitea.osmocom.org/osmocom/libosmocore.git
cd libosmocore/
autoreconf -i
./configure
make -j16
sudo make install
sudo ldconfig -i
cd ..
libosmo-gprs (dependency)
git clone https://gitea.osmocom.org/osmocom/libosmo-gprs.git
cd libosmo-gprs/
autoreconf -i
./configure
make -j16
sudo make install
sudo ldconfig -i
cd ..
osmocom-bb
git clone https://gitea.osmocom.org/phone-side/osmocom-bb.git
cd osmocom-bb
cd src
make nofirmware
cd ../..
Configuration files️
The configuration files for the applications will be stored in the directory ~/osmocom/config.️
mkdir ~/osmocom/config
osmo-hlr.cfg
We took the configuration file from example. We added subscriber-create-on-demand 3 cs+ps under ussd. This configuration creates a new entry in the HLR for each new IMSI registered on the network, assigning a random three-digit MSISDN number in the CS (Circuit Switched) and PS (Packet Switched) networks.️
!
! OsmoHLR example configuration
!
log stderr
logging filter all 1
logging color 1
logging print category-hex 0
logging print category 1
logging timestamp 0
logging print file basename last
logging print level 1
logging level main notice
logging level db notice
logging level auc notice
logging level ss notice
logging level linp error
!
line vty
bind 127.0.0.1
ctrl
bind 127.0.0.1
hlr
gsup
bind ip 127.0.0.1
ussd route prefix *#100# internal own-msisdn
ussd route prefix *#101# internal own-imsi
subscriber-create-on-demand 3 cs+ps
ps
pdp-profiles default
profile 1
apn internet
profile 2
apn *
osmo-stp.cfg
We take the configuration file from example. We do not make any changes in this case.️
!
! osmo-stp (0.0.6.3.179-b248) configuration saved from vty
!!
!
log stderr
logging filter all 1
logging color 1
logging print category 1
logging timestamp 0
logging level set-all notice
line vty
no login
!
cs7 instance 0
xua rkm routing-key-allocation dynamic-permitted
listen m3ua 2905
accept-asp-connections dynamic-permitted
osmo-mgw.cfg
We take the configuration file from example. We make no changes in this case.️
!
! MGCP configuration example
!
log stderr
logging color 1
logging print category-hex 0
logging print category 1
logging timestamp 0
logging print file basename last
logging print level 1
mgcp
bind ip 127.0.0.1
rtp port-range 4002 16001
rtp bind-ip 127.0.0.1
rtp ip-probing
rtp ip-dscp 46
bind port 2427
number endpoints 512
force-realloc 1
rtcp-omit
rtp-patch ssrc
rtp-patch timestamp
osmo-msc.cfg
We took the configuration file from example. We modified the values for network country code, mobile network code, short name, and long name. The MCC (network country code) and MNC (mobile network code) values for test networks are 001 and 01, respectively. For the short name of the network, we will use Test, and for the long name, we will use Test Network.️
!
! OsmoMSC configuration saved from vty
!
log stderr
logging color 1
logging print category-hex 0
logging print category 1
logging timestamp 0
logging print file basename last
logging print level 1
line vty
no login
!
network
network country code 001
mobile network code 01
short name Test
long name Test Network
encryption a5 0
rrlp mode none
mm info 1
mgw 0
remote-ip 127.0.0.1
remote-port 2427
local-port 2728
msc
assign-tmsi
auth-tuple-max-reuse-count 3
auth-tuple-reuse-on-error 1
osmo-bsc.cfg
We took the configuration file from example. We modified the values network country code, mobile network code, band, and arfcn. For network country code and mobile network code we took the previous values. As frequency band band we used GSM900 in the 900 MHz and as channel number arfcn, since it is a virtual network, we can use one at random, such as the 1 (935.2 MHz).️
! osmo-bsc default configuration
! (assumes STP to run on 127.0.0.1 and uses default point codes)
!
log stderr
logging color 1
logging print category-hex 0
logging print category 1
logging timestamp 0
logging print file basename last
logging print level 1
e1_input
e1_line 0 driver ipa
network
network country code 001
mobile network code 01
encryption a5 0
neci 1
paging any use tch 0
handover 0
handover algorithm 1
handover1 window rxlev averaging 10
handover1 window rxqual averaging 1
handover1 window rxlev neighbor averaging 10
handover1 power budget interval 6
handover1 power budget hysteresis 3
handover1 maximum distance 9999
! T3212 is in units of 6min, so below we set 5 * 6 = 30min
timer net T3212 5
mgw 0
remote-ip 127.0.0.1
remote-port 2427
local-port 2727
bts 0
type osmo-bts
band GSM900
cell_identity 6969
location_area_code 0x0001
base_station_id_code 63
ms max power 15
cell reselection hysteresis 4
rxlev access min 0
radio-link-timeout 32
channel allocator mode set-all ascending
rach tx integer 9
rach max transmission 7
channel-description attach 1
channel-description bs-pa-mfrms 5
channel-description bs-ag-blks-res 1
early-classmark-sending forbidden
ipa unit-id 6969 0
oml ipa stream-id 255 line 0
codec-support fr
gprs mode none
trx 0
rf_locked 0
arfcn 1
nominal power 23
! to use full TRX power, set max_power_red 0
max_power_red 20
rsl e1 tei 0
timeslot 0
phys_chan_config CCCH+SDCCH4
hopping enabled 0
timeslot 1
phys_chan_config TCH/F
hopping enabled 0
timeslot 2
phys_chan_config TCH/F
hopping enabled 0
timeslot 3
phys_chan_config TCH/F
hopping enabled 0
timeslot 4
phys_chan_config TCH/F
hopping enabled 0
timeslot 5
phys_chan_config TCH/F
hopping enabled 0
timeslot 6
phys_chan_config TCH/F
hopping enabled 0
timeslot 7
phys_chan_config TCH/F
hopping enabled 0
msc 0
! Do not allow emergency calls unless you can route
! them to the local emergency services
allow-emergency deny
bsc
mid-call-timeout 0
osmo-bts.cfg
We took the configuration file from example. We modified the value band with the value 900. We added the lines gsmtap-remote-host 127.0.0.1 and gsmtap-sapi enable-all below the one of oml in the section of bts to be able to monitor the traffic of the network through UDP port 4729.️
!
! OsmoBTS () configuration saved from vty
!!
!
log stderr
logging color 1
logging print category-hex 0
logging print category 1
logging timestamp 0
logging print file basename last
logging print level 1
logging level rsl notice
logging level oml notice
logging level rll notice
logging level rr notice
logging level meas error
logging level pag error
logging level l1c error
logging level l1p error
logging level dsp error
logging level abis error
!
line vty
no login
!
phy 0
instance 0
osmotrx ip local 127.0.0.1
osmotrx ip remote 127.0.0.1
bts 0
band 900
ipa unit-id 6969 0
oml remote-ip 127.0.0.1
gsmtap-remote-host 127.0.0.1
gsmtap-sapi enable-all
trx 0
phy 0 instance 0
mobile.cfg
We take the configuration file from example. We modify the value sim reader to sim test, the imei, the imsi and the rplmn within test-sim. We will simulate a SIM card with the value sim test, with an IMEI 454527910940629, IMSI 001012698452156 randomly generated and a RPLMN (Registered Public Land Mobile Network) corresponding to the MCC and MNC previously configured.️
!
! OsmocomBB example configuration for mobile application
!!
!
line vty
no login
!
gps device /dev/ttyACM0
gps baudrate default
no gps enable
!
no hide-default
!
ms 1
layer2-socket /tmp/osmocom_l2
sap-socket /tmp/osmocom_sap
mncc-socket /tmp/ms_mncc_1
mncc-handler internal
sim test
network-selection-mode auto
imei 454527910940629 0
imei-fixed
no emergency-imsi
no sms-service-center
no call-waiting
no auto-answer
no force-rekey
no clip
no clir
tx-power auto
no simulated-delay
no stick
location-updating
neighbour-measurement
codec full-speed prefer
codec half-speed
no abbrev
support
sms
a5/1
a5/2
p-gsm
e-gsm
r-gsm
no gsm-850
dcs
no pcs
class-900 4
class-850 4
class-dcs 1
class-pcs 1
channel-capability sdcch+tchf+tchh
full-speech-v1
full-speech-v2
half-speech-v1
no full-data-14400
full-data-9600
full-data-4800
half-data-4800
full-data-2400
half-data-2400
min-rxlev -106
dsc-max 90
no skip-max-per-band
test-sim
imsi 001012698452156
ki comp128 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
no barred-access
rplmn 001 01
tch-data
io-handler unix-sock
io-tch-format ti
unix-socket /tmp/ms_data_1
call-params type-rate 71
call-params ce transparent
call-params async
call-params async nr-stop-bits 1
call-params async nr-data-bits 8
call-params async parity none
tch-voice
io-handler l1phy
! io-format ti
alsa-output-dev default
alsa-input-dev default
no shutdown
Starting the base station with tmux
The deployment of the applications will be carried out using the terminal multiplexer tmux, which will create a window called Osmocom with the applications and their logs. It will also create another window called OsmoCTL with the vty interfaces to interact with the applications through console. For all the applications, we specify the configuration file with the -c argument.️
With the program fake_trx.py in the directory ~/osmocom/osmocom-bb/src/target/trx_toolkit, we create a transceiver for the base station and for a mobile device. With the program trxcon in the directory ~/osmocom/osmocom-bb/src/host/trxcon/src, we create a bridge between the application mobile and the transceiver. The application mobile is located in the directory ~/osmocom/osmocom-bb/src/host/layer23/src/mobile.️
tmux new-session -d -s Osmocom
tmux new-window -a -t Osmocom -n HLR 'osmo-hlr -c ~/osmocom/config/osmo-hlr.cfg'
tmux new-window -a -t Osmocom -n STP 'osmo-stp -c ~/osmocom/config/osmo-stp.cfg'
tmux new-window -a -t Osmocom -n MGW 'osmo-mgw -c ~/osmocom/config/osmo-mgw.cfg'
tmux new-window -a -t Osmocom -n MSC 'osmo-msc -c ~/osmocom/config/osmo-msc.cfg'
tmux new-window -a -t Osmocom -n BSC 'osmo-bsc -c ~/osmocom/config/osmo-bsc.cfg'
tmux new-window -a -t Osmocom -n TRX 'python3 ~/osmocom/osmocom-bb/src/target/trx_toolkit/fake_trx.py'
tmux new-window -a -t Osmocom -n BTS 'osmo-bts-trx -c ~/osmocom/config/osmo-bts-trx.cfg'
tmux new-window -a -t Osmocom -n TRC '~/osmocom/osmocom-bb/src/host/trxcon/src/trxcon'
tmux new-window -a -t Osmocom -n MOB '~/osmocom/osmocom-bb/src/host/layer23/src/mobile/mobile -c ~/osmocom/config/mobile.cfg'
tmux new-session -d -s OsmoCTL
tmux new-window -a -t OsmoCTL -n HLR 'telnet 127.0.0.1 4258'
tmux new-window -a -t OsmoCTL -n STP 'telnet 127.0.0.1 4239'
tmux new-window -a -t OsmoCTL -n MGW 'telnet 127.0.0.1 4243'
tmux new-window -a -t OsmoCTL -n MSC 'telnet 127.0.0.1 4254'
tmux new-window -a -t OsmoCTL -n BSC 'telnet 127.0.0.1 4242'
tmux new-window -a -t OsmoCTL -n BTS 'telnet 127.0.0.1 4241'
tmux new-window -a -t OsmoCTL -n MOB 'telnet 127.0.0.1 4247'
tmux attach-session -t Osmocom
tmux attach-session -t OsmoCTL
Conclusion️
With the applications installed, configured and deployed, it will be possible to start with the network analysis using Wireshark listening on port 4729 for UDP packets. On the other hand, with the mobile application, it will be possible to use a virtual mobile phone to perform operations such as making calls or sending SMS.️