Repository files navigation

• Introduction
• Release Features/Capabilities
• Supported Hardware
  • Ettus Research USRP
  • CPU requirements
• Phones/Modems tested
• SIMS and Authentication
• Build, Install, Setup, and Run Instructions
  • Prerequisites
  • Ettus Research USRP
  • Obtaining the Source
  • Configure and Build
  • Running OpenBTS-UMTS

• Programming your own USIM card
  • Prerequisites
  • Providers
  • Get the SIM programmer
  • Get the software (PySIM, PCSCd, Pyscard)
  • Programming the SIM card
  • Adding subscribers
• References

OpenBTS-UMTS is a Linux-based application that uses a software radio topresent a UMTS network to any standard 3G UMTS handset or modem. Itbuilds upon the OpenBTS framework, where the MS or UE is treated as anIP endpoint at the edge of the network.

• supports original UMTS Release 99 (or Release 3)
• supports packet-switched services only (i.e. data)
• supports a single U-ARFCN
• supports one or two high-speed active data sessions
• spreading factors of 4-256
• rate-1/2 convolutional coding
• rate-1/3 turbo coding
• maximum downlink data speed of 106 Kbytes/s
• maximum uplink data speed of 52 Kbytes/s
• Integrity Protection of GSM SIMs
• Features not supported in this release:
  • circuit-switched services (e.g. voice, text)
  • handover
  • Inter-RAT mobility (moving b/w a 2G and 3G network)
  • paging
  • ciphering
  • USIM-based authentication

Initial integration of the OpenBTS-UMTS public release was accomplishedwith the Range Networks SDR1 (a.k.a. RAD1). Support for recent EttusResearch USRP devices is now available. Integration with othersoftware-defined radios is ongoing, seeRadioIntegration for more information aboutconnecting OpenBTS and OpenBTS-UMTS to different radio interfaces.

Important note: Requires USB 3.0!

Supported Ettus Research products include third generation USRP devices(B200 series and X-series) and second generation models with capablebandwidth for UMTS (N-series). Older Ettus ResearchUSB 2.0 basedproducts are not supported by OpenBTS-UMTS due to transport buslimitations. Supported USRP devices include Intel SSE optimization forUMTS pulse shaping and host resampling operations.

For full USRP details, seeEttus ResearchUSRP.

OpenBTS-UMTS is a more computationally intensive application thanOpenBTS, since the UMTS channel bandwidth is roughly 13x larger than aGSM channel. Generally, a multi-core high performance CPU is required,such as Intel Core i3, i5, or i7 running at more than 1.6Ghz. Intel Atomprocessors are too weak to support the current implementation

• Works
  • iPhones (3, 4, 5 and 7)
  • HTC Velocity
  • Samsung Galaxy
  • Palm Pre
  • a variety of Multitech modems

UMTS mandates mutual authentication between the UE and the NodeB. Thisis a major change from 2G/2.5G authentication, where only the BTSauthenticates the MS.

A good presentation of UMTS security is available at:http://www.netlab.tkk.fi/opetus/s38153/k2003/Lectures/g42UMTS_security.pdf

Another detailed description is available at:http://www.3g4g.co.uk/Tutorial/ZG/zg_security.html

So what does this mean? The subscriber registry will need to know theSIM's Ki value to:

• perform authentication and
• enable integrity protection.

Without proper authentication and integrity protection, the UE will notattach (or register) with OpenBTS-UMTS. For most users, this means youmust provide the SIMs for the UEs on the network. The only way to useSIMs from another provider is to obtain the Ki through a roaminginterface to the provider's HLR/HSS.

This also means that some of the features that circumventedauthentication in OpenBTS, like open registration, are not possible withOpenBTS-UMTS.

USIMs (e.g. 3G SIMs) are not currently supported by the OpenBTS-UMTSimplementation. They require different authentication algorithms thanGSM SIMs; these algorithms are not supported in the public release ofOpenBTS-UMTS.

The following instructions support the Range Networks RAD1 and EttusResearch USRP devices.

The following prerequisites are required to build and run OpenBTS-UMTS:

• Development and build packages for your Linux distribution. Theseare mostly unchanged from OpenBTS.

