📶 GSM (2G) Network with LimeSDR and Osmocom

⚠️ Warning: Setting up a GSM network involves using frequencies that are, in general, heavily regulated. In most jurisdictions, transmitting on these frequencies without proper authorization is against the law and subject to severe penalties.

Familiarize yourself with your local telecommunications laws and be aware of the legal and operational risks involved, including the possibility of causing interference with emergency services and public communications. You might want to explore the possibility of using Faraday cages or direct connections from the base station (SDR) to the mobile station (such as a smartphone) to avoid unauthorized use of the spectrum.

The author and publisher of this guide explicitly reject any liability for illegal use or any adverse outcomes resulting from following this guide. The responsibility for any actions taken rests entirely with you.

This guide provides a straightforward method to set up a basic GSM network using a LimeSDR, software from the Osmocom project, and a Linux-based computer.

GSM is the second generation (2G) digital cellular network technology which mobile communications have once relied on. It has long been obsoleted due to its limitations and well-documented security vulnerabilities, being replaced by newer standards such as UMTS (3G), LTE (4G) and, more recently, 5G. Remarkably, despite its obsolescense, even the most current smartphones remain compatible with GSM!

The setup outlined in this guide supports voice calls and SMS between the GSM network's subscribers and is capable of providing emergency alerts over CB (Cell Broadcast). It also provides internet access, although the slow speeds of 2G technologies (GPRS and EDGE) render it impractical for using modern websites and apps, as even loading a simple page can take long minutes.

It should be possible to enable calls to and from other carriers by using the OsmoSIPConnector, PBX software, and a compatible SIP service provider. However, that is beyond the scope of this guide, as its focus is on creating a minimalist, self-contained network.

As for what is the practical purpose of setting up a GSM network, that is up to you. It could simply be for entertainment value, or it could serve as a means to explore the evolution of mobile communication protocols, including their security aspects. These DIY GSM networks are sometimes showcased at hacker events around the world as fun demonstrations, despite the questionable legality (see the warning at the beginning of this guide).

What about 3G and up?

The Osmocom project does support the UMTS standard; however, its documentation indicates the need for a third-party hNodeB, a separate hardware component.

While the LimeSDR hardware is probably capable of handling the protocol, I haven't been able to find documentation on anyone successfully using it for that purpose. Online searches have led me to OpenBTS-UMTS, a now-discontinued project, making it challenging to find supporting resources. Given these difficulties, and since 2G met my experimental needs, I have decided not to pursue 3G.

For 4G and beyond, the srsRAN project is well-established, and provides examples such as a setup using a Raspberry Pi 4 and SDRs to create an eNodeB. While I haven't experimented with this yet, it is certainly on my future project list.

Security Considerations

It's clear that 2G technology is outdated and insecure. No GSM network should be considered safe for transmitting sensitive information. Additionally, creating a GSM network like this could pose risks to both the host system and any other networks (e.g. Ethernet and Wi-Fi) connected to it.

The Osmocom project's components use a variety of TCP ports for different purposes. One key feature is the VTY (virtual terminal), which allows a user to connect, monitor, and tweak settings on a running component. In the setup we're discussing, these ports are configured to only accept connections from the local machine (localhost) and don't require any authentication. This means that anyone with access to the system could potentially log in, run commands, and change the settings of any active Osmocom component.

If this level of access doesn't suit your needs, you'll need to dive into the configuration files to tighten security, and consider strategies such as firewall rules that distinguish between users, utilizing network namespaces, among others.

Keep in mind that, as your GSM network offers internet access, there's a chance subscribers might misuse it. Forwarding packets could inadvertently expose other devices on your networks to unauthorized access from the GSM network users. As such, it's wise to implement appropriate firewall rules.

Setup

These setup instructions are based on a Debian 12 (“bookworm”) environment with a LimeSDR connected via USB. Should your setup differ, you may have to make adjustments to these steps.

Deciding on authentication

In 2G networks, unlike on 3G/4G/5G, the network authenticates the subscribers, but the mobile devices are not required to authenticate the network itself. In effect, this means you can choose to have an “open” network that authenticates any device attempting to connect to it and, as such, does not require a custom SIM card to be used.

Your decision on whether to enforce authentication or not will significantly impact how users connect to your network and the technical steps required for your setup.

If you opt to enforce authentication, you will need programmable SIM cards and must program them with specific network parameters, including the PLMN[^1] lists and the authentication key (Ki)[^2]. Furthermore, you'll need to add each subscriber to the network database managed by OsmoHLR.

If you decide for an “open” network, users can manually select your network by disabling automatic network selection in their phone's settings. Even without enforcing authentication, you can still use programmable SIM cards for automatic connection to your network (i.e. so automatic network selection doesn't need to be disabled), although those are not required for connection.

[^1]: PLMN (Preferred List of Mobile Networks) refers to a list stored on a SIM card containing the mobile networks that the subscriber should connect to. This list is used by the mobile phone to automatically select one of the networks when they are available.

[^2]: Ki is a 128-bit value used in the authentication and ciphering process between the mobile device and the GSM network. It is stored both in the subscriber's SIM card and the network's database, and is used to authenticate the authorized users to the network.

Programmable SIM cards

For programmable SIM cards, sysmocom is a renowned and reliable provider. Alternatively, marketplaces like Banggood and AliExpress offer inexpensive writeable SIM cards, though quality and features can vary.

One possible concern with SIM cards from these marketplaces is that they may sometimes require software provided by the vendors for writing parameters to them. Often, this software can be best described as opaque — its origins and functionalities are not transparent, raising legitimate concerns about security and integrity. There's a real risk of them containing malware.

If you find yourself needing to use vendor-provided software from these less reputable sources, you should take precautions such as running the software within an isolated virtual machine.

Install required packages

First up, add the Osmocom project repository to your system. On Debian, the simplest route to do so is by using extrepo. For other Linux flavors, refer to the Osmocom wiki.

apt install extrepo
extrepo enable osmocom-latest
apt update

Next, proceed to install the following packages.

apt install git            \
            telnet         \
            iptables       \
            limesuite      \
            osmo-hlr       \
            osmo-msc       \
            osmo-mgw       \
            osmo-stp       \
            osmo-bsc       \
            osmo-ggsn      \
            osmo-sgsn      \
            osmo-bts-trx   \
            osmo-trx-lms   \
            osmo-pcu       \
            osmo-cbc       \
            osmo-cbc-utils

If you haven't done so yet, you might want to take this opportunity to check that your LimeSDR is connected, updated and working properly, by running LimeUtil --update and LimeQuickTest.

Clone the repository

This repository contains the basic configuration files and auxiliary scripts needed for our setup. Clone it using Git.

git clone git@github.com:miraliumre/gsm.git

Customize settings

Within the cloned repository, navigate to etc/osmocom for the relevant Osmocom configuration files. Update these files based on your network preferences.

First, in [osmo-bsc.cfg], set the MCC[^6] and MNC[^7] for your network. As defaults, we hav