sudo apt-get install build-essential debhelper pkg-config autoconf libtool libtool-bin libortp-dev libsqlite3-dev libusb-1.0-0-dev libreadline-dev libzmq3-dev libosip2-dev sqlite3 libusb-1.0-0 libortp-dev libc6 pkg-config libreadline6 libosip2-11 git

We also need ASN.1 C compiler that turns the formal ASN.1 specifications into the C code.

Useasn1c-0.9.23.tar.gz which is in the root folder of this repository.

test -f configure || autoreconf -iv./configuremakesudo make install

OpenBTS uses the coredumper shared library to produce meaningful debugging information if OpenBTS crashes.

git clone https://github.com/RangeNetworks/libcoredumper.gitcd libcoredumpersudo ./build.shsudo dpkg -i libcoredumper1_1.2.1-1_amd64.deb libcoredumper-dev_1.2.1-1_amd64.deb

Subscriber Registry API and SIP Authentication Server.

git clone https://github.com/RangeNetworks/subscriberRegistry.gitcd subscriberRegistrygit submodule initgit submodule updatesudo NodeManager/install_libzmq.shautoreconf -i./configuremakesudo make install

• Valid SIM with a known IMSI and Ki values. These values must beadded to the subscriber registry.

USRP Driver:

sudo apt-get install libuhd-dev libuhd003 uhd-host

Make sure that the Ettus UHD driver was found in the output when runningconfigure. When found, Intel SSE support will also be tested andautomatically enabled. If UHD is not found, verify that the UHD driveris properly installed.

checking for UHD... yeschecking whether mmx is supported... yeschecking whether sse is supported... yeschecking whether sse2 is supported... yeschecking whether sse3 is supported... yeschecking whether ssse3 is supported... yeschecking whether sse4.1 is supported... yeschecking whether sse4.2 is supported... yes

The UHD device should be detectable before running OpenBTS. Devicepresence can be checked with theuhd_usrp_probe command installed withthe UHD driver.

$ uhd_usrp_probelinux; GNU C++ version 4.8.3 20140911 (Red Hat 4.8.3-7); Boost_105400; UHD_003.007.003-0-ge10df19c  _____________________________________________________ /|       Device: B-Series Device|     _____________________________________________________|    /|   |       Mboard: B210|   |   revision: 4|   |   product: 2|   |   serial: E0R05Z8BT|   |   FW Version: 4.0|   |   FPGA Version: 3.0

You will need to go into the TransceiverRAD1 directory and run thefollowing script right before running the OpenBTS-UMTS binary in theapps directory (OpenBTS-UMTS/apps/):

sudo ./clkit_61_44mhz.sh

OpenBTS-UMTS is available on GitHub, ensure that you have Git version1.8.2+ installed on your system.

git clone https://github.com/mgp25/OpenBTS-UMTS

TheNodeManager component is setup as a git submodule and can be addedwith the following commands. Note that the current configurationrequires a GitHub account to check out the submodule.

git submodule initgit submodule update

You are now ready to build OpenBTS-UMTS, from your checked-outOpenBTS-UMTS directory:

sudo NodeManager/install_libzmq.sh./autogen.sh./configuremakesudo make install

Note: When runningsudo NodeManager/install_libzmq.sh it might throw an error (source not found 404), you can ignote it.

To setup OpenBTS-UMTS, it may be needed to modify the settings such as ARFCN, DNS, Firewall. Navigate to~/OpenBTS-UMTS/app folder and openOpenBTS-UMTS.example.sql file with the preferable text editor. You may need to edit following options:

• 'GGSN.DNS' set to '8.8.8.8' to enable Google DNS.
• 'GGSN.Firewall.Enable' set to '0' to disable Firewall.
• 'UMTS.Radio.Band' - set the band you are going to use. Select from 850, 900, 1700, 1800, 1900 or 2100.
• 'UMTS.Radio.C0' - set the UARFCN. Range of valid values depend upon the selected operating band. Please, ensure that you are using free operating band.

To create folders and working database:

sudo mkdir /var/log/OpenBTS-UMTScd /etc/OpenBTSsudo sqlite3 /etc/OpenBTS/OpenBTS-UMTS.db “.read OpenBTS-UMTS.example.sql”sudo cp TransceiverUHD/transceiver ~/OpenBTS-UMTS/sudo cp TransceiverUHD/transceiver apps

It's necessary to setup forwarding in iptables to properly forward data between devices, host machine, and the Internet:

sudo suiptables -t nat -A POSTROUTING -j MASQUERADE -o eth0echo 1 > /proc/sys/net/ipv4/ip_forwardexit

If you have Internet connection through the another interface (for example, Wi-Fi), you need to change eth0 to the applicable one (i.e., wlan0). Please note, that you need to setup forwarding in iptables every time after you computer rebooted.

For SipAuthServe:

Subscriber Registry controls database of subscriber information and in fact works as HLR (Home Location Registry):

sudo mkdir /var/lib/asterisk/sudo mkdir /var/lib/asterisk/sqlite3dir/sudo cp apps/comp128 ~/OpenBTS-UMTS/sudo cp apps/comp128 ~/OpenBTS-UMTS/apps/sudo cp apps/comp128 /OpenBTS

After successfully building and configuring, you are ready to launchOpenBTS-UMTS:

cd OpenBTS-UMTS/appssudo ./OpenBTS-UMTScd subscriberRegistry/appssudo ./sipauthserve

UMTSCLI part isn't working fine yet

Several useful commands are available for debugging the packet-switchedOpenBTS-UMTS application. Launch the OpenBTS-UMTS CLI to manipulate andconfigure your UMTS installation.

sudo /OpenBTS-UMTS/OpenBTS-UMTSCLI

In the CLI, typehelp and press ENTER for a list of availablecommands.help command gives you a detailed info on a particularcommand. Typequit to exit the CLI. THis does not stop theOpenBTS-UMTS.

sudo apt-get install python-pip

sudo python -m pip install serial pycrypto

sysmoUSIM-SJS1 4FF/nano SIM + USIM Card (10-pack):

http://shop.sysmocom.de/products/sysmousim-sjs1-4ff

You need a SIM card programmer which is compatible with the PCSC application on Linux. To have a more or less complete list of the compatible devices, please visit this page:

http://pcsclite.alioth.debian.org/ccid/supported.html

Don't forget that you need a programmer with APDU support. Personally we useSCM Microsystems Inc. SCR 3310, you can find it and many of the above list on Ebay.

First install dependencies:

sudo apt-get install pcscd pcsc-tools libccid libpcsclite-dev

Connect your SIM card reader, plug thhe programmable SIM card in, and check connectivity by running the following command:

sudo pcsc_scan

If your reader and card got recognized, you will see something similar:

PC/SC device scannerV 1.4.22 (c) 2001-2011, Ludovic Rousseau <ludovic.rousseau@free.fr>Compiled with PC/SC lite version: 1.8.10Using reader plug'n play mechanismScanning present readers...0: OMNIKEY AG CardMan 3121 01 00Wed Dec 24 14:56:32 2014Reader 0: OMNIKEY AG CardMan 3121 01 00  Card state: Card inserted,  ATR: 3B 9F 95 80 1F C7 80 31 E0 73 FE 21 13 57 12 29 11 02 01 00 00 C2ATR: 3B 9F 95 80 1F C7 80 31 E0 73 FE 21 13 57 12 29 11 02 01 00 00 C2+ TS = 3B --> Direct Convention+ T0 = 9F, Y(1): 1001, K: 15 (historical bytes)  TA(1) = 95 --> Fi=512, Di=16, 32 cycles/ETU    125000 bits/s at 4 MHz, fMax for Fi = 5 MHz => 156250 bits/s  TD(1) = 80 --> Y(i+1) = 1000, Protocol T = 0-----  TD(2) = 1F --> Y(i+1) = 0001, Protocol T = 15 - Global interface bytes following-----  TA(3) = C7 --> Clock stop: no preference - Class accepted by the card: (3G) A 5V B 3V C 1.8V+ Historical bytes: 80 31 E0 73 FE 21 13 57 12 29 11 02 01 00 00  Category indicator byte: 80 (compact TLV data object)    Tag: 3, len: 1 (card service data byte)      Card service data byte: E0        - Application selection: by full DF name        - Application selection: by partial DF name        - BER-TLV data objects available in EF.DIR        - EF.DIR and EF.ATR access services: by GET RECORD(s) command        - Card with MF    Tag: 7, len: 3 (card capabilities)      Selection methods: FE        - DF selection by full DF name        - DF selection by partial DF name        - DF selection by path        - DF selection by file identifier        - Implicit DF selection        - Short EF identifier supported        - Record number supported      Data coding byte: 21        - Behaviour of write functions: proprietary        - Value 'FF' for the first byte of BER-TLV tag fields: invalid        - Data unit in quartets: 2      Command chaining, length fields and logical channels: 13        - Logical channel number assignment: by the card        - Maximum number of logical channels: 4    Tag: 5, len: 7 (card issuer's data)      Card issuer data: 12 29 11 02 01 00 00+ TCK = C2 (correct checksum)Possibly identified card (using /usr/share/pcsc/smartcard_list.txt):3B 9F 95 80 1F C7 80 31 E0 73 FE 21 13 57 12 29 11 02 01 00 00 C2        sysmocom sysmoUSIM-GR1        http://sysmocom.de/

HitCtrl+C to exitpcsc_scan.

Now you need to download and install Pyscard:

http://pyscard.sourceforge.net/

Download and extract the latest Pyscard version:

https://sourceforge.net/projects/pyscard/files/pyscard/

Go to the extracted Pyscard folder (where the setup.py file is located) and run the following command:

sudo /usr/bin/python setup.py build_ext install

Now get the code of PySIM:

git clone git://git.osmocom.org/pysim pysimcd pysim

and run the/pySim-read.py to read your card:

./pySim-read.py

if you done everything allright, you will see something similar:

Reading ...ICCID: 8901901550000123456IMSI: 901550000123456SMSP: fffffffffffffffffffffffffdffffffffffffffffffffffff069186770700f9ffffffffffffffffACC: ffffMSISDN: Not availableDone !

Sometimes it is necessary to give the program the number of the card programmer:

./pySim-read.py -p 0 or./pySim-read.py -p 1

Now we are ready to program the USIM finally! :-)

Get Sysmo USIM tool:

git clone git://git.sysmocom.de/sysmo-usim-tool

We will need:sysmo-usim-tool.sjs1.py

Important:

In order to program the USIM cards, you must use thezecke/tmp2 branch of Pysim. Please note that with thezecke/tmp2 branch you can program but cannot read the cards. If you want to read the cards you will need to swtich back to themaster branch.If you are not using thezecke/tmp2branch or you are not giving the ADM1 pin correctly, you can permanently damage your card!!!

To change branch tozecke/tmp2, use this command:

git checkout zecke/tmp2

Example to program a SysmoUSIM-SJS1 card:

./pySim-prog.py -p 0 --mcc 101 --mnc 02 -t sysmoUSIM-SJS1 --imsi 101020000000003 --iccid 8988211000000012345 --ki 8BAF473F2F8FD09487CCCBD7097C6862 --pin-adm 53770832

IMPORTANT: Where-a is the part where you need to give theADM1 for this specific SIM card. Again, if you are not using thezecke/tmp2 branch or not giving the properADM1 pin when you try to program the Sysmo-USIm S1J1 SIMs, you will likely end up with a permamnently damaged card!

Now lets set COMP128v1 algorithm and disable USIM application in order to make it work with OpenBTS or OpenBTS-UMTS:

./sysmo-usim-tool.sjs1.py --adm1 ADM1_KEY -T COMP128v1:COMP128v1 --classic

Reference:Sysmo USIM Manual

nmcli.py can be found in theNodeManager folder from OpenBTS-UMTS.

Note: The IMSI field consists of the numeric IMSI prefixed with the liter‐al string “IMSI.”

sudo ./nmcli.py sipauthserve subscribers create "name" imsi msisdn ki

Example (without Ki, we recommend you to set Ki too):

Values imsi, msisdn and ki should be taken from your SIM-card.

You can use the following command to show all subscribers:

./nmcli.py sipauthserve subscribers read

Now, connect your phone to the network and test 3G. That's it!

• Getting Started with OpenBTS. Michael Iedema